---
title: "Upload file for verification"
method: POST
path: "/v1/verify/file"
tags: ["File Processing"]
---

# Upload file for verification

`POST /v1/verify/file`

## Request

- Base URL: `https://api.billionverify.com`
- URL: `https://api.billionverify.com/v1/verify/file`
- Auth: API key in header `BV-API-KEY`

Upload a file containing email addresses for asynchronous batch verification.

**Supported formats:**
- CSV (.csv)
- Excel (.xlsx)
- Text (.txt) - one email per line

**Limits:**
- Maximum file size: 20 GB (aligned with the web uploader)
- No application-enforced row-count limit

**Large uploads:** small files are parsed synchronously and the response
includes email counts. Files above the inline-parse threshold are accepted
and prepared asynchronously: the response returns `status: preparing`
without counts, and clients poll `status_url` for progress and counts.

## Response `200`

File uploaded successfully

- FileUploadApiResponse
  - `success` boolean
  - `code` string
  - `message` string
  - `data` FileVerifyTaskResponse: Returned from POST /v1/verify/file (file upload). Includes job_id and status_url customers poll to check verification progress.
    - `task_id` string: Job ID; use this with GET /v1/verify/file/{job_id} to poll status.
    - `file_name` string
    - `file_size` integer
    - `status` string: Initial job status. `pending` for synchronously parsed uploads; `preparing` for large uploads deferred to asynchronous preparation (counts arrive later via status polling).
    - `message` string: Human-readable status message.
    - `status_url` string: Convenience URL clients can GET to poll task status (relative or absolute).
    - `created_at` string, date-time
    - `estimated_count` integer: Pre-parse estimated email count.
    - `unique_emails` integer, nullable: Distinct email count after dedup. omitempty in Go.
    - `total_rows` integer, nullable: Total file rows excluding header. omitempty in Go.
    - `email_column` string, nullable: Detected email column name. omitempty in Go.
  - `error` ErrorInfo
    - `code` string: Detailed error code
    - `message` string: Detailed error message
    - `description` string, nullable: Additional human-readable context (omitempty in Go)
    - `details` unknown

## Other responses

- `400`: Bad request - invalid parameters
- `401`: Unauthorized - invalid or missing API key
- `402`: Payment required - insufficient credits
- `413`: File too large

---

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