> ## Documentation Index > Fetch the complete documentation index at: https://docs.amplemarket.com/llms.txt > Use this file to discover all available pages before exploring further. # People Search > Learn how to find the right people. 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 | ## 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: ```js theme={null} 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. ```js theme={null} 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 ```js theme={null} 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). ```js theme={null} 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. ```js theme={null} 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 ```js theme={null} 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). ```js theme={null} 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. ```js theme={null} 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](/api-reference/introduction#usage-limits), 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](#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](/api-reference/introduction#usage-limits). ```js theme={null} 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 } ``` ```bash theme={null} 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: ```js theme={null} 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: ```js theme={null} GET /people/enrichment-requests/{{id}} HTTP/1.1 Content-Type: application/json ``` ```bash theme={null} 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. ```js theme={null} 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: ```js theme={null} GET /people/enrichment-requests/1 HTTP/1.1 Content-Type: application/json ``` ```bash theme={null} curl https://api.amplemarket.com/people/enrichment-requests/{{id}} \ -H "Authorization: Bearer {{API Key}}" ``` **Response** The response will display up to 100 results: ```js theme={null} 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: ```js theme={null} PATCH /people/enrichment-requests/1 HTTP/1.1 Content-Type: application/json { "status": "canceled" } ``` ```bash theme={null} 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. ```js theme={null} 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" } } } ``` 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: ```js theme={null} 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. ```js theme={null} 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 } } ```