Company Lists
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 enrichment process (LinkedIn followers, employee counts, etc.) — this typically completes within minutes to hours.
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.
Authorization
ApiKeyAuth 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.
A human-readable name for the imported list (1–200 characters)
1 <= length <= 200Describes the external source to import companies from
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/companies/lists/import" \ -H "Content-Type: application/json" \ -d '{ "name": "HubSpot — Technology companies", "source": { "type": "hubspot", "filter": { "propertyName": "industry", "operator": "EQ", "value": "Technology" } } }'{ "id": "string", "name": "string", "prompt": "string", "filter": { "domains": [ "string" ], "names": [ "string" ], "handles": [ "string" ], "websites": [ "string" ], "industries": [ "string" ], "sizes": [ "string" ], "types": [ "string" ], "founded": { "before": 0, "after": 0 }, "location": { "cities": [ "string" ], "states": [ "string" ], "countryCodes": [ "string" ] }, "exclude": { "industries": [ "string" ], "sizes": [ "string" ], "types": [ "string" ], "domains": [ "string" ], "location": { "cities": [ "string" ], "states": [ "string" ], "countryCodes": [ "string" ] } }, "questionIds": [ "string" ], "technologies": [ "string" ] }, "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z", "unresolvedDomains": [ "string" ]}Returns an estimate of how many companies 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" before they commit. Blur-mode counts are estimates: list
creation charges based on the same estimate, and the final list size
can differ slightly. For filters without technologies the count is a
fast database query (always free, and exact).
Results are cached for 5 minutes per caller.
Authorization
ApiKeyAuth 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.
Criteria for filtering companies
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/companies/lists/count-preview" \ -H "Content-Type: application/json" \ -d '{ "filter": { "technologies": [ "stripe" ], "location": { "countryCodes": [ "NL" ] } } }'{ "count": 0, "credits": 0}Retrieve a paginated list of company lists belonging to the authenticated caller.
Authorization
ApiKeyAuth API key authentication using Bearer token. Format: sk_live_ followed by a secure random string.
In: header
Query Parameters
Maximum number of lists to return (1–100, default 20)
1 <= value <= 10020Number of lists to skip for pagination (default 0)
0 <= value0Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/companies/lists"{ "items": [ { "id": "string", "name": "string", "prompt": "string", "filter": { "domains": [ "string" ], "names": [ "string" ], "handles": [ "string" ], "websites": [ "string" ], "industries": [ "string" ], "sizes": [ "string" ], "types": [ "string" ], "founded": { "before": 0, "after": 0 }, "location": { "cities": [ "string" ], "states": [ "string" ], "countryCodes": [ "string" ] }, "exclude": { "industries": [ "string" ], "sizes": [ "string" ], "types": [ "string" ], "domains": [ "string" ], "location": { "cities": [ "string" ], "states": [ "string" ], "countryCodes": [ "string" ] } }, "questionIds": [ "string" ], "technologies": [ "string" ] }, "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z" } ], "total": 0, "limit": 0, "offset": 0, "hasMore": true}Create a named company list with a filter definition. The filter criteria determine which companies belong to the list.
Creating a list whose filter includes technologies charges
1 credit per matched company to reveal the matching companies —
charged once at creation; subsequent reads of the list are free.
The charge is based on the match-count estimate at creation time;
blur-mode counting, deduplication, and the fetch page cap mean the
final list size can differ slightly from the amount charged.
POST /v1/companies/lists/count-preview returns the same free
estimate — call it first to show "X companies match, ~Y credits"
before committing. Lists without a technologies filter are free to
create.
Results are cached for 5 minutes per caller. Mutations (create, update, delete) automatically invalidate the cache for the authenticated caller.
Authorization
ApiKeyAuth 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.
A human-readable name for the list (1–200 characters)
1 <= length <= 200Criteria for filtering companies
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/companies/lists" \ -H "Content-Type: application/json" \ -d '{ "name": "Mid-size US SaaS companies", "filter": { "industries": [ "Computer Software" ], "sizes": [ "51-200", "201-500" ], "location": { "countryCodes": [ "US" ] } } }'{ "id": "string", "name": "string", "prompt": "string", "filter": { "domains": [ "string" ], "names": [ "string" ], "handles": [ "string" ], "websites": [ "string" ], "industries": [ "string" ], "sizes": [ "string" ], "types": [ "string" ], "founded": { "before": 0, "after": 0 }, "location": { "cities": [ "string" ], "states": [ "string" ], "countryCodes": [ "string" ] }, "exclude": { "industries": [ "string" ], "sizes": [ "string" ], "types": [ "string" ], "domains": [ "string" ], "location": { "cities": [ "string" ], "states": [ "string" ], "countryCodes": [ "string" ] } }, "questionIds": [ "string" ], "technologies": [ "string" ] }, "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z"}Retrieve a single company list including its name and filter definition.
Authorization
ApiKeyAuth API key authentication using Bearer token. Format: sk_live_ followed by a secure random string.
In: header
Path Parameters
The unique identifier of the company list
Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/companies/lists/string"{ "id": "string", "name": "string", "prompt": "string", "filter": { "domains": [ "string" ], "names": [ "string" ], "handles": [ "string" ], "websites": [ "string" ], "industries": [ "string" ], "sizes": [ "string" ], "types": [ "string" ], "founded": { "before": 0, "after": 0 }, "location": { "cities": [ "string" ], "states": [ "string" ], "countryCodes": [ "string" ] }, "exclude": { "industries": [ "string" ], "sizes": [ "string" ], "types": [ "string" ], "domains": [ "string" ], "location": { "cities": [ "string" ], "states": [ "string" ], "countryCodes": [ "string" ] } }, "questionIds": [ "string" ], "technologies": [ "string" ] }, "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z"}Soft-delete a company list. The list will no longer appear in list results. This operation cannot be undone via the API.
Authorization
ApiKeyAuth API key authentication using Bearer token. Format: sk_live_ followed by a secure random string.
In: header
Path Parameters
The unique identifier of the company list to delete
Response Body
application/json
application/json
application/json
curl -X DELETE "https://example.com/v1/companies/lists/string"Update the name and/or filter of an existing company list. Both fields are required in the request body (full replacement, not a patch).
Authorization
ApiKeyAuth API key authentication using Bearer token. Format: sk_live_ followed by a secure random string.
In: header
Path Parameters
The unique identifier of the company list to update
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Updated name for the list (1–200 characters)
1 <= length <= 200Criteria for filtering companies
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X PUT "https://example.com/v1/companies/lists/string" \ -H "Content-Type: application/json" \ -d '{ "name": "Updated list name", "filter": { "industries": [ "Internet" ], "sizes": [ "201-500" ] } }'{ "id": "string", "name": "string", "prompt": "string", "filter": { "domains": [ "string" ], "names": [ "string" ], "handles": [ "string" ], "websites": [ "string" ], "industries": [ "string" ], "sizes": [ "string" ], "types": [ "string" ], "founded": { "before": 0, "after": 0 }, "location": { "cities": [ "string" ], "states": [ "string" ], "countryCodes": [ "string" ] }, "exclude": { "industries": [ "string" ], "sizes": [ "string" ], "types": [ "string" ], "domains": [ "string" ], "location": { "cities": [ "string" ], "states": [ "string" ], "countryCodes": [ "string" ] } }, "questionIds": [ "string" ], "technologies": [ "string" ] }, "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z"}Retrieve companies that belong to a company list, paginated. Companies are returned with basic profile information and optional LinkedIn enrichment data.
Authorization
ApiKeyAuth API key authentication using Bearer token. Format: sk_live_ followed by a secure random string.
In: header
Path Parameters
The unique identifier of the company list
Query Parameters
Maximum number of companies to return (1–100, default 25)
1 <= value <= 10025Number of companies to skip for pagination (default 0)
0 <= value0Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/companies/lists/string/companies"{ "items": [ { "id": "string", "domain": "string", "name": "string", "handle": "string", "website": "string", "industry": "string", "size": "string", "type": "string", "founded": 0, "city": "string", "state": "string", "countryCode": "string", "enrichedData": { "liId": 0, "liFollowers": 0, "liFoundEmployees": 0 } } ], "total": 0, "limit": 0, "offset": 0, "hasMore": true}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.
Authorization
ApiKeyAuth API key authentication using Bearer token. Format: sk_live_ followed by a secure random string.
In: header
Path Parameters
The unique identifier of the company list
uuidRequest Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Optional parameters for the company list CSV export.
Optional firmographic columns to include after the fixed name and
website columns, in the order specified. Unknown values return 422.
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.
Response Body
text/csv
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/companies/lists/497f6eca-6276-4993-bfeb-53cbbbba6f08/export" \ -H "Content-Type: application/json" \ -d '{ "fields": [ "industry", "size", "country_code" ] }'"name,website,industry,size,is_hiring_answer,is_hiring_confidence\nAcme Corp,acme.com,Software,51-200,true,0.92\nGlobex,globex.com,Manufacturing,201-500,,\n"