The API is designed and optimized to allow for multiple search methods and workflows, including Autocomplete, Single-Field and Multi-Field. The simple workflow combined with simple API requests make integrating Experian Address Validation into your system a pain-free process. With just two resources (POST/Search and GET /Format) it is easy to build your requests and get the best global address capture user experience.
The Experian Address Validation API can sit behind a multitude of different user interfaces to create the best user experience for your website.
For a more personalized integration, please feel free to contact us.
You can use any number of different website designs to integrate the Experian Address Validation API. In this document we will cover three types of search methods – Autocomplete, Multi-Field and Single-Field.
If your website uses a different search method to the ones in this document, our Experian Address Validation API can still be used in conjunction with it as long as it lends itself to a twostep search/format approach.
Whether you choose to display your results in a dropdown, predictive style, rolodex style or another function, Experian Address Validation API can integrate seamlessly into your website so that the results are displayed to suit your website design.
Please note for the purposes of this document we will be using the dropdown approach.
You can also decide what results are searched for when a user types in an address.
The Experian Address Validation API will use either a partial or complete address to return a list of suggestions. Selecting a suggestion allows the user to then retrieve a well formatted (one that could be printed on an envelope) address.
It is a twostep process including two endpoints:
Within each search method you have the option to include our data enrichment products to gain an improved level of insight into individuals, households and geographic areas. For example, you can find out an address's geocoordinates. For more information go to our Experian Enrichment article.
There are three main search methods that can be used: Autocomplete, Single-field or Multi-field. The API works in the same way backend but works with the search method of your choice to produce a list of results.
Our Global Address Key will provide you access to our address enrichment products.
For the best performance and greatest user experience:
The Autocomplete search method is designed so that the user can enter addresses quickly and easily, using a real-time picklist and fuzzy matching, along with Smart Searching in certain countries, while delimiters such as commas and dashes are handled accurately and transparently.
As your end user starts typing an address into a single text box, our API will attempt to Autocomplete by providing a list of addresses that match the current input. Each keystroke will update the list with more accurate suggestions.
The recommended workflow (as demonstrated by our sample code) is:
The Single-Field search method is designed so that the user can enter minimal information in order to produce a list of matching and close-matching addresses from which they can select the required one, when Autocomplete is not desired.
Single-Field searching requires a user to type in two or three address elements. Single-Field searches can use a variety of techniques to return the correct address from incomplete information, including fuzzy matching along with Smart Searching in certain countries.
The user types an address into the single text box and triggers the validation process (by hitting a button, tabbing out of the last box, pressing enter etc.) . Suggestions will be displayed in a drop-down.
The user selects the correct address
When a selection is made, the final address is displayed per your website design i.e. a single text box or a multi-fielded layout.
The recommended workflow is:
The Multi-Field search method is designed so that the user can enter an address into multiple fields and, when searched for, provides an address using fuzzy matching along with Smart Searching in certain countries.
Your end user will enter the address into multiple fields and then signal (for example by clicking a button) the API to search and try to match the address entered. Your end user can then select their address from a list of results provided.
The user types the address into separate fields.
The user then triggers the validation process (i.e. by hitting a button or tabbing out of the last box).
Suggestions will be displayed in a drop-down.
When a selection is made, the final address is displayed per your website multi-fielded layout.
The recommended workflow is:
The map below illustrates the level of coverage for each country and territory. The coverage levels represent how accurate the addresses are for major parts of the country.
To use our API and to get a response, you’ll need:
We strongly recommended that you specify the permitted URLs to be used for address capture. This is essential to prevent fraudulent use of your token on another domain by ensuring that only requests made from your specified URLs are authenticated. See our portal help page for more information about tokens and instructions on how to set your permitted URLs.
This API uses TLS 1.2 encryption. Find out more.
Haven’t got your token? This article explains tokens and includes instructions on where to find yours.
If you are looking to upgrade from Pro Web or Address Validate API SOAP (Formerly known as Pro On Demand) to Experian Address Validation you will need to understand the differences in integration approach and how to prepare for this.
User Experience (UX) - requires a change in workflow; changes to the user input form are required.
Experian Address Validation can be much more interactive compared with previous versions of Address Validate API SOAP, therefore more requests may be made, using the Autocomplete search method.
Implementation change - going from SOAP to RESTful web services.
Experian Address Validation forgoes the traditional address layout functionality in favor of returning a global 7 line address collection along with a full component breakdown. The 7 lines are for displaying back to the end user whilst the full component collection allows for specific components to be entered into relevant database fields.
Pro Web customers should understand the additional security considerations of calling out to an external web service - opening ports/firewalls etc.
Experian have recently updated to token authentication instead of username/password credentials. Customers will not be able to use existing username/passwords from previous versions of Address Validate SOAP when using Experian Address Validation.
A token can be passed through as a Request Header:
Auth-Token = a1b234c5-a1bc-1234-a1bc-123a4567891bc
If you have the Global Intuitive API and are upgrading to the Experian Address Validation API, please review the requirements below:
Change 'GET' to 'POST' on /search
The search term now needs to go in the body of the /search request (see API specification for an example)
Change the header parameter from a URL argument to an auth-token in /search
Change the /search endpoint response in parsing from 'GET' to 'POST'
Change the header parameter from a URL argument to an auth-token in /format
This section looks at sending your first API request and the different ways you can integrate.
There are many different ways to make API requests. This section covers two ways you can send a test request to the API
Follow the instructions below to send requests to the API from this page:
Postman is a free, easy-to-use third-party application that you can use to send API calls.
Follow these instructions to send requests to the API via Postman:
We provide two ways to integrate this API:
If you’ve purchased Professional Services support along with your license, contact us for assistance. Our consultants are highly skilled in all key programming languages and they will help you set up and integrate the API.
To view the API's Swagger specification in JSON format, go to API specification and click the View specification link under the POST block.
We now have pre-configured Postman collections for our APIs.
You can quickly test out the requests and responses and see how the API behaves. Simply import the relevant collections, add your token as a variable and start making requests with your desired parameters.
The optional dataset parameter allows you to specify the dataset the address you're searching for is sourced from.
Currently, dataset supports 3 countries:
The table below contains information about the dataset values you can specify for each country.
|Australia||"DataFusion"||Dataset which consists of both PAF and G-NAF data. Also known as the AUE dataset.|
|"GNAF"||Australia's Geocoded National Address File (G-NAF) dataset. Also known as the AUG dataset.|
|"PAF"||Australia Post's Postal Address File (PAF) dataset. Also known as the AUS dataset.|
|Ireland||"Eircode"||Ireland's postcodes (Eircodes) dataset.|
|"PAF"||Ireland's Postal Address File (PAF) dataset.|
|New Zealand||"DataFusion"||Dataset which contains additional, postally non-deliverable addresses that are not included in the PAF data. Also known as the NZD dataset.|
|"PAF"||New Zealand's Postal Address File (PAF) dataset. Also known as the NZL dataset.|
Note: The dataset you specify when sending a search request will also be used for the format call. If you don't specify a dataset, the default value, "PAF", will be used.
The Experian Address Validation API specification defines the available resources, parameters and the expected response values.
The length and format of IDs are subject to change without prior notice. Caching or validation rules should not be implemented for IDs.
Endpoint 1 and 2:
When a successful Format request is made, three collections will be returned.
The Address collection comprises up to seven address lines representing a formatted address for the chosen country. The first three address lines will be comprised of a number of specific components relating to the premises and street. The next four lines contain the locality, province, postal code and country. Country specific information for our most popular countries is shown below:
|United Kingdom||United States||Canada||Australia||New Zealand||France||Rest of World|
|addressLine1||Auto Line||Auto Line||Auto Line||Auto Line||Auto Line||Auto Line||Auto Line|
|addressLine2||Auto Line||Auto Line||Auto Line||Auto Line||
|Auto Line||Auto Line|
|addressLine3||Auto Line||Auto Line||Auto Line||Auto Line||Auto Line||Auto Line||Auto Line|
|locality||Town||City Name||Municipality||Locality||Suburb/Lobby Name/Rural Delivery||Town||Locality|
|province||State Code||Province Code||State Code||City||Province|
|postalCode||Postcode||Zip - Zip+4 Code||Postal Code||Postcode||PostalCode||Postcode||Postal Code|
The Components collection comprises a number of specific address components. Each individual component can be added to relevant fields in your database. Each component will differ slightly from country to country. Any components that are blank for the selected address will not be returned by the API. 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. The components that are returned will depend on the level of coverage available in the data.
|United Kingdom||United States||Canada||Australia||New Zealand||France||Rest of World|
|deliveryService1||Delivery Service Identifier||PO Box||Route Service Type/Number||All Postal Delivery Types||All Postal Delivery Types||All PO Box Types|
|deliveryService3||Delivery Service Type/Name|
|deliveryPointID1||Delivery Point Identifier|
|subBuilding1||Extension Designation||Secondary Number||Suite Name/Number||Flat/Unit Name||Unit Textual + Unit alpha-num||Secondary Number + Secondary Number Ext||Secondary Address Units e.g. Apartments, Suites, Units etc.|
|subBuilding2||Building Level||Floor Number|
|subBuilding3||Sub-Building Number||Sub-Building Number|
|subBuilding4||Building Name 2|
|building1||Building||Building Name||Building Name||Building Name|
|organisation1||Organisation Name||Company Name|
|streetNumber1||Street Number||Primary Number||Street Number + Suffix||Building Number||Street Number||Number + Number Extension||Address/House Number|
|street1||Primary Thoroughfare Name & Type||Street||Street||Street||Street||Street||Street|
|street2||Secondary Thoroughfare Name & Type|
|locality2||District Level 1 (dependent location 1)||Delivery Installation||Lobby Name||Cedex Office||Settlement|
|locality3||District Level 1 (dependent location 2)||PNR Lobby Name||Additional Geographic Data|
|locality4||Rural Delivery||Submitted Postal Locality/Geographic Town|
|provinceCode1||State Code||Province Code||State Code||INSEE code|
|postalCode1||Postcode||Zip - Zip+4 Code||Postal Code||Postal Code||Postcode||Postcode||Postal Code|
|country1||Country Name||Country Name||Country Name||Country Name||Country Name||Country Name||Country Name|
|countryISO1||Three Character ISO Country Code||Three Character ISO Country Code||Three Character ISO Country Code||Three Character ISO Country Code||Three Character ISO Country Code||Three Character ISO Country Code||Three Character ISO Country Code|
The Metadata object contains relevant metadata for the returned address. The metadata can be stored in your database or used to decide if the address should be rejected.
The current metadata available is:
For all other countries, an empty metadata object will be returned.
The table below describes the DPV data that is returned inside the metadata object.
|cmraIndicator||Indicates whether the selected address is a Commercial Mail Receiving Agency.||Y|
|seedIndicator||Indicates if the address selected is a seed address.||Y|
|dpvIndicator||Indicates whether the selected address is DPV confirmed.||Y|
|footnotes||The footnotes contain extra information returned by the DPV lookup.||AA, M3|
Indicates if the address selected is known to be vacant and not receiving mail deliveries.
|noStatsIndicator||Indicates known addresses not receiving mail deliveries, for example an address for a house still under construction.||Y|
|pbsaIndicator||Indicates addresses known to be Post Office Box Street Addresses (PBSA).||Y|
The table below describes the addressSource data that is returned inside the metadata object.
Indicates whether the address is sourced from:
|description||A description of the code.||Address exists on both PAF and G-NAF|
|200: OK||Request processed successfully.|
|400: Bad Request||Request failed due to malformed syntax.|
|401: Unauthorized||Auth-Token provided is incorrect.|
|403: Forbidden||Request is not authorized to use the service.|
|404: Not Found||The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissable.|
|500: Internal Server Error||The server has encountered an error.|
|502: Bad Gateway||Provider failure.|
If the HTTP status code of the response is 200, among other fields, the response body will contain a confidence level.
|Verified Match||Only 1 address match has been returned|
|Multiple Match||2 or more address matches have been returned|
|No Match||No address matches have been returned|
|Insufficient Search Terms||Not enough characters were entered to provide a result|
Follow these steps to diagnose and solve your issue: