<!-- @generated by `npm run docs:gen` from src/content/docs/ — DO NOT EDIT. -->

# Get company

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](https://ask.xverum.com/docs/authentication.md).

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

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

```bash
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](https://ask.xverum.com/docs/search.md) and [profile](https://ask.xverum.com/docs/profiles.md) endpoints.

### CompanyLocation shape

Each entry in `locations` is one office address:

```json
{
  "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

```json
{
  "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](https://ask.xverum.com/docs/authentication.md)):

| 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](https://ask.xverum.com/docs/rate-limits.md) |
| `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 |

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