Lead Lists - Amplemarket API

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:

POST /lead-lists/ with a list of LinkedIn URLs that will be processed and revealed
In the response, follow the URL provided in response._links.self.href
Continue polling the endpoint while respecting the Retry-After HTTP Header
When validation completes, the results are in response.results
If the results are larger than the default limit, then follow the URL provided in response._links.next.href

Lead List Object

Field	Type	Description
`id`	string	The ID of the Lead List
`name`	string	The name of the Lead List
`status`	string	The 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
`shared`	boolean	If the Lead List is shared across the Account
`visible`	boolean	If the Lead List is visible in the Dashboard
`owner`	string	The email of the owner of the Lead List
`options`	object	Options 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
`type`	string	The 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
`leads`	array of lead_list_entry	The entries of the Lead List; the default number of results that appear is up to 100
`_links`	array of links	Contains useful links related to this resource

Lead List Entry Object

Field	Type	Description
`id`	string	The ID of the entry
`email`	string	The email address of the entry
`person_id`	string	The ID of the Person matched with this entry
`linkedin_url`	string	The LinkedIn URL of the entry
`first_name`	string	The first name of the entry
`last_name`	string	The last name of the entry
`company_name`	string	The company name of the entry
`company_domain`	string	The company domain of the entry
`industry`	string	The industry of the entry
`title`	string	The title of the entry
`email_validation_result`	object of type email_validation_result	The result of the email validation if one occurred
`data`	object	Other 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
}

On this page

Lead List Object
Lead List Entry Object
Lead List Endpoints
Creating a new Lead List
Polling a Lead List
Retrieving a Lead List
List Lead Lists
Add Leads

Usually the flow for this is:

POST /lead-lists/ with a list of LinkedIn URLs that will be processed and revealed
In the response, follow the URL provided in response._links.self.href
Continue polling the endpoint while respecting the Retry-After HTTP Header
When validation completes, the results are in response.results
If the results are larger than the default limit, then follow the URL provided in response._links.next.href

Lead List Object

Field	Type	Description
`id`	string	The ID of the Lead List
`name`	string	The name of the Lead List
`status`	string	The 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
`shared`	boolean	If the Lead List is shared across the Account
`visible`	boolean	If the Lead List is visible in the Dashboard
`owner`	string	The email of the owner of the Lead List
`options`	object	Options 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
`type`	string	The 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
`leads`	array of lead_list_entry	The entries of the Lead List; the default number of results that appear is up to 100
`_links`	array of links	Contains useful links related to this resource

Lead List Entry Object

Field	Type	Description
`id`	string	The ID of the entry
`email`	string	The email address of the entry
`person_id`	string	The ID of the Person matched with this entry
`linkedin_url`	string	The LinkedIn URL of the entry
`first_name`	string	The first name of the entry
`last_name`	string	The last name of the entry
`company_name`	string	The company name of the entry
`company_domain`	string	The company domain of the entry
`industry`	string	The industry of the entry
`title`	string	The title of the entry
`email_validation_result`	object of type email_validation_result	The result of the email validation if one occurred
`data`	object	Other 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" }
  }
}

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
}

On this page

Lead List Object
Lead List Entry Object
Lead List Endpoints
Creating a new Lead List
Polling a Lead List
Retrieving a Lead List
List Lead Lists
Add Leads

​Lead List Object

​Lead List Entry Object

​Lead List Endpoints

​Creating a new Lead List

​Polling a Lead List

​Retrieving a Lead List

​List Lead Lists

​Add Leads

Webhooks

​Lead List Object

​Lead List Entry Object

​Lead List Endpoints

​Creating a new Lead List

​Polling a Lead List

​Retrieving a Lead List

​List Lead Lists

​Add Leads

Lead List Object

Lead List Entry Object

Lead List Endpoints

Creating a new Lead List

Polling a Lead List

Retrieving a Lead List

List Lead Lists

Add Leads

Lead List Object

Lead List Entry Object

Lead List Endpoints

Creating a new Lead List

Polling a Lead List

Retrieving a Lead List

List Lead Lists

Add Leads