Company Lists

Company Lists

Company Lists let you build and manage curated sets of companies based on filter criteria such as industry, size, location, and more.

Typical workflow:

1. POST /v1/companies/search — preview up to 50 companies matching a filter (no list created)

2. POST /v1/companies/lists — save the filter as a named list

3. GET /v1/companies/lists/{listId}/companies — page through matching companies

4. PUT /v1/companies/lists/{listId} — update the list name or filter

5. DELETE /v1/companies/lists/{listId} — remove the list

Caching: Results are cached for 5 minutes per unique filter and caller. Write operations (create, update, delete) automatically invalidate the cache for the authenticated caller.

Import a company list from HubSpot

post

Create a company list by importing companies directly from a connected HubSpot portal using a property filter.

The endpoint queries the HubSpot CRM for companies matching the filter, upserts stub records in Saber so the list is immediately queryable, and returns the created list. Stub records are enriched asynchronously by the normal background pipeline (LinkedIn followers, employee counts, etc.) — this typically completes within minutes to hours depending on queue depth.

If some company stubs fail to upsert, those domains are excluded from the list and returned in unresolvedDomains so callers can surface a warning to the user.

Requires a connected HubSpot installation. Returns 400 if no HubSpot portal is linked to the authenticated organization.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

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

Body

application/json

namestring · min: 1 · max: 200Required

A human-readable name for the imported list (1–200 characters)

Example: HubSpot — Technology companies

Responses

201

Company list imported and created successfully

application/json

400

Bad Request — no HubSpot installation connected, or invalid parameters

application/json

401

Unauthorized — invalid or missing API key

application/json

422

Unprocessable Entity — filter matched zero companies

application/json

429

Too Many Requests — rate limit exceeded

application/json

500

Internal Server Error

application/json

post

/v1/companies/lists/import

HTTPcURLJavaScriptPython

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

{
  "name": "HubSpot — Technology companies",
  "source": {
    "type": "hubspot",
    "filter": {
      "propertyName": "industry",
      "operator": "EQ",
      "value": "Technology"
    }
  }
}

{
  "id": "text",
  "name": "Mid-size US SaaS companies",
  "prompt": "text",
  "filter": {
    "domains": [
      "text"
    ],
    "names": [
      "text"
    ],
    "handles": [
      "text"
    ],
    "websites": [
      "text"
    ],
    "industries": [
      "Computer Software",
      "Internet"
    ],
    "sizes": [
      "51-200",
      "201-500"
    ],
    "types": [
      "text"
    ],
    "founded": {
      "before": 1,
      "after": 1
    },
    "location": {
      "cities": [
        "text"
      ],
      "states": [
        "text"
      ],
      "countryCodes": [
        "US",
        "GB"
      ]
    },
    "exclude": {
      "industries": [
        "text"
      ],
      "sizes": [
        "text"
      ],
      "types": [
        "text"
      ],
      "domains": [
        "text"
      ],
      "location": {
        "cities": [
          "text"
        ],
        "states": [
          "text"
        ],
        "countryCodes": [
          "text"
        ]
      }
    },
    "questionIds": [
      "text"
    ],
    "technologies": [
      "stripe",
      "hubspot"
    ]
  },
  "createdAt": "2026-03-27T19:48:32.142Z",
  "updatedAt": "2026-03-27T19:48:32.142Z",
  "unresolvedDomains": [
    "broken-domain.io"
  ]
}

Preview expected company count and credit cost

post

Returns the number of companies that match a given filter and the Saber credit cost to create that list — without creating the list or charging any credits.

When technologies is present the count is fetched from Theirstack in blur mode (free), so you can show the user "X companies match, Y credits required" before they commit. For filters without technologies the count is a fast database query (always free).

Results are cached for 5 minutes per caller.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

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

Body

application/json

Responses

200

Count and credit cost returned successfully

application/json

countintegerRequired

Number of companies expected to match the filter

Example: 142

creditsintegerRequired

Saber credits that will be charged when the list is created

Example: 142

401

Unauthorized - Invalid or missing API key

application/json

429

Too Many Requests - Rate limit exceeded

application/json

500

Internal Server Error

application/json

post

/v1/companies/lists/count-preview

HTTPcURLJavaScriptPython

POST /v1/companies/lists/count-preview HTTP/1.1
Host: api.saber.app
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 73

{
  "filter": {
    "technologies": [
      "stripe"
    ],
    "location": {
      "countryCodes": [
        "NL"
      ]
    }
  }
}

{
  "count": 142,
  "credits": 142
}

List all company lists

get

Retrieve a paginated list of company lists belonging to the authenticated caller.

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

Company lists retrieved successfully

application/json

Paginated list of company lists

totalintegerRequired

Total number of lists

Example: 5

limitintegerRequired

Maximum results per page

Example: 20

offsetintegerRequired

Number of results skipped

Example: 0

hasMorebooleanRequired

Whether more results are available

Example: false

401

Unauthorized - Invalid or missing API key

application/json

429

Too Many Requests - Rate limit exceeded

application/json

500

Internal Server Error

application/json

get

/v1/companies/lists

HTTPcURLJavaScriptPython

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

{
  "items": [
    {
      "id": "text",
      "name": "Mid-size US SaaS companies",
      "prompt": "text",
      "filter": {
        "domains": [
          "text"
        ],
        "names": [
          "text"
        ],
        "handles": [
          "text"
        ],
        "websites": [
          "text"
        ],
        "industries": [
          "Computer Software",
          "Internet"
        ],
        "sizes": [
          "51-200",
          "201-500"
        ],
        "types": [
          "text"
        ],
        "founded": {
          "before": 1,
          "after": 1
        },
        "location": {
          "cities": [
            "text"
          ],
          "states": [
            "text"
          ],
          "countryCodes": [
            "US",
            "GB"
          ]
        },
        "exclude": {
          "industries": [
            "text"
          ],
          "sizes": [
            "text"
          ],
          "types": [
            "text"
          ],
          "domains": [
            "text"
          ],
          "location": {
            "cities": [
              "text"
            ],
            "states": [
              "text"
            ],
            "countryCodes": [
              "text"
            ]
          }
        },
        "questionIds": [
          "text"
        ],
        "technologies": [
          "stripe",
          "hubspot"
        ]
      },
      "createdAt": "2026-03-27T19:48:32.142Z",
      "updatedAt": "2026-03-27T19:48:32.142Z"
    }
  ],
  "total": 5,
  "limit": 20,
  "offset": 0,
  "hasMore": false
}

Create a company list

post

Create a named company list with a filter definition. The filter criteria determine which companies belong to the list.

Results are cached for 5 minutes per caller. Mutations (create, update, delete) automatically invalidate the cache for the authenticated caller.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

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

Body

application/json

namestring · min: 1 · max: 200Required

A human-readable name for the list (1–200 characters)

Example: Mid-size US SaaS companies

Responses

201

Company list created successfully

application/json

400

Bad Request - Invalid parameters (e.g. empty or too-long name)

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

post

/v1/companies/lists

HTTPcURLJavaScriptPython

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

{
  "name": "Mid-size US SaaS companies",
  "filter": {
    "industries": [
      "Computer Software"
    ],
    "sizes": [
      "51-200",
      "201-500"
    ],
    "location": {
      "countryCodes": [
        "US"
      ]
    }
  }
}

{
  "id": "text",
  "name": "Mid-size US SaaS companies",
  "prompt": "text",
  "filter": {
    "domains": [
      "text"
    ],
    "names": [
      "text"
    ],
    "handles": [
      "text"
    ],
    "websites": [
      "text"
    ],
    "industries": [
      "Computer Software",
      "Internet"
    ],
    "sizes": [
      "51-200",
      "201-500"
    ],
    "types": [
      "text"
    ],
    "founded": {
      "before": 1,
      "after": 1
    },
    "location": {
      "cities": [
        "text"
      ],
      "states": [
        "text"
      ],
      "countryCodes": [
        "US",
        "GB"
      ]
    },
    "exclude": {
      "industries": [
        "text"
      ],
      "sizes": [
        "text"
      ],
      "types": [
        "text"
      ],
      "domains": [
        "text"
      ],
      "location": {
        "cities": [
          "text"
        ],
        "states": [
          "text"
        ],
        "countryCodes": [
          "text"
        ]
      }
    },
    "questionIds": [
      "text"
    ],
    "technologies": [
      "stripe",
      "hubspot"
    ]
  },
  "createdAt": "2026-03-27T19:48:32.142Z",
  "updatedAt": "2026-03-27T19:48:32.142Z"
}

Get a company list by ID

get

Retrieve a single company list including its name and filter definition.

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 company list

Responses

200

Company list retrieved successfully

application/json

A saved company list with its filter definition

idstringRequired

Unique identifier for the list

namestringRequired

Human-readable list name

Example: Mid-size US SaaS companies

promptstringOptional

Optional prompt used to generate the filter

createdAtstring · date-timeRequired

When the list was created

updatedAtstring · date-timeOptional

When the list was last updated

401

Unauthorized - Invalid or missing API key

application/json

404

Company list not found

application/json

500

Internal Server Error

application/json

get

/v1/companies/lists/{listId}

HTTPcURLJavaScriptPython

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

{
  "id": "text",
  "name": "Mid-size US SaaS companies",
  "prompt": "text",
  "filter": {
    "domains": [
      "text"
    ],
    "names": [
      "text"
    ],
    "handles": [
      "text"
    ],
    "websites": [
      "text"
    ],
    "industries": [
      "Computer Software",
      "Internet"
    ],
    "sizes": [
      "51-200",
      "201-500"
    ],
    "types": [
      "text"
    ],
    "founded": {
      "before": 1,
      "after": 1
    },
    "location": {
      "cities": [
        "text"
      ],
      "states": [
        "text"
      ],
      "countryCodes": [
        "US",
        "GB"
      ]
    },
    "exclude": {
      "industries": [
        "text"
      ],
      "sizes": [
        "text"
      ],
      "types": [
        "text"
      ],
      "domains": [
        "text"
      ],
      "location": {
        "cities": [
          "text"
        ],
        "states": [
          "text"
        ],
        "countryCodes": [
          "text"
        ]
      }
    },
    "questionIds": [
      "text"
    ],
    "technologies": [
      "stripe",
      "hubspot"
    ]
  },
  "createdAt": "2026-03-27T19:48:32.142Z",
  "updatedAt": "2026-03-27T19:48:32.142Z"
}

Update a company list

put

Update the name and/or filter of an existing company list. Both fields are required in the request body (full replacement, not a patch).

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 company list to update

Body

application/json

namestring · min: 1 · max: 200Required

Updated name for the list (1–200 characters)

Example: Updated list name

Responses

200

Company list updated successfully

application/json

A saved company list with its filter definition

idstringRequired

Unique identifier for the list

namestringRequired

Human-readable list name

Example: Mid-size US SaaS companies

promptstringOptional

Optional prompt used to generate the filter

createdAtstring · date-timeRequired

When the list was created

updatedAtstring · date-timeOptional

When the list was last updated

400

Bad Request - Invalid parameters

application/json

401

Unauthorized - Invalid or missing API key

application/json

404

Company list not found

application/json

500

Internal Server Error

application/json

put

/v1/companies/lists/{listId}

HTTPcURLJavaScriptPython

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

{
  "name": "Updated list name",
  "filter": {
    "industries": [
      "Internet"
    ],
    "sizes": [
      "201-500"
    ]
  }
}

{
  "id": "text",
  "name": "Mid-size US SaaS companies",
  "prompt": "text",
  "filter": {
    "domains": [
      "text"
    ],
    "names": [
      "text"
    ],
    "handles": [
      "text"
    ],
    "websites": [
      "text"
    ],
    "industries": [
      "Computer Software",
      "Internet"
    ],
    "sizes": [
      "51-200",
      "201-500"
    ],
    "types": [
      "text"
    ],
    "founded": {
      "before": 1,
      "after": 1
    },
    "location": {
      "cities": [
        "text"
      ],
      "states": [
        "text"
      ],
      "countryCodes": [
        "US",
        "GB"
      ]
    },
    "exclude": {
      "industries": [
        "text"
      ],
      "sizes": [
        "text"
      ],
      "types": [
        "text"
      ],
      "domains": [
        "text"
      ],
      "location": {
        "cities": [
          "text"
        ],
        "states": [
          "text"
        ],
        "countryCodes": [
          "text"
        ]
      }
    },
    "questionIds": [
      "text"
    ],
    "technologies": [
      "stripe",
      "hubspot"
    ]
  },
  "createdAt": "2026-03-27T19:48:32.142Z",
  "updatedAt": "2026-03-27T19:48:32.142Z"
}

Delete a company list

delete

Soft-delete a company list. The list will no longer appear in list results. This operation cannot be undone via the API.

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 company list to delete

Responses

204

Company list deleted successfully

401

Unauthorized - Invalid or missing API key

application/json

404

Company list not found

application/json

500

Internal Server Error

application/json

delete

/v1/companies/lists/{listId}

HTTPcURLJavaScriptPython

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

No content

Get companies in a list

get

Retrieve companies that belong to a company list, paginated. Companies are returned with basic profile information and optional LinkedIn enrichment data.

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 company list

Query parameters

limitinteger · min: 1 · max: 100Optional

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

Default: 25

offsetintegerOptional

Number of companies to skip for pagination (default 0)

Default: 0

Responses

200

Companies retrieved successfully

application/json

Paginated list of companies in a company list

totalintegerRequired

Total number of companies in the list

Example: 150

limitintegerRequired

Maximum results per page

Example: 25

offsetintegerRequired

Number of results skipped

Example: 0

hasMorebooleanRequired

Whether more results are available

Example: true

401

Unauthorized - Invalid or missing API key

application/json

404

Company list not found

application/json

429

Too Many Requests - Rate limit exceeded

application/json

500

Internal Server Error

application/json

get

/v1/companies/lists/{listId}/companies

HTTPcURLJavaScriptPython

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

{
  "items": [
    {
      "id": "text",
      "domain": "example.com",
      "name": "Example Inc",
      "handle": "text",
      "website": "text",
      "industry": "Computer Software",
      "size": "51-200",
      "type": "text",
      "founded": 2015,
      "city": "text",
      "state": "text",
      "countryCode": "US",
      "enrichedData": {
        "liId": 1,
        "liFollowers": 1,
        "liFoundEmployees": 1
      }
    }
  ],
  "total": 150,
  "limit": 25,
  "offset": 0,
  "hasMore": true
}

Export a company list as CSV

post

Export all companies in a list as a CSV file. Returns a text/csv file with one row per company.

Fixed columns (always present): name, website

Optional firmographic columns — specify via the fields array in any order. Allowed values: industry, size, founded, city, state, country_code. Unknown values return 422.

Signal columns — specify signalTemplateIds to include two columns per matching subscription: {signal_name}_answer and {signal_name}_confidence. If signalTemplateIds is absent or empty, no signal columns are added.

The export is truncated to the first 10,000 companies. No credits are charged.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

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

Path parameters

listIdstring · uuidRequired

The unique identifier of the company list

Body

application/json

Optional parameters for the company list CSV export.

signalTemplateIdsstring · uuid[]Optional

IDs of signal templates whose subscriptions should be included as columns. Two columns are added per subscription: {signal_name}_answer and {signal_name}_confidence. If absent or empty, no signal columns are added.

Example: ["123e4567-e89b-12d3-a456-426614174000"]

Responses

200

CSV file streamed successfully

text/csv

Responsestring · binary

401

Unauthorized - Invalid or missing API key

application/json

404

Company list not found

application/json

422

Unprocessable Entity - Invalid field name or list exceeds 10,000 companies

application/json

429

Too Many Requests - Rate limit exceeded

application/json

500

Internal Server Error

application/json

post

/v1/companies/lists/{listId}/export

HTTPcURLJavaScriptPython

POST /v1/companies/lists/{listId}/export HTTP/1.1
Host: api.saber.app
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 45

{
  "fields": [
    "industry",
    "size",
    "country_code"
  ]
}

Firmographic columns, no signalsFirmographic columns + two signal subscriptions

name,website,industry,size,is_hiring_answer,is_hiring_confidence
Acme Corp,acme.com,Software,51-200,true,0.92
Globex,globex.com,Manufacturing,201-500,,

Search companies matching a filter

post

Returns up to 50 companies that match the given filter criteria.

Results are cached for 5 minutes per unique filter. Identical filters will return cached data during this window.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

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

Body

application/json

Responses

200

Companies matching the filter

application/json

totalintegerRequired

Total number of companies matching the filter

Example: 1234

400

Bad Request - Invalid filter parameters

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

post

/v1/companies/search

HTTPcURLJavaScriptPython

POST /v1/companies/search HTTP/1.1
Host: api.saber.app
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 111

{
  "filter": {
    "industries": [
      "Computer Software"
    ],
    "sizes": [
      "51-200",
      "201-500"
    ],
    "location": {
      "countryCodes": [
        "US"
      ]
    }
  }
}

{
  "companies": [
    {
      "id": "text",
      "domain": "example.com",
      "name": "Example Inc",
      "handle": "text",
      "website": "text",
      "industry": "Computer Software",
      "size": "51-200",
      "type": "text",
      "founded": 2015,
      "city": "text",
      "state": "text",
      "countryCode": "US",
      "enrichedData": {
        "liId": 1,
        "liFollowers": 1,
        "liFoundEmployees": 1
      }
    }
  ],
  "total": 1234
}