GenPage External API Documentation

Postman collection → OpenAPI spec →

Introduction

Welcome to the GenPage External API documentation. This guide will help you integrate with our platform and access our powerful features programmatically.

Getting Started

1. Create an Account

Visit https://app.genpage.ai and create your account.

2. Generate an API Token

  1. Navigate to Settings → Integrations
  2. Create a new API token
  3. Store this token securely - you'll need it for all API requests

3. Base URL

All API requests should be made to:

Developer Support

Need a test account? If you're a developer requiring a test account, please contact us at team@genpage.ai and we'll be happy to help you get started.

Authentication info

Include your Bearer API token in the Authorization header of all requests, like this:

This documentation aims to provide all the information you need to work with our API.

Documentation Features

This documentation provides comprehensive information for working with our API, including:

  • Code Examples: Interactive code samples in multiple programming languages
  • Request/Response Examples: Real-world examples for each endpoint
  • Error Handling: Common error codes and troubleshooting guides

Ready to get started? Explore the endpoints below to begin integrating with GenPage!

Flow

Step 0: Authentication

Have the user get the Bearer API token from the GenPage website.

Step 1: Get Workspaces

Call /workspaces/get-list to get the list of workspaces the user has access to. The workspace value has to be added to most calls, to specify which workspace this applies to.

Step 2: Get Campaigns and Audiences

Call /campaigns/get-list and /audiences/get-list. Let the user select which campaign and audience they want to add the leads to.

Step 3: Get the Variables / Columns

Call the /workspaces/get-variable-list endpoint to get the list of all the existing variables / columns for that workspace. Use the response to know which columns already exists, and to do a mapping between values in your system and the GenPage system. These keys should be used when calling Upsert lead.

Note that Upsert lead accepts keys that does not exist yet, it will then create new columns/variables with that key name.

Step 4: Upsert Leads

Call the Upsert (update or insert) endpoint. You will get a JobId in return. Send the following data:

  • CampaignID: The selected campaign ID
  • AudienceID: The selected audience ID
  • Leads: List of leads the user wants to upsert (update or insert)

Step 4: Check Job Status

Check the status of the job by calling the /leads/get-status endpoint with the JobId you received from /leads/upsert.

Step 5: Get Updated Leads

Get the latest value of the leads by calling /leads/get-leads.

Result

In the response from /leads/get-leads, you will get a genpage_url - this is the URL to the custom GenPage's that have been generated.

Authenticating requests

To authenticate requests, include a Authorization header with the value "Bearer <Token>".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

Audiences

Get the list of audiences.

GET
https://backend.genpage.ai
/api/external/v1/audiences/get-list
requires authentication

This endpoint is used to get the list of audiences.

Headers

Authorization
Example:
Bearer <Token>
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
curl --request GET \
    --get "https://backend.genpage.ai/api/external/v1/audiences/get-list" \
    --header "Authorization: Bearer &lt;Token&gt;" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"workspace_id\": 16
}"
Example response:
{
    "audiences": [
        {
            "id": 1,
            "name": "Default Audience"
        }
    ]
}
{
    "message": "Unauthenticated."
}

Authentication

Generate an API token. Should be done from the GenPage dashboard.

POST
https://backend.genpage.ai
/api/external/v1/generate-api-token
requires authentication

This endpoint returns the generated token to be used in the external integration.

Headers

Authorization
Example:
Bearer <Token>
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
curl --request POST \
    "https://backend.genpage.ai/api/external/v1/generate-api-token" \
    --header "Authorization: Bearer &lt;Token&gt;" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"b\",
    \"workspace_id\": 16
}"
Example response:
{
    "token": "Bearer <Bearer token>"
}
{
    "message": "Unauthenticated."
}

Test authentication endpoint.

GET
https://backend.genpage.ai
/api/external/v1/hello-world
requires authentication

This endpoint is used to test the authentication.

Headers

Authorization
Example:
Bearer <Token>
Content-Type
Example:
application/json
Accept
Example:
application/json
Example request: 
curl --request GET \
    --get "https://backend.genpage.ai/api/external/v1/hello-world" \
    --header "Authorization: Bearer &lt;Token&gt;" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "message": "Hello World"
}
{
    "message": "Unauthenticated."
}

Campaigns

Get the list of campaigns.

GET
https://backend.genpage.ai
/api/external/v1/campaigns/get-list
requires authentication

This endpoint is used to get the list of campaigns.

Headers

Authorization
Example:
Bearer <Token>
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
curl --request GET \
    --get "https://backend.genpage.ai/api/external/v1/campaigns/get-list" \
    --header "Authorization: Bearer &lt;Token&gt;" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"workspace_id\": 16
}"
Example response:
{
    "campaigns": [
        {
            "id": 1,
            "name": "Test Campaign 1",
            "slug": "test-campaign-1"
        },
        {
            "id": 2,
            "name": "Saas Outreach",
            "slug": "saas-outreach"
        }
    ]
}
{
    "message": "Unauthenticated."
}

Endpoints

GET api/external/v1/get-api-tokens

GET
https://backend.genpage.ai
/api/external/v1/get-api-tokens
requires authentication

Headers

Authorization
Example:
Bearer <Token>
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
curl --request GET \
    --get "https://backend.genpage.ai/api/external/v1/get-api-tokens" \
    --header "Authorization: Bearer &lt;Token&gt;" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"workspace_id\": 16
}"
Example response:

DELETE api/external/v1/delete-api-token

DELETE
https://backend.genpage.ai
/api/external/v1/delete-api-token
requires authentication

Headers

Authorization
Example:
Bearer <Token>
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
curl --request DELETE \
    "https://backend.genpage.ai/api/external/v1/delete-api-token" \
    --header "Authorization: Bearer &lt;Token&gt;" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"token_id\": \"architecto\"
}"

GET api/external/v1/hello-world-user

GET
https://backend.genpage.ai
/api/external/v1/hello-world-user
requires authentication

Headers

Authorization
Example:
Bearer <Token>
Content-Type
Example:
application/json
Accept
Example:
application/json
Example request: 
curl --request GET \
    --get "https://backend.genpage.ai/api/external/v1/hello-world-user" \
    --header "Authorization: Bearer &lt;Token&gt;" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:

Leads

Upsert leads.

POST
https://backend.genpage.ai
/api/external/v1/leads/upsert-leads
requires authentication

This endpoint is used to upsert (update or insert) leads.

The leads are sent in the request body. The leads are an array of objects. The leads.*.values are key/value pairs with the values of the lead.

Required fields for creating or updating a lead

To create a new lead, at least one of:

  • email
  • linkedin_profile_url

To update an existing lead, at least one of:

  • lead_id (GenPage Lead ID)
  • genpage_url (GenPage URL)

Optional but strongly recommended fields

  • first_name
  • company_name

  • company_domain

The response is the job ID.

The job ID can be used to get the status of the job, and get all the leads that were upserted by this request.

Headers

Authorization
Example:
Bearer <Token>
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
curl --request POST \
    "https://backend.genpage.ai/api/external/v1/leads/upsert-leads" \
    --header "Authorization: Bearer &lt;Token&gt;" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"from\": \"MyCompanyName\",
    \"campaign_id\": 1,
    \"audience_id\": 1,
    \"leads\": [
        {
            \"values\": {
                \"last_name\": \"Doe\",
                \"company_domain\": \"amazon.com\",
                \"my_custom_variable\": \"My custom value\"
            }
        }
    ]
}"
Example response:
{
    "job_id": "1234567890"
}
{
    "message": "Unauthenticated."
}

Get the status of the job.

GET
https://backend.genpage.ai
/api/external/v1/leads/get-status
requires authentication

This endpoint is used to get the status of the job. Once the job is completed, the status will be "completed".

The status can be:

  • pending
  • completed
  • failed

Once the job is completed, please use the getLeads endpoint to get all the leads that were upserted by this request.

Headers

Authorization
Example:
Bearer <Token>
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
curl --request GET \
    --get "https://backend.genpage.ai/api/external/v1/leads/get-status" \
    --header "Authorization: Bearer &lt;Token&gt;" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"job_id\": \"architecto\"
}"
Example response:
{
    "status": "pending",
    "processed_rows": 10,
    "total_rows": 100
}
{
    "message": "Unauthenticated."
}

Get the leads that were upserted by a job.

GET
https://backend.genpage.ai
/api/external/v1/leads/get-leads
requires authentication

This endpoint is used to get the leads that were upserted by a job.

Headers

Authorization
Example:
Bearer <Token>
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
curl --request GET \
    --get "https://backend.genpage.ai/api/external/v1/leads/get-leads" \
    --header "Authorization: Bearer &lt;Token&gt;" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"workspace_id\": 16,
    \"job_id\": \"architecto\"
}"
Example response:
{
    "leads": [
        {
            "lead_id": 56789,
            "workspace_id": 222,
            "campaign_id": 333,
            "job_id": "1234567890",
            "values": {
                "name": "John Doe",
                "email": "john@aws.com",
                "company_name": "AWS",
                "url_slug": "aws-john",
                "logo": "https://aws.com/logo.png",
                "logo_color": "#000000",
                "genpage_url": "https://myworkspace.genpa.ge/aws-john"
            }
        }
    ]
}
{
    "message": "Unauthenticated."
}

Workspaces

Get the list of workspaces.

GET
https://backend.genpage.ai
/api/external/v1/workspaces/get-list
requires authentication

This endpoint is used to get the list of workspaces the user has access to.

Headers

Authorization
Example:
Bearer <Token>
Content-Type
Example:
application/json
Accept
Example:
application/json
Example request: 
curl --request GET \
    --get "https://backend.genpage.ai/api/external/v1/workspaces/get-list" \
    --header "Authorization: Bearer &lt;Token&gt;" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
[
  {
    "id": 1,
    "name": "My Company Name",
    "slug": "my-company-name"
  }
  {
    "id": 2,
    "name": "SAAS Outreach",
    "slug": "saas-outreach"
  }
]
{
    "message": "Unauthenticated."
}

Get the list of variables (or columns) for a workspace.

GET
https://backend.genpage.ai
/api/external/v1/workspaces/get-variable-list
requires authentication

This endpoint retrieves all available variables/columns for a specific workspace. It returns both default variables (first_name, email, company_name, company_domain) and any custom variables that have been created for the workspace.

When updating or inserting a lead, you can use the variables/columns from this endpoint to add the values to the specific variable/column for the lead.

Headers

Authorization
Example:
Bearer <Token>
Content-Type
Example:
application/json
Accept
Example:
application/json

Query Parameters

workspace_id
integer
required
Example:
16
Example request: 
curl --request GET \
    --get "https://backend.genpage.ai/api/external/v1/workspaces/get-variable-list?workspace_id=16" \
    --header "Authorization: Bearer &lt;Token&gt;" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
[
    {
        "key": "first_name"
    },
    {
        "key": "email"
    },
    {
        "key": "company_name"
    },
    {
        "key": "company_domain"
    },
    {
        "key": "linkedin_profile_url"
    },
    {
        "key": "My Custom Variable1"
    },
    {
        "key": "custom_variable2"
    }
]
{
    "message": "Unauthenticated."
}
{
    "message": "The given data was invalid.",
    "errors": {
        "workspace_id": [
            "The workspace id field is required."
        ]
    }
}

Zapier

The structure of the request is:

Test authentication endpoint.

GET
https://backend.genpage.ai
/api/external/v1/zapier/test
requires authentication

This endpoint is used to test the authentication.

Headers

Authorization
Example:
Bearer <Token>
Content-Type
Example:
application/json
Accept
Example:
application/json
Example request: 
curl --request GET \
    --get "https://backend.genpage.ai/api/external/v1/zapier/test" \
    --header "Authorization: Bearer &lt;Token&gt;" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
  "message": "Hello World"
  "user": {
    "id": 123,
    "name": "John Doe",
    "email": "john@example.com"
  }
}
{
    "message": "Unauthenticated."
}

Create a lead through Zapier.

POST
https://backend.genpage.ai
/api/external/v1/zapier/upsert-lead
requires authentication

Headers

Authorization
Example:
Bearer <Token>
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
curl --request POST \
    "https://backend.genpage.ai/api/external/v1/zapier/upsert-lead" \
    --header "Authorization: Bearer &lt;Token&gt;" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"project_slug\": \"architecto\",
    \"campaign_id\": 16,
    \"is_test\": false,
    \"linkedin_profile_url\": \"http:\\/\\/www.bailey.biz\\/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html\",
    \"company_domain\": \"architecto\",
    \"email\": \"zbailey@example.net\",
    \"callback_url\": \"https:\\/\\/www.gulgowski.com\\/nihil-accusantium-harum-mollitia-modi-deserunt\"
}"