# Create Email Verification

`POST https://api.getprospect.com/v2/email-verifications`

Create a bulk email verification job from a list of up to 10,000 addresses (`data.emails`). Costs 1 email verification credit per unique valid-syntax address (`counts.billable`), charged when the job starts; the unverified remainder is refunded on cancel or failure. The job counts the list and then starts on its own, usually within a minute; when the balance is short of `counts.billable` it stays `awaiting_confirmation` and starts once the credits are there (or with `email_verifications_start`). Answers 202 with the job and `Location: /v2/jobs/{id}`; poll it, or subscribe once to `job.finished` with `POST /v2/webhooks`, then read `GET /v2/email-verifications/{id}/results` (one item per address in request order). `data.file_key` (an uploaded file) is for the App: that job parks at `awaiting_confirmation` for `email_verifications_start`. With an `Idempotency-Key`, a retry of the same request answers the job it created instead of creating another. 1 `jobs` rate-limit unit.

> **How are credits spent?**
>
> 1 email verification credit per unique valid-syntax address, charged when
> the job starts; the unverified remainder is refunded on cancel or failure.
> Duplicates and addresses with invalid syntax are free.

## How the job works

Send up to **10,000** addresses in `data.emails`. The answer is `202` with the
job and `Location: /v2/jobs/{id}`. The job first counts the list, then starts
on its own, usually within a minute. If the balance is short of the billable
count, it waits in `awaiting_confirmation` and starts once the credits are
there.

When it is done, page [Get Email Verification Results](https://getprospect.com/api-docs/email-verifications-results.md):
one item per address in request order (a duplicate appears at each of its
positions) with `status`, `provider`, `domain` and `free_email`. Addresses with
invalid syntax come back `invalid` without being checked.

Poll the job or subscribe to `job.finished` as described in
[Bulk jobs: poll or webhook](https://getprospect.com/api-docs/bulk-jobs.md). `data.file_key` is for files
uploaded in the app; use `data.emails` from the API.


## Authentication

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

## Body parameters

- `data` (object, required): What to verify: a list of addresses (`emails`), or in the App an uploaded file (`file_key`).
  - `emails` (string[], optional): The addresses to verify, 1-10,000, each at most 320 characters. Exactly one of `emails` / `file_key`. The job starts on its own once counted; repeated addresses are charged once and answered at each position in `GET /v2/email-verifications/{id}/results`. Example: `["emily.carter.sample@intercom.com","liam.novak.sample@getprospect.com"]`
  - `file_key` (string, optional, max length: 512): App only: the S3 key on the imports bucket, as returned by the /aws/pre-signed upload flow. Exactly one of `emails` / `file_key`. The job parks at `awaiting_confirmation` for `email_verifications_start`.
  - `name` (string, optional, max length: 128): Display name; defaults to the uploaded file's name, or to the date for `emails`.
  - `email_column` (integer, optional, min: 0): With `file_key` only. Zero-based index of the email column (from inspect), range-checked against the file. Optional: without it the one column that holds addresses is used; a file with none or several answers 400 `missing_field` with `email_column_candidates` in `payload`.
  - `source` (enum, optional): With `file_key` only: how the emails arrived - a paste still uploads a generated CSV. Defaults to `file`; a job from `emails` reads `source: api`. Allowed values: `file`, `paste`.

## Example request

```bash
curl --request POST \
  --url https://api.getprospect.com/v2/email-verifications \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "data": {
    "emails": [
      "emily.carter.sample@intercom.com",
      "liam.novak.sample@getprospect.com"
    ],
    "name": "CRM sync"
  }
}
'
```

## Response 202

The job, `queued`.

```json
{
  "success": true,
  "data": {
    "id": "6703f1c2a9e4b5d6c7f80912",
    "name": "CRM sync",
    "source": "api",
    "status": "queued",
    "stopped_reason": null,
    "counts": {
      "total_rows": 0,
      "parsed_rows": 0,
      "billable": 0,
      "duplicates": 0,
      "invalid_syntax": 0,
      "blank": 0,
      "verified": 0,
      "valid": 0,
      "invalid": 0,
      "accept_all": 0,
      "unknown": 0
    },
    "batches": {
      "total": 0,
      "done": 0
    },
    "progress_percent": 0,
    "result_files": null,
    "result_expires_at": null,
    "results_expires_at": null,
    "links": {
      "self": "/v2/email-verifications/6703f1c2a9e4b5d6c7f80912",
      "job": "/v2/jobs/6703f1c2a9e4b5d6c7f80912",
      "results": null
    },
    "owner": {
      "id": "64b7c0ffee0123456789abcd",
      "first_name": "Emily",
      "last_name": "Carter",
      "photo_url": null
    },
    "created_by": {
      "id": "64b7c0ffee0123456789abcd",
      "name": "Emily Carter"
    },
    "error": null,
    "created_at": "2026-10-08T14:05:12.000Z",
    "updated_at": "2026-10-08T14:05:12.000Z"
  },
  "metadata": {
    "timestamp": "2026-10-08T14:07:55.000Z"
  }
}
```

## Response 400

Invalid body or `Idempotency-Key`: both or neither of `emails` / `file_key` (`conflicting_fields` / `missing_field`), more than 10,000 or a blank address, or, with `file_key`, an unreadable or empty file, `email_column` out of range, or no `email_column` for a file with none or several address columns (`VALIDATION_ERROR`, `missing_field` with `email_column_candidates`).

```json
{
  "success": false,
  "data": null,
  "metadata": {
    "timestamp": "2026-10-08T14:07:55.000Z"
  },
  "errors": [
    {
      "name": "VALIDATION_ERROR",
      "message": "emails and file_key exclude each other: send exactly one of them",
      "payload": {
        "field": "data.emails",
        "code": "conflicting_fields",
        "received_value": [
          "emily.carter.sample@intercom.com"
        ],
        "received_type": "object",
        "constraints": {
          "conflictingFields": "emails and file_key exclude each other: send exactly one of them"
        }
      }
    }
  ]
}
```

## Response 401

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

## Response 403

The file belongs to another workspace (`FORBIDDEN`).

## Response 409

The `Idempotency-Key` was used for another request (`CONFLICT`, `idempotency_key_reused`).

```json
{
  "success": false,
  "data": null,
  "metadata": {
    "timestamp": "2026-10-08T14:07:55.000Z"
  },
  "errors": [
    {
      "name": "CONFLICT",
      "message": "This Idempotency-Key was already used with a different request or by another principal.",
      "payload": {
        "code": "idempotency_key_reused"
      }
    }
  ]
}
```

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