Companies endpoints

List companies

GET /v1/companies returns {data, next_cursor}. Optional query fields are name, limit, and cursor. Name is a 1–200 character substring; limit defaults to 50 and must be 1–100. Unknown or repeated fields return 400.

curl --request GET "$HEADCOUNTLABS_BASE_URL/v1/companies?name=salesforce&limit=20" --header 'Authorization: Bearer <API_KEY>'

Search companies

curl --request POST "$HEADCOUNTLABS_BASE_URL/v1/companies/search" --header 'Authorization: Bearer <API_KEY>' --header 'Content-Type: application/json' --data-raw '{"name":"salesforce","limit":3}'

The body accepts optional name, two-letter country, status (active, retired, or merged), numeric limit (default 50, range 1–100), and cursor. The request body limit is 16,384 bytes; unknown fields are rejected. Response envelope: {data:[company], next_cursor}.

Read a company

GET /v1/companies/{companyId} returns {data: company}. The object contains company_id, name, nullable country, and status (active, retired, or merged). A merged ID redirects with HTTP 308 and a Location header.

curl --request GET "$HEADCOUNTLABS_BASE_URL/v1/companies/000edf59-a91d-4ab2-970f-a9c25f46060a" --header 'Authorization: Bearer <API_KEY>'

List jobs for a company

GET /v1/companies/{companyId}/jobs is available with an API key. It validates the canonical company ID, follows a merged-company redirect, and pages jobs with the jobs-list filters and response envelope. If supplied, company_id must match the path ID. Projection or company lookup failures can return 503.

Example response shape

{"data":[{"company_id":"000edf59-a91d-4ab2-970f-a9c25f46060a","name":"Salesforce","country":null,"status":"active"}],"next_cursor":null}

Company IDs are registry IDs

A company ID is a canonical UUID from the company projection, not an employer-domain or discovery key. Company list cursors pin a retained release; they do not return the jobs snapshot_watermark.