Lead Lists can be used to upload a set of leads which will then undergo additional enrichment and processing in order to reveal as much information on each lead as possible, leveraging Amplemarket’s vast database.

Usually the flow for this is:

  1. POST /lead-lists/ with a list of LinkedIn URLs that will be processed and revealed

  2. In the response, follow the URL provided in response._links.self.href

  3. Continue polling the endpoint while respecting the Retry-After HTTP Header

  4. When validation completes, the results are in response.results

  5. If the results are larger than the default limit, then follow the URL provided in response._links.next.href

​
Lead List Object

FieldTypeDescription
idstringThe ID of the Lead List
namestringThe name of the Lead List
statusstringThe status of the Lead List:
queued: The validation operation hasn’t started yet
processing: The validation operation is in-progress
completed: The validation operation terminated successfully
canceled: The validation operation terminated due to being canceled
sharedbooleanIf the Lead List is shared across the Account
visiblebooleanIf the Lead List is visible in the Dashboard
ownerstringThe email of the owner of the Lead List
optionsobjectOptions for the Lead List:
reveal_phone_numbers: boolean - If phone numbers should be revealed for the leads
validate_email: boolean - If the emails of the leads should be validated
enrich: boolean - If the leads should be enriched
typestringThe type of the Lead List:
linkedin: The inputs were LinkedIn URLs
email: The inputs were emails
title_and_company: The inputs were titles and company names
name_and_company: The inputs were person names and company names
salesforce: The inputs were Salesforce Object IDs
hubspot: The inputs were Hubspot Object IDs
person: The inputs were Person IDs
adaptive: The input CSV file’s columns were used dynamically during enrichment
leadsarray of lead_list_entryThe entries of the Lead List; the default number of results that appear is up to 100
_linksarray of linksContains useful links related to this resource

​
Lead List Entry Object

FieldTypeDescription
idstringThe ID of the entry
emailstringThe email address of the entry
person_idstringThe ID of the Person matched with this entry
linkedin_urlstringThe LinkedIn URL of the entry
first_namestringThe first name of the entry
last_namestringThe last name of the entry
company_namestringThe company name of the entry
company_domainstringThe company domain of the entry
industrystringThe industry of the entry
titlestringThe title of the entry
email_validation_resultobject of type email_validation_resultThe result of the email validation if one occurred
dataobjectOther arbitrary fields may be included here

​
Lead List Endpoints

​
Creating a new Lead List

Request

A list of leads can be supplied to create a new Lead List with a subset of settings that are included within the lead_list object:

  • owner (string, mandatory) - email of the owner of the lead list which must be an existing user; if a revoked users is provided, the fallback will be the oldest admin’s account instead

  • shared (boolean, mandatory) - indicates whether this list should be shared across the account or just for the specific user

  • type (string, mandatory) - currently only linkedin, email, and titles_and_company are supported

  • leads (array of lead_list_entry, mandatory) where:

    • For the linkedin type, each entry only requires the field linkedin_url

    • For the email type, each entry only requires the field email

    • For the titles_and_company type, each entry only requires the fields title and company_name (or company_domain)

  • name (string, optional) - defaults to an automatically generated one when not supplied

  • visible (boolean, optional) - defaults to true

  • options (object)

    • reveal_phone_numbers (boolean) - if phone numbers should be revealed for the leads

    • validate_email (boolean) - if the emails of the leads should be validated

      • Can only be disabled for lists of type email

    • enrich (boolean) - if the leads should be enriched

      • Can only be disabled for lists of type email
POST /lead-lists HTTP/1.1
Content-Type: application/json

{
  "name": "Example",
  "shared": true,
  "visible": true,
  "owner": "user@example.com",
  "type": "linkedin",
  "leads": [
    {
      "linkedin_url": "..."
    },
    {
      "linkedin_url": "..."
    }
  ]
}

Response

This will return a 202 Accepted indicating that the email validation will soon be started:

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /lead-lists/81f63c2e-edbd-4c1a-9168-542ede3ce98f

{
  "id": "81f63c2e-edbd-4c1a-9168-542ede3ce98f",
  "object": "lead_list",
  "name": "Example",
  "status": "queued",
  "shared": true,
  "visible": false,
  "owner": "user@example.com",
  "type": "linkedin",
  "options": {
    "reveal_phone_numbers": false,
    "validate_email": true,
    "enrich": true,
  },
  "leads": [],
  "_links": {
    "self": { "href": "/lead-lists/81f63c2e-edbd-4c1a-9168-542ede3ce98f" }
  }
}

HTTP Headers

  • Location: GET points back to the object that was created

Links

  • self - GET points back to the object that was created

​
Polling a Lead List

Request

The Lead List object can be polled in order to receive results:

GET /lead-lists/{{id}} HTTP/1.1
Content-Type: application/json

Response

Will return a 200 OK while the operation hasn’t yet terminated.

HTTP/1.1 200 OK
Content-Type: application/json
Retry-After: 60

{
  "id": "81f63c2e-edbd-4c1a-9168-542ede3ce98f",
  "object": "lead_list",
  "name": "Example",
  "status": "processing",
  "shared": true,
  "visible": false,
  "owner": "user@example.com",
  "type": "linkedin",
  "options": {
    "reveal_phone_numbers": false,
    "validate_email": true,
    "enrich": true,
  },
  "leads": [],
  "_links": {
    "self": { "href": "/lead-lists/81f63c2e-edbd-4c1a-9168-542ede3ce98f" }
  }
}

HTTP Headers

  • Retry-After - indicates how long to wait until performing another GET request

Links

  • self - GET points back to the same object

​
Retrieving a Lead List

Request

When the processing of the lead list has terminated, the results can be retrieved using the same url:

GET /lead-lists/{{id}} HTTP/1.1
Content-Type: application/json

Response

The response will display up to 100 results and will contain as much information as available about each lead, however there may be many fields that don’t have all information.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "81f63c2e-edbd-4c1a-9168-542ede3ce98f",
  "object": "lead_list",
  "name": "Example",
  "status": "completed",
  "shared": true,
  "visible": false,
  "owner": "user@example.com",
  "type": "linkedin",
  "options": {
    "reveal_phone_numbers": false,
    "validate_email": true,
    "enrich": true,
  },
  "leads": [
		{
      "id": "81f63c2e-edbd-4c1a-9168-542ede3ce98a",
      "object": "lead_list_entry",
      "email": "lead@company1.com",
      "person_id": "576ed970-a4c4-43a1-bdf0-154d1d9049ed",
      "linkedin_url": "https://www.linkedin.com/in/lead1/",
      "first_name": "Lead",
      "last_name": "One",
      "company_name": "Company 1",
      "company_domain": "company1.com",
      "industry": "Computer Software",
      "title": "CEO",
      "email_validation_result": {
        "object": "email_validation_result",
        "email": "lead@company1.com",
        "result": "deliverable",
        "catch_all": false
      },
      "data": {
        // other data fields
      }
    },
    {
      "id": "81f63c2e-edbd-4c1a-9168-542ede3ce98a",
      "object": "lead_list_entry",
      "email": "lead@company2.com",
      "person_id": "1dfe7176-5491-4e95-a20f-10ebac3c7c4b",
      "linkedin_url": "https://www.linkedin.com/in/jim-smith",
      "first_name": "Jim",
      "last_name": "Smith",
      "company_name": "Example, Inc",
      "company_domain": "example.com",
      "industry": "Computer Software",
      "title": "CTO",
      "email_validation_result": {
        "object": "email_validation_result",
        "email": "lead@company1.com",
        "result": "deliverable",
        "catch_all": false
      },
      "data": {
        // other data fields
      }
		},
		{
			"id": "6ba3394f-b0f2-44e0-86e0-f360a0a8dcec",
      "object": "lead_list_entry",
      "email": null,
      "person_id": null,
      "linkedin_url": "https://www.linkedin.com/in/nobody",
      "first_name": null,
      "last_name": null,
      "company_name": null,
      "company_domain": null,
      "industry": null,
      "title": null,
      "email_validation_result": null,
      "data": {
        // other data fields
      }
		}
	],
  "_links": {
    "self": { "href": "/lead-lists/81f63c2e-edbd-4c1a-9168-542ede3ce98f" },
    "prev": { "href": "/lead-lists/1?page[size]=100&page[before]=81f63c2e-edbd-4c1a-9168-542ede3ce98a" },
    "next": { "href": "/lead-lists/1?page[size]=100&page[after]=81f63c2e-edbd-4c1a-9168-542ede3ce98a" }
  }
}

If the list contains more than 100 entries, then pagination is required transverse them all and can be done using the links such as: response._links.next.href (e.g. GET /lead-lists/81f63c2e-edbd-4c1a-9168-542ede3ce98f?page[size]=100&page[after]=81f63c2e-edbd-4c1a-9168-542ede3ce98a).

Links

  • self - GET points back to the same object

  • next - GET points to the next page of entries, when available

  • prev - GET points to the previous page of entries, when available

​
List Lead Lists

Request

Retrieve a list of Lead Lists:

GET /lead-lists HTTP/1.1
Authorization: Bearer {{API Key}}

curl -X GET https://api.amplemarket.com/lead-lists \
	-H "Authorization: Bearer {{API Key}}"

Response

This will return a 200 OK with a list of Lead Lists:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "lead_lists": [
    {
      "id": "01937248-a242-7be7-9666-ba15a35d223d",
      "name": "Sample list 1",
      "status": "queued",
      "shared": false,
      "visible": true,
      "owner": "foo-23@email.com",
      "type": "linkedin"
    }
  ],
  "_links": {
    "self": {
      "href": "/lead-lists?page[size]=20"
    }
  }
}

​
Add Leads

Request

You can also append leads to a Lead List using the ID of the Lead List and the leads you want to add.

You can add up to 10,000 leads at a time. However, each Lead List can have a maximum of 20,000 leads.

When approaching this limit, new leads will be added partially until the limit is reached. When the limit is hit, a 409 HTTP status code will be returned.

Enriching, email validation, and reveal settings are inherited from the Lead List settings. If credits are spent, those will be deducted from the admin user of the account.

POST /lead-lists/{id}/leads HTTP/1.1
Content-Type: application/json

{
  "leads": [
    {
      "linkedin_url": "..."
    },
    {
      "linkedin_url": "..."
    }
  ]
}

Response

This will also return a 202 Accepted

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "total":2,
  "total_added_to_lead_list":2
}