| Name | Type | Description |
|---|---|---|
| Auth-Token | string | Input your unique token here. This is required to submit an API request. |
| Reference-Id (Optional) |
string | Identifier that will be returned to the response to help you track the request. |
| Add-Metadata (Optional) |
boolean | Specify whether the response should return all fields and values, in addition to the main core information. The default value of this setting is false. |
| Name | Type | Description |
|---|---|---|
| batch_id | string | A unique identifier for the batch. |
The response from the API returns the below fields within a result object. Should an error occur, an error object is returned instead.
| Name | Type | Description |
|---|---|---|
| batch_id |
string | A unique identifier for the batch. |
| batch_reference_id (Optional) |
string | Optional reference identifier provided during batch creation to support tracking of the batch. |
| status |
string | The current processing status of the batch. |
| reason (Optional) |
string | The reason for the current batch status. |
| records |
integer | The number of addresses submitted. |
| records_processed |
integer | The number of addresses processed. |
| date_submitted |
string | The date and time when the batch was created in ISO-8601 format. |
| date_started |
string | The date and time when the batch was started in ISO-8601 format. |
| date_ended |
string | The date and time when the batch ended in ISO-8601 format. |
| Name | Type | Description | |
|---|---|---|---|
| batch_config | object | Batch configuration metadata. | |
| country_iso | string | Default country ISO. | |
| datasets | array[string] | Default datasets. | |
| add_components | boolean | Indicates if address components are returned. | |
| add_metadata | boolean | Indicates if address metadata is returned. | |
| add_extra_match_info | boolean | Indicates if information about how the input address was matched is returned. | |
| max_processing_time | string | Maximum processing time of the batch. | |
The following response codes can be returned by the API:
| HTTP status code | Title | Scenario |
|---|---|---|
| 200 | Success | You've submitted a successful request and a valid response was returned. |
| 400 | Bad Request | You've submitted an invalid field. |
| 401 | Unauthorized | The authentication token you've provided is incorrect. Sign in to the Self Service Portal to find the right token. |
| 403 | Forbidden | Request is not authorized to use this service. |
| 406 | Not Acceptable | Request is not in an acceptable format. |
| 408 | Request Timeout | Your request has timed out. Try submitting another request. |
| 415 | Unsupported Media Type | You've specified an invalid Content-Type header. Try submitting another call and make sure you specify a valid Content-Type value. |
| 429 | Too Many Requests | You've submitted too many requests. To protect all customers, your account has been temporarily throttled. |
| 500 | Internal Server Error | An unexpected server error was encountered. Try submitting another request. If the issue persists, contact us. |
| 503 | Service Unavailable | The service is currently unavailable. Check the API's uptime and downtime on our service status page. |
Successful API request returns the response within a result object. However, should an error occur, an error object is returned instead with the below fields.
| Name | Type | Description |
|---|---|---|
| type | string | A link to documentation that provides more details about the error you've encountered. |
| title | string | The title of the error. |
| detail | string | A description of the error. |
| instance | string | The endpoint that returned the error. |
GET https://api.experianaperture.io/address/bulk/v1/batches/<batch_id>
{
"result": {
"batch_id": "00000000-0000-0000-0000-000000000000",
"status": "completed",
"records": 3,
"records_processed": 3,
"date_submitted": "2025-09-10T01:02:03.004005Z",
"date_ended": "2025-09-10T01:02:03.004005Z"
}
}
{
"result": {
"batch_id": "00000000-0000-0000-0000-000000000000",
"status": "processing",
"records": 3,
"records_processed": 0,
"date_submitted": "2025-09-10T01:02:03.004005Z"
}
}
{
"result": {
"batch_id": "00000000-0000-0000-0000-000000000000",
"status": "stopped",
"reason": "max_processing_time_reached",
"records": 3,
"records_processed": 2,
"date_submitted": "2025-09-10T01:02:03.004005Z",
"date_ended": "2025-09-10T01:02:03.004005Z"
}
}
{
"result": {
"batch_id": "00000000-0000-0000-0000-000000000000",
"status": "completed",
"records": 3,
"records_processed": 3,
"date_submitted": "2025-09-10T01:02:03.004005Z",
"date_ended": "2025-09-10T01:02:03.004005Z"
},
"metadata": {
"batch_config": {
"add_components": true,
"add_metadata": true,
"add_extra_match_info": true
}
}
}