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

Get batch results

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.

Path parameter

Name Type Description
batch_id string Batch ID.

Body

The response from the API returns the validation result of a batch of addresses within a result object (see the below fields). 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 string Optional reference identifier provided during batch creation to support tracking of the batch.
credits_charged integer The number of credits charged for this batch.
status string The current processing status of the batch.
reason string The reason for the current batch status.
statistics array[object] The statistics of the address confidence level.
name string Confidence level.
value integer Count.
addresses object The address validation results.

Addresses object

Name Type Description
addresses[] object The address validation results.
address string The input address that is the subject of the validation.
country_iso string The input country ISO of the validation.
datasets array[string] The input datasets of the validation.
confidence string The outcome (confidence level) of the validation.
match_type string Match type for verified address.
match_confidence string Match confidence for verified address.
match_info object Match information details.
addresses_formatted array[object] Address formatted details for verified address.
components object Structured address components data.
metadata object Address metadata.

Match info object

Name Type Description
match_info object Match information details.
postcode_action string Postcode action information.
address_action string Address action information.
generic_info array[string] General match codes information.
aus_info array[string] Australia-specific match codes information.
deu_info array[string] Germany-specific match codes information.
fra_info array[string] France-specific match codes information.
gbr_info array[string] United Kingdom-specific match codes information.
nld_info array[string] Netherlands-specific match codes information.
nzl_info array[string] New Zealand-specific match codes information.
sgp_info array[string] Singapore-specific match codes information.

Addresses formatted collection

Name Type Description
addresses_formatted array[object] Addresses formatted details for verified address.
layout_name string The layout name for address to map.
address object The address formatted.

Components object

The Components object comprises seven address lines representing the formatted address for a given country, each containing up to 256 characters. The first three address lines will be composed of a number of specific components relating to the premises and street. The next four lines contain the locality, province, postal code and country. The full list of components with details for our most popular countries plus a rest of world column for all other supported countries can be found below.

Name United Kingdom United States Canada Australia New Zealand France Rest of the world
language Language Language Language Language Language Language Language
country_name Country Country Country Country Country Country Country
country_iso_3 ISO 3166-1 alpha-3 country code ISO 3166-1 alpha-3 country code ISO 3166-1 alpha-3 country code ISO 3166-1 alpha-3 country code ISO 3166-1 alpha-3 country code ISO 3166-1 alpha-3 country code ISO 3166-1 alpha-3 country code
country_iso_2 ISO 3166-2 code* ISO 3166-2 code* ISO 3166-2 code* ISO 3166-2 code* ISO 3166-2 code* ISO 3166-2 code* ISO 3166-2 code*

/* ISO 3166-2 standard consists of two parts: the first part is the ISO 3166-1 alpha-2 country code, the second part (when present) is a string of up to three alphanumeric characters indicating country subdivision.
/* ISO 3166 numeric-3 is a three-digit numeric code (numeric-3) which can be useful if you need to avoid using Latin script.

Name United Kingdom United States Canada Australia New Zealand France Rest of the world
full_name Postcode Zip code Postal code Postal code Postcode Postcode Postcode
primary ZIP Postal code Postcode Postcode
secondary Plus4
Name United Kingdom United States Canada Australia New Zealand France Rest of the world
full_name Delivery service Delivery service Delivery service All postal delivery types All postal delivery types All PO Box types
service_type Delivery service type Delivery service type Delivery service type
service_number Delivery service value Delivery service value Delivery service value
post_centre_name
Name United Kingdom United States Canada Australia New Zealand France Rest of the world
full_name Station information Delivery service
service_type Station information type Delivery service type
service_number Station information value Delivery service value
post_centre_name
Name United Kingdom United States Canada Australia New Zealand France Rest of the world
name Building name / Flat / Unit name (GNAF) AFNOR line 3
entrance
full_name Subbuilding number
type
value
floor
full_name Building level
type Building level type
value Building level number
door
full_name Extension designation Secondary number Suite name / number Flat / Unit name Unit textual + Unit alphanumeric Secondary address unit
type Extension designation type Secondary address identifier Suite name Flat / Unit type
value Extension designation value Secondary address number Suite number Flat / Unit number
Name United Kingdom United States Canada Australia New Zealand France Rest of the world
building_name Building name Building name Building name Additional geographic data Building name
secondary_name Group building name (Ireland only)
building_number Street number Primary number Street number and suffix Building number Street number Number and number extension Address/ house number
secondary_number Secondary number and Secondary number extension
allotment_number Allotment number
Name United Kingdom United States Canada Australia New Zealand France Rest of the world
department_name Department Department Department
secondary
_department_name
company_name Organization name Company name
Name United Kingdom United States Canada Australia New Zealand France Rest of the world
full_name Thoroughfare Street Street Street Street Street Street
prefix Street prefix Street prefix
name Thoroughfare name Street name Street name Street name Street name
type Thoroughfare type Street type Street type Street type Street type Street type
suffix Street suffix Street suffix Street suffix
Name United Kingdom United States Canada Australia New Zealand France Rest of the world
full_name Dependent thoroughfare
prefix
name Dependent thoroughfare name
type Dependent thoroughfare type
suffix
Name United Kingdom United States Canada Australia New Zealand France Rest of the world
full_name Rural route / General delivery Route service type / number
service_type
service_number
delivery_name
qualifier
Name United Kingdom United States Canada Australia New Zealand France Rest of the world
region
name Constituent country State name Region Département Region
code State code Province code State code INSEE code
description
sub_region
name Geographic county County Subregion
code
description
town
name Town City Municipality Locality Suburb Town / CEDEX office Town
code
description
district
name Dependent locality Urbanization Delivery area installation Lobby Geographic town Settlement
code
description
sub_district
name Double-dependent locality PNR lobby Postal locality / Geographic town
code
description
Name United Kingdom United States Canada Australia New Zealand France Rest of the world
region
name
code
description
sub_region
name
code
description
town
name Town / City
code
description
district
name Suburb
code
description
sub_district
name
code
description

Metadata object

The Metadata object contains additional information about the returned address, such as deliverability indicators. The metadata can be stored in your database or used to decide if the address should be rejected.
Metadata is only supported for certain countries (see table below). For all other countries, an empty metadata object will be returned.

The following metadata elements are currently available:

Name Country Description
address_info
sources Australia Indicates the source of address information:
  • PAF: Australia Post's Postal Address File
  • GNAF: Geoscape Australia's Geocoded National Address File
If the address appears in both sources, both PAF and GNAF indicators will be returned.
number_of_households United Kingdom Number of households present at the address for Royal Mail's Multiple Residence and Not Yet Built addresses.
just_built_date United Kingdom Construction date of a property, if activated within the past six months.
identifier
udprn United Kingdom Royal Mail's Unique Delivery Point Reference Number, an eight-digit code assigned to every delivery point in the Postcode Address File (PAF).
umrrn United Kingdom Royal Mail's Unique Multiple Residence Reference Number, an eight-digit code linked to UDPRNs in Royal Mail's Multiple Residence dataset.
dpid Australia
New Zealand		 Delivery Point Identifier that uniquely identifies an address:
  • Australia Post's Delivery Point Identifier, an eight-digit number that uniquely identifies a physical location to which Australia Post delivers mail.
  • New Zealand Post's Delivery Point Identifier, a unique reference number of up to seven digits which is assigned to each delivery point address in the postal address file.
gnafPid Australia Geoscape Australia's Geocoded National Address File Persistent Identifier (G-NAF ID).
hin Australia Household Identification Number (HIN), unique reference ID for each household.
paf_address_key United Kingdom Royal Mail's PAF Address Key.
route_classification
id New Zealand New Zealand Post's unique numeric identifier for a street, for example 1324.
carrier_route United States Code assigned by the USPS to a group of addresses to aid mail delivery within a ZIP code. Consists of a carrier route type and carrier route code (length: 4 bytes). For example, C001.
barcode
sort_plan_number Australia Three-digit Barcode Sort Plan (BSP) number for each full address to facilitate pre-sorting of mail items.
delivery_point_barcode Australia
United States
  • Australia: Customer barcode is a 37-digit string generated from the DPID.
  • USA: Delivery point barcode (DPBC) consists of ZIP+4 followed by the last two digits of the house/box number, or if the match is made to a highrise record, the secondary unit number representing the delivery point information.
check_digit United States Delivery point barcode (DPBC) consists of ZIP+4 followed by a check digit which is used to confirm the validity of the preceding digits
address_classification
delivery_type Australia
United Kingdom
United States 		The type of mail delivery at the address:
  • business
  • residential
  • mixed
  • P (PO Box)
address_type
code Australia
New Zealand
United States		 Record type code indicating the type of address.
USA:
  • F: Firm
  • G: General Delivery
  • H: High-rise
  • P: PO Box
  • R: Rural Route / Contract
  • S: Street
description Australia
New Zealand
United States		 Description of the address type code.
is_deliverable New Zealand Indicates whether the address can receive mail.
dpv
cmra_indicator United States Indicates whether selected address is a Commercial Mail Receiving Agency.
  • Y: Address listed in the table of CMRA addresses.
  • N: Address not listed in the table of CMRA addresses.
  • Blank: Address not presented to hash table.
seed_indicator United States Indicates whether selected address is a seed address. Seed records are control records placed by the USPS to prevent unauthorized tampering (e.g., creation of lists containing every single delivery point in a geographical region).
  • Y: Address matched to a seed record.
  • N: Address did not match to a seed record.
  • Blank: Address not presented to hash table.
dpv_indicator United States Indicates whether selected address is confirmed as deliverable via Delivery Point Validation process.
  • Y: Address DPV confirmed for both primary and (if present) secondary numbers.
  • D: Address DPV confirmed for the primary number only, and secondary number information was missing.
  • S: Address DPV confirmed for the primary number only, and secondary number information was present but unconfirmed.
  • N: Both primary and (if present) secondary number information failed to DPV Confirm.
footnotes United States Array containing zero or more of the following elements:
  • AA: Input address matched to the ZIP+4 file.
  • A1: Input address not matched to the ZIP+4 file.
  • BB: Input address matched to DPV (all components).
  • C1: Input address primary number matched, secondary number not matched, secondary number required.
  • CC: Input address primary number matched, secondary number not matched, secondary number not required.
  • F1: Input address matched to a military address.
  • G1: Input address matched to a general delivery address.
  • IA: Informed address identified.
  • N1: Input address primary number matched, secondary number missing, secondary number required.
  • M1: Input address primary number missing.
  • M3: Input address primary number invalid.
  • P1: Input address RR or HC Box number missing.
  • P3: Input address PO, RR, or HC Box number Invalid.
  • PB: Identified PO Box street address.
  • R1: Input address matched to CMRA but PMB designator not present (PMB 123 or #123).
  • R7: Addresses that are assigned to a phantom route of R777 or R779.
  • RR: Input address matched to CMRA and PMB designator present (PMB 123 or #123).
  • TA: Input address primary number matched to DPV by dropping trailing alpha.
  • U1: Input address matched to a unique ZIP Code.
vacancy_indicator United States Indicates whether selected address is known to be vacant and not receiving mail deliveries:
  • Y: Address listed in the table of vacant addresses.
  • N: Address not listed in the table of vacant addresses.
  • Blank: Address not presented to hash table.
no_stats_indicator United States Indicates whether selected address is not receiving mail deliveries. These addresses are not receiving delivery because a) delivery has not been established; b) customer receives mail as a part of a drop; or c) the address is no longer a possible delivery because the carrier destroys or returns all of the mail. Addresses for delivery points in gated communities may also be identified as No-Stats.
  • Y: Address listed in the table of no-stats addresses.
  • N: Address not listed in the table of no-stats addresses.
  • Blank: Address not presented to hash table.
pbsa_indicator United States Indicates whether selected address is a Post Office Box Street Address, a USPS alternative to traditional PO BOX addresses for customers who require a formal street address for delivery (as opposed to a PO BOX number).
  • Y: Address listed in the table of PBSA addresses
  • N: Address not listed in the table of PBSA addresses
  • Blank: Address not presented to hash table.

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.
404 Not Found The resource you've requested could not be found. Try submitting another call and make sure you're using the correct endpoint URL. If the issue persists, contact us.
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.
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

GET https://api.experianaperture.io/address/bulk/v1/batches/<batch_id>/results

Response

{
  "result": {
    "batch_id": "00000000-0000-0000-0000-000000000000",
    "credits_charged": 0,
    "status": "processing",
    "statistics": [],
    "addresses": []
  }
}

 {
    "result": {
        "batch_id": "00000000-0000-0000-0000-000000000000",
        "credits_charged": 3,
        "status": "completed",
        "statistics": [
            {
                "name": "verified match",
                "value": 3
            }
        ],
        "addresses": [
            {
                "address": "77 Station Road, Kelty",
                "country_iso": "GBR",
                "datasets": [
                    "gb-additional-multipleresidence",
                    "gb-additional-notyetbuilt",
                    "gb-additional-business"
                ],
                "confidence": "verified match",
                "match_type": "full_with_post_code",
                "match_confidence": "high",
                "addresses_formatted": [
                    {
                        "layout_name": "default",
                        "address": {
                            "address_line_1": "77 Station Road",
                            "address_line_2": "",
                            "address_line_3": "",
                            "locality": "KELTY",
                            "region": "",
                            "postal_code": "KY4 0BL",
                            "country": "UNITED KINGDOM"
                        }
                    }
                ],
                "metadata": {
                    "address_info": {
                        "identifier": {
                            "udprn": "12353231",
                            "paf_address_key": "0748244400000000S"
                        }
                    },
                    "barcode": {
                        "delivery_point_barcode": "(KY40BL2NQ)"
                    }
                }
            },
            {
                "address": "20 Main St Ste 125, Vista CA",
                "country_iso": "USA",
                "datasets": [
                    "us-address"
                ],
                "confidence": "verified match",
                "match_type": "full_with_post_code",
                "match_confidence": "high",
                "addresses_formatted": [
                    {
                        "layout_name": "default",
                        "address": {
                            "address_line_1": "20 Main St Ste 125",
                            "address_line_2": "",
                            "address_line_3": "",
                            "locality": "Vista",
                            "region": "CA",
                            "postal_code": "92083-5847",
                            "country": "UNITED STATES OF AMERICA"
                        }
                    }
                ],
                "metadata": {
                    "route_classification": {
                        "carrier_route": "C010"
                    },
                    "barcode": {
                        "delivery_point_barcode": "92083584725",
                        "check_digit": "7"
                    },
                    "address_classification": {
                        "address_type": {
                            "code": "H",
                            "description": "High-rise"
                        },
                        "delivery_type": "Business"
                    },
                    "dpv": {
                        "cmra_indicator": "N",
                        "dpv_indicator": "Y",
                        "footnotes": [
                            "AABB"
                        ],
                        "vacancy_indicator": "N",
                        "no_stats_indicator": "N",
                        "pbsa_indicator": "N"
                    }
                }
            },
            {
                "address": "56 Queens Road, ASQUITH  NSW 2077",
                "country_iso": "AUS",
                "datasets": [
                    "au-address"
                ],
                "confidence": "verified match",
                "match_type": "full_with_post_code",
                "match_confidence": "high",
                "addresses_formatted": [
                    {
                        "layout_name": "default",
                        "address": {
                            "address_line_1": "56 Queens Rd",
                            "address_line_2": "",
                            "address_line_3": "",
                            "locality": "ASQUITH",
                            "region": "NSW",
                            "postal_code": "2077",
                            "country": "AUSTRALIA"
                        }
                    }
                ],
                "metadata": {
                    "address_info": {
                        "identifier": {
                            "dpid": "37822946",
                            "hin": "104146992"
                        }
                    },
                    "barcode": {
                        "delivery_point_barcode": "1301011021220202301120313033213131213",
                        "sort_plan_number": "004"
                    },
                    "address_classification": {
                        "delivery_type": "Residential"
                    }
                }
            }
        ]
    }
}

{
    "result": {
        "batch_id": "00000000-0000-0000-0000-000000000000",
        "credits_charged": 3,
        "status": "completed",
        "statistics": [
            {
                "name": "verified match",
                "value": 3
            }
        ],
        "addresses": [
            {
                "address": "77 Station Road, Kelty",
                "country_iso": "GBR",
                "datasets": [
                    "gb-additional-multipleresidence",
                    "gb-additional-notyetbuilt",
                    "gb-additional-business"
                ],
                "confidence": "verified match",
                "match_type": "full_with_post_code",
                "match_confidence": "high",
                "addresses_formatted": [
                    {
                        "layout_name": "default",
                        "address": {
                            "address_line_1": "77 Station Road",
                            "address_line_2": "",
                            "address_line_3": "",
                            "locality": "KELTY",
                            "region": "",
                            "postal_code": "KY4 0BL",
                            "country": "UNITED KINGDOM"
                        }
                    }
                ]
            },
            {
                "address": "20 Main St Ste 125, Vista CA",
                "country_iso": "USA",
                "datasets": [
                    "us-address"
                ],
                "confidence": "verified match",
                "match_type": "full_with_post_code",
                "match_confidence": "high",
                "addresses_formatted": [
                    {
                        "layout_name": "default",
                        "address": {
                            "address_line_1": "20 Main St Ste 125",
                            "address_line_2": "",
                            "address_line_3": "",
                            "locality": "Vista",
                            "region": "CA",
                            "postal_code": "92083-5847",
                            "country": "UNITED STATES OF AMERICA"
                        }
                    }
                ]
            },
            {
                "address": "56 Queens Road, ASQUITH  NSW 2077",
                "country_iso": "AUS",
                "datasets": [
                    "au-address"
                ],
                "confidence": "verified match",
                "match_type": "full_with_post_code",
                "match_confidence": "high",
                "addresses_formatted": [
                    {
                        "layout_name": "default",
                        "address": {
                            "address_line_1": "56 Queens Rd",
                            "address_line_2": "",
                            "address_line_3": "",
                            "locality": "ASQUITH",
                            "region": "NSW",
                            "postal_code": "2077",
                            "country": "AUSTRALIA"
                        }
                    }
                ]
            }
        ]
    }
}

{
  "result": {
    "batch_id": "00000000-0000-0000-0000-000000000000",
    "credits_charged": 3,
    "status": "completed",
    "statistics": [
      {
        "name": "verified match",
        "value": 3
      }
    ],
    "addresses": [
      {
        "address": "Rontgenstr. 9|67133",
        "country_iso": "DEU",
        "datasets": [
          "de-address-ed"
        ],
        "confidence": "verified match",
        "match_info": {
          "generic_info": [
            "no_place",
            "num_chum_missing",
            "street_desc_changed",
            "street_name_error",
            "place_name_error"
          ]
        },
        "addresses_formatted": [
          {
            "layout_name": "default",
            "address": {
              "address_line_1": "Röntgenstr. 9",
              "address_line_2": "",
              "address_line_3": "",
              "locality": "Maxdorf",
              "region": "Rheinland-Pfalz",
              "postal_code": "67133",
              "country": "GERMANY"
            }
          }
        ],
        "components": {
          "country_name": "GERMANY",
          "country_iso_3": "DEU",
          "country_iso_2": "DE",
          "postal_code": {
            "full_name": "67133",
            "primary": "67133"
          },
          "building": {
            "building_number": "9"
          },
          "street": {
            "full_name": "Röntgenstr."
          },
          "locality": {
            "region": {
              "name": "Rheinland-Pfalz"
            },
            "town": {
              "name": "Maxdorf"
            }
          }
        },
        "metadata": {}
      },
      {
        "address": "77 Station Road, Kelty",
        "country_iso": "GBR",
        "datasets": [
          "gb-address"
        ],
        "confidence": "verified match",
        "match_type": "full_with_post_code",
        "match_confidence": "high",
        "match_info": {
          "postcode_action": "added",
          "address_action": "corrected",
          "generic_info": [
            "address_cleaned"
          ]
        },
        "addresses_formatted": [
          {
            "layout_name": "default",
            "address": {
              "address_line_1": "77 Station Road",
              "address_line_2": "",
              "address_line_3": "",
              "locality": "KELTY",
              "region": "",
              "postal_code": "KY4 0BL",
              "country": "UNITED KINGDOM"
            }
          }
        ],
        "components": {
          "country_name": "UNITED KINGDOM",
          "country_iso_3": "GBR",
          "country_iso_2": "GB",
          "postal_code": {
            "full_name": "KY4 0BL",
            "primary": "KY4 0BL"
          },
          "building": {
            "building_number": "77"
          },
          "street": {
            "full_name": "Station Road",
            "name": "Station",
            "type": "Road"
          },
          "locality": {
            "region": {
              "name": "Fife"
            },
            "town": {
              "name": "KELTY"
            }
          }
        },
        "metadata": {
          "address_info": {
            "identifier": {
              "udprn": "12353231",
              "paf_address_key": "0748244400000000S"
            }
          },
          "barcode": {
            "delivery_point_barcode": "(KY40BL2NQ)"
          }
        }
      },
      {
        "address": "PO Box M, New York 10034",
        "country_iso": "USA",
        "datasets": [
          "us-address"
        ],
        "confidence": "verified match",
        "match_type": "full_with_post_code",
        "match_confidence": "high",
        "match_info": {
          "postcode_action": "corrected",
          "address_action": "corrected",
          "generic_info": [
            "address_cleaned"
          ]
        },
        "addresses_formatted": [
          {
            "layout_name": "default",
            "address": {
              "address_line_1": "PO Box M",
              "address_line_2": "",
              "address_line_3": "",
              "locality": "New York",
              "region": "NY",
              "postal_code": "10034-0267",
              "country": "UNITED STATES OF AMERICA"
            }
          }
        ],
        "components": {
          "country_name": "UNITED STATES OF AMERICA",
          "country_iso_3": "USA",
          "country_iso_2": "US",
          "postal_code": {
            "full_name": "10034-0267",
            "primary": "10034",
            "secondary": "0267"
          },
          "street": {
            "full_name": "PO Box M",
            "prefix": "PO Box M"
          },
          "locality": {
            "region": {
              "code": "NY"
            },
            "sub_region": {
              "name": "New York"
            },
            "town": {
              "name": "New York"
            }
          }
        },
        "metadata": {
          "route_classification": {
            "carrier_route": "B005"
          },
          "barcode": {
            "delivery_point_barcode": "10034026799",
            "check_digit": "9"
          },
          "address_classification": {
            "address_type": {
              "code": "P",
              "description": "PO Box"
            },
            "delivery_type": "Residential"
          },
          "dpv": {
            "cmra_indicator": "N",
            "dpv_indicator": "Y",
            "footnotes": [
              "AABB"
            ],
            "vacancy_indicator": "Y",
            "no_stats_indicator": "N",
            "pbsa_indicator": "N"
          }
        }
      }
    ]
  }
}
Experian Address Validation

Bulk API reference