Use this endpoint to:

Monitor batch processing progress
Check if processing is complete
View success and failure counts
Get detailed processing statistics

Batch Status Values:

pending: Batch is queued and waiting to be processed
in_progress: Batch is actively being processed
completed: All records have been processed
failed: Batch processing encountered a critical error

Polling Recommendations:

Wait 1-2 minutes after upload before first check
Poll every 30-60 seconds while status is pending or in_progress
Set a timeout of 30 minutes maximum for large batches
Stop polling once status is completed or failed

Path Parameters

batchId

Required: Yes Type: string (uuid)

The unique batch identifier returned from the upload endpoint

Example: 784d4045-c900-4050-aad6-8fe4c8d2fb16

Response: 200 Success

Batch status retrieved successfully.

Response Fields:

batchId: Unique identifier for this batch.
status: Current processing status - pending (queued), in_progress (actively processing), completed (finished), or failed (critical error).
totalRecords: Total rows in the uploaded CSV.
processedRecords: Number of records that have been processed (successful + failed).
failedRecords: Number of records that encountered errors during processing.
createdAt: ISO 8601 timestamp when the batch was uploaded.
updatedAt: ISO 8601 timestamp of the last status update.
startedAt: ISO 8601 timestamp when processing began (null if still pending).
completedAt: ISO 8601 timestamp when processing finished (null if not yet completed).
summary.successfulRecords: Number of records successfully verified with KYC provider.
summary.errors: List of errors encountered during processing. Reserved for future use; this field is currently always empty.

Example: Completed Batch

Example response for a successfully completed batch.

{
  "batchId": "f208a887-9fa6-4447-a52b-c1d6e089536f",
  "status": "completed",
  "totalRecords": 19,
  "processedRecords": 19,
  "failedRecords": 0,
  "createdAt": "2025-10-08T11:40:20.796Z",
  "updatedAt": "2025-10-08T11:44:53.043Z",
  "startedAt": "2025-10-08T11:42:53.043Z",
  "completedAt": "2025-10-08T11:44:53.000Z",
  "summary": {
    "successfulRecords": 19,
    "errors": []
  }
}

Example: Processing Batch

Example response for a batch currently being processed.

{
  "batchId": "f208a887-9fa6-4447-a52b-c1d6e089536f",
  "status": "in_progress",
  "totalRecords": 100,
  "processedRecords": 45,
  "failedRecords": 2,
  "createdAt": "2025-10-08T11:40:20.796Z",
  "updatedAt": "2025-10-08T11:42:15.123Z",
  "startedAt": "2025-10-08T11:41:00.000Z",
  "completedAt": null,
  "summary": {
    "successfulRecords": 43,
    "errors": []
  }
}

Example: Pending Batch

Example response for a batch waiting to be processed.

{
  "batchId": "f208a887-9fa6-4447-a52b-c1d6e089536f",
  "status": "pending",
  "totalRecords": 50,
  "processedRecords": 0,
  "failedRecords": 0,
  "createdAt": "2025-10-08T11:40:20.796Z",
  "updatedAt": "2025-10-08T11:40:20.796Z",
  "startedAt": null,
  "completedAt": null,
  "summary": {
    "successfulRecords": 0,
    "errors": []
  }
}

Response: 401 Unauthorized

Authentication required or invalid API key.

Error: Missing API Key

{
  "code": "0000000100",
  "message": "Invalid Authorization: missing API key",
  "parameter": ""
}

Error: Invalid API Key

{
  "code": "0000000200",
  "message": "Invalid Authorization",
  "parameter": ""
}

Response: 404 Not Found

Batch not found - invalid batchId or batch belongs to a different business.

Error: Batch Not Found

{
  "code": "0701020100",
  "message": "Batch not found",
  "parameter": ""
}

Response: 500 Internal Server Error

Internal server error while retrieving batch status.