Upload Batch File
Upload a CSV or JSON file for batch processing using POST /v1/batch/upload.
Upload Batch File
Upload a CSV or JSON file containing items for batch verification.
POST
/v1/batch/uploadUpload a file and receive a fileId for use in batch creation.
Uploaded files expire after 1 hour and can only be used once. The file is consumed atomically when creating a batch.
Request
Send a multipart/form-data request with the file.
Form Fields
| Parameter | Type | Description |
|---|
Example Request
Response
Success Response (200)
{
"fileId": "550e8400-e29b-41d4-a716-446655440000",
"originalFileName": "claims.csv",
"format": "csv",
"itemCount": 87,
"validationErrors": [],
"expiresAt": "2024-01-15T11:30:00Z",
"message": "File uploaded successfully"
}Success with Warnings
{
"fileId": "550e8400-e29b-41d4-a716-446655440000",
"originalFileName": "claims.csv",
"format": "csv",
"itemCount": 85,
"validationErrors": [
{ "row": 12, "error": "Content is empty, row skipped" },
{ "row": 45, "error": "Content exceeds maximum length (50000 chars), row skipped" }
],
"expiresAt": "2024-01-15T11:30:00Z",
"message": "File uploaded with 2 validation warning(s). Items with errors were skipped."
}Error Response (400)
{
"error": "File parsing failed",
"validationErrors": [
{ "row": 1, "error": "Missing required column: content" }
]
}Response Fields
| Parameter | Type | Description |
|---|
Error Responses
400 Bad Request
{
"error": {
"code": "validation_error",
"message": "File is required. Use form field name \"file\"."
}
}402 Payment Required
{
"error": {
"code": "quota_exceeded",
"message": "Batch processing is not available on the free plan."
}
}413 Payload Too Large
{
"error": {
"code": "payload_too_large",
"message": "File size exceeds maximum of 10 MB"
}
}503 Service Unavailable
{
"error": {
"code": "FILE_STORAGE_UNAVAILABLE",
"message": "File upload is not configured. Please use direct JSON items array instead."
}
}File Formats
See File Formats for detailed CSV and JSON specifications.
Workflow
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Upload File │ ──> │ Get fileId │ ──> │ Create Batch │
│ POST /upload │ │ (valid 1hr) │ │ POST /batch │
└─────────────────┘ └─────────────────┘ └─────────────────┘
Each fileId can only be used once. After creating a batch, the file is atomically consumed and cannot be reused. Upload the file again if you need to create another batch.