GenPage External API Documentation

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

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

3. Base URL

All API requests should be made to:

Base URL: https://backend.genpage.ai/api/external/v1/

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

Have the user get the Bearer API token from the GenPage website.
Call /campaigns/get-list and /audiences/get-list. Let the user select which campaign and audience they want to add the leads to.
Call the Upsert (update or insert) endpoint. You will get a JobId in return. Send the user selected

CampaignID
AudienceID
list of leads the user wants to upsert (update or insert)

Check the status of the job by calling the /leads/get-status endpoint with the JobId you got from /leads/upsert
Get the latest value of the leads by calling /leads/get-leads

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

http://127.0.0.1:8000

/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

Example:

application/json

Body Parameters

workspace_id

integer

required

Example:

Auth

Headers

Body

{ "workspace_id": 16 }

Received response

Example request:

curl --request GET \
    --get "http://127.0.0.1:8000/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"
        }
    ]
}

Authentication

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

POST

http://127.0.0.1:8000

/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

Example:

application/json

Body Parameters

name

string

required

Must be at least 2 characters. Must not be greater than 255 characters.

Example:

workspace_id

integer

required

Example:

Auth

Headers

Body

{ "name": "b", "workspace_id": 16 }

Received response

Example request:

curl --request POST \
    "http://127.0.0.1:8000/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>"
}

Test authentication endpoint.

GET

http://127.0.0.1:8000

/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

Example:

application/json

Auth

Headers

Received response

Example request:

curl --request GET \
    --get "http://127.0.0.1:8000/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"
}

Campaigns

Get the list of campaigns.

GET

http://127.0.0.1:8000

/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

Example:

application/json

Body Parameters

workspace_id

integer

required

Example:

Auth

Headers

Body

{ "workspace_id": 16 }

Received response

Example request:

curl --request GET \
    --get "http://127.0.0.1:8000/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"
        }
    ]
}

Endpoints

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

GET

http://127.0.0.1:8000

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

requires authentication

Headers

Authorization

Example:

Bearer <Token>

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

workspace_id

integer

required

Example:

Auth

Headers

Body

{ "workspace_id": 16 }

Received response

Example request:

curl --request GET \
    --get "http://127.0.0.1:8000/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

http://127.0.0.1:8000

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

requires authentication

Headers

Authorization

Example:

Bearer <Token>

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

token_id

string

required

Example:

architecto

Auth

Headers

Body

{ "token_id": "architecto" }

Received response

Example request:

curl --request DELETE \
    "http://127.0.0.1:8000/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\"
}"

Leads

Upsert leads.

POST

http://127.0.0.1:8000

/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

Example:

application/json

Body Parameters

from

string

required

The service that is sending the leads, use your own company/service name please.

Example:

MyCompanyName

campaign_id

integer

required

The campaign ID to add the leads to.

Example:

audience_id

integer

required

The audience ID to add the leads to.

Example:

leads

string[]

required

Array of lead objects to upsert.

lead_id

integer

The GenPage Lead ID for updating existing leads.

Example:

genpage_url

string

The GenPage URL for updating existing leads.

Example:

https://myworkspace.genpa.ge/aws-john

values

object

required

Object containing key/value pairs with the lead data. You can send any key/value (value can be a string or a number) pairs that you want to add to the lead.

first_name

string

The first name of the lead.

Example:

John

last_name

string

The last name of the lead.

Example:

Doe

string

The email address of the lead.

Example:

john@aws.com

company_name

string

The company name of the lead.

Example:

Amazon Web Services

linkedin_profile_url

string

The LinkedIn profile URL of the lead.

Example:

https://www.linkedin.com/in/john-doe-1234567890

company_domain

string

The company domain of the lead.

Example:

amazon.com

my_custom_variable

string

Custom variable for the lead.

Example:

My custom value

Auth

Headers

Body

{ "from": "MyCompanyName", "campaign_id": 1, "audience_id": 1, "leads": { "lead_id": 16, "genpage_url": "https:\/\/myworkspace.genpa.ge\/aws-john", "values": { "first_name": "John", "last_name": "Doe", "email": "john@aws.com", "company_name": "Amazon Web Services", "linkedin_profile_url": "https:\/\/www.linkedin.com\/in\/john-doe-1234567890", "company_domain": "amazon.com", "my_custom_variable": "My custom value" } } }

Received response

Example request:

curl --request POST \
    "http://127.0.0.1:8000/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"
}

Get the status of the job.

GET

http://127.0.0.1:8000

/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

Example:

application/json

Body Parameters

job_id

string

required

Example:

architecto

Auth

Headers

Body

{ "job_id": "architecto" }

Received response

Example request:

curl --request GET \
    --get "http://127.0.0.1:8000/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
}

Get the leads that were upserted by a job.

GET

http://127.0.0.1:8000

/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

Example:

application/json

Body Parameters

workspace_id

integer

required

Example:

job_id

string

required

Example:

architecto

Auth

Headers

Body

{ "workspace_id": 16, "job_id": "architecto" }

Received response

Example request:

curl --request GET \
    --get "http://127.0.0.1:8000/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"
            }
        }
    ]
}