People (Contact) APIs
Use the API playground at https://api.salesintel.io to test the API request and response patterns.
Retrieve contacts matching filter parameters
GET
https://api.circleback.com/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 US state abbreviations |
company_location_zipcodes | String | Comma-separated list of US ZIP codes |
company_location_zipcodes_distance | Long | Radius (in miles) from provided ZIP codes |
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 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 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 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 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 |
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 for accepted enums. |
job_departments | String | Comma-separated set of values identifying the department/function for which the contact works. See below 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 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
200: OK
To see the full response, use the playground at https://api.salesintel.io
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.
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.
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
Last updated