# People (Contact) APIs Use the API playground at to test the API request and response patterns. ## Retrieve contacts matching filter parameters `GET` `https://api.salesintel.io/service/people[/preview]` You can also use this endpoint to append information to identified contacts, using the email parameter to specify the contact. If you use the email field, you should leave other fields empty. Email is preferred because it is a unique, unambiguous identifier. If you do not have an email address, consider combinations of first\_name, last\_name, and company domain to help find the contact. The SalesIntel team can help you refine your strategy to ensure best match. If you are making a request that could yield multiple contacts and you aren't sure which ones you ultimately want to pay for, use the `/service/people/preview` endpoint first. This endpoint provides contact name, company, and job title, along with masked contact information, but does not take credits. Once your target contacts are identified use the `/service/people` endpoint along with the match\_ids of the identified contacts to return just those contacts. The response set is paginated, with up to 50 records per page. You are charged credits based on the number of records on the pages accessed. If you only retrieve the first page of results out of 10, at a page size of 50, you will be charged for 50 records. The page size is adjustable. Regardless of page size, you can only paginate 10,000 records deep in any given results set. ## Query Parameters | Name | Type | Description | | ------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | company\_domain | String | Comma-separated list of domains | | company\_industries | String | Obsolete | | company\_location\_states | String | Comma-separated list of state/region abbreviations (ISO standard) | | company\_location\_zipcodes | String | Comma-separated list of ZIP/postal codes | | company\_location\_zipcodes\_distance | Long | Radius (in miles) from provided ZIP codes (US only) | | company\_max\_revenue | Integer | Maximum annual revenue (in millions) | | company\_max\_size | Integer | Maximum company employee size | | company\_min\_revenue | Integer | Minimum annual revenue (in millions) | | company\_min\_size | Integer | Minimum company employee size | | company\_naics\_codes | String | Comma-separated list of NAICS codes | | company\_name | String | Comma-separated list of names; names are not case-sensitive and are matched using "contains" | | company\_sic\_codes | String | Comma-separated list of SIC codes | | is\_international | Boolean | Person is located in the US (false) or outside of the US (true). Without this parameter, you may return multiples of the same organization based in different countries | | location\_country\_codes | String | Comma-separated list of ISO alpha-2 country codes | | specialties | String | Comma-separated list of keywords that describe a company | | tech\_category | String | Tilda (\~) - separated lists of technographic categories in use by the company (this filter requires add-on permissions; use the [technologies taxonomy API](https://developer.salesintel.io/salesintel-api-documentation/technographic-apis#retrieve-the-category-subcategory-technology-taxonomy) to identify supported categories) | | tech\_subcategory | String | Tilda (\~) - separated lists of technographic sub-categories in use by the company (this filter requires add-on permissions; use the [technologies taxonomy API](https://developer.salesintel.io/salesintel-api-documentation/technographic-apis#retrieve-the-category-subcategory-technology-taxonomy) to identify supported sub-categories) | | tech\_product | String | Tilda (\~) - separated lists of technographic products in use by the company (this filter requires add-on permissions; use the [technologies taxonomy API](https://developer.salesintel.io/salesintel-api-documentation/technographic-apis#retrieve-the-product-vendor-technology-taxonomy) to identify supported products) | | tech\_vendor | String | Tilda (\~) - separated lists of technographic vendors in use by the company (this filter requires add-on permissions; use the [technologies taxonomy API](https://developer.salesintel.io/salesintel-api-documentation/technographic-apis#retrieve-the-product-vendor-technology-taxonomy) to identify supported vendors) | | verified | Boolean | Company details are human verified (true) or machine verified (false). Without this parameter, you may return multiples of the same organization | | page | Integer | Page number | | page\_size | Integer | If not specified, the default page size is 50 records | | sort\_by | String | Sort field, either company\_name or company\_location | | sort\_direction | String | Sort direction, either asc or desc | | email | String | Comma-separated list of email addresses; email addresses match to work or personal emails | | first\_name | String | Contact first name | | job\_title | String | Comma-separated set of job titles or keywords; titles are not case-sensitive and are matched using "contains" | | job\_levels | String | Comma-separated set of values identifying the level/seniority of the contact. [See below](#enums) for accepted enums. | | job\_departments | String | Comma-separated set of values identifying the department/function for which the contact works. [See below](#enums) for accepted enums. | | last\_name | String | Contact last name | | matchOnJobHistory | Boolean | Used in conjunction with email; when not used, it is assumed to be true and email will be matched to past and current job positions | | match\_ids | String | Comma-separated list of SalesIntel contact match ids; typically used to cherry-pick contacts from a preview response when making a credited search request for just those contacts | | required\_fields | String | Used to specify that contacts must contain certain data elements to be returned. Elements use the AND operator, so if multiple elements are specified, all must be present. [See below](#enums) for accepted enums. | | is\_ev\_contact | Boolean | Contact's email is verified but contact may otherwise be machine verified. Use with the *verified* parameter to surface non-verified contacts with emails. All human verified contacts are email verified regardless of this field value. | | linkedin\_url | String | Contact linkedin url; expects a full url format, not the token or identifier in the url | | mobile\_phone | String | Mobile phone number with no formatting, such as 5555555555. In North America, no country code is required | ## Headers | Name | Type | Description | | --------------------------------------------- | ------ | ---------------- | | X-CB-ApiKey\* | | {your API key} | | Accept\* | String | application/json | ## Response {% tabs %} {% tab title="200: OK" %} 200: OK To see the full response, use the playground at {% endtab %} {% tab title="401: Unauthorized" %} 401: Unauthorized You have not included your credentials properly in your request {% endtab %} {% tab title="402: Payment Required " %} 402: Payment Required You do not have enough credits to return any/all of your request {% endtab %} {% tab title="403: Forbidden" %} 403: Forbidden Your account does not have the necessary permissions to access this service {% endtab %} {% tab title="500: Internal Server Error" %} 500: Internal Server Error There may be an outage on the SalesIntel side. If the error persists, please contact us. {% endtab %} {% endtabs %} {% hint style="danger" %} If your SalesIntel plan includes different pricing for Append vs Net-New contacts, you must include `email` or one of either `first_name` or `last_name` in your paid endpoint request. If a personal identifier is not included in your paid request, any records will be invoiced as net-new. A match\_id from a `/preview` request is not a sufficient personal identifier. {% endhint %} {% hint style="info" %} Be sure to review the `verified` param to ensure that the contacts returned meet your accuracy requirements. For requests that may return multiple contacts, consider using the `/preview` route to ensure that you are satisfied with the contact set being returned before using the credited route. {% endhint %} {% code title="Response Model" %} ```json { "aggregations": {}, "batch_id": {}, "error": "string", "is_preview": true, "page": 0, "page_size": 0, "result_count": 0, "search_results": [ { "_score": {}, "addresses": [ { "city": "string", "country": "string", "is_hq": true, "location_id": 0, "state": "string", "street_1": "string", "street_2": "string", "type": "string", "zip": "string" } ], "cds_batch_id": {}, "company": { "actual_revenue": 0, "domains": [ "string" ], "id": 0, "linkedin_url": "string", "naics_codes": [ "string" ], "name": "string", "predicted_revenue": 0, "revenue": 0, "revenue_range": "string", "sic_codes": [ "string" ], "size": 0, "size_range": "string" }, "company_actual_revenue": 0, "company_domains": [ "string" ], "company_id": 0, "company_name": "string", "company_predicted_revenue": 0, "company_revenue": 0, "company_revenue_range": "string", "company_score": {}, "company_size": 0, "company_size_range": "string", "company_status": {}, "dates": { "created_date": "string", "last_modified_date": "string" }, "display_name": "string", "doc_id": "string", "email": "string", "email_hash": "string", "firmographic": {}, "first_name": "string", "industry": "string", "intent": {}, "is_executive": true, "is_international": true, "job_department": "string", "job_level": "string", "job_title": "string", "last_name": "string", "linkedin_url": {}, "location": "string", "location_type": {}, "locations": {}, "logo_url": {}, "match_id": "string", "naics_code": "string", "other_emails": [ "string" ], "person_id": 0, "personal_addresses": [ { "city": "string", "country": "string", "is_hq": true, "location_id": 0, "state": "string", "street_1": "string", "street_2": "string", "type": "string", "zip": "string" } ], "personal_email": "string", "personal_email_hash": "string", "phone_numbers": [ { "country_code": "string", "hash": "string", "type": "string", "value": "string" } ], "position_location_hashid": "string", "position_location_id": 0, "prefix": "string", "primary_country": {}, "primary_domain": {}, "primary_name": {}, "relations": {}, "revenue_range": "string", "sector": "string", "sic_code": "string", "size_range": "string", "social_profiles": [ { "type": "string", "url": "string" } ], "specialties": {}, "status_reason": {}, "suffix": "string", "tags": {}, "technographics": {}, "tier": 0, "tier_counts": {}, "topics": [ { "category": "string", "topic_id": 0, "topic_name": "string" } ], "verified": true } ], "sort_by": "string", "sort_direction": "string", "took": 0, "total_count": 0, "tracking_id": "string" } ``` {% endcode %} ## Enums ### Job Departments fnad - Finance/Administrative hr - Human Resources it\_is - IT lgl - Legal mrkt - Marketing ops - Operations prc - Procurement enrd - Engineering/R\&D sale - Sales/CS/Support other - All Other ### Job Levels brd - Board Member chf - C-Level vp - Vice President dir - Director mgr - Manager stf - other ### Required Fields address - any address phone - any phone number direct\_phone - any direct line including work or mobile any\_mobile - a mobile number personal\_email - a personal email address linkedin\_url - a linkedin profile url job\_title - a job title ## Response Reference ### All Available Phone Type Values work\_hq work\_branch work mobile ### All Available Social Type Values linkedin facebook twitter