> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bouncedetector.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Batch

> Submit emails for batch verification.

Submit up to 1000 emails for batch verification. Returns a batch ID to poll for results via [Get Batch Results](/api-reference/endpoint/batch-get).

## Request

<ParamField body="emails" type="string[]" required>
  Array of email addresses (1–1000 items)
</ParamField>

## Response

<ResponseField name="id" type="string">
  Batch ID (use for GET /api/v1/batches/:id)
</ResponseField>

<ResponseField name="status" type="string">
  `pending`, `processing`, `completed`, `failed`, or `cancelled`
</ResponseField>

<ResponseField name="totalCount" type="number">
  Total emails in batch
</ResponseField>

<ResponseField name="processedCount" type="number">
  Emails processed so far
</ResponseField>

<ResponseField name="message" type="string">
  Hint for next steps
</ResponseField>

<RequestExample>
  ```bash Request theme={null}
  curl -X POST "https://api.bouncedetector.com/api/v1/verify/batch" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"emails": ["user1@example.com", "user2@example.com", "user3@example.com"]}'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "507f1f77bcf86cd799439011",
    "status": "pending",
    "totalCount": 3,
    "processedCount": 0,
    "message": "Batch job created. Use GET /api/v1/batches/:id to check status."
  }
  ```
</ResponseExample>


## OpenAPI

````yaml POST /api/v1/verify/batch
openapi: 3.1.0
info:
  title: BounceDetector API
  description: >-
    Email verification API. All endpoints require API key authentication via
    Bearer token.
  version: 1.0.0
servers:
  - url: https://api.bouncedetector.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Verification
    description: Single and bulk email verification
  - name: Batch
    description: Batch job management
paths:
  /api/v1/verify/batch:
    post:
      tags:
        - Batch
      summary: Create batch verification
      description: >-
        Submit up to 1000 emails for batch verification. Returns a batch ID to
        poll for results.
      operationId: createBatch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - emails
              properties:
                emails:
                  type: array
                  items:
                    type: string
                    format: email
                  minItems: 1
                  maxItems: 1000
                  example:
                    - a@test.com
                    - b@test.com
                    - c@test.com
            examples:
              small:
                summary: Small batch (3 emails)
                value:
                  emails:
                    - user1@example.com
                    - user2@example.com
                    - user3@example.com
              large:
                summary: Larger batch
                value:
                  emails:
                    - contact@company.com
                    - support@company.com
                    - sales@company.com
                    - info@company.com
      responses:
        '201':
          description: Batch job created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Batch ID (use for GET /batches/:id)
                  status:
                    type: string
                    enum:
                      - pending
                      - processing
                      - completed
                      - failed
                      - cancelled
                  totalCount:
                    type: integer
                  processedCount:
                    type: integer
                    default: 0
                  message:
                    type: string
              example:
                id: 507f1f77bcf86cd799439011
                status: pending
                totalCount: 3
                processedCount: 0
                message: >-
                  Batch job created. Use GET /api/v1/batches/:id to check
                  status.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: Plan limit exceeded or no active subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                statusCode: 402
                message: Plan limit exceeded
components:
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Your API key (e.g. bdt_abc123...). Obtain from the dashboard.

````