---
title: "Create a batch verification request."
method: POST
path: "/v1/requests"
---

# Create a batch verification request.

`POST /v1/requests`

## Request

- Base URL: `https://api.bounceless.io`
- URL: `https://api.bounceless.io/v1/requests`
- Auth: API key in header `X-Api-Key`

Creation returns 202. A replay with the same Idempotency-Key and body returns 200 with the same request.id.

## Headers

- `Idempotency-Key` string, required

## Request body

- BatchInput
  - `emails` string[], required

## Response `200`

Idempotent replay.

- BatchRequest
  - `request` RequestDescriptor, required
    - `id` string, uuid, required
    - `mode` string, required
    - `state` 'received' | 'validating' | 'queued' | 'running' | 'retrying' | 'degraded' | 'paused' | 'completed' | 'finalized' | 'failed_validation' | 'rejected_credit' | 'cancelled' | 'failed' | 'expired' | 'purged', required
    - `partial` boolean
    - `finalized` boolean
    - `countsMayChange` boolean
    - `createdAt` string, date-time, required
  - `counters` Counters, required
  - `resultCounters` ResultCounters: Whole-list final result categories, returned by request detail; independent of search and pagination. Existing counters retain first-pass semantics.
    - `submittedCount` integer
    - `totalCount` integer
    - `validCount` integer
    - `catchAllCount` integer
    - `unknownCount` integer
    - `invalidCount` integer
    - `riskyCount` integer
    - `recheckCount` integer
    - `pendingCount` integer
    - `otherCount` integer
  - `summary` RequestSummary: Full-request aggregates, returned by GET /v1/requests/{id}. deliverableRate is omitted when no address has resolved.
    - `checkedCount` integer, required: Resolved addresses: valid, invalid, risky, catch_all and unknown.
    - `deliverableCount` integer, required
    - `deliverableRate` number: deliverableCount / checkedCount as a ratio, 4 decimals.
    - `recheckCount` integer, required: Rows across the whole request requiring another check (deferred or recheck_scheduled).
  - `replayed` boolean
  - `requestId` string, required

## Other responses

- `202`: Created.
- `400`: Error response.
- `401`: Error response.
- `402`: Error response.
- `404`: Error response.
- `422`: Error response.
- `429`: Rate limit exceeded.
- `503`: Error response.

---

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