# Create People Enrichment

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

Starts a job that matches up to 10,000 people against GetProspect and, with `enrich_email` (the default), reveals and finds their emails; `enrich_phone` adds mobile numbers. 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 no usable identifier combination (a LinkedIn URL, an email, or first and last name with a company domain or name) is accepted and counted under `counts.invalid`. At least one email credit (and, with `enrich_phone`, one phone credit) is needed to start; the job charges as it runs and stops early, keeping what it found, if the balance runs out. 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?**
>
> As in the app's CSV enrichment, during the job: 1 email credit per person
> whose email is revealed and your workspace does not already own (the live
> finder charges only when it finds a valid email), 1 phone credit per mobile
> number found with `enrich_phone`. Re-enriching people you already revealed
> is free, and `enrich_email: false` matches people without spending anything.
> Starting needs at least one email credit; if the balance runs out the job
> stops early and keeps what it found.

## How the job works

Send up to **10,000** rows, the same items as
[People Bulk Enrich](https://getprospect.com/api-docs/people-bulk-enrich.md) without `id` and
`linkedin_id`, each with an optional `identifier` of yours. The answer is `202`
with the job and `Location: /v2/jobs/{id}`: the job is already running, with no
estimate to confirm and no start call.

Each row is matched by LinkedIn URL, email, or first and last name with a
company domain or name. With `enrich_email` the job reveals the stored email
of every matched person and runs the live email finder for rows with a name
and a company that we do not hold, or hold without a valid email, so it finds
more emails than the sync bulk enrich. A row with no usable lookup is kept and
reported as `invalid`; it never fails the request.

Then poll the job or subscribe to `job.finished`, and page the results with
[Get Enrichment Results](https://getprospect.com/api-docs/enrichments-results.md). The full walkthrough,
with a Node example and the bulk email finder recipe, is in
[Bulk jobs: poll or webhook](https://getprospect.com/api-docs/bulk-jobs.md).

Send an `Idempotency-Key` so a retried request answers the job it created
instead of starting a second one. At most 5 enrichments run per workspace at a
time; a sixth answers `409` with `limit_reached`.


## 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 person 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 person URL (e.g. "https://linkedin.com/in/john-doe").
  - `email` (string, optional, max length: 512): Reverse-lookup the person by their stored email address.
  - `first_name` (string, optional, max length: 512): Used together with last_name + company_domain or company_name.
  - `last_name` (string, optional, max length: 512): Used together with first_name + company_domain or company_name.
  - `company_domain` (string, optional, max length: 512): Company domain for the name+company composite lookup.
  - `company_name` (string, optional, max length: 512): Company name for the name+company composite lookup.
- `enrich_email` (boolean, optional, default: true): Enrich a verified business email for every matched row; set false to skip.
- `enrich_phone` (boolean, optional, default: false): If true, attempt to enrich a mobile phone for every matched row.

## Example request

```bash
curl --request POST \
  --url https://api.getprospect.com/v2/people/enrichments \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "name": "Q4 webinar leads",
  "data": [
    {
      "identifier": "crm-1",
      "linkedin_url": "https://linkedin.com/in/jane-doe"
    },
    {
      "identifier": "crm-2",
      "first_name": "John",
      "last_name": "Smith",
      "company_domain": "acme.com"
    },
    {
      "identifier": "crm-3",
      "email": "ann@globex.com"
    }
  ],
  "enrich_email": true,
  "enrich_phone": false
}
'
```

## Response 202

The job, `matching`.

```json
{
  "success": true,
  "data": {
    "id": "6703f1c2a9e4b5d6c7f80931",
    "type": "people",
    "name": "Q4 webinar leads",
    "source": "api",
    "status": "matching",
    "stopped_reason": null,
    "options": {
      "enrich_email": true,
      "enrich_phone": false
    },
    "progress": {
      "percent": 3,
      "done": 300,
      "total": 10000
    },
    "counts": {
      "rows": 10000,
      "matched": 180,
      "not_matched": 120,
      "invalid": 200,
      "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, `enrich_phone` without `enrich_email`, 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 402

A people job that reveals emails (or phones) and no credits of that kind left (`PAYMENT_REQUIRED`).

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