Skip to main content
POST

Authorizations

Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Scopes

publicAPI.v1.all

Public API v1

Body

application/json
searchResultIds
string[]

Array of search result IDs obtained from a prior /search/contacts call. Each ID triggers a contact research request, charged for the components it researches (see researchTypes and Credits). Intended as an alternative to the contacts property; if both are sent, their combined length must not exceed 500.

Maximum array length: 500
Example:
isJobChange
boolean
default:false

When set to true, triggers a job change research for the provided contacts. Must be used together with the contacts array; cannot be used with searchResultIds.

Example:

false

contacts
object[]

Contact enrich request. Provide an array of contacts to research by identity. Each item must include one of the following combinations:

  • contactName and companyName (optionally include title when using isJobChange)
  • contactName and domain
  • email
  • liProfileUrl
  • liSalesNavUrl
  • liRecruiterUrl

Intended as an alternative to searchResultIds; if both are sent, their combined length must not exceed 500. When isJobChange is true, only the contacts array should be used. Each contact is charged the same way as a searchResultId.

Maximum array length: 500
listIds
integer[]

IDs of the contact lists to add each newly saved contact to. Contacts that were already researched are not saved again, so they are not added to the lists. The lists must already belong to the authenticated user; an unknown ID fails the research request items, which report the error when you poll for them.

Maximum array length: 50
Example:
skipDeduplicationCheck
boolean
default:false

When true, research skips both duplicate checks and researches the record again, which charges credits again. By default a request is reported as duplicate when the same record was researched in the last few minutes, and as contact-already-researched when the contact is already saved in your My Contacts. Within those few minutes, a request for contact data the earlier research didn't get (for example phone after an email-only research) is researched onto that contact instead, and only the new data is charged. Repeated IDs within a single request are always collapsed into one research request.

researchTypes
enum<string>[]

Optional. Defaults to ["email", "phone"], or to the user's Contact Data setting if it's set to emails or phones only. Applies to every contact in the request, including contact details and job changes.

Send ["email"], ["phone"], or ["email", "phone"] (Full Contact). Order doesn't matter, duplicates are removed, and null is the same as leaving it out.

Each component is charged at its price. See Credits for the default prices, custom pricing and refunds.

Rejected with:

  • 400 invalidArguments when it isn't a non-empty array of email and/or phone
  • 403 fullContactRequired when your organization's Contact Data is locked to Full Contact and you send one component
  • 403 component-disabled-for-org when your organization disabled a component you sent
  • 403 variable-credits-disabled when your account isn't on component-based pricing and you send one component
Minimum array length: 1
Available options:
email,
phone
Example:

Response

The request IDs for research

success
boolean

Indicates whether the research request was accepted successfully.

Example:

true

requestIds
string[]

Array of request IDs corresponding to each contact research request. Use these IDs to poll for results via /contacts/research/poll.

Maximum array length: 500
Example: