Upload file

​

Overview

​

POST /api/v1/tasks/batch/upload

​

Request

• Content-Type: multipart/form-data

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

• 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).

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

{
  "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"
}

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

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