# Create Company Enrichment

`POST https://api.getprospect.com/v2/companies/enrichments`

Starts a job that matches up to 10,000 companies (by LinkedIn URL, domain or name) against GetProspect. Free: no credits. The job runs at once and the answer carries no estimate: poll it at `Location` (`GET /v2/jobs/{id}`) or read it at `GET /v2/enrichments/{id}`, or subscribe once to `job.finished` with `POST /v2/webhooks`. A row with none of the three is accepted and counted under `counts.invalid`. At most 5 enrichments are active per workspace. With an `Idempotency-Key`, a retry answers the job it created. 1 `jobs` rate-limit unit.

> **How are credits spent?**
>
> Company enrichment jobs are free.

## How the job works

Send up to **10,000** rows, the same items as
[Company Bulk Enrich](https://getprospect.com/api-docs/company-bulk-enrich.md) without `id` and
`linkedin_id` (`domain`, `name` or `linkedin_url`), each with an optional
`identifier` of yours. The answer is `202` with the job and
`Location: /v2/jobs/{id}`; the job is already running. A row with no usable
lookup is kept and reported as `invalid`.

Poll the job or subscribe to `job.finished`, then page the results with
[Get Enrichment Results](https://getprospect.com/api-docs/enrichments-results.md): one item per row in
request order, `matched` rows with the same `company` object the sync bulk
enrich returns. See [Bulk jobs: poll or webhook](https://getprospect.com/api-docs/bulk-jobs.md).


## Authentication

Pass your API key in the `x-api-key` header.

## Body parameters

- `name` (string, optional, max length: 128): A label for the job.
- `data` (object[], required): Array of company lookup rows (1-10000). Each row is matched independently.
  - `identifier` (string, optional, max length: 128): Client-supplied correlation key echoed back with the row result. If omitted, the row index is used.
  - `linkedin_url` (string, optional, max length: 512): The LinkedIn company URL.
  - `domain` (string, optional, max length: 512): The company domain.
  - `name` (string, optional, max length: 512): The company name.

## Example request

```bash
curl --request POST \
  --url https://api.getprospect.com/v2/companies/enrichments \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "name": "Target accounts",
  "data": [
    {
      "identifier": "acct-1",
      "domain": "acme.com"
    },
    {
      "identifier": "acct-2",
      "name": "Globex"
    },
    {
      "identifier": "acct-3",
      "linkedin_url": "https://linkedin.com/company/initech"
    }
  ]
}
'
```

## Response 202

The job, `matching`.

```json
{
  "success": true,
  "data": {
    "id": "6703f1c2a9e4b5d6c7f80931",
    "type": "companies",
    "name": "Target accounts",
    "source": "api",
    "status": "matching",
    "stopped_reason": null,
    "options": {
      "enrich_email": false,
      "enrich_phone": false
    },
    "progress": {
      "percent": 10,
      "done": 1,
      "total": 3
    },
    "counts": {
      "rows": 3,
      "matched": 1,
      "not_matched": 0,
      "invalid": 0,
      "emails_found": 0,
      "phones_found": 0
    },
    "credits_used": {
      "email": 0,
      "phone": 0
    },
    "created_at": "2026-10-17T10:00:00.000Z",
    "started_at": "2026-10-17T10:00:00.000Z",
    "finished_at": null,
    "results_expires_at": null,
    "links": {
      "self": "/v2/enrichments/6703f1c2a9e4b5d6c7f80931",
      "job": "/v2/jobs/6703f1c2a9e4b5d6c7f80931",
      "results": null,
      "csv": null,
      "jsonl": null
    }
  },
  "metadata": {
    "timestamp": "2026-10-05T09:00:00.000Z"
  }
}
```

## Response 400

Invalid body or `Idempotency-Key`, more than 10,000 rows, or no row with a usable identifier combination (`VALIDATION_ERROR`). A row without one is otherwise accepted and ends in `counts.invalid`.

```json
{
  "success": false,
  "data": null,
  "metadata": {
    "timestamp": "2026-10-05T09:00:00.000Z"
  },
  "errors": [
    {
      "name": "VALIDATION_ERROR",
      "message": "data must contain no more than 10000 elements",
      "payload": {
        "field": "data",
        "code": "out_of_range",
        "constraints": {
          "arrayMaxSize": "data must contain no more than 10000 elements"
        }
      }
    }
  ]
}
```

## Response 401

Missing, unknown or inactive credentials (`UNAUTHORIZED`).

## Response 409

`CONFLICT`: 5 enrichments are already active in the workspace (`limit_reached`, `payload.limit`), or the `Idempotency-Key` was used for another request (`idempotency_key_reused`), or its first request is still running (`idempotency_in_progress`, `Retry-After: 2`).

```json
{
  "success": false,
  "data": null,
  "metadata": {
    "timestamp": "2026-10-05T09:00:00.000Z"
  },
  "errors": [
    {
      "name": "CONFLICT",
      "message": "The workspace already has 5 active enrichments; the limit is 5.",
      "payload": {
        "code": "limit_reached",
        "limit": 5
      }
    }
  ]
}
```

## Response 429

Over the `jobs` rate limit (`RATE_LIMIT`); wait `Retry-After` seconds. Sent only where rate limits are enforced for the caller channel.

## Response 500

Unexpected server error.