Skip to main content

Experian Address Validation

Overview

Experian Address Validation is a fast and efficient REST API for capturing validated global addresses. Get up and running in minutes with our client-side JavaScript sample code.

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.

API Personalization

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.

Search methods

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.

Display function

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.

Search suggestions

You can also decide what results are  searched for when a user types in an address.

  • Program the search to only look at addresses within a specific country
  • Ask the user to select a country first, then program the search to only look at addresses within this country.
  • Program multiple searches to occur simultaneously – each search a different country (i.e. your top 4 most used)

Address search types

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:

  1. Search for an address either partially or in full. This will provide a selection of address to choose from.
  2. Format the selected address, using a ‘global address key’, thereby creating a well formatted address.

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.

Best practices

For the best performance and greatest user experience:

  • Minimize the number of interactions between your website and the API e. search after a number of characters or after a period of inactivity.
  • Make sure that you delete /over-ride any previous searches captured from the users input.
  • Prevent browser auto-fill pop up, as this can cover up suggestions or input incorrect data.
  • For Autocomplete and Single-field search methods, inform your users to separate address elements by commas.
  • Make sure it is clear to users that more suggestions are available, they just need to continue to type to refine the search.

Autocomplete

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.

Sequence diagrams

User Workflow
  1. The user starts to type into the single text box. Suggestions will be displayed in a drop-down.
  2. The end user can then either:
    1. Continue to type for a more refined selection in the drop-down
    2. Select from the results in the drop-down
  3. 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.
 Developer Workflow  

The recommended workflow (as demonstrated by our sample code) is:

  1. Make a POST /Search request as the user types into the address capture field. Each request will comprise of the 3-digit ISO code of the country the user is searching on, the current text entered in the field. We recommend that you cancel any unfinished requests upon additional keystrokes.
  2. Display the address suggestions to the user beneath the address capture field. Each suggestion will have a global address key which needs to be held until a selection is made.
  3. Make a GET /Format request when the user selects their address from the suggestions. The URL for this request is returned as part of the search suggestions.
  4. Display the selected address back to the user. You can do this by populating your relevant address fields or displaying outside of your form. The API will use the global address key to arrange the address in either a single text box or in your own address layout using the returned address elements.
  5. Store the relevant address components in your database if required.

Single-field

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.

Sequence diagram

User Workflow
  1. 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.

  2. The user selects the correct address

  3. 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. 

Developer workflow

The recommended workflow is:

  1. Make a POST/Search request once the user triggers a search. Each request will comprise of the 3-digit ISO code of the country the user is searching on, the current text entered in the field.
  2. Display the address suggestions to the user beneath the address capture field. Each result will have a global address key which needs to be held until a selection is made.
  3. Make a GET /Format request when the user selects their address from the suggestions. The URL for this request is returned as part of the search suggestions.
  4. Display the selected address back to the user. You can do this by populating your relevant address fields or displaying outside of your form. The API will use the global address key to arrange the address in either a single text box or in your own address layout using the returned address elements.
  5. Store the relevant address components in your database if required.

Multi-field

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.

Sequence diagram

User Workflow
  1. The user types the address into separate fields.

  2. The user then triggers the validation process (i.e. by hitting a button or tabbing out of the last box).

  3. Suggestions will be displayed in a drop-down.

  4. When a selection is made, the final address is displayed per your website multi-fielded layout. 

Developer Workflow

The recommended workflow is:

  1. Make a POST/Search request from combining the text of all the fields (separated by commas).
  2. Display the address suggestions to the user beneath the address capture field. Each result will have a global address key which needs to be held until a selection is made.
  3. Make a GET /Format request when the user selects their address from the suggestions. The URL for this request is returned as part of the search suggestions.
  4. Display the selected address back to the user. You can do this by populating your relevant address fields or displaying outside of your form. The API will use the global address key to arrange the address in your own address layout using the returned address elements.
  5. Store the relevant address components in your database if required.

Pre-requisites

There are several considerations before installing, please review these.

Supported countries

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. 

Delivery Point Addresses are accurate to delivery point level. e.g. a single delivery point within an apartment building, block of flats or high rise. Building/House Number Addresses are accurate to building level e.g. a single house or retail unit. Delivery point information may need to be entered manually. Street Addresses are accurate to street level. Delivery point information will need to be entered manually. Locality Addresses will be returned for some localities (e.g. cities and towns). Street and delivery point information will need to be entered manually.

Authorization

To use our API and to get a response, you’ll need:

  • A license to use the product.
    Haven’t got a license? Talk to your account manager or contact support to get it.
  • Your token. An Auth-Token is used to authenticate the service. Your Auth-Token must be specified in the request header. Existing customers can view and manage their tokens via the Self Service Portal.

Permitted URLs

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.

Upgrading from existing services

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.

Considerations

  • 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.

Security

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

Upgrading from Global Intuitive

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 

Integrations

This section looks at  sending your first API request and the different ways you can integrate.

Sending my first API request

There are many different ways to make API requests. This section covers two ways you can send a test request to the API

From this page

Follow the instructions below to send requests to the API from this page:

  1. Go to API specification and click the POST block, so that it expands.
  2. Click the Try it out button in the upper-right corner.
  3. Enter your token in the Auth-Token field.
  4. (Optional) Enter an identifier in the Reference-Id field.
  5. (Optional) Enter the maximum time you are prepared to wait for a response , in seconds.
  6. (Optional) Under addressRequest, you can replace the address value with an address of your choice. Note that the address value must be enclosed in quotation marks, e.g. "125 summer St". Alternatively, you can skip this step and use the preset values.
  7. (Optional) Select an option from the Parameter content type and the request content type . Check out Supported data formats for more information.
  8. Click the Execute button to send the request to the API.
  9. View the response returned by the API under Responses. Note that your request was successful only if the API returned an HTTP status code of 200 - Success. Check out Response status codes to find out more about scenarios where the API returns errors.

Using Postman

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:

  1. Download and install the free Postman app.
  2. Download the relevant file.
  3. Open the Postman app and click the Import button in the upper-left corner.
  4. Import the file you've downloaded. 
  5. Go to the Collections tab on the left-hand side panel and click the API request you want to test.
  6. Go to the Headers tab.
  7. Replace the {{Auth-Token}} value with your token.
  8. Go to the Body tab.
  9. (Optional) Replace the address value with an  address of your choice. Note that the address value must be enclosed in quotation marks, e.g. "125 summer St ". Alternatively, you can skip this step and use the preset values.
  10. Click the Send button to submit the API request.
  11. View the response returned by the API. Note that your request was successful only if the API returned an HTTP status code of 200 - Success. Check out Response status codes to find out more about scenarios where the API returns errors. 

Ways to integrate

We provide two ways to integrate this API:

Contact Experian Professional Services

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.

Swagger

To view the API's Swagger specification in JSON format, go to API specification  and click the View specification link under the POST block.

Using Sample codes

Experian Address Validation JavaScript sample code is hosted on our GitHub repository. The sample code is open sourced and includes information on how to get up and running quickly and how to modify and contribute to the code.

Get sample code

Using Postman collections

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.

Get Postman collections

 

API reference

This section will look at datasets, API specifications and response components.

Supported datasets

The optional dataset parameter allows you to specify the dataset the address you're searching for is sourced from.

Currently, dataset supports 3 countries:

  • Australia
  • Ireland
  • New Zealand

The table below contains information about the dataset values you can specify for each country.

Country Value Description
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.

API specification

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:

Format response components

When a successful Format request is made, three collections will be returned.

Address

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 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
country  Country  Country Country   Country Country  Country  Country

Components

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  
deliveryService2     PO Box         
deliveryService3     Delivery Service Type/Name         
deliveryService4   Box Number           
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   
organisation2  Department          Department Name   
organisation3               
organisation4               
streetNumber1 Street Number  Primary Number  Street Number + Suffix  Building Number  Street Number  Number + Number Extension  Address/House Number
streetNumber2       Allotment Number       
street1 Primary Thoroughfare Name & Type Street  Street  Street  Street  Street  Street
street2 Secondary Thoroughfare Name & Type            
locality1 Town  City Name  Municipality  Locality  Suburb Town  Town/City
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   
county1   County Name          County
province1       State Name  City  Departement  Province/State
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   

Metadata

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:

  • Delivery Point Validation (DPV). Only returned for addresses in the USA.
  • Only returned for addresses in Australia.

For all other countries, an empty metadata object will be returned.

DPV data

The table below describes the DPV data that is returned inside the metadata object.

 Property Name Description Example
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
vacancyIndicator
Indicates if the address selected is known to be vacant and not receiving mail deliveries.
Y
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

addressSource data

The table below describes the addressSource data that is returned inside the metadata object.

 Property Name Description Example
code

Indicates whether the address is sourced from:

  • PAF data only (P).
  • G-NAF data only (G).
  • both (PG).
  • both, but the level information is exclusive to the PAF data (PGB).
PG
description A description of the code. Address exists on both PAF and G-NAF

Response status codes

Status CodeDescription
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.

Confidence level

If the HTTP status code of the response is 200, among other fields, the response body will contain a confidence level. 

Confidence Description
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

Release notes

View the release notes for details on the latest changes to Experian Address Validation.

FAQs

Are Royal Mail postcode recodes supported by Experian Address Validation?

Unfortunately postcode recodes are not supported at this time.

 

Are Royal Mail counties supported by Experian Address Validation?

Unfortunately counties are not supported at this time.

 

What are the differences between older address layouts and the way addresses are returned by Experian Address Validation?

Experian Address Validation does not use the older layouts functionality. All addresses are returned in both a 7 line global format as well as each individual address component. The 7 line layout is designed to be displayed to the user upon selection of an address, whilst the individual address components are for storing in relevant database fields.

 

How are the search results ordered in Global Intuitive?

Results are ordered alphabetically by locality first.

 

Why am I getting exceptions when I attempt to connect to the service?

 Follow these steps to diagnose and solve your issue

 

  • Firstly, check that you are not having network or firewall connectivity issues by entering the URL in to an up to date browser. Make sure that the URL is correctly formatted.

    If the URL does not work then you should check your configuration so that you have access to https://api.edq.com/capture.
  •  If you have ruled out connectivity issues, then you may be experiencing issues with TLS compatibility. TLS 1.2 and SHA-256 support is required of the client by 

    In .NET you will get the following exception WebExceptions - Underlying connection closed. This is a result of .NET 4.5 and below defaulting to use TLS 1.1.

    To solve this problem in .NET, either recompile in .NET 4.6 or above (which defaults to TLS 1.2) or add the following line to your program:
    SecurityProtocol = SecurityProtocolType.Tls12;

     Follow these steps to diagnose and solve your issue: