Data Quality user documentation
home/Address validation/Experian Address Validation/Bulk API reference/Create batch

Create batch

Headers

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-Components
(Optional)		 boolean Specifies if the response should contain the address broken down into its components.

The default value of this setting is false.
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.
Add-ExtraMatchInfo
(Optional)		 boolean Specify if the response should include validation match info details.

The default value of this setting is false.

Body

Name Type Description
defaults
(Optional)		 object The default options that apply to all the addresses.
country_iso string The country ISO3 code of address.

The default value of this setting is empty.
datasets array[string] The datasets for address validation.
batch_reference_id
(Optional)		 string A custom reference you can provide to track the batch.
max_processing_time
(Optional)		 string Optional maximum processing time of the batch. If the batch is still processing after this time, it will be stopped. The value should be in ISO 8601 duration format, for example PT30M (30 minutes). Maximum allowed value is PT24H (24 hours). Minimum allowed value is PT1M (1 minute).
addresses array[object] List of input components. Minimum 1 address. Maximum 10,000 addresses.
address string The address to validate.
country_iso string You can indicate the 3-letter ISO country code if the address that is subject to validation doesn't contain an address country code. This will overwrite the country_iso in the default options.
datasets array[string] The datasets to apply. This will overwrite the datasets in the default options.

Body

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.

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 (the web server failed to respond in the specified time frame). 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. You can check the API's uptime and downtime by going to our service status page.

Error response

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.

Request

The following examples show how to structure create batch requests for different scenarios. You have the flexibility to:

  • omit the default country and datasets,
  • include a default country and datasets, and
  • optionally you can specify maximum processing time.
{
  "addresses": [
    {
      "address": "Am Sickenbrünnle 12|||Bauschlott|Neulingen|75245",
      "country_iso": "DEU",
      "datasets": [
        "de-address-ed"
      ]
    },
    {
      "address": "3 donghyeon-ro|||boryeong-si|chungcheongnam-do|33430",
      "country_iso": "KOR",
      "datasets": [
        "kr-address-ed"
      ]
    }
  ]
}

{
  "defaults": {
    "country_iso": "DEU",
    "datasets": [
      "de-address-ed"
    ]
  },
  "addresses": [
    {
      "address": "Am Sickenbrünnle 12|||Bauschlott|Neulingen|75245"
    },
    {
      "address": "Am Stadtwald 7|||Altenburg||04600"
    }
  ]
}

{
  "defaults": {
    "country_iso": "DEU",
    "datasets": [
      "de-address-ed"
    ],
    "max_processing_time": "PT25M"
  },
  "addresses": [
    {
      "address": "Am Sickenbrünnle 12|||Bauschlott|Neulingen|75245"
    }
  ]
}

Response

{
  "result": {
    "batch_id": "<batch_id>",
    "status": "submitted"
  }
}
Experian Address Validation

Bulk API reference