Skip to main content

Address Validate REST Verification

Overview

Address Validate API provides a REST interface for accessing address searching and verification functionality. 

Currently, only GBRUSA and CAN datasets are supported. For other countries, use our Global Intuitive or SOAP API.

Note that this API uses TLS 1.2 encryption. Find out more.

Workflows

Address Validate API provides different address search workflows, depending on the dataset and your requirements.

GBR & USA datasets

search-address method:

With this method, the address is entered on a single line. This is the quickest and most efficient way to enter an address; allowing for partial address entry to achieve a complete and validated address.

 

verify-address method:

With this method, the whole address is entered first (similar to online address forms with multiple fields for address, city and postal code) and then passed on for searching. It requires the user to enter the complete address and works with your existing address forms.

GBR search examples

Search TypeExample
Full address known

Enter the premises number followed by the postcode:
35, de238lh
The correct address is returned:
35 Douglas Street
DERBY
DE23 8LH

Sub-premises known

If the full address contains known sub-premises, enter the sub-premises followed by the premises number, then the postcode:
2, 18, eh105ly
The correct address is returned:
18/2 Morningside Drive
EDINBURGH
EH10 5LY

Postcode not known If the postcode is not known, enter the premises number and street name followed by the locality:

1 fairfield st, leeds
The correct address is returned:
1 Fairfield Street
LEEDS
LS13 3DX

Only street name known

If the street name only is known, entering the street will return a picklist allowing further refinement. Address Validate API can handle abbreviated street descriptors such as st, rd, ave or cl.
Enter Fairfield Street to view a list of every street of that name in the country.

Character missing from address

If one character is missing from the address, the unknown character can be replaced with a question mark.
Enter 12 ?arden rd, kendal and the correct address is returned:
12 Garden Road
KENDAL
Cumbria
LA9 7ED

Address contains spelling mistake

Entering an address that contains one or more spelling errors can still return the correct address.
Entering 2 joyland rd, bromley will still return the correct address:
2 Boyland Road
BROMLEY
BR1 4QF

Incomplete address element

If you only have partial address information, you can replace the remainder of an address element with an asterisk.
Entering church rd, winte* will display a picklist of Church Roads in all places beginning with 'winte'.

Incomplete address element

Sometimes it is helpful to tag a part of the search string to let Address Validate API know which part of the address it is.
Searching on king*@s, bolton tells Address Validate API to display a picklist of streets that begin with “king...” in Bolton.

All organisation types in location  Enter *bank, brighton to view a list of all the banks in Brighton.

USA search examples

ScenarioverifylevelExample
Verified address found Verified

12 Dakota Drive
Zebulon
NC
27597-6670

Match to multiple results found Multiple

200 Rodeo Drive
Beverly Hills
CA

Not enough information provided  None

Rodeo Drive
CA

 
No property number provided StreetPartial 

Rosemont Road
North Jackson
OH
44451-9631

More than one apartment exists at provided address PremisesPartial 

1825 South Main Street Walnut Creek
CA
94595

No city or ZIP information provided InteractionRequired 

1664 Fyler Rd Lot 1
NY

 

CAN dataset

verify-address method:

With this method, the whole address is entered first (similar to online address forms with multiple fields for address, city and postal code) and then passed on for searching. It requires the user to enter the complete address and works with your existing address forms.

CAN search examples

ScenarioverifylevelExample
Verified address found Verified

825 Dusseault Crt Yellowknife
NT
X1A 2Z4

Match to multiple results found Multiple

14 Arnold Ave
ON

Not enough information provided  None

NoStreet
NoTown

No property (premise/building) information provided StreetPartial 

38th Ave W
Vancouver
BC
V6M 1R9

More than one apartment exists at provided address PremisesPartial 

351 Saguenay Dr
Saskatoon
ON
S7K 5T4

Street name provided is incorrect/postal code is incomplete InteractionRequired 

151 David Rd
Nepean
ON
K2G

The length and format of monikers and IDs are subject to change without prior notice. Caching or validation rules should not be implemented for monikers and IDs.

Sample Code

You can use our REST sample code for validating addresses, phones and emails. See Capture sample code guide for details.

Get sample code

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

Authentication

In order to access address searching and verification functionality, the request has to be authenticated. 

Token is a unique alphanumeric code that allows you to use the products covered by your license. It can be retrieved from Self Service Portal > Licenses.

There are two ways to make an authenticated API request:

  1. The Auth-Token HTTP request header has to be passed with the GET request. For example:
GET https://api.experianmarketingservices.com/capture/v1/search-address/text?query=Clapham%20Court%2C%20Kings%20Avenue%2C%20LONDON&country=GBR HTTP/1.1

Auth-Token: 55929877-683b-856c-d3b8-7047fcf0582a
  

Test your token

Ensure your token works before proceeding. For example, using cURL:

curl -XGET -k --header "Auth-Token: 55929877-683b-856c-d3b8-7047fcf0582a"

"https://api.experianmarketingservices.com/capture/v1/search-address/text/?query=Clapham%20Court%2C%20Kings%20Avenue%2C%20LONDON&country=GBR" 

  1. Alternatively, the token (auth-token) can be passed as a query parameter in the URL endpoint. For example: 
GET https://api.experianmarketingservices.com/capture/v1/search-address/text?query=Clapham%20Court%2C%20Kings%20Avenue%2C%20LONDON&auth-token=<your auth-token value>&country=GBR HTTP/1.1

Security

Permitted URLs

We strongly recommend 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 Self Service Portal help for more information about tokens and full instructions on how to set your permitted URLs.

CORS

Address Validate API REST supports Cross Origin Resource Sharing (CORS). This is a specification developed by W3C that allows browsers to make cross-domain requests thus enabling client side integrations. When making a request, the browser will add an origin request header. The API will then respond with a CORS specific response header denoting the origin domains allowed to make requests to the API.

CORS Supported OS and Browsers:

  • iOS devices (all versions)
  • Safari, IE and Chrome

API reference

The Address Validate REST API reference defines the available resources, parameters and the expected response values. 

Default layouts

The default layouts for each country that are used when making a GET /address-layout request are listed below.

GBR: 

Line 1: auto
Line 2: auto
Line 3: auto
Line 4: Town (L21)
Line 5: County (L11)
Line 6: Postcode (C11)
Line 7: Country name (X11)

USA: 

Line 1: auto
Line 2: auto
Line 3: auto
Line 4: City name (L31)
Line 5: State Code (L11)
Line 6: ZIP code, +4 code (C11, C21)
Line 7: Country name (X11)

Canada:

Line 1: auto
Line 2: auto
Line 3: auto
Line 4: Municipality name (L31)
Line 5: Province code (L11)
Line 6: Postal code (C11)
Line 7: Country name (X11)

Picklist threshold

The threshold for the picklist (a list of suggested addresses) is set to 50, meaning that the first 50 addresses will be returned. 

This value is currently not configurable. 

However, for verify-address the results will not be affected by this threshold.

For example, if 100 results are found, then:

  • 50 addresses will be returned with verify-address.
  • 50 addresses will be returned. However, if the skip parameter is set to 50, then the remaining 51-100 addresses will be shown with verify-address.

Informational picklist

If unable to return a search result, Address Validate REST API will return an informational picklist (a list of suggested addresses).

Informational picklist will not be affected by the skip and take parameters (used by search-address and verify-address).

GBR: search-address returns no match


{ "count": 0, "results": [ { "id": "",
"text": "No matches",
"grouped": false,
"url": null } ] }

GBR: search-address returns too many matches


{ "count": 0, "results": [ { "id": "",
"text": "Search canceled (too many matches)",
"grouped": false,
"url": null } ] }

USA: search-address is unable to match


{ "count": 0, "results": [ { "id": "",
"text": "Continue typing",
"grouped": false,
"url": null } ] }

GBR/USA/CAN: verify-address returns no match

{ 
"prompt": "",
"verifylevel": "None",
"
count": 0, "results": [ { "id": "",
"text": "No matches",
"grouped": false,
"url": null } ] }

USA: verify-address is unable to refine an address

{ 
"prompt": "",
"
count": 0, "results": [ { "id": "",
"text": "Address not recognized",
"grouped": false,
"url": null } ] }

CAN: verify-address is unable to refine an address

{ 
"prompt": "",
"
count": 0, "results": [] }

GBR: verify-address returns too many matches

{ 
"prompt": "",
"verifylevel": "None",
"
count": 0, "results": [] }

Standard response codes

The following response codes can potentially be returned by all methods:

Status CodeDescription

400: Bad Request 

(applicable to search-address and verify-address methods only) 

This code is returned when there is something wrong with the formatting of the request, i.e. bad syntax. It is normally accompanied by a message explaining what is wrong with the request in more detail. Sample messages/scenarios:

  • "The query property is required": missing the mandatory query parameter
  • "The query field is required": empty value for query 
  • "The value <value> is not valid for skip": invalid value for skip 
  • "The skip field must be a positive integer": negative integer for skip 
  • "The value <value> is not valid for take": invalid value for take 
  • "The take field must be a positive integer": negative integer for take 
  • "This method does not support <country>": invalid method 
401: Unauthorized

Returned when a user makes a request without being authenticated. This is normally associated with an invalid token. Sample messages/scenarios:

"Authentication has been denied for this request" 

  • Missing/empty/invalid Auth-Token
  • The mandatory country parameter is missing/empty/invalid
  • Empty value for id
  • Your token is setup with the URL restriction via Self Service Portal > Licenses. Check the Permitted URL value.
403: Forbidden

Returned when a user has authenticated but does not have permission to access the resource. This is normally associated with a token that is valid but not for the service being requested. Sample messages/scenarios: "Authorization has been denied for this request": Token that is not entitled to use the product

404: Not Found

(applicable to address-layout method only) 

Returned when the server has not found anything matching the Request-URI. Sample messages/scenarios: "The value '' is not valid for Id": Invalid value foid

500: Internal Server Error

Returned when the server encountered an unexpected condition which prevented it from fulfilling the request. Sample messages/scenarios: "Please contact Experian support.": Server encounters an unexpected condition

503: Service Unavailable  The service is down for maintenance.

Troubleshooting

SSL certificate errors

Your SSL certificates might have expired. You will need to update your certificates with the relevant certificate files. 
  1. Download both Entrust and GlobalSign files. 
  2. Extract the files.
  3. Install the certificates in the correct certificate stores as shown below:
  Trusted RootIntermediatePersonal
Entrust

EntrustCA
EntrustRootCA-G2

EntrustCA-L1K

api.experianmarketingservices.com

GlobalSign

GlobalSignRoot-R1

GlobalSigncloudsslsha2g3r3

EDQincapsula

For further help contact support. 

Connection issues

In order to use our services, you need to ensure that certain IP addresses (listed below) are accessible to you (i.e. not blocked by your firewalls). 

  • 167.107.82.39
  • 45.60.31.210
  • 45.60.32.212
  • 45.60.33.210
  • 45.60.34.212
  • 45.60.35.210
  • 45.60.36.212
  • 45.60.37.210
  • 45.60.38.212
  • 45.60.39.210
  • 45.60.40.212