NAV Navbar
Python Javascript cURL

LeadGenius API Docs

Welcome to the LeadGenius API!

The LeadGenius public API is a RESTful API that can send and receive records from LeadGenius' Dashboard product. Records are associated to Campaigns in Dashboard and consist of Accounts that can optionally include related Contact records. A Campaign can be created in Dashboard using the Dashboard Wizard or via the API. Any Campaign in Dashboard can be accessed using the LeadGenius API. To get started with the API contact sales@leadgenius.com or your Customer Success rep.

General Data Flow

The following is an example of how the typical integration is setup, this isn't the exact flow in all cases but it's a good example of what the typical use case looks like:

  1. A Campaign is created in Dashboard that outlines what Account and Contact data is going to be requested
  2. After creating the campaign, a webhook URL is provided and sample data is generated that describes how to access the newly created Campaign via the API
  3. The customer system sends a collection of Account records to Dashboard using the previously provided job ID and field names
  4. Once either the Accounts are enriched or Contacts added (records are finalized in both cases), a message is sent via the webhook that contains the IDs of the records that are ready to be downloaded
  5. The customer system requests the enriched or added records by ID successfully.

Creating a Campaign

After a Campaign is created, records are sent to that Campaign via the API to be enriched or appended with new Contacts. How the Campaign is created will determine if this is an Enrichment or Contact append Campaign (or both).

Creating Campaigns using the API

Three kinds of campaigns can be created via the API

Creating Campaigns in Dashboard

Contact support if you need help creating a Campaign in Dashboard. Once your Campaign is created in Dashboard, you can enable 'API Access' to it in the Campaign summary. After you enable API access, sample code will be displayed in the app that outlines the field names and the Campaign identifier needed to properly send and request records.

Code Examples & Documentation

All responses are encoded in JSON. We’ve provided a few code examples in the documentation below but let us know if you have any questions.

Authentication

API Key

To authorize, use this code:

URL = 'https://leadgenius.com/'
TOKEN = 'apikey'
STATUS_URL = 'api/v1/enrichment/status/'

HEADERS = {
    'Authorization': 'Token {0}'.format(TOKEN),
    'Content-Type': 'application/json'
}

const axios = require('axios').default;

const URL = 'https://leadgenius.com/';
const TOKEN = 'apikey';
const STATUS_URL = 'api/v1/enrichment/status/';

const HEADERS = {
    'Authorization': "TOKEN " + TOKEN,
    'Content-Type': 'application/json'
};

const CONFIG = {
  headers: HEADERS
};

curl -H "Content-Type: application/json" -H "Authorization: Token apikey"

Make sure to replace apikey with your API key. LeadGenius uses API keys to allow access to the API. LeadGenius customers may contact Sales for an API subscription and key.

LeadGenius expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Token {apikey}

Creating an API Campaign

The API accepts the following:

Object Optional/Required? Type Definition
slug required 1 string This is the job identifier. If the job doesn't exist a new one will be created. If you do not provide a slug, you will receive an error.
  • You can add additional records to an existing job by specifying the slug of the existing job.
  • The slug can contain letters, numbers, underscores, or hyphens, but not spaces.
  • The slug for Campaings created in Dashboard can be found on the Campaign details page in Dashboard
type required 1 string This is the type of job that you want to create.

If you are adding additional records to an existing job, you must use the same job type as the existing job.

If you do not include the type parameter, you will receive an error. The job type must contain one of the following values:
fields required 1 array The fields parameter is where you can list the fields that you require to be included in the job, that you would like us to return to you. If your Campaign is created in Dashboard it can include non-standard data points but these must be selected and defined in Dashboard first.
records required 1 JSON array of objects The records you would like us to enrich. Records can be Accounts, Contacts, or leads. If you do not include the records array,or if any of the fields that you pass in the records array do not match the fields that we allow, you will receive an error.

Each record should include the identifier fields as specified below. Account or company records only require a company identifier. Contact records only require a Contact identifier. Leads (where the records contain both company and Contact data) require both types of identifier fields. org_record_id and contact_record_id are optional.
  • Contact identifier (choose 1 of these)
    • contact_last_name
    • contact_email
  • Company identifier (choose 1 of these)
    • org_company_name
    • org_website
  • org_record_id OR contact_record_id (optional)
webhook_url optional string Url to the webhook url you want to be called when record[s] finalized on LeadGenius side

1: If you don't include these required parameters, you will receive an error.

Job Types

Dashboard

To Submit records to a Dashboard API Campaign, use this code:

import requests
import json

URL = 'https://leadgenius.com/'
TOKEN = 'apikey'
UPLOAD_URL = 'api/v1/enrichment/upload/'

HEADERS = {
    'Authorization': 'Token {0}'.format(TOKEN),
    'Content-Type': 'application/json'
}

slug = 'your-campaign-name-here'
data = {
    'slug': slug,
    'type': 'datahub',
    'fields': ['org_company_name', 'org_website', 'org_linkedin_url', 'contact_first_name',
      'contact_last_name', 'contact_email', 'contact_job_title', 'contact_linkedin_url'],
    'records': [
      {'contact_first_name': 'Jane', 'contact_last_name': 'Doe', 'contact_email': '',
       'org_company_name': 'Zinc Holdings', 'org_website': 'simplefake.org'},
      {'contact_first_name': '', 'contact_last_name': 'Johnson', 'contact_email': '',
       'org_company_name': 'Zinc Holdings', 'org_website': 'simplefake.org'},
      {'contact_first_name': '', 'contact_last_name': 'Diamond', 'contact_email': 'ediamond@earthstar.org',
       'org_company_name': 'EarthStar', 'org_website': 'earthstar.org'},
    ]
}

response = requests.post(url=URL + UPLOAD_URL, headers=HEADERS, data=json.dumps(data))
print(response.content)

const axios = require('axios').default;

const URL = 'https://leadgenius.com/';
const TOKEN = 'apikey';
const UPLOAD_URL = 'api/v1/enrichment/upload/';

const HEADERS = {
    'Authorization': "Token " + TOKEN,
    'Content-Type': 'application/json'
};

const slug = 'your-campaign-name-here3';
const data = {
    'slug': slug,
    'type': 'datahub',
    'fields': ['org_company_name', 'org_website', 'org_linkedin_url', 'contact_first_name',
      'contact_last_name', 'contact_email', 'contact_job_title', 'contact_linkedin_url'],
    'records': [
      {'contact_first_name': 'Jane', 'contact_last_name': 'Doe', 'contact_email': '',
       'org_company_name': 'Zinc Holdings', 'org_website': 'simplefake.org'},
      {'contact_first_name': '', 'contact_last_name': 'Johnson', 'contact_email': '',
       'org_company_name': 'Zinc Holdings', 'org_website': 'simplefake.org'},
      {'contact_first_name': '', 'contact_last_name': 'Diamond', 'contact_email': 'ediamond@earthstar.org',
       'org_company_name': 'EarthStar', 'org_website': 'earthstar.org'},
    ]
};

const CONFIG = {
    headers: HEADERS
};


async function request(){
    try{
        let response = await axios.post(URL + UPLOAD_URL, data, CONFIG);
        console.log(response.data)
    }
    catch(error){
        console.log(error)
    }
}


request();

curl -H "Content-Type: application/json" -H "Authorization: Token apikey" -X POST -d '{"slug":"api-test-standard-fields","type":"datahub","records":[{"contact_first_name":"Jules", "contact_last_name":"Verne", "contact_email":"", "org_company_name":"Zinc Holdings", "org_website":"simplefake.org"},{"contact_first_name":"Johnny","contact_last_name":"Cash", "contact_email":"", "org_company_name":"Zinc Holdings", "org_website":"simplefake.org"},{"contact_first_name":"Boyce","contact_last_name":"Shaves", "contact_email":"", "org_company_name":"Somewhere Else", "org_website":"elsewhere.org"}]}' "https://leadgenius.com/api/v1/enrichment/upload/"

Make sure to replace apikey with your API key.

Supported Fields

The following fields are supported for enrichment via the API, if your job is using a campaign created in Dashboard the Object names that corospond to any non-standard fields can be found in the sample code provided in Dashboard:

Standard Account fields:

Object Definition
org_city The city where the company is located.
org_linkedin_url The URL of the company's LinkedIn profile.
org_company_name The name of the company.
org_phone The main phone number of the company.
org_country The country where the company is located.
org_num_employees The number of employees at the company, expressed as a range.
org_num_employees_exact The exact number of employees at the company.
org_industry The industry of the company.
org_annual_revenue The annual revenue of the company.
org_state The state or province where the company is located.
org_street The street address where the company is located.
org_website The URL for the company's website.
org_zip_code The ZIP code or postal code of the company.
org_record_id The record ID of the company or account. This can be the account ID from your CRM.

Standard Contact fields

Object Definition
contact_linkedin_url The URL of the contact's LinkedIn profile.
contact_department The department where the contact works.
contact_email The contact's work email address.
contact_first_name The contact's first name.
contact_job_title The contact's job title.
contact_last_name The contact's last name, or surname.
contact_seniority The contact's seniority level. (C-Level, VP, Director, Manager, Senior, Entry Level)
contact_record_id The record ID of the contact. This can be the contact or lead ID from your CRM.

Campaign Status

To Query Campaign Status, use this code:

import requests

URL = 'https://leadgenius.com/'
TOKEN = 'apikey'
RETRIEVE_URL = 'api/v1/enrichment/retrieve/{slug}/'
RETRIEVE_BY_ID_URL = 'api/v1/enrichment/retrieve/{slug}/?id=1&id=2'  # use this format to filter out records by id

HEADERS = {
    'Authorization': 'Token {0}'.format(TOKEN),
    'Content-Type': 'application/json'
}

slug = 'your-campaign-name-here'

response = requests.get(url=URL + RETRIEVE_URL.format(slug=slug), headers=HEADERS)
print(response.content)

const axios = require('axios').default;

const URL = 'https://leadgenius.com/';
const TOKEN = 'apikey';

const slug = 'your-campaign-name-here';
const RETRIEVE_URL = 'api/v1/enrichment/retrieve/' + slug;

const HEADERS = {
    'Authorization': "TOKEN " + TOKEN,
    'Content-Type': 'application/json'
};


const CONFIG = {
  headers: HEADERS
};

async function request(){
  try{
    let response = await axios.get(URL + RETRIEVE_URL, CONFIG);
    console.log(response.data)
  }
  catch(error){
    console.log(error.response.data)
  }
}

request();

curl -H "Content-Type: application/json" -H "Authorization: Token apikey" -X GET "https://leadgenius.com/api/v1/enrichment/retrieve/your-campaign-name-here"

Replace your-campaign-name-here with your campaign slug.

JSON Response (Job Completed):

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 15,
            "finalized": "2019-08-30T10:18:48",
            "data": {
                "org_num_employees": "",
                "org_street": "",
                "org_company_name": "blizord",
                "contact_first_name": "Leeroy",
                "org_industry": "",
                "org_zip_code": "",
                "org_phone": "4158128811",
                "contact_linkedin_url": "",
                "contact_record_id": "31337",
                "org_country": "",
                "org_website": "",
                "org_city": "",
                "org_record_id": "",
                "contact_email": "leeroy@blizord.com",
                "org_state": "",
                "contact_last_name": "Jenkins",
                "org_linkedin_url": "https://linkedin.com/u/leeroy",
                "org_annual_revenue": "",
                "org_num_employees_exact": "",
                "contact_department": "",
                "contact_job_title": "CEO",
                "contact_seniority": "C"
            },
            "created": "2019-08-30T10:15:27",
            "status": "finalized_incomplete"
        },
    ],
    "count_uploaded": 1,
    "count_enriched": 1
}

You can easily query a running job to find out the status of an API campaign. If the campaign has been completed, you will receive the completed data.

The API accepts:

The API returns:

The API supports pagination at 100 records

API Usage Stats

To Query API Usage, use this code:

import requests

URL = 'https://leadgenius.com/'
TOKEN = 'apikey'
STATUS_URL = 'api/v1/enrichment/status/'

HEADERS = {
    'Authorization': 'Token {0}'.format(TOKEN),
    'Content-Type': 'application/json'
}

response = requests.get(url=URL + STATUS_URL, headers=HEADERS)
print(response.content)

const axios = require('axios').default;

const URL = 'https://leadgenius.com/';
const TOKEN = 'apikey';
const STATUS_URL = 'api/v1/enrichment/status/';

const HEADERS = {
    'Authorization': "TOKEN " + TOKEN,
    'Content-Type': 'application/json'
};

const CONFIG = {
  headers: HEADERS
};

async function request(){
  try{
    let response = await axios.get(URL + STATUS_URL, CONFIG);
    console.log(response.data)
  }
  catch(error){
    console.log(error)
  }
}

request();

curl -H "Content-Type: application/json" -H "Authorization: Token apikey" -X GET "https://leadgenius.com/api/v1/enrichment/status/"

JSON Response:

{
    "total": {
        "uploaded": 2,
        "enriched": 2
    },
    "current_period": {
        "uploaded": 2,
        "enriched": 2,
        "remaining": 98,
        "end_date": "2019-09-01T00:00:00",
        "start_date": "2019-08-01T00:00:00"
    },
    "updated_at": "2019-08-28T09:51:31"
}

This call is used to check the current status of your API subscription.

The API returns:

Exclusion Records

The API accepts the following:

Object Optional/Required? Type Definition
records required 1 JSON array of objects The records you would like us to exclude. Records can be Accounts, Contacts. If you do not include the records array, or if any of the fields that you pass in the records array do not match the fields that we allow, you will receive an error.

Each record should include the identifier fields as specified below. Account or company records only require a company identifier. Contact records only require a Contact identifier.
  • Contact identifier (choose 1 of these)
    • contact_linkedin_url
    • contact_email
  • Company identifier (choose 1 of these)
    • org_linkedin_url
    • org_website

Exclusion List

To Submit records to exclusion list via api, use this code:

import requests
import json

URL = 'https://leadgenius.com/'
TOKEN = 'apikey'
UPLOAD_URL = 'api/v1/exclusion/upload/'

HEADERS = {
    'Authorization': 'Token {0}'.format(TOKEN),
    'Content-Type': 'application/json'
}

data = {
    'records': [
      {'entity': 'contact', 'contact_first_name': 'Jane', 'contact_last_name': 'Doe', 'contact_email': 'jane@simplefake.org',
       'org_company_name': 'Zinc Holdings', 'org_website': 'simplefake.org'},
      {'entity': 'contact', 'contact_first_name': '', 'contact_last_name': 'Johnson', 'contact_email': 'johnson@simplefake.org',
       'org_company_name': 'Zinc Holdings', 'org_website': 'simplefake.org'},
      {'entity': 'org', 'org_company_name': 'EarthStar', 'org_website': 'earthstar.org'},
    ]
}

response = requests.post(url=URL + UPLOAD_URL, headers=HEADERS, data=json.dumps(data))
print(response.content)

const axios = require('axios').default;

const URL = 'https://leadgenius.com/';
const TOKEN = 'apikey';
const UPLOAD_URL = 'api/v1/exclusion/upload/';

const HEADERS = {
    'Authorization': "Token " + TOKEN,
    'Content-Type': 'application/json'
};

const data = {
    'records': [
      {'entity': 'contact', 'contact_first_name': 'Jane', 'contact_last_name': 'Doe', 'contact_email': 'jane@simplefake.org',
       'org_company_name': 'Zinc Holdings', 'org_website': 'simplefake.org'},
      {'entity': 'contact', 'contact_first_name': '', 'contact_last_name': 'Johnson', 'contact_email': 'johnson@simplefake.org',
       'org_company_name': 'Zinc Holdings', 'org_website': 'simplefake.org'},
      {'entity': 'org', 'org_company_name': 'EarthStar', 'org_website': 'earthstar.org'},
    ]
};

const CONFIG = {
    headers: HEADERS
};


async function request(){
    try{
        let response = await axios.post(URL + UPLOAD_URL, data, CONFIG);
        console.log(response.data)
    }
    catch(error){
        console.log(error)
    }
}


request();

curl -H "Content-Type: application/json" -H "Authorization: Token apikey" -X POST -d '{"records": [{"entity": "contact", "contact_first_name": "Jane", "contact_last_name": "Doe", "contact_email": "jane@simplefake.org", "org_company_name": "Zinc Holdings", "org_website": "simplefake.org"}, {"entity": "contact", "contact_first_name": "", "contact_last_name": "Johnson", "contact_email": "johnson@simplefake.org", "org_company_name": "Zinc Holdings", "org_website": "simplefake.org"}, {"entity": "org", "org_company_name": "EarthStar", "org_website": "earthstar.org"}]}' "https://leadgenius.com/api/v1/exclusion/upload/"

Make sure to replace apikey with your API key.

Supported Fields

The following fields are supported for exclusion via the API.

Excluded Account Fields

Object Definition
entity org (static value)
org_linkedin_url The URL of the company's LinkedIn profile.
org_company_name The name of the company.
org_phone The main phone number of the company.
org_website The URL for the company's website.

Excluded Contact Fields

Object Definition
entity contact (static value)
contact_linkedin_url The URL of the contact's LinkedIn profile.
contact_email The contact's work email address.
contact_first_name The contact's first name.
contact_last_name The contact's last name, or surname.
org_linkedin_url The URL of the company's LinkedIn profile.
org_company_name The name of the company.
org_phone The main phone number of the company.
org_website The URL for the company's website.

Webhook

An example of incoming JSON payload

{
  "slug": "project slug on leadgenius side",
  "records": [123444, 123233],
  "uploaded": 3,
  "enriched": 2,
  "complete": false
}

When creating a campaign either in Dashboard or via the API there is an optional webhook_url field, if the webhook URL is set then a POST request will be sent back the specified URL with content-type: application/json every time a record is finalized. If the Campaign is created in Dashboard the webhook URL is defined in the Dashboard UI.

Keys

Key Type Definition
slug string Campaign slug/identifier on LeadGenius platform
records array An array of finalized record ids
uploaded integer Total number of records uploaded to the campaign
enriched integer Total number of verified records uploaded to thecampaign
complete boolean Flag if all uploaded records were verified

Rate Limits

Our API has a rate limit of 50 requests per minute, with up to 200 records per request. Sending more than 50 requests per minute will return a 429 error.

Currently, there is no limit on the number of records per job, however turn-around time will be increased for larger jobs.

Errors

The LeadGenius API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid in some way
401 Unauthorized -- Your API key is invalid
403 Forbidden -- The resource requested is hidden for administrators only
404 Not Found -- The specified resource could not be found
405 Method Not Allowed -- You tried to access a resource with an invalid method
406 Not Acceptable -- You requested a format that isn't supported
410 Gone -- The resource requested has been removed from our servers
418 I'm a teapot
429 Too Many Requests -- You're exceeding your rate-limits.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Specific Errors

Error Message HTTP Code Description/Solution
{"type":["This field is required."]} 400 The type parameter was not included with your request.
{"type":["\"foo\" is not a valid choice."]} 400 The value given for type is not a valid option.
{"fields":["single_field type requires 1 field. Passed 2"]} 400 More than 1 other field has been given (in addition to identifier fields) for the fields parameter.
{"fields":["This list may not be empty. single_field type requires 1 field"]} 400 No field (in addition to identifier fields) was given for the fields parameter.
Python Javascript cURL