Skip to main content
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:
FieldTypeDescription
idstringID of the Person
objectstringObject type (always “person”)
linkedin_urlstringLinkedIn URL of the Person
namestringName of the Person
emailstringEmail address of the Person
first_namestringFirst name of the Person
last_namestringLast name of the Person
genderenumGender of the Person
titlestringTitle of the Person
headlinestringHeadline of the Person
aboutstringAbout section of the Person
current_position_start_datestringStart date of the Person’s current position
current_position_descriptionstringDescription of the Person’s current position
locationstringLocation of the Person
image_urlstringImage URL of the Person
location_detailsobjectLocation details of the Person
experiencesarrayArray of experience objects for the Person
educationsarrayArray of education objects for the Person
languagesarrayArray of language objects for the Person
phone_numbersarrayArray of phone number objects for the Person
companyCompany objectCompany the Person currently works for

​
Company Object

Here is the description of the Company object:
FieldTypeDescription
idstringAmplemarket ID of the Company
objectstringObject type (always “company”)
namestringName of the Company
linkedin_urlstringLinkedIn URL of the Company
websitestringWebsite of the Company
overviewstringDescription of the Company
logo_urlstringLogo URL of the Company
founded_yearintegerYear the Company was founded
traffic_rankintegerTraffic rank of the Company
sic_codesarray of integersSIC codes of the Company
naics_codesarray of integersNAICS codes of the Company
typestringType of the Company (Public Company, etc.)
total_fundingintegerTotal funding of the Company
latest_funding_stagestringLatest funding stage of the Company
latest_funding_datestringLatest funding date of the Company
keywordsarray of stringsKeywords of the Company
estimated_number_of_employeesintegerEstimated number of employees at the Company
followersintegerNumber of followers on LinkedIn
sizestringSelf reported size of the Company
industrystringIndustry of the Company
locationstringLocation of the Company
location_detailsobjectLocation details of the Company
locationsarrayArray of location objects for the Company
is_b2bbooleantrue if the Company has a B2B component
is_b2cbooleantrue if the Company has a B2C component
technologiesarray of stringsTechnologies detected for the Company
department_headcountobjectHeadcount by department
job_function_headcountobjectHeadcount by job function
estimated_revenuestringThe estimated annual revenue of the company
revenueintegerThe 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": "[email protected]"
}
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"
    }
  ]
}
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:
  1. POST /people/enrichment-requests with a list of leads that will be enriched
  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 enrichment 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

​
Enrichment Request Object

FieldTypeDescription
idintegerThe ID of the enrichment request
statusstringThe 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
resultsarray of enrichment_request_resultThe enrichment results for the leads provided; default number of results range from 1 up to 100
_linksarray of linksContains useful links related to this resource
_errorsarray of errorsContains the errors if the operation fails

​
Enrichment Request Result Object

FieldTypeDescription
idintegerThe ID of the enrichment result
statusstringThe 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
resultPerson objectThe enriched Person object (see Person Object)
emailstringThe email address used to search for this person (if provided in the request)
linkedin_idstringThe LinkedIn ID used to search for this person (if provided in the request)
company_domainstringThe company domain used to search for this person (if provided in the request)
company_namestringThe company name used to search for this person (if provided in the request)
namestringThe person name used to search for this person (if provided in the request)
titlestringThe 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_id": "person-linkedin-1"
    },
    {
      "email": "[email protected]"
    },
    {
      "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_id": "person-linkedin-1"},
    {"email": "[email protected]"}
  ]
}'
Request Parameters
ParameterTypeRequiredDescription
leadsarrayYesArray of lead objects to enrich (max 100,000)
reveal_emailbooleanNoWhether to reveal email addresses for the enriched people (consumes additional credits)
reveal_phone_numbersbooleanNoWhether 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:
PropertyTypeDescription
emailstringEmail address of the person
linkedin_idstringLinkedIn ID of the person
company_domainstringCompany domain (used with name and/or title)
company_namestringCompany name (used with name and/or title)
namestringFull name of the person
titlestringJob 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_id": "person-linkedin-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": "[email protected]",
      "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": "[email protected]",
        "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_id": "person-linkedin-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"
    }
  }
}
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]=1). 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

​
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
  }
}