People Search

Matching against a Person in our database allows the retrieval of data associated with said Person.

Person Object

The Person object represents a b2b contact, typically associated with a company. Here is a description of the Person object:

Field	Type	Description
`id`	string	ID of the Person
`object`	string	Object type (always “person”)
`linkedin_url`	string	LinkedIn URL of the Person
`name`	string	Name of the Person
`email`	string	Email address of the Person
`first_name`	string	First name of the Person
`last_name`	string	Last name of the Person
`gender`	enum	Gender of the Person
`title`	string	Title of the Person
`headline`	string	Headline of the Person
`about`	string	About section of the Person
`current_position_start_date`	string	Start date of the Person’s current position
`current_position_description`	string	Description of the Person’s current position
`location`	string	Location of the Person
`image_url`	string	Image URL of the Person
`location_details`	object	Location details of the Person
`experiences`	array	Array of experience objects for the Person
`educations`	array	Array of education objects for the Person
`languages`	array	Array of language objects for the Person
`phone_numbers`	array	Array of phone number objects for the Person
`company`	Company object	Company the Person currently works for

Phone Number Object

Phone number objects appear in phone_numbers arrays across the API (e.g. on Person, Contact, and Lead List objects). Each entry has the following fields:

Field	Type	Description
`object`	string	Always `"phone_number"`
`id`	string	The ID of the phone number
`number`	string	The phone number in E.164-style format
`type`	string	Phone type (`mobile`, `office`, `phone`, `landline`, `voip`, `direct`)
`source`	string	Origin of the number (`amplemarket`, `crm`, `user_uploaded`)
`wrong_number`	boolean	`true` if the number was manually marked as wrong
`do_not_call`	boolean	`true` if DNC screening is enabled and the number is on a DNC list. Omitted when DNC screening is disabled for the account.

wrong_number - true when the number was manually marked as wrong. You can mark a number as wrong via POST /phone_numbers/{id}/review with reason: "wrong_number".
do_not_call - true when Do Not Call screening is enabled for your account and the number is on a DNC list. This field is omitted (not false) when DNC screening is disabled in account Safety settings.

Company Object

Here is the description of the Company object:

Field	Type	Description
`id`	string	Amplemarket ID of the Company
`object`	string	Object type (always “company”)
`name`	string	Name of the Company
`linkedin_url`	string	LinkedIn URL of the Company
`website`	string	Website of the Company
`overview`	string	Description of the Company
`logo_url`	string	Logo URL of the Company
`founded_year`	integer	Year the Company was founded
`traffic_rank`	integer	Traffic rank of the Company
`sic_codes`	array of integers	SIC codes of the Company
`naics_codes`	array of integers	NAICS codes of the Company
`type`	string	Type of the Company (Public Company, etc.)
`total_funding`	integer	Total funding of the Company
`latest_funding_stage`	string	Latest funding stage of the Company
`latest_funding_date`	string	Latest funding date of the Company
`keywords`	array of strings	Keywords of the Company
`estimated_number_of_employees`	integer	Estimated number of employees at the Company
`followers`	integer	Number of followers on LinkedIn
`size`	string	Self reported size of the Company
`industry`	string	Industry of the Company
`location`	string	Location of the Company
`location_details`	object	Location details of the Company
`locations`	array	Array of location objects for the Company
`is_b2b`	boolean	`true` if the Company has a B2B component
`is_b2c`	boolean	`true` if the Company has a B2C component
`technologies`	array of strings	Technologies detected for the Company
`department_headcount`	object	Headcount by department
`job_function_headcount`	object	Headcount by job function
`estimated_revenue`	string	The estimated annual revenue of the company
`revenue`	integer	The annual revenue of the company

People Endpoints

Finding a Person

Request The following endpoint can be used to find a Person on Amplemarket:

GET /people/find?linkedin_url=https://www.linkedin.com/in/person-1 HTTP/1.1
GET /people/find?email=person@example.com HTTP/1.1
GET /people/find?name=John%20Doe&title=CEO&company_name=Example HTTP/1.1
GET /people/find?name=John%20Doe&title=CEO&company_domain=example.com HTTP/1.1

Response The response contains the Linkedin URL of the Person along with the other relevant data.

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

{
  "id": "84d31ab0-bac0-46ea-9a8b-b8721126d3d6",
  "object": "person",
  "name": "Jonh Doe",
  "first_name": "Jonh",
  "last_name": "Doe",
  "linkedin_url": "https://www.linkedin.com/in/person-1",
  "title": "Founder and CEO",
  "headline": "CEO @ Company",
  "location": "San Francisco, California, United States",
  "company": {
    "id": "eec03d70-58aa-46e8-9d08-815a7072b687",
    "object": "company",
    "name": "A Company",
    "website": "https://company.com",
    "linkedin_url": "https://www.linkedin.com/company/company-1",
    "keywords": [
      "sales",
      "ai sales",
      "sales engagement"
    ],
    "estimated_number_of_employees": 500,
    "size": "201-500 employees",
    "industry": "Software Development",
    "location": "San Francisco, California, US",
    "is_b2b": true,
    "is_b2c": false,
    "technologies": ["Salesforce"]
  }
}

Revealing an email address

GET /people/find?linkedin_url=https://www.linkedin.com/in/person-1&reveal_email=true HTTP/1.1

Response The response contains the Linkedin URL of the Person along with the other relevant data and the revealed email address (if successful).

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

{
  "id": "84d31ab0-bac0-46ea-9a8b-b8721126d3d6",
  "object": "person",
  "name": "Jonh Doe",
  "first_name": "Jonh",
  "last_name": "Doe",
  "linkedin_url": "https://www.linkedin.com/in/person-1",
  "title": "Founder and CEO",
  "headline": "CEO @ Company",
  "location": "San Francisco, California, United States",
  "company": {
    "id": "eec03d70-58aa-46e8-9d08-815a7072b687",
    "object": "company",
    "name": "A Company",
    "website": "https://company.com",
    "linkedin_url": "https://www.linkedin.com/company/company-1",
    "keywords": [
      "sales",
      "ai sales",
      "sales engagement"
    ],
    "estimated_number_of_employees": 500,
    "size": "201-500 employees",
    "industry": "Software Development",
    "location": "San Francisco, California, US",
    "is_b2b": true,
    "is_b2c": false,
    "technologies": ["Salesforce"]
  },
  "email": "john.doe@company.com"
}

Response (Request Timeout) It is possible for the request to time out when revealing an email address, in this case the response will look like this.

HTTP/1.1 408 Request Timeout
Content-Type: application/json
Retry-After: 60

{
  "object": "error",
  "_errors": [
    {
      "code": "request_timeout",
      "title": "Request timeout"
      "detail": "We are processing your request, try again later."
    }
  ]
}

In this case you are free to retry the request after the specified time in the Retry-After header.

Revealing phone numbers

GET /people/find?linkedin_url=https://www.linkedin.com/in/person-1&reveal_phone_numbers=true HTTP/1.1

Response The response contains the Linkedin URL of the Person along with the other relevant data and the revealed phone numbers (if successful).

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

{
  "id": "84d31ab0-bac0-46ea-9a8b-b8721126d3d6",
  "object": "person",
  "name": "Jonh Doe",
  "first_name": "Jonh",
  "last_name": "Doe",
  "linkedin_url": "https://www.linkedin.com/in/person-1",
  "title": "Founder and CEO",
  "headline": "CEO @ Company",
  "location": "San Francisco, California, United States",
  "company": {
    "id": "eec03d70-58aa-46e8-9d08-815a7072b687",
    "object": "company",
    "name": "A Company",
    "website": "https://company.com",
    "linkedin_url": "https://www.linkedin.com/company/company-1",
    "keywords": [
      "sales",
      "ai sales",
      "sales engagement"
    ],
    "estimated_number_of_employees": 500,
    "size": "201-500 employees",
    "industry": "Software Development",
    "location": "San Francisco, California, US",
    "is_b2b": true,
    "is_b2c": false,
    "technologies": ["Salesforce"]
  },
  "phone_numbers": [
    {
      "object": "phone_number",
      "id": "84d31ab0-bac0-46ea-9a8b-b8721126d3d6",
      "number": "+1 123456789",
      "type": "mobile",
      "source": "amplemarket",
      "wrong_number": false,
      "do_not_call": true
    }
  ]
}

Response (Request Timeout) It is possible for the request to time out when revealing phone numbers, in this case the response will look like this.

HTTP/1.1 408 Request Timeout
Content-Type: application/json
Retry-After: 60

{
  "object": "error",
  "_errors": [
    {
      "code": "request_timeout",
      "title": "Request timeout"
      "detail": "We are processing your request, try again later."
    }
  ]
}

In this case you are free to retry the request after the specified time in the Retry-After header.

Finding multiple people

Enrichment requests allow you to retrieve comprehensive data about multiple people simultaneously. This bulk operation is ideal for enriching large lists of leads with detailed information including their current company, title, location, and optionally their email addresses and phone numbers. The enrichment request flow will usually follow these steps:

POST /people/enrichment-requests with a list of leads that will be enriched
In the response, follow the URL provided in response._links.self.href
Continue polling the endpoint while respecting the Retry-After HTTP Header
When enrichment 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

Enrichment Request Object

Field	Type	Description
`id`	integer	The ID of the enrichment request
`status`	string	The status of the enrichment request:
		`queued`: The enrichment request hasn’t started yet
		`processing`: The enrichment request is in-progress
		`completed`: The enrichment request terminated successfully
		`canceled`: The enrichment request terminated due to being canceled
		`error`: The enrichment request terminated with an error; see `_errors` for more details
`results`	array of enrichment_request_result	The enrichment results for the leads provided; default number of results range from 1 up to 100
`_links`	array of links	Contains useful links related to this resource
`_errors`	array of errors	Contains the errors if the operation fails

Enrichment Request Result Object

Field	Type	Description
`id`	integer	The ID of the enrichment result
`status`	string	The result of the enrichment:
		`enriched`: Successfully found and enriched the person
		`not_found`: Unable to find a matching person in the database
		`gdpr_removed`: The person data has been removed due to GDPR compliance
`result`	Person object	The enriched Person object (see Person Object)
`email`	string	The email address used to search for this person (if provided in the request)
`linkedin_url`	string	The LinkedIn URL used to search for this person (if provided in the request)
`company_domain`	string	The company domain used to search for this person (if provided in the request)
`company_name`	string	The company name used to search for this person (if provided in the request)
`name`	string	The person name used to search for this person (if provided in the request)
`title`	string	The person title used to search for this person (if provided in the request)

Start Enrichment Request

Request A batch of leads can be sent to the enrichment request service, up to 10,000 leads according to usage limits.

POST /people/enrichment-requests HTTP/1.1
Content-Type: application/json

{
  "leads": [
    {
      "linkedin_url": "https://www.linkedin.com/in/person-1"
    },
    {
      "email": "person@example.com"
    },
    {
      "name": "John Doe",
      "title": "CEO",
      "company_domain": "example.com"
    }
  ],
  "reveal_email": true,
  "reveal_phone_numbers": false
}

curl -X POST https://api.amplemarket.com/people/enrichment-requests \
	-H "Authorization: Bearer {{API Key}}" \
	-H "Content-Type: application/json" \
	-d '{
  "leads": [
    {"linkedin_url": "https://www.linkedin.com/in/person-1"},
    {"email": "person@example.com"}
  ]
}'

Request Parameters

Parameter	Type	Required	Description
`leads`	array	Yes	Array of lead objects to enrich (max 100,000)
`reveal_email`	boolean	No	Whether to reveal email addresses for the enriched people (consumes additional credits)
`reveal_phone_numbers`	boolean	No	Whether to reveal phone numbers for the enriched people (consumes additional credits)

Lead Object Properties Each lead object can contain one or more of the following identifiers:

Property	Type	Description
`email`	string	Email address of the person
`linkedin_url`	string	LinkedIn URL of the person
`company_domain`	string	Company domain (used with `name` and/or `title`)
`company_name`	string	Company name (used with `name` and/or `title`)
`name`	string	Full name of the person
`title`	string	Job title of the person

Response This will return a 202 Accepted indicating that the enrichment request will soon be started:

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /people/enrichment-requests/1

{
  "id": 1,
  "object": "person_enrichment",
  "status": "queued",
  "results": [],
  "_links": {
    "self": {
      "href": "/people/enrichment-requests/1"
    }
  }
}

HTTP Headers

Location: GET points back to the enrichment request object that was created

Links

self - GET points back to the enrichment request object that was created

Enrichment Request Polling

Request The Enrichment Request object can be polled in order to receive results:

GET /people/enrichment-requests/{{id}} HTTP/1.1
Content-Type: application/json

curl https://api.amplemarket.com/people/enrichment-requests/{{id}} \
	-H "Authorization: Bearer {{API Key}}"

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": 1,
  "object": "person_enrichment",
  "status": "processing",
  "results": [],
  "_links": {
    "self": {
      "href": "/people/enrichment-requests/1"
    }
  }
}

HTTP Headers

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

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

Retrieving Enrichment Request Results

Request When the enrichment request has terminated, the results can be retrieved using the same url:

GET /people/enrichment-requests/1 HTTP/1.1
Content-Type: application/json

curl https://api.amplemarket.com/people/enrichment-requests/{{id}} \
	-H "Authorization: Bearer {{API Key}}"

Response The response will display up to 100 results:

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

{
  "id": 1,
  "object": "person_enrichment",
  "status": "completed",
  "results": [
    {
      "id": 1,
      "linkedin_url": "https://www.linkedin.com/in/person-1",
      "status": "enriched",
      "result": {
        "id": "84d31ab0-bac0-46ea-9a8b-b8721126d3d6",
        "object": "person",
        "name": "John Doe",
        "first_name": "John",
        "last_name": "Doe",
        "linkedin_url": "https://www.linkedin.com/in/person-1",
        "title": "Founder and CEO",
        "headline": "CEO @ Company",
        "location": "San Francisco, California, United States",
        "location_details": {
          "city": "San Francisco",
          "state": "California",
          "country": "United States"
        },
        "current_position_start_date": "2020-01-01",
        "image_url": "https://example.com/image.jpg",
        "gender": "male",
        "company": {
          "id": "eec03d70-58aa-46e8-9d08-815a7072b687",
          "object": "company",
          "name": "A Company",
          "website": "https://company.com",
          "linkedin_url": "https://www.linkedin.com/company/company-1",
          "keywords": [
            "sales",
            "ai sales",
            "sales engagement"
          ],
          "estimated_number_of_employees": 500,
          "size": "201-500 employees",
          "industry": "Software Development",
          "location": "San Francisco, California, US",
          "is_b2b": true,
          "is_b2c": false,
          "technologies": [
            "Salesforce"
          ]
        }
      }
    },
    {
      "id": 2,
      "email": "person@example.com",
      "status": "enriched",
      "result": {
        "id": "94e42bc1-cad1-57fb-ba9c-c9832237e4e7",
        "object": "person",
        "name": "Jane Smith",
        "first_name": "Jane",
        "last_name": "Smith",
        "linkedin_url": "https://www.linkedin.com/in/person-2",
        "email": "person@example.com",
        "title": "VP of Engineering",
        "headline": "VP Engineering @ Tech Co",
        "location": "New York, New York, United States",
        "location_details": {
          "city": "New York",
          "state": "New York",
          "country": "United States"
        },
        "current_position_start_date": "2019-06-15",
        "image_url": "https://example.com/image2.jpg",
        "gender": "female",
        "company": {
          "id": "ffd04e81-69bb-57f9-a019-816a8183c798",
          "object": "company",
          "name": "Tech Co",
          "website": "https://techco.com",
          "linkedin_url": "https://www.linkedin.com/company/techco",
          "keywords": [
            "technology",
            "saas"
          ],
          "estimated_number_of_employees": 250,
          "size": "201-500 employees",
          "industry": "Technology",
          "location": "New York, NY, US",
          "is_b2b": true,
          "is_b2c": false,
          "technologies": [
            "AWS",
            "React"
          ]
        }
      }
    }
  ],
  "_links": {
    "self": {
      "href": "/people/enrichment-requests/1"
    },
    "next": {
      "href": "/people/enrichment-requests/1?page[size]=100&page[after]=2"
    },
    "prev": {
      "href": "/people/enrichment-requests/1?page[size]=100&page[before]=1"
    }
  }
}

If the results contain more than 100 entries, then pagination is required to traverse them all and can be done using the links such as: response._links.next.href (e.g. GET /people/enrichment-requests/1?page[size]=100&page[after]=2). 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

Cancelling a running Enrichment Request

Request You can cancel an enrichment request that’s still running by sending a PATCH request:

PATCH /people/enrichment-requests/1 HTTP/1.1
Content-Type: application/json

{
  "status": "canceled"
}

curl -X PATCH https://api.amplemarket.com/people/enrichment-requests/{{id}} \
	-H "Authorization: Bearer {{API Key}}" \
	-H "Content-Type: application/json" \
	-d '{"status": "canceled"}'

Only "status" is supported in this request, any other field will be ignored. Response The response will display any available results up until the point the enrichment request was canceled.

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

{
  "id": 1,
  "object": "person_enrichment",
  "status": "canceled",
  "results": [
    {
      "id": 1,
      "linkedin_url": "https://www.linkedin.com/in/person-1",
      "status": "enriched",
      "result": {
        "id": "84d31ab0-bac0-46ea-9a8b-b8721126d3d6",
        "object": "person",
        "name": "John Doe",
        "first_name": "John",
        "last_name": "Doe",
        "linkedin_url": "https://www.linkedin.com/in/person-1",
        "title": "Founder and CEO",
        "headline": "CEO @ Company",
        "location": "San Francisco, California, United States",
        "company": {
          "id": "eec03d70-58aa-46e8-9d08-815a7072b687",
          "object": "company",
          "name": "A Company"
        }
      }
    }
  ],
  "_links": {
    "self": {
      "href": "/people/enrichment-requests/1"
    },
    "next": {
      "href": "/people/enrichment-requests/1?page[size]=100&page[after]=1"
    }
  }
}

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

Searching for multiple People

The following endpoint can be used to search for multiple People on Amplemarket:

POST /people/search HTTP/1.1
Content-Type: application/json

{
  "person_name": "Jonh Doe",
  "person_titles": ["CEO"],
  "person_locations": ["San Francisco, California, United States"],
  "company_names": ["A Company"],
  "page": 1,
  "page_size": 10
}

Response The response contains the Linkedin URL of the Person along with the other relevant data.

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

{
  "object": "person_search_result",
  "results": [
    {
      "id": "84d31ab0-bac0-46ea-9a8b-b8721126d3d6",
      "object": "person",
      "name": "Jonh Doe",
      "first_name": "Jonh",
      "last_name": "Doe",
      "linkedin_url": "https://www.linkedin.com/in/person-1",
      "title": "Founder and CEO",
      "headline": "CEO @ Company",
      "location": "San Francisco, California, United States",
      "company": {
        "id": "eec03d70-58aa-46e8-9d08-815a7072b687",
        "object": "company",
        "name": "A Company",
        "website": "https://company.com",
        "linkedin_url": "https://www.linkedin.com/company/company-1",
        "keywords": [
          "sales",
          "ai sales",
          "sales engagement"
        ],
        "estimated_number_of_employees": 500,
        "size": "201-500 employees",
        "industry": "Software Development",
        "location": "San Francisco, California, US",
        "is_b2b": true,
        "is_b2c": false,
        "technologies": ["Salesforce"]
      }
    }
  ],
  "_pagination": {
    "page": 1,
    "page_size": 1,
    "total_pages": 1,
    "total": 1
  }
}

Home

Guides

Person Object

Phone Number Object

Company Object

People Endpoints

Finding a Person

Revealing an email address

Revealing phone numbers

Finding multiple people

Enrichment Request Object

Enrichment Request Result Object

Start Enrichment Request

Enrichment Request Polling

Retrieving Enrichment Request Results

Cancelling a running Enrichment Request

Searching for multiple People

​Person Object

​Phone Number Object

​Company Object

​People Endpoints

​Finding a Person

​Revealing an email address

​Revealing phone numbers

​Finding multiple people

​Enrichment Request Object

​Enrichment Request Result Object

​Start Enrichment Request

​Enrichment Request Polling

​Retrieving Enrichment Request Results

​Cancelling a running Enrichment Request

​Searching for multiple People

Person Object

Phone Number Object

Company Object

People Endpoints

Finding a Person

Revealing an email address

Revealing phone numbers

Finding multiple people

Enrichment Request Object

Enrichment Request Result Object

Start Enrichment Request

Enrichment Request Polling

Retrieving Enrichment Request Results

Cancelling a running Enrichment Request

Searching for multiple People