Contact Lists

Contact Lists

Contact Lists let you capture a snapshot of people at a company who match specific criteria — job titles, keywords, and/or countries — using LinkedIn Sales Navigator.

Typical workflow:

1. POST /v1/contacts/lists — provide a company LinkedIn URL and at least one filter; the API runs a live Sales Navigator search and stores the results as a snapshot

2. GET /v1/contacts/lists/{listId}/contacts — page through the stored contacts at any time, no new Sales Navigator call needed

3. GET /v1/contacts/lists — list all your saved contact lists

4. PUT /v1/contacts/lists/{listId} — rename a list

5. DELETE /v1/contacts/lists/{listId} — remove a list and its contacts

What gets stored: Each contact in the list is stored as a point-in-time snapshot including name, role, company, location, headline, seniority, positions, avatar, and Sales Navigator profile URL. The snapshot reflects what Sales Navigator returned at creation time and is not updated automatically.

Sales Navigator requirement: Creating a list requires a LinkedIn Sales Navigator connection on your account. If Sales Navigator is not connected, the POST returns a connector error and no list is created. Reading existing lists (GET) works regardless of connector status.

List all contact lists — paginated

get

Authorizations

ApiKeyAuth

AuthorizationstringRequired

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

Query parameters

limitinteger · min: 1 · max: 100Optional

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

Default: 20

offsetintegerOptional

Number of lists to skip for pagination (default 0)

Default: 0

Responses

200

Contact lists retrieved successfully

application/json

Paginated list of contact lists

totalintegerRequired

Total number of contact lists for this organization

Example: 3

limitintegerRequiredExample: 20

offsetintegerRequiredExample: 0

hasMorebooleanRequiredExample: false

401

Unauthorized — invalid or missing API key

application/json

500

Internal Server Error

application/json

get

/v1/contacts/lists

HTTPcURLJavaScriptPython

GET /v1/contacts/lists HTTP/1.1
Host: api.saber.app
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

Create a contact list — runs a Sales Navigator search and stores a snapshot of matching contacts

post

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

Authorizations

ApiKeyAuth

AuthorizationstringRequired

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

Body

application/json

Request body for creating a contact list

namestring · max: 200Required

Display name for the contact list

Example: Engineering leads at Stripe

Responses

201

Contact list created successfully

application/json

400

Bad Request — missing required filter or invalid URL

application/json

401

Unauthorized — invalid or missing API key

application/json

429

Too Many Requests — rate limit exceeded

application/json

500

Internal Server Error

application/json

504

Gateway Timeout — Sales Navigator search exceeded the request timeout

application/json

post

/v1/contacts/lists

HTTPcURLJavaScriptPython

POST /v1/contacts/lists HTTP/1.1
Host: api.saber.app
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 193

{
  "name": "Engineering leads at Stripe",
  "filters": {
    "companyLinkedInUrls": [
      "https://www.linkedin.com/company/stripe"
    ],
    "jobTitles": [
      "Engineering Manager",
      "VP Engineering"
    ],
    "countries": [
      "US",
      "GB"
    ]
  }
}

Engineering leads at one companySearch across multiple companiesCross-company list (no company scope)

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

Get a contact list by ID — returns metadata and contact count

get

Authorizations

ApiKeyAuth

AuthorizationstringRequired

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

Path parameters

listIdstringRequired

The unique identifier of the contact list

Example: abc123

Responses

200

Contact list retrieved successfully

application/json

A contact list with metadata and stored search filters

idstringRequired

Unique identifier for the contact list

Example: abc123

namestringRequired

Display name for the contact list

Example: Engineering leads at Stripe

contactCountintegerRequired

Number of contacts stored in this list

Example: 47

createdAtstring · date-timeRequiredExample: 2026-03-03T12:00:00Z

updatedAtstring · date-timeRequiredExample: 2026-03-03T12:00:00Z

401

Unauthorized — invalid or missing API key

application/json

404

Contact list not found

application/json

500

Internal Server Error

application/json

get

/v1/contacts/lists/{listId}

HTTPcURLJavaScriptPython

GET /v1/contacts/lists/{listId} HTTP/1.1
Host: api.saber.app
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

Rename a contact list

put

Authorizations

ApiKeyAuth

AuthorizationstringRequired

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

Path parameters

listIdstringRequired

The unique identifier of the contact list

Example: abc123

Body

application/json

Request body for renaming a contact list

namestring · max: 200Required

New display name for the contact list

Example: Senior engineers at Stripe

Responses

200

Contact list updated successfully

application/json

A contact list with metadata and stored search filters

idstringRequired

Unique identifier for the contact list

Example: abc123

namestringRequired

Display name for the contact list

Example: Engineering leads at Stripe

contactCountintegerRequired

Number of contacts stored in this list

Example: 47

createdAtstring · date-timeRequiredExample: 2026-03-03T12:00:00Z

updatedAtstring · date-timeRequiredExample: 2026-03-03T12:00:00Z

400

Bad Request — invalid name

application/json

401

Unauthorized — invalid or missing API key

application/json

404

Contact list not found

application/json

500

Internal Server Error

application/json

put

/v1/contacts/lists/{listId}

HTTPcURLJavaScriptPython

PUT /v1/contacts/lists/{listId} HTTP/1.1
Host: api.saber.app
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 37

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

Delete a contact list and all its stored contacts

delete

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

The underlying base_contacts identity records are not deleted — they are global records shared across all organizations.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

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

Path parameters

listIdstringRequired

The unique identifier of the contact list

Example: abc123

Responses

204

Contact list deleted successfully

401

Unauthorized — invalid or missing API key

application/json

404

Contact list not found

application/json

500

Internal Server Error

application/json

delete

/v1/contacts/lists/{listId}

HTTPcURLJavaScriptPython

DELETE /v1/contacts/lists/{listId} HTTP/1.1
Host: api.saber.app
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Get contacts in a list — returns the stored snapshot, no new Sales Navigator call

get

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.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

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

Path parameters

listIdstringRequired

The unique identifier of the contact list

Example: abc123

Query parameters

limitinteger · min: 1 · max: 100Optional

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

Default: 25

offsetintegerOptional

Number of contacts to skip for pagination (default 0)

Default: 0

Responses

200

Contacts retrieved successfully

application/json

Paginated list of contacts within a contact list

totalintegerRequired

Total number of contacts in this list

Example: 47

limitintegerRequiredExample: 25

offsetintegerRequiredExample: 0

hasMorebooleanRequiredExample: true

401

Unauthorized — invalid or missing API key

application/json

404

Contact list not found

application/json

500

Internal Server Error

application/json

get

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

HTTPcURLJavaScriptPython

GET /v1/contacts/lists/{listId}/contacts HTTP/1.1
Host: api.saber.app
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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