List Contacts

List contacts

curl --request GET \
  --url https://my.jobin.cloud/api/openapi/v1/contacts \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://my.jobin.cloud/api/openapi/v1/contacts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "items": [
    {
      "id": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "firstName": "<string>",
      "middleName": "<string>",
      "lastName": "<string>",
      "workEmail": "<string>",
      "privateEmail": "<string>",
      "otherEmails": [
        "<string>"
      ],
      "workPhone": "<string>",
      "privatePhone": "<string>",
      "otherPhones": [
        "<string>"
      ],
      "workMobilePhone": "<string>",
      "privateMobilePhone": "<string>",
      "otherMobilePhones": [
        "<string>"
      ],
      "socialUrls": [
        "<string>"
      ],
      "currentTitle": "<string>",
      "currentCompany": "<string>",
      "currentCompanyFrom": "2023-11-07T05:31:56Z",
      "currentCompanyTo": "2023-11-07T05:31:56Z",
      "currentCompanyTenureYears": 123,
      "currentCompanyUrl": "<string>",
      "currentCompanySocialUrl": "<string>",
      "location": {
        "fullAddress": "<string>",
        "address": "<string>",
        "addressLine2": "<string>",
        "city": "<string>",
        "state": "<string>",
        "region": "<string>",
        "country": "<string>",
        "countryCode": "<string>",
        "postalCode": "<string>"
      },
      "industry": "<string>",
      "seniority": "<string>",
      "managementLevel": "<string>",
      "previousTitle": "<string>",
      "previousCompany": "<string>",
      "previousCompanySocialUrl": "<string>",
      "headline": "<string>",
      "summary": "<string>",
      "openProfile": true,
      "openToWork": true,
      "connectionLevels": [
        {
          "jobinUser": {
            "id": "<string>",
            "firstName": "<string>",
            "lastName": "<string>"
          },
          "connectionLevel": "1st"
        }
      ],
      "currentCampaign": {
        "campaignId": "<string>",
        "stagePositionCode": "<string>"
      },
      "tags": [
        {
          "_id": "<string>",
          "value": "<string>",
          "iconName": "<string>",
          "color": "<string>"
        }
      ],
      "skills": [
        {
          "value": "<string>",
          "skillType": "<string>",
          "level": 123,
          "topSkill": true
        }
      ],
      "education": [
        {
          "school": "<string>",
          "schoolSocialUrl": "<string>",
          "degreeLevel": "<string>",
          "degrees": [
            "<string>"
          ],
          "fieldOfStudy": "<string>",
          "majors": [
            "<string>"
          ],
          "minors": [
            "<string>"
          ],
          "period": {
            "from": "2023-11-07T05:31:56Z",
            "to": "2023-11-07T05:31:56Z",
            "isCurrent": true
          }
        }
      ],
      "experiences": [
        {
          "title": "<string>",
          "company": "<string>",
          "from": "2023-11-07T05:31:56Z",
          "to": "2023-11-07T05:31:56Z",
          "isCurrent": true,
          "location": {
            "fullAddress": "<string>",
            "address": "<string>",
            "addressLine2": "<string>",
            "city": "<string>",
            "state": "<string>",
            "region": "<string>",
            "country": "<string>",
            "countryCode": "<string>",
            "postalCode": "<string>"
          },
          "employmentType": "<string>",
          "description": "<string>"
        }
      ],
      "languages": [
        {
          "value": "<string>",
          "level": 123,
          "note": "<string>"
        }
      ],
      "volunteering": [
        {
          "roleTitle": "<string>",
          "organization": {
            "name": "<string>",
            "socialUrl": "<string>",
            "companyWebsite": "<string>",
            "employeeCountRange": "<string>"
          },
          "cause": "<string>",
          "description": "<string>",
          "location": {
            "fullAddress": "<string>",
            "address": "<string>",
            "addressLine2": "<string>",
            "city": "<string>",
            "state": "<string>",
            "region": "<string>",
            "country": "<string>",
            "countryCode": "<string>",
            "postalCode": "<string>"
          },
          "period": {
            "from": "2023-11-07T05:31:56Z",
            "to": "2023-11-07T05:31:56Z",
            "isCurrent": true
          }
        }
      ],
      "accomplishments": [
        {
          "value": "<string>",
          "type": "<string>",
          "issuer": "<string>",
          "description": "<string>",
          "date": "2023-11-07T05:31:56Z",
          "organization": {
            "name": "<string>",
            "socialUrl": "<string>",
            "companyWebsite": "<string>",
            "employeeCountRange": "<string>"
          }
        }
      ],
      "customFieldList": [
        {
          "_id": "<string>",
          "fieldName": "<string>",
          "value": "<string>"
        }
      ],
      "source": "<string>",
      "sourceType": "<string>",
      "unsubscribed": true
    }
  ],
  "page": 123,
  "limit": 123,
  "nextCursor": "<string>",
  "total": 123
}

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "<string>",
  "retryAfterSeconds": 123
}

GET

contacts

List contacts

curl --request GET \
  --url https://my.jobin.cloud/api/openapi/v1/contacts \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://my.jobin.cloud/api/openapi/v1/contacts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "items": [
    {
      "id": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "firstName": "<string>",
      "middleName": "<string>",
      "lastName": "<string>",
      "workEmail": "<string>",
      "privateEmail": "<string>",
      "otherEmails": [
        "<string>"
      ],
      "workPhone": "<string>",
      "privatePhone": "<string>",
      "otherPhones": [
        "<string>"
      ],
      "workMobilePhone": "<string>",
      "privateMobilePhone": "<string>",
      "otherMobilePhones": [
        "<string>"
      ],
      "socialUrls": [
        "<string>"
      ],
      "currentTitle": "<string>",
      "currentCompany": "<string>",
      "currentCompanyFrom": "2023-11-07T05:31:56Z",
      "currentCompanyTo": "2023-11-07T05:31:56Z",
      "currentCompanyTenureYears": 123,
      "currentCompanyUrl": "<string>",
      "currentCompanySocialUrl": "<string>",
      "location": {
        "fullAddress": "<string>",
        "address": "<string>",
        "addressLine2": "<string>",
        "city": "<string>",
        "state": "<string>",
        "region": "<string>",
        "country": "<string>",
        "countryCode": "<string>",
        "postalCode": "<string>"
      },
      "industry": "<string>",
      "seniority": "<string>",
      "managementLevel": "<string>",
      "previousTitle": "<string>",
      "previousCompany": "<string>",
      "previousCompanySocialUrl": "<string>",
      "headline": "<string>",
      "summary": "<string>",
      "openProfile": true,
      "openToWork": true,
      "connectionLevels": [
        {
          "jobinUser": {
            "id": "<string>",
            "firstName": "<string>",
            "lastName": "<string>"
          },
          "connectionLevel": "1st"
        }
      ],
      "currentCampaign": {
        "campaignId": "<string>",
        "stagePositionCode": "<string>"
      },
      "tags": [
        {
          "_id": "<string>",
          "value": "<string>",
          "iconName": "<string>",
          "color": "<string>"
        }
      ],
      "skills": [
        {
          "value": "<string>",
          "skillType": "<string>",
          "level": 123,
          "topSkill": true
        }
      ],
      "education": [
        {
          "school": "<string>",
          "schoolSocialUrl": "<string>",
          "degreeLevel": "<string>",
          "degrees": [
            "<string>"
          ],
          "fieldOfStudy": "<string>",
          "majors": [
            "<string>"
          ],
          "minors": [
            "<string>"
          ],
          "period": {
            "from": "2023-11-07T05:31:56Z",
            "to": "2023-11-07T05:31:56Z",
            "isCurrent": true
          }
        }
      ],
      "experiences": [
        {
          "title": "<string>",
          "company": "<string>",
          "from": "2023-11-07T05:31:56Z",
          "to": "2023-11-07T05:31:56Z",
          "isCurrent": true,
          "location": {
            "fullAddress": "<string>",
            "address": "<string>",
            "addressLine2": "<string>",
            "city": "<string>",
            "state": "<string>",
            "region": "<string>",
            "country": "<string>",
            "countryCode": "<string>",
            "postalCode": "<string>"
          },
          "employmentType": "<string>",
          "description": "<string>"
        }
      ],
      "languages": [
        {
          "value": "<string>",
          "level": 123,
          "note": "<string>"
        }
      ],
      "volunteering": [
        {
          "roleTitle": "<string>",
          "organization": {
            "name": "<string>",
            "socialUrl": "<string>",
            "companyWebsite": "<string>",
            "employeeCountRange": "<string>"
          },
          "cause": "<string>",
          "description": "<string>",
          "location": {
            "fullAddress": "<string>",
            "address": "<string>",
            "addressLine2": "<string>",
            "city": "<string>",
            "state": "<string>",
            "region": "<string>",
            "country": "<string>",
            "countryCode": "<string>",
            "postalCode": "<string>"
          },
          "period": {
            "from": "2023-11-07T05:31:56Z",
            "to": "2023-11-07T05:31:56Z",
            "isCurrent": true
          }
        }
      ],
      "accomplishments": [
        {
          "value": "<string>",
          "type": "<string>",
          "issuer": "<string>",
          "description": "<string>",
          "date": "2023-11-07T05:31:56Z",
          "organization": {
            "name": "<string>",
            "socialUrl": "<string>",
            "companyWebsite": "<string>",
            "employeeCountRange": "<string>"
          }
        }
      ],
      "customFieldList": [
        {
          "_id": "<string>",
          "fieldName": "<string>",
          "value": "<string>"
        }
      ],
      "source": "<string>",
      "sourceType": "<string>",
      "unsubscribed": true
    }
  ],
  "page": 123,
  "limit": 123,
  "nextCursor": "<string>",
  "total": 123
}

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "<string>",
  "retryAfterSeconds": 123
}

Start here when you need to discover a contactId before enrichment or campaign assignment. Use minYearsInCurrentRole and maxYearsInCurrentRole when your sourcing rule depends on tenure or years at the current company. For example, pass maxYearsInCurrentRole=10 to avoid candidates who have been at their current company for more than ten years. page is capped at 100. For result sets beyond page 100, continue with cursor pagination: read nextCursor from the response and pass it back as the cursor query parameter on the next request. includeTotal defaults to false and should be used sparingly. Returning the page itself is cheaper than calculating the full matching count, so requests with includeTotal=true have a stricter 60 requests/minute budget and can take longer to finish. Leave it off unless your integration actually needs the total.

Authorizations

x-api-key

string

header

required

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

Query Parameters

string<email>

Filter contacts by work, private, or other email.

Maximum string length: 320

firstName

string

Search contacts by structured first-name value. This uses the indexed contact search path and is more selective than legacy full-name matching.

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

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 contacts by city. Matches the contact's person location and role-level location fallback fields.

Required string length: 2 - 256

region

string

Filter contacts by state, province, county, or region. Matches the contact's person location and role-level location fallback fields.

Required string length: 2 - 256

country

string

Filter contacts by country name. Matches the contact's person location and role-level location fallback fields.

Required string length: 2 - 256

countryCode

string

Filter contacts by two-letter ISO country code, for example IT or US.

Required string length: 2

minYearsInCurrentRole

number

Minimum current-company tenure in years. Recruiters often call this tenure or years at current company.

Required range: 0 <= x <= 80

maxYearsInCurrentRole

number

Maximum current-company tenure in years. Use 10 to exclude candidates who have been at the current company for more than ten years.

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

When true, include the matching contact count. The default is false, so ordinary list requests omit the count. Counting is more expensive than returning the page itself, so requests with includeTotal use a stricter 60 requests/minute limit and can take longer to complete. Only enable it when your integration actually uses the count.

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

Show child attributes

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. The response returns null unless includeTotal is true.

Overview

Authentication

Contacts

Campaigns

Authorizations

Query Parameters

Response