Skip to main content
GET
List contacts
Find a contact before enrichment or campaign assignment. Combine the query parameters below to narrow your results. Location filters use the contact’s recorded profile location. Search by country name with country, a case-insensitive two-letter ISO code with countryCode, or a state, province, county, or region with region. Country codes map to country names, so contacts recorded without a country code remain searchable. When both are supplied, country takes precedence over countryCode. Use email or a complete socialUrl to check whether a contact already exists. Email matching ignores case and surrounding whitespace. Supported profile URLs use the same canonical form as contact imports, ignoring tracking parameters and trailing slashes. Use firstName and lastName for name searches, and minYearsInCurrentRole and maxYearsInCurrentRole for tenure at the current company. Search results can briefly lag contact updates.

Continue through results

Use page for the first 100 pages. Continue larger result sets by passing the returned nextCursor as cursor on the next request. Set includeTotal=true when you need a matching count. An empty result then returns total: 0; the default response returns total: null. Rate limit: 120 requests/minute per endpoint and workgroup; 60 when requesting totals. Details.

Authorizations

x-api-key
string
header
required

Primary public authentication method. Create keys in Jobin.cloud under Workgroups > Integrations > Custom integration.

Query Parameters

email
string<email>

Filter contacts by work, private, or other email.

Maximum string length: 320
firstName
string

Search contacts by their structured first-name value.

Required string length: 2 - 256
lastName
string

Search contacts by structured last-name value. Combine with firstName when both values are known for the most selective contact lookup.

Required string length: 2 - 256
phone
string

Search contacts by work, private, mobile, or other phone number fields. The endpoint matches exact stored values, normalized E.164 variants when derivable, and digit-only partials. Pass the most specific number available; the value must contain at least 6 digits.

Required string length: 6 - 64
socialUrl
string<uri>

Filter contacts by profile URL or identifier.

Maximum string length: 2048
campaignId
string

Filter contacts assigned to a campaign/sequence.

Pattern: ^[a-fA-F0-9]{24}$
tagIds
string[]

Filter contacts by one or more tag ids. Repeat the parameter or pass comma-separated ids. Contacts matching any supplied tag are returned.

Maximum array length: 50
Pattern: ^[a-fA-F0-9]{24}$
roleTitle
string

Filter contacts by current or previous role title text.

Required string length: 2 - 256
city
string

Filter by city in the candidate's recorded profile location.

Required string length: 2 - 256
region
string

Filter by state, province, county, or region in the candidate's recorded profile location.

Required string length: 2 - 256
country
string

Filter by country name in the candidate's recorded profile location.

Required string length: 2 - 256
countryCode
string

Filter by the recorded profile location's two-letter ISO country code. Case-insensitive.

Required string length: 2
minYearsInCurrentRole
number

Minimum current-company tenure in years. Recently updated contacts can briefly lag in search results.

Required range: 0 <= x <= 80
maxYearsInCurrentRole
number

Maximum current-company tenure in years. Recently updated contacts can briefly lag in search results.

Required range: 0 <= x <= 80
cursor
string

Opaque cursor returned as nextCursor from a previous list response. Use this to continue beyond page 100.

Maximum string length: 512
includeTotal
boolean
default:false

Include the matching contact count. Defaults to false; when enabled, an empty result returns total: 0.

page
integer
default:1

One-based result page. Page-number pagination is capped at 100; use nextCursor as the cursor query parameter to continue beyond page 100.

Required range: 1 <= x <= 100
limit
integer
default:25

Maximum contacts to return per page.

Required range: 1 <= x <= 100

Response

Paged contacts

items
object[]
page
integer
limit
integer
nextCursor
string | null

Opaque cursor for the next page, or null when no more contacts are available.

total
integer | null

Matching contact count, including zero when no contacts match. The response returns null unless includeTotal is true.