---
title: "Get companies in batch"
method: POST
path: "/api/v1/company/batch"
---

# Get companies in batch

`POST /api/v1/company/batch`

## Request

- Base URL: `https://api.fetchin.io`
- URL: `https://api.fetchin.io/api/v1/company/batch`
- Auth: API key in header `X-API-Key`

Fetch up to 50 companies in one call: `GET /api/v1/company` once per entry, with the same company object for each one found and a per-entry error for the others, in input order. The response is 200 even when some or all entries failed - read `found` or each entry's `error`. Billing: 1 credit per company returned; not-found and failed entries are free. The balance is checked for the whole batch (one credit per distinct entry) before any work, otherwise 402 QUOTA_EXHAUSTED. Validation errors are 400 and free. Rate limit: the batch uses your plan's per-second limit - the request takes one unit and each company after the first consumes one more from the same budget, waiting for it when the window is full, so a 50-company batch on a 5 req/s plan takes about 10 seconds. Entries that could not be fetched within 90 seconds come back with an error `RATE_LIMITED` (status 429) and are not billed.

## Request body

- object
  - `companies` string[], required: 1 to 50 companies, each a company page URL, a public identifier (universal name, e.g. `microsoft`) or a URN (`urn:li:fsd_company:1035`). Duplicates (same text, case-insensitive) are fetched, billed and returned once. Refused with a free 400: not an array or empty (`'companies' must be an array of 1 to 50 company URLs, public identifiers or URNs.`), more than 50 entries (`'companies' accepts at most 50 entries (received N).`), an entry that is not a non-empty string (`'companies[i]' must be a non-empty string.`).

## Response `200`

One result per distinct input, in input order. Billed 1 credit per entry returned with a `company`.

- object
  - `results` object[], required
    - `input` string, required: The entry as sent (trimmed).
    - `company` object: The same object as GET /api/v1/company returns. Billed 1 credit.
      - `id` string: Company URN (unique identifier)
      - `companyId` string: Numeric company id as a string
      - `name` string
      - `publicIdentifier` string: Public identifier (slug)
      - `url` string: Canonical company page URL
      - `websiteUrl` string: The company's own website
      - `domain` string: Website domain, minus a leading www.
      - `industry` string: Primary industry in the current taxonomy, matching the label shown on the company's public page
      - `industryV1` string: The same company's industry in the legacy taxonomy, for integrations that pinned the older labels. Not a renaming of `industry`: a company can sit under two unrelated entries in the two taxonomies, so this must not be used as a translation table. Prefer `industry`.
      - `employeeCount` number: Number of employees on the platform
      - `employeeCountRange` object
        - `start` number
        - `end` number: Absent for open-ended brackets
      - `foundedOn` object
        - `year` number
        - `month` number
        - `day` number
      - `headquarter` object
        - `line1` string
        - `line2` string
        - `city` string
        - `geographicArea` string: State / region
        - `postalCode` string
        - `country` string: ISO country code
        - `description` string: Office label, e.g. "Headquarters"
        - `headquarter` boolean: true for the headquarters entry
      - `locations` object[]
        - `line1` string
        - `line2` string
        - `city` string
        - `geographicArea` string: State / region
        - `postalCode` string
        - `country` string: ISO country code
        - `description` string: Office label, e.g. "Headquarters"
        - `headquarter` boolean: true for the headquarters entry
      - `followerCount` number
      - `logoUrl` string
      - `coverImageUrl` string: Cover/background image URL
      - `description` string
      - `specialities` string[]
      - `phone` string
      - `tagline` string
      - `companyType` string: The company's legal type as an English label, e.g. "Public Company", "Privately Held", "Self-Employed", "Sole Proprietorship", "Partnership", "Government Agency", "Nonprofit", "Educational".
      - `companyTypeCode` string: The same type as a stable code, e.g. "PUBLIC_COMPANY", "PRIVATELY_HELD". Branch on this rather than on the label.
      - `hashtags` string[]: Hashtags the page lists on its profile, in its order, without the `#`.
    - `error` object: Why this entry was not returned. Not billed.
      - `code` string, required: Same codes as a single call: `COMPANY_NOT_FOUND`, `RATE_LIMITED` (the batch ran out of time waiting for your rate limit), `INVALID_PARAMETER` / `INVALID_URN` (not a usable company input), `SERVICE_UNAVAILABLE`, `INTERNAL_ERROR`.
      - `message` string, required: Human-readable description. Do not branch on it.
      - `status` integer, required: The HTTP status a single GET /api/v1/company call would have returned for this entry.
  - `found` integer, required: Entries returned with a `company` - the credits billed.
  - `notFound` integer, required: Entries whose error has status 404.
  - `failed` integer, required: Every other error: rate limit, invalid entry, failure on our side.

## Other responses

- `400`: Bad request - a required parameter is missing or a value is invalid.
- `401`: Unauthorized - the X-API-Key header is missing or invalid.
- `402`: Payment required - you are out of credits (QUOTA_EXHAUSTED): the plan allowance for the current period is spent AND no pay-as-you-go credits are left. Buy pay-as-you-go credits (self-serve, https://fetchin.io/credits), upgrade your plan, or wait for renewal; retrying will not help and no Retry-After is sent. Distinct from the per-second rate limit, which is a 429 (RATE_LIMITED).
- `429`: Too many requests - your per-second rate limit (RATE_LIMITED) was exceeded. Back off and retry, honoring the Retry-After header. (Running out of credits is a separate 402 PaymentRequired / QUOTA_EXHAUSTED, and buying credits never raises this per-second limit.)
- `500`: Internal server error - an unexpected error occurred in our API. Safe to retry; contact support if it persists.

---

[API](https://skmtc.dev/fetchin/apis/fetchin-api.md) - [All operations](https://skmtc.dev/fetchin/apis/fetchin-api/llms.txt) - [OpenAPI document](https://skmtc.dev/fetchin/apis/fetchin-api/revisions/19a0b5d0320f?raw)