DocsAPI DocumentationBatch Address Processing & ETL API

Batch Address Processing & ETL API

POST /v1/batch/process

Bulk validate, standardize, and geocode up to 500,000 address records asynchronously.

Updated: September 20261 min read

Endpoint Overview

POST /v1/batch/process

Submits a CSV, TSV, or raw text address dataset for asynchronous processing by Redis/BullMQ background workers. Outputs a sanitized 30+ column dataset stored in object storage.

Submit Batch Job

Submit raw CSV dataset for asynchronous processing:

1
2
3
4
5
6
7
8
9
10
curl -X POST "https://api.addressvalid.io/v1/batch/process" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "customer_addresses.csv",
    "fileContent": "street,city,state,postal_code\n134 Gerard Road,Ikoyi,Lagos,105291\n88 Sanusi Fafunwa Street,Victoria Island,Lagos,102478",
    "region": "Nigeria",
    "enhancedMatching": true,
    "validationScope": "full"
  }'

Response (202 Accepted)

The API immediately queues the job and returns a tracking identifier:

1
2
3
4
5
6
7
8
{
  "success": true,
  "jobId": "job_batch_9f8e7d6c5b",
  "status": "QUEUED",
  "filename": "customer_addresses.csv",
  "region": "Nigeria",
  "message": "Batch processing job successfully enqueued for background processing."
}

Check Job Status & Download Results

Poll or query the job status endpoint to monitor progress and retrieve the presigned download URL:

1
2
curl -X GET "https://api.addressvalid.io/v1/batch/job_batch_9f8e7d6c5b" \
  -H "Authorization: Bearer sk_live_your_api_key"

Status Response

Completed response with breakdown and signed download link:

1
2
3
4
5
6
7
8
9
10
11
12
{
  "id": "job_batch_9f8e7d6c5b",
  "status": "COMPLETED",
  "filename": "customer_addresses.csv",
  "rowCount": 2,
  "highConfidenceCount": 2,
  "partialMatchCount": 0,
  "unverifiedCount": 0,
  "validatedPercent": 100,
  "downloadUrl": "https://storage.addressvalid.io/processed/job_batch_9f8e7d6c5b/addressvalid_validated.csv?signature=...",
  "region": "Nigeria"
}

Was this documentation page helpful?

Your feedback helps us continuously improve our developer docs.

PreviousSemantic & Landmark Search NextWebhooks & Event Subscriptions