Company Lists

Import a company list from HubSpot

POST
/v1/companies/lists/import

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

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

Length1 <= length <= 200
source*

Describes 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": "Mid-size US SaaS companies",  "prompt": "string",  "filter": {    "domains": [      "string"    ],    "names": [      "string"    ],    "handles": [      "string"    ],    "websites": [      "string"    ],    "industries": [      "Computer Software",      "Internet"    ],    "sizes": [      "51-200",      "201-500"    ],    "types": [      "string"    ],    "founded": {      "before": 0,      "after": 0    },    "location": {      "cities": [        "string"      ],      "states": [        "string"      ],      "countryCodes": [        "US",        "GB"      ]    },    "exclude": {      "industries": [        "string"      ],      "sizes": [        "string"      ],      "types": [        "string"      ],      "domains": [        "string"      ],      "location": {        "cities": [          "string"        ],        "states": [          "string"        ],        "countryCodes": [          "string"        ]      }    },    "questionIds": [      "string"    ],    "technologies": [      "stripe",      "hubspot"    ]  },  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z",  "unresolvedDomains": [    "broken-domain.io"  ]}
{  "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"    }  }}
{  "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"    }  }}

Preview expected company count and credit cost

POST
/v1/companies/lists/count-preview

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.

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.

filter*

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": 142,  "credits": 142}
{  "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"    }  }}

List company lists

GET
/v1/companies/lists

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

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

application/json

curl -X GET "https://example.com/v1/companies/lists"
{  "items": [    {      "id": "string",      "name": "Mid-size US SaaS companies",      "prompt": "string",      "filter": {        "domains": [          "string"        ],        "names": [          "string"        ],        "handles": [          "string"        ],        "websites": [          "string"        ],        "industries": [          "Computer Software",          "Internet"        ],        "sizes": [          "51-200",          "201-500"        ],        "types": [          "string"        ],        "founded": {          "before": 0,          "after": 0        },        "location": {          "cities": [            "string"          ],          "states": [            "string"          ],          "countryCodes": [            "US",            "GB"          ]        },        "exclude": {          "industries": [            "string"          ],          "sizes": [            "string"          ],          "types": [            "string"          ],          "domains": [            "string"          ],          "location": {            "cities": [              "string"            ],            "states": [              "string"            ],            "countryCodes": [              "string"            ]          }        },        "questionIds": [          "string"        ],        "technologies": [          "stripe",          "hubspot"        ]      },      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z"    }  ],  "total": 5,  "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"    }  }}
{  "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 company list

POST
/v1/companies/lists

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.

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

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

Length1 <= length <= 200
filter*

Criteria 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": "Mid-size US SaaS companies",  "prompt": "string",  "filter": {    "domains": [      "string"    ],    "names": [      "string"    ],    "handles": [      "string"    ],    "websites": [      "string"    ],    "industries": [      "Computer Software",      "Internet"    ],    "sizes": [      "51-200",      "201-500"    ],    "types": [      "string"    ],    "founded": {      "before": 0,      "after": 0    },    "location": {      "cities": [        "string"      ],      "states": [        "string"      ],      "countryCodes": [        "US",        "GB"      ]    },    "exclude": {      "industries": [        "string"      ],      "sizes": [        "string"      ],      "types": [        "string"      ],      "domains": [        "string"      ],      "location": {        "cities": [          "string"        ],        "states": [          "string"        ],        "countryCodes": [          "string"        ]      }    },    "questionIds": [      "string"    ],    "technologies": [      "stripe",      "hubspot"    ]  },  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z"}
{  "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 company list by ID

GET
/v1/companies/lists/{listId}

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

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 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": "Mid-size US SaaS companies",  "prompt": "string",  "filter": {    "domains": [      "string"    ],    "names": [      "string"    ],    "handles": [      "string"    ],    "websites": [      "string"    ],    "industries": [      "Computer Software",      "Internet"    ],    "sizes": [      "51-200",      "201-500"    ],    "types": [      "string"    ],    "founded": {      "before": 0,      "after": 0    },    "location": {      "cities": [        "string"      ],      "states": [        "string"      ],      "countryCodes": [        "US",        "GB"      ]    },    "exclude": {      "industries": [        "string"      ],      "sizes": [        "string"      ],      "types": [        "string"      ],      "domains": [        "string"      ],      "location": {        "cities": [          "string"        ],        "states": [          "string"        ],        "countryCodes": [          "string"        ]      }    },    "questionIds": [      "string"    ],    "technologies": [      "stripe",      "hubspot"    ]  },  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z"}
{  "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 company list

DELETE
/v1/companies/lists/{listId}

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

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

Response Body

application/json

application/json

application/json

curl -X DELETE "https://example.com/v1/companies/lists/string"
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"    }  }}

Update a company list

PUT
/v1/companies/lists/{listId}

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

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Updated name for the list (1–200 characters)

Length1 <= length <= 200
filter*

Criteria 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": "Mid-size US SaaS companies",  "prompt": "string",  "filter": {    "domains": [      "string"    ],    "names": [      "string"    ],    "handles": [      "string"    ],    "websites": [      "string"    ],    "industries": [      "Computer Software",      "Internet"    ],    "sizes": [      "51-200",      "201-500"    ],    "types": [      "string"    ],    "founded": {      "before": 0,      "after": 0    },    "location": {      "cities": [        "string"      ],      "states": [        "string"      ],      "countryCodes": [        "US",        "GB"      ]    },    "exclude": {      "industries": [        "string"      ],      "sizes": [        "string"      ],      "types": [        "string"      ],      "domains": [        "string"      ],      "location": {        "cities": [          "string"        ],        "states": [          "string"        ],        "countryCodes": [          "string"        ]      }    },    "questionIds": [      "string"    ],    "technologies": [      "stripe",      "hubspot"    ]  },  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z"}
{  "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 companies in a list

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

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

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

Query Parameters

limit?integer

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

Default25
Range1 <= value <= 100
offset?integer

Number of companies to skip for pagination (default 0)

Default0
Range0 <= value

Response 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": "example.com",      "name": "Example Inc",      "handle": "string",      "website": "string",      "industry": "Computer Software",      "size": "51-200",      "type": "string",      "founded": 2015,      "city": "string",      "state": "string",      "countryCode": "US",      "enrichedData": {        "liId": 0,        "liFollowers": 0,        "liFoundEmployees": 0      }    }  ],  "total": 150,  "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"    }  }}
{  "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"    }  }}

Export a company list as CSV

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

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

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

fields?array<>

Optional firmographic columns to include after the fixed name and website columns, in the order specified. Unknown values return 422.

signalTemplateIds?array<>

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

Search companies matching a filter

POST
/v1/companies/search

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.

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.

filter*

Criteria for filtering companies

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/companies/search" \  -H "Content-Type: application/json" \  -d '{    "filter": {      "industries": [        "Computer Software"      ],      "sizes": [        "51-200",        "201-500"      ],      "location": {        "countryCodes": [          "US"        ]      }    }  }'
{  "companies": [    {      "id": "string",      "domain": "example.com",      "name": "Example Inc",      "handle": "string",      "website": "string",      "industry": "Computer Software",      "size": "51-200",      "type": "string",      "founded": 2015,      "city": "string",      "state": "string",      "countryCode": "US",      "enrichedData": {        "liId": 0,        "liFollowers": 0,        "liFoundEmployees": 0      }    }  ],  "total": 1234}
{  "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"    }  }}

On this page

Import a company list from HubSpotPreview expected company count and credit costList company listsCreate a company listGet a company list by IDDelete a company listUpdate a company listGet companies in a listExport a company list as CSVSearch companies matching a filter