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

# Upload file

> Upload a file for batch verification.

## Overview

Upload a file of email addresses to start a batch verification task. Processing runs asynchronously, and you can optionally provide a webhook for completion notifications.

## POST /api/v1/tasks/batch/upload

Purpose: upload a file containing email addresses for batch verification. Processing happens asynchronously.

### Request

Headers:

* `Content-Type: multipart/form-data`

Form fields:

* `file` (required): the email list file.
* `webhook_url` (optional): webhook URL for notifications.
* `email_column` (optional): column header or 1-based index for CSV/XLSX.
* `column` (optional): alias for `email_column`.

Notes:

* Allowed formats and max file size are enforced by server config. Supported extensions: `.txt`, `.csv`, `.xlsx`.
* `email_column` is not supported for `.txt` files.
* `user_id` is not allowed in the form body.
* Maximum of 10,000 emails per file.
* Credits are reserved at task creation for the full email count; `unknown` results are refunded after the task completes (final charge equals non-`unknown` results).

Example request:

```bash theme={null}
curl -X POST \
  'https://api.boltroute.ai/api/v1/tasks/batch/upload' \
  -F 'file=@emails.csv' \
  -F 'webhook_url=https://example.com/webhook' \
  -F 'email_column=email'
```

### Response

Status: `202 Accepted`

Example response:

```json theme={null}
{
  "upload_id": "7d3df4c6-9a7d-4d16-9f2b-2a5ddf4f4f53",
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "filename": "emails.csv",
  "email_count": 123,
  "status": "processing",
  "message": "File uploaded successfully and is being processed",
  "uploaded_at": "2025-01-01T12:00:00Z"
}
```

Response fields:

* `upload_id`: UUID for this upload.
* `task_id`: task created for processing.
* `filename`: original file name.
* `email_count`: emails queued for processing.
* `status`: current status (`processing`, `completed`, `failed`).
* `message`: human-readable status message.
* `uploaded_at`: timestamp of the upload.

Errors:

* `400` file missing, unsupported file format, invalid file, invalid webhook URL, invalid `email_column`, no valid emails, email limit exceeded, or validation failures.
* `401` unauthorized.
* `402` insufficient credit balance.
* `500` internal error.