Documentation

Get company

Last updated: 5 October 2026

Get a single company's full record directly by its id. Stateless — you do not need a prior search, and there is no result-set handle to manage. Billed per fetch.

GET/v1/companies/{company_id}

Authenticated with your x-api-key. See Authentication.

How it works

Every company search result carries an id. Pass it here to retrieve that company's complete record — the card fields plus description, specialties, office locations, organisation type, follower count and funding. You can also fetch any id you already hold; a prior search is not required.

There is one response shape and one price. The endpoint takes no options beyond the id.

The charge is deduped per `(api-key, company_id)` within a short window: a repeat fetch of the same company re-reads fresh data but charges 0. Only the charge is deduped — the data returned is always current.

Request

GET /v1/companies/{company_id}
Host: search-api.xverum.com
x-api-key: XVERUM-API-KEY

Path parameter

Parameter	Description
`company_id`	Opaque company id, e.g. from a `search_company_xverum` or `target: company` search result. Stable across sessions — an id you received in a previous search or session stays fetchable.

Example

curl "https://search-api.xverum.com/v1/companies/c1d2e3f4" \
  -H "x-api-key: XVERUM-API-KEY"

Response — 200 OK

Field	Type	Description
`social_url`	string \| null	Company social URL; `null` when none is on record for the company
`company_name`	string \| null	Company name; `null` when no name is on record for the company
`slogan`	string \| null	Short tagline; `null` when none is on record
`headquarters`	string \| null	Headquarters as `City, Region`; `null` when no location is on record
`country_code`	string \| null	Lowercase country code of the headquarters; `null` when not known
`industry`	string \| null	Industry vertical; `null` when not known
`employees_num`	integer \| null	Employee count; `null` when not known
`website`	string \| null	Company website; `null` when none is on record
`founded`	integer \| null	Year the company was founded; `null` when not known
`evidence_summary`	string	How recently this record was verified, from its refresh date — `Verified last 30 days` through `Verified over 120 days ago`
`about_us`	string \| null	Company description; `null` when none is on record
`specialties`	string[]	Self-declared specialties; `[]` when none are on record
`locations`	`CompanyLocation[]`	Office addresses (see schema below); `[]` when none are on record
`type`	string \| null	Organisation type, e.g. `Privately Held`; `null` when not known
`social_followers`	integer \| null	Social follower count; `null` when not known
`funding`	integer \| null	Total raised, in USD; `null` until sourced
`credits_used`	integer	Credits deducted (`4`; `0` on a deduped retry)
`credits_remaining`	integer	Credits left after this call — a best-effort fresh read from billing; on a transient billing outage it falls back to the balance seen at auth time
`request_id`	string	Correlation id — also returned in the `X-Request-Id` header

Every field is always present in the JSON. A null means the value is not held for that company, never that it was withheld from this response. Employee lists are deliberately not part of this record — fetch people through the people search and profile endpoints.

CompanyLocation shape

Each entry in locations is one office address:

{
  "address": "123 Market St, Suite 400",
  "address_2": "San Francisco, CA 94103",
  "primary": true
}

Field	Type	Description
`address`	string \| null	Street address line; `null` when not on record for this office
`address_2`	string \| null	Second address line (city, region, postal code); `null` when not on record
`primary`	boolean \| null	Whether this is the primary office; `null` when not indicated

Example response

{
  "social_url": "https://www.linkedin.com/company/acme",
  "company_name": "Acme",
  "slogan": "Build better, ship faster",
  "headquarters": "San Francisco, CA",
  "country_code": "us",
  "industry": "software",
  "employees_num": 320,
  "website": "https://acme.example.com",
  "founded": 2014,
  "evidence_summary": "Verified last 30 days",
  "about_us": "Acme builds developer tooling for distributed systems...",
  "specialties": ["developer tools", "observability", "distributed systems"],
  "locations": [
    {
      "address": "123 Market St, Suite 400",
      "address_2": "San Francisco, CA 94103",
      "primary": true
    }
  ],
  "type": "Privately Held",
  "social_followers": 48213,
  "funding": 52000000,
  "credits_used": 4,
  "credits_remaining": 4992,
  "request_id": "1a2b3c4d5e6f7081"
}

Billing

Every fetch costs 4 credits, echoed back as credits_used; credits_remaining shows the balance left. A repeat fetch of the same company_id with the same API key within the dedup window charges 0 (you still get fresh data).

credits_remaining is read fresh from billing on each successful call and is best-effort: if billing is briefly unavailable it falls back to the balance seen at authentication. Treat it as an indicative post-call balance, not a settled ledger figure.

Errors

All /v1 errors use the structured envelope (see Authentication):

Status	`error.code`	Condition
`401`	`invalid_api_key`	Missing or invalid API key
`402`	`out_of_credits`	Out of credits — the envelope carries an `upgrade_url` to top up
`403`	`account_not_authorized`	Account not authorized
`404`	`company_not_found`	No company exists for the given `company_id`
`422`	`validation_error`	The `company_id` is empty or longer than 128 characters
`429`	`rate_limited`	Rate limit exceeded — see Rate limits
`502`	`upstream_unavailable`	An upstream dependency failed — retry shortly
`503`	`search_unavailable`	The company store is temporarily saturated or unreachable — retry shortly
`503`	`auth_unavailable`	Authentication is briefly unreachable — retry shortly

{
  "error": {
    "code": "company_not_found",
    "message": "No company for id 'c1d2e3f4'.",
    "request_id": "1a2b3c4d5e6f7081"
  }
}