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

# Create batch verification task

> Create a batch verification task for up to 10,000 emails.

## Overview

Create a batch verification task for up to 10,000 emails. Processing runs asynchronously, and you can optionally provide a webhook for completion notifications.

## POST /api/v1/tasks

Purpose: create a batch verification task (up to 10,000 emails). Emails are grouped by domain and queued for processing. Optional webhook to receive completion callbacks.

### Request

Headers:

* `Content-Type: application/json`

Body:

* `emails` (array of string, required, max 10,000)
* `webhook_url` (string, optional, must be a valid URL)

Example request:

```bash theme={null}
curl -X POST \
  'https://api.boltroute.ai/api/v1/tasks' \
  -H 'Content-Type: application/json' \
  -d '{
    "emails": ["user1@example.com", "user2@example.com"],
    "webhook_url": "https://example.com/webhook"
  }'
```

### Response

Status: `201 Created`

Example response:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "webhook_url": "https://example.com/webhook",
  "source": "frontend",
  "created_at": "2025-01-01T12:00:00Z",
  "email_count": 2,
  "domain_count": 1
}
```

Response fields:

* `id`: batch verification task UUID.
* `user_id`: derived from auth (may be null for dev keys).
* `webhook_url`: webhook URL stored for the batch verification task.
* `source`: indicates batch verification origin (`frontend` or `api_key`).
* `created_at`: batch verification creation timestamp.
* `email_count`: total emails submitted.
* `domain_count`: number of unique domains queued.

Notes:

* Credits are reserved at task creation for the full email count.
* Final charge equals the count of emails with a non-`unknown` status; `unknown` results are refunded once the task finishes.

Errors:

* `400` invalid payload (invalid emails, webhook URL, or >10,000 emails).
* `402` insufficient credit balance.
* `401` unauthorized.
* `429` rate limited.
* `500` internal error.