Contact Lists

List contact lists

GET
/v1/contacts/lists

Authorization

ApiKeyAuth
AuthorizationBearer <token>

API key authentication using Bearer token. Format: sk_live_ followed by a secure random string.

In: header

Query Parameters

limit?integer

Maximum number of lists to return (1–100, default 20)

Default20
Range1 <= value <= 100
offset?integer

Number of lists to skip for pagination (default 0)

Default0
Range0 <= value

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/v1/contacts/lists"
{  "items": [    {      "id": "abc123",      "name": "Engineering leads at Stripe",      "filters": {        "companyLinkedInUrls": [          "https://www.linkedin.com/company/stripe"        ],        "jobTitles": [          "Engineering Manager",          "VP Engineering"        ],        "keywords": "Kubernetes",        "countries": [          "US",          "GB"        ]      },      "contactCount": 47,      "createdAt": "2026-03-03T12:00:00Z",      "updatedAt": "2026-03-03T12:00:00Z"    }  ],  "total": 3,  "limit": 20,  "offset": 0,  "hasMore": false}
{  "error": {    "type": "VALIDATION",    "code": "VALIDATION_ERROR",    "message": "validation failed for 'departments': invalid value: Engineering Ops",    "errorCode": "string",    "errorAction": "string",    "details": {},    "requestId": "e69ed773-2674-4dca-be61-886d6698f360",    "fields": [      {        "field": "domain",        "message": "'domain' must be a valid hostname (e.g., 'example.com') without protocol (https://) or path"      }    ],    "debug": {      "cause": "string"    }  }}
{  "error": {    "type": "VALIDATION",    "code": "VALIDATION_ERROR",    "message": "validation failed for 'departments': invalid value: Engineering Ops",    "errorCode": "string",    "errorAction": "string",    "details": {},    "requestId": "e69ed773-2674-4dca-be61-886d6698f360",    "fields": [      {        "field": "domain",        "message": "'domain' must be a valid hostname (e.g., 'example.com') without protocol (https://) or path"      }    ],    "debug": {      "cause": "string"    }  }}

Create a contact list

POST
/v1/contacts/lists

Creates a named contact list by running a live LinkedIn Sales Navigator search for the given company and filters, then storing the results as a persistent snapshot.

The request is synchronous — it waits for the search to complete before returning. The response includes the list metadata with an accurate contactCount.

Requirements:

  • A valid company LinkedIn URL is required
  • At least one filter (jobTitles, keywords, or countries) must be provided
  • LinkedIn Sales Navigator must be connected on the API key owner's account

Notes:

  • Up to ~125 contacts are captured (5 pages × 25 results per page)
  • Contacts are stored as a point-in-time snapshot; the list is not automatically updated when profiles change
  • The list and all its contacts are committed atomically — if the request fails, no partial data is stored

Authorization

ApiKeyAuth
AuthorizationBearer <token>

API key authentication using Bearer token. Format: sk_live_ followed by a secure random string.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Display name for the contact list

Lengthlength <= 200
filters*

Search filters stored on a contact list

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/contacts/lists" \  -H "Content-Type: application/json" \  -d '{    "name": "Engineering leads at Stripe",    "filters": {      "companyLinkedInUrls": [        "https://www.linkedin.com/company/stripe"      ],      "jobTitles": [        "Engineering Manager",        "VP Engineering"      ],      "countries": [        "US",        "GB"      ]    }  }'

{  "id": "abc123",  "name": "Engineering leads at Stripe",  "filters": {    "companyLinkedInUrls": [      "https://www.linkedin.com/company/stripe"    ],    "jobTitles": [      "Engineering Manager",      "VP Engineering"    ],    "countries": [      "US",      "GB"    ]  },  "contactCount": 47,  "createdAt": "2026-03-03T12:00:00Z",  "updatedAt": "2026-03-03T12:00:00Z"}

{  "error": "BAD_REQUEST",  "message": "At least one filter (jobTitles, keywords, or countries) is required"}
{  "error": {    "type": "VALIDATION",    "code": "VALIDATION_ERROR",    "message": "validation failed for 'departments': invalid value: Engineering Ops",    "errorCode": "string",    "errorAction": "string",    "details": {},    "requestId": "e69ed773-2674-4dca-be61-886d6698f360",    "fields": [      {        "field": "domain",        "message": "'domain' must be a valid hostname (e.g., 'example.com') without protocol (https://) or path"      }    ],    "debug": {      "cause": "string"    }  }}
{  "error": {    "type": "VALIDATION",    "code": "VALIDATION_ERROR",    "message": "validation failed for 'departments': invalid value: Engineering Ops",    "errorCode": "string",    "errorAction": "string",    "details": {},    "requestId": "e69ed773-2674-4dca-be61-886d6698f360",    "fields": [      {        "field": "domain",        "message": "'domain' must be a valid hostname (e.g., 'example.com') without protocol (https://) or path"      }    ],    "debug": {      "cause": "string"    }  }}
{  "error": {    "type": "VALIDATION",    "code": "VALIDATION_ERROR",    "message": "validation failed for 'departments': invalid value: Engineering Ops",    "errorCode": "string",    "errorAction": "string",    "details": {},    "requestId": "e69ed773-2674-4dca-be61-886d6698f360",    "fields": [      {        "field": "domain",        "message": "'domain' must be a valid hostname (e.g., 'example.com') without protocol (https://) or path"      }    ],    "debug": {      "cause": "string"    }  }}
{  "error": {    "type": "VALIDATION",    "code": "VALIDATION_ERROR",    "message": "validation failed for 'departments': invalid value: Engineering Ops",    "errorCode": "string",    "errorAction": "string",    "details": {},    "requestId": "e69ed773-2674-4dca-be61-886d6698f360",    "fields": [      {        "field": "domain",        "message": "'domain' must be a valid hostname (e.g., 'example.com') without protocol (https://) or path"      }    ],    "debug": {      "cause": "string"    }  }}

Get a contact list by ID

GET
/v1/contacts/lists/{listId}

Authorization

ApiKeyAuth
AuthorizationBearer <token>

API key authentication using Bearer token. Format: sk_live_ followed by a secure random string.

In: header

Path Parameters

listId*string

The unique identifier of the contact list

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/contacts/lists/abc123"
{  "id": "abc123",  "name": "Engineering leads at Stripe",  "filters": {    "companyLinkedInUrls": [      "https://www.linkedin.com/company/stripe"    ],    "jobTitles": [      "Engineering Manager",      "VP Engineering"    ],    "keywords": "Kubernetes",    "countries": [      "US",      "GB"    ]  },  "contactCount": 47,  "createdAt": "2026-03-03T12:00:00Z",  "updatedAt": "2026-03-03T12:00:00Z"}
{  "error": {    "type": "VALIDATION",    "code": "VALIDATION_ERROR",    "message": "validation failed for 'departments': invalid value: Engineering Ops",    "errorCode": "string",    "errorAction": "string",    "details": {},    "requestId": "e69ed773-2674-4dca-be61-886d6698f360",    "fields": [      {        "field": "domain",        "message": "'domain' must be a valid hostname (e.g., 'example.com') without protocol (https://) or path"      }    ],    "debug": {      "cause": "string"    }  }}
{  "error": {    "type": "VALIDATION",    "code": "VALIDATION_ERROR",    "message": "validation failed for 'departments': invalid value: Engineering Ops",    "errorCode": "string",    "errorAction": "string",    "details": {},    "requestId": "e69ed773-2674-4dca-be61-886d6698f360",    "fields": [      {        "field": "domain",        "message": "'domain' must be a valid hostname (e.g., 'example.com') without protocol (https://) or path"      }    ],    "debug": {      "cause": "string"    }  }}
{  "error": {    "type": "VALIDATION",    "code": "VALIDATION_ERROR",    "message": "validation failed for 'departments': invalid value: Engineering Ops",    "errorCode": "string",    "errorAction": "string",    "details": {},    "requestId": "e69ed773-2674-4dca-be61-886d6698f360",    "fields": [      {        "field": "domain",        "message": "'domain' must be a valid hostname (e.g., 'example.com') without protocol (https://) or path"      }    ],    "debug": {      "cause": "string"    }  }}

Delete a contact list and all its stored contacts

DELETE
/v1/contacts/lists/{listId}

Permanently deletes the contact list and all its stored contact snapshots.

Authorization

ApiKeyAuth
AuthorizationBearer <token>

API key authentication using Bearer token. Format: sk_live_ followed by a secure random string.

In: header

Path Parameters

listId*string

The unique identifier of the contact list

Response Body

application/json

application/json

application/json

curl -X DELETE "https://example.com/v1/contacts/lists/abc123"
Empty
{  "error": {    "type": "VALIDATION",    "code": "VALIDATION_ERROR",    "message": "validation failed for 'departments': invalid value: Engineering Ops",    "errorCode": "string",    "errorAction": "string",    "details": {},    "requestId": "e69ed773-2674-4dca-be61-886d6698f360",    "fields": [      {        "field": "domain",        "message": "'domain' must be a valid hostname (e.g., 'example.com') without protocol (https://) or path"      }    ],    "debug": {      "cause": "string"    }  }}
{  "error": {    "type": "VALIDATION",    "code": "VALIDATION_ERROR",    "message": "validation failed for 'departments': invalid value: Engineering Ops",    "errorCode": "string",    "errorAction": "string",    "details": {},    "requestId": "e69ed773-2674-4dca-be61-886d6698f360",    "fields": [      {        "field": "domain",        "message": "'domain' must be a valid hostname (e.g., 'example.com') without protocol (https://) or path"      }    ],    "debug": {      "cause": "string"    }  }}
{  "error": {    "type": "VALIDATION",    "code": "VALIDATION_ERROR",    "message": "validation failed for 'departments': invalid value: Engineering Ops",    "errorCode": "string",    "errorAction": "string",    "details": {},    "requestId": "e69ed773-2674-4dca-be61-886d6698f360",    "fields": [      {        "field": "domain",        "message": "'domain' must be a valid hostname (e.g., 'example.com') without protocol (https://) or path"      }    ],    "debug": {      "cause": "string"    }  }}

Rename a contact list

PUT
/v1/contacts/lists/{listId}

Authorization

ApiKeyAuth
AuthorizationBearer <token>

API key authentication using Bearer token. Format: sk_live_ followed by a secure random string.

In: header

Path Parameters

listId*string

The unique identifier of the contact list

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

New display name for the contact list

Lengthlength <= 200

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com/v1/contacts/lists/abc123" \  -H "Content-Type: application/json" \  -d '{    "name": "Senior engineers at Stripe"  }'
{  "id": "abc123",  "name": "Engineering leads at Stripe",  "filters": {    "companyLinkedInUrls": [      "https://www.linkedin.com/company/stripe"    ],    "jobTitles": [      "Engineering Manager",      "VP Engineering"    ],    "keywords": "Kubernetes",    "countries": [      "US",      "GB"    ]  },  "contactCount": 47,  "createdAt": "2026-03-03T12:00:00Z",  "updatedAt": "2026-03-03T12:00:00Z"}
{  "error": {    "type": "VALIDATION",    "code": "VALIDATION_ERROR",    "message": "validation failed for 'departments': invalid value: Engineering Ops",    "errorCode": "string",    "errorAction": "string",    "details": {},    "requestId": "e69ed773-2674-4dca-be61-886d6698f360",    "fields": [      {        "field": "domain",        "message": "'domain' must be a valid hostname (e.g., 'example.com') without protocol (https://) or path"      }    ],    "debug": {      "cause": "string"    }  }}
{  "error": {    "type": "VALIDATION",    "code": "VALIDATION_ERROR",    "message": "validation failed for 'departments': invalid value: Engineering Ops",    "errorCode": "string",    "errorAction": "string",    "details": {},    "requestId": "e69ed773-2674-4dca-be61-886d6698f360",    "fields": [      {        "field": "domain",        "message": "'domain' must be a valid hostname (e.g., 'example.com') without protocol (https://) or path"      }    ],    "debug": {      "cause": "string"    }  }}
{  "error": {    "type": "VALIDATION",    "code": "VALIDATION_ERROR",    "message": "validation failed for 'departments': invalid value: Engineering Ops",    "errorCode": "string",    "errorAction": "string",    "details": {},    "requestId": "e69ed773-2674-4dca-be61-886d6698f360",    "fields": [      {        "field": "domain",        "message": "'domain' must be a valid hostname (e.g., 'example.com') without protocol (https://) or path"      }    ],    "debug": {      "cause": "string"    }  }}
{  "error": {    "type": "VALIDATION",    "code": "VALIDATION_ERROR",    "message": "validation failed for 'departments': invalid value: Engineering Ops",    "errorCode": "string",    "errorAction": "string",    "details": {},    "requestId": "e69ed773-2674-4dca-be61-886d6698f360",    "fields": [      {        "field": "domain",        "message": "'domain' must be a valid hostname (e.g., 'example.com') without protocol (https://) or path"      }    ],    "debug": {      "cause": "string"    }  }}

Get contacts in a contact list

GET
/v1/contacts/lists/{listId}/contacts

Returns the stored contact snapshot for the given list, paginated. Reads directly from the database — no Sales Navigator API call is made, so this is always fast and does not consume credits.

Contacts are returned in the order they were stored at list creation time.

Authorization

ApiKeyAuth
AuthorizationBearer <token>

API key authentication using Bearer token. Format: sk_live_ followed by a secure random string.

In: header

Path Parameters

listId*string

The unique identifier of the contact list

Query Parameters

limit?integer

Maximum number of contacts to return (1–100, default 25)

Default25
Range1 <= value <= 100
offset?integer

Number of contacts to skip for pagination (default 0)

Default0
Range0 <= value

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/contacts/lists/abc123/contacts"
{  "items": [    {      "id": "item_001",      "listId": "abc123",      "baseContactId": "bc_001",      "firstName": "John",      "lastName": "Doe",      "fullName": "John Doe",      "role": "Engineering Manager",      "companyName": "Stripe",      "location": "San Francisco, California",      "seniority": [        "MANAGER"      ],      "linkedInSalesNavigatorProfileUrl": "https://www.linkedin.com/sales/lead/ACwAAABOW1g",      "createdAt": "2026-03-03T12:00:00Z"    }  ],  "total": 47,  "limit": 25,  "offset": 0,  "hasMore": true}
{  "error": {    "type": "VALIDATION",    "code": "VALIDATION_ERROR",    "message": "validation failed for 'departments': invalid value: Engineering Ops",    "errorCode": "string",    "errorAction": "string",    "details": {},    "requestId": "e69ed773-2674-4dca-be61-886d6698f360",    "fields": [      {        "field": "domain",        "message": "'domain' must be a valid hostname (e.g., 'example.com') without protocol (https://) or path"      }    ],    "debug": {      "cause": "string"    }  }}
{  "error": {    "type": "VALIDATION",    "code": "VALIDATION_ERROR",    "message": "validation failed for 'departments': invalid value: Engineering Ops",    "errorCode": "string",    "errorAction": "string",    "details": {},    "requestId": "e69ed773-2674-4dca-be61-886d6698f360",    "fields": [      {        "field": "domain",        "message": "'domain' must be a valid hostname (e.g., 'example.com') without protocol (https://) or path"      }    ],    "debug": {      "cause": "string"    }  }}
{  "error": {    "type": "VALIDATION",    "code": "VALIDATION_ERROR",    "message": "validation failed for 'departments': invalid value: Engineering Ops",    "errorCode": "string",    "errorAction": "string",    "details": {},    "requestId": "e69ed773-2674-4dca-be61-886d6698f360",    "fields": [      {        "field": "domain",        "message": "'domain' must be a valid hostname (e.g., 'example.com') without protocol (https://) or path"      }    ],    "debug": {      "cause": "string"    }  }}

On this page

List contact listsCreate a contact listGet a contact list by IDDelete a contact list and all its stored contactsRename a contact listGet contacts in a contact list