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

200: OK

To see the full response, use the playground at https://api.salesintel.io

401: Unauthorized

401: Unauthorized

You have not included your credentials properly in your request

402: Payment Required

402: Payment Required

You do not have enough credits to return any/all of your request

403: Forbidden

403: Forbidden

Your account does not have the necessary permissions to access this service

500: Internal Server Error

500: Internal Server Error

There may be an outage on the SalesIntel side. If the error persists, please contact us.

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.

Response Model

{
  "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"
}

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