Skip to main content

Address Validate REST Verification


Are you compatible with TLS 1.2?
Test your connections as soon as possible to avoid service disruptions. 

.

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.

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

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, what parameters to include with each request and the expected response values. 

https://api.experianmarketingservices.com/capture/v1

The three available resources correspond to the three main actions:

Headers

The following header is understood by every Address Validate API request:

HeaderDescriptionAssumed Default
Auth-Token Used in token-based authentication. If not specified or the value is invalid, the request is not authenticated and an error will be returned. N/A

GET /search-address/text

Searches for addresses based on an unstructured text query. 

GET /search-address/text?query={address}&country={country ISO code}&id={id to refine on}&take={number of results to return}&skip={number of results to skip}

 Optional parameters in italics.

Request

Parameters

NameRequiredExampleDescription
query yes experian%20data%20quality The search query to return matches for. This input should be HTTP encoded.
country yes USA The country to search against. This value should correspond to a three-lettered value as defined by ISO 3166-1.
id no ZODGBREQHeBwAAAAABAwEAAAABSRZNUYAgAAAAADE1AAD The unique identifier of an address to filter results by. This parameter is used in interrogating the details of grouped results, e.g. tower blocks. 
skip no 0

The number of search results to skip over. This allows results to be paginated when the number of results which could be returned is larger than the default or that of the take parameter. The default value is 0.

For example: if the returned results are A, B, C and D then
skip 1 take 2 will return and C;
skip 1 take 3 will return B, C, and D

take no 50 The number of matches to be returned in one request. The default value is 50

 

Sample Request

GET https://api.experianmarketingservices.com/capture/v1/search-address/text/?query=15%20bramble%20close&country=gbr&take=2

Response

Search results are returned in an array. A successful response is a lightweight representation of an address where the details are formatted onto a single line.

This format is used to support smaller payloads required by many UI integrations:

NameValueDescription
count integer The total number of available results. This is not affected by the values supplied for the skip and take parameters.
results object[] An array of search results.
result.id string The unique identifier for the address. This can be passed into the Search method to interrogate the details of grouped results, e.g. tower blocks. This can also be passed to the address-layout method to return the full address resource.
result.text string The address formatted as a single line of plain text with no breaks or formatting.
result.grouped boolean Indicates whether or not this result has grouped a large number of related addresses together (e.g. a tower block). A separate call to the refine method is required to retrieve the grouped results.
result.url string URL to the corresponding address resource for this result. 

Sample Response 

{
  "count": 43,
  "results": [
    {
      "id": "ZODGBREQHeBwAAAAABAwEAAAABSRZNUYAgAAAAADE1AAD..2QAAAAA.....wAAAAAAAAAAADE1IGJyYW1ibGUgY2xvc2UAns0WAlzbMk",
"text": "15 Bramble Close, Aston, BIRMINGHAM B6 5HW",
"grouped": false,
"url": "/capture/v1/address-layout/ZODGBREQHeBwAAAAABAwEAAAABSRZNUYAgAAAAADE1AAD..2QAAAAA.....wAAAAAAAAAAADE1IGJyYW1ibGUgY2xvc2UAns0WAlzbMk/" },
{ "id": "oODGBREQHeBwAAAAABAwEAAAABSTeukYAgAAAAADE1AAD..2QAAAAA.....wAAAAAAAAAAADE1IGJyYW1ibGUgY2xvc2UAHDATPZfBye", "text": "15 Bramble Close, Coleshill, BIRMINGHAM B46 1AX", "grouped": false, "url": "/capture/v1/address-layout/oODGBREQHeBwAAAAABAwEAAAABSTeukYAgAAAAADE1AAD..2QAAAAA.....wAAAAAAAAAAADE1IGJyYW1ibGUgY2xvc2UAHDATPZfBye/" } ] }

GET verify-address/text

This method verifies the address based on an unstructured text query.

GET https://api.experianmarketingservices.com/capture/v1/verify-address/text?query={address}&country={country ISO code}&id={id to refine on}&take={number of results to return}&skip={number of results to skip}

Optional parameters in italics.

Request

Parameters

NameRequiredExampleDescription
query yes experian%20data%20quality The address or refinement query to return matches for. This input should be HTTP encoded.
country yes USA The country to verify against. This value should correspond to a three-lettered value as defined by ISO 3166-1.
id no ZODGBREQHeBwAAAAABAwEAAAABSRZNUYAgAAAAADE1AAD The unique identifier of an address to filter results by. This parameter is used in interrogating the details of grouped results, e.g. tower blocks. 
skip no 0

The number of results to skip over. This allows results to be paginated when the number of results which could be returned is larger than the default or that of the take parameter. The default value is 0.

For example: if the returned results are A, B, C and D then
skip 1 take 2 will return and C;
skip 1 take 3 will return B, C, and D

take no 50 The number of matches to be returned in one request. The default value is 50

Sample requests

Final address:

GET https://api.experianmarketingservices.com/capture/v1/verify-address/text/?query=28%20Keeler%20Rd%2C%20Bridgewater%20CT%20%2006752&country=USA

List of addresses:

GET https://api.experianmarketingservices.com/capture/v1/verify-address/text/?query=121%20Massol%20Ave%2C%20Los%20Gatos%20CA%2095030&country=USA&take=2

Refinement:

GET https://api.experianmarketingservices.com/capture/v1/verify-address/text?id=690USA-lOUSADwHeBwEDAQABH4IxQAAAAAAAZAA-a8NP8qgyW2&query=103&country=USA

Response

Search results are returned as a final address or a picklist, depending on the verification level (degree of confidence in the returned match):

If verifylevel is Verified or InteractionRequired, a final address will be returned.

If verifylevel is PremisesPartial/StreetPartial/Multiple, picklist(s) will be returned which may require further refinement and/or address-layout to be called to get the final address.

This response is a lightweight representation of an address where the details are formatted onto a single line. This format is used to support smaller payloads required by many UI integrations:

NameValueDescription
count integer The total number of available results. This is not affected by the values supplied for the skip and take parameters.
prompt string A prompt that guides the user with specific action.
verifylevel string The unique match level that indicates the success of address search.
results object[] An array of search results.
result.id string The unique identifier for the address. This can be passed into the Search method to interrogate the details of grouped results, e.g. tower blocks. This can also be passed to the address-layout method to return the full address resource.
result.text string The address formatted as a single line of plain text with no breaks or formatting.
result.grouped boolean Indicates whether or not this result has grouped a large number of related addresses together (e.g. a tower block). A separate call to the refine method is required to retrieve the grouped results.
result.url string URL to the corresponding address resource for this result. 

Sample responses

Final address:

{
  "verifylevel": "Verified",
  "fields": [
    {
      "id": "",
"label": "",
"content": "28 Keeler Rd"
},
{ "id": "", "label": "", "content": "" { "id": "", "label": "", "content": "" { "id": "City name", "label": "City name", "content": "Bridgewater" { "id": "State code", "label": "State code", "content": "CT" { "id": "ZIP Code, +4 code", "label": "ZIP Code, +4 code", "content": "06752-1331" { "id": "Country", "label": "Country", "content": "United States of America" } ] }

List of addresses:

{
  "prompt": "Please confirm your Apt/Ste/Unit Number"
"verifylevel": "PremisesPartial",
"count": 13, "results": [ { "id": "690USA-fOUSADwHeBwEDAQABH4I0AAAAAAAAZAA-Ke1A8uddtC",
"text": "121 Massol Ave, Los Gatos CA 95030-5928",
"grouped": false,
"url": "/capture/v1/address-layout/690USA-fOUSADwHeBwEDAQABH4I0AAAAAAAAZAA-Ke1A8uddtC/" },
{
"id": "690USA-lOUSADwHeBwEDAQABH4IxQAAAAAAAZAA-a8NP8qgyW2", "text": "121 Massol Ave Apt 1 ... 103, Los Gatos CA 95030-5903", "grouped": true, "url": "/capture/v1/verify-address/text?country=USA&id=690USA-lOUSADwHeBwEDAQABH4IxQAAAAAAAZAA-a8NP8qgyW2&query=Please%20enter%20refinement%20text" } ] }

Refinement:

{
  "prompt": "Enter selection"
"count": 1, "results": [ { "id": "690USA-qOUSADwHeBwEDAQABH4IxQAAAAAAxMDMAAAA-EP31cl77KP",
"text": "121 Massol Ave Apt 103, Los Gatos CA 95030-5903",
"grouped": false,
"url": "/capture/v1/address-layout/690USA-qOUSADwHeBwEDAQABH4IxQAAAAAAxMDMAAAA-EP31cl77KP/" } ] }

 

GET /address-layout

This method returns a single, detailed address layout record for a supplied identifier.

GET /address-layout/{id}

Request

Parameters 

NameRequiredExampleDescription
id yes ZODGBREQHeBwAAAAABAwEAAAABSRZNUYAgAAAAADE1AAD The unique identifier of the address to be returned as a detailed address layout record. 

Sample requests

GBR:

GET https://api.experianmarketingservices.com/capture/v1/address-layout/690GBR-YOUSADwfdBwEDAQABHxCjwAAAAAAxMDMAAAA-/

USA:

GET https://api.experianmarketingservices.com/capture/v1/address-layout/690USA-YOUSADwfdBwEDAQABHxCjwAAAAAAxMDMAAAA-/

Canada:

GET https://api.experianmarketingservices.com/capture/v1/address-layout/690CAN-HOCANBQLeBwEDAQAASEU8wAAAAAAxMDEAAAA-/

Response

This service returns a fully-detailed representation of an address which contains the following properties:

NameValueDescription
fields object A representation of the detailed layout.
field.id string Currently returns the same value as field.label (see below).
field.label string A description of the layout element (e.g. “City” or “Postcode”). The value of this field will depend on the locale of the request.
field.content string The value of the layout element (e.g. “12 Main Street”).

Sample responses

GBR:

{
  "fields": [
     {
      "id": "",
      "label": "",
      "content": "15 Bramble Close"
     },
{ "id": "", "label": "", "content": "Aston" },
{ "id": "", "label": "", "content": "" },
{ "id": "Town", "label": "Town", "content": "Birmingham" },
{ "id": "County", "label": "County", "content": "" },
{ "id": "Postcode", "label": "Postcode", "content": "B6 5HW" },
{ "id": "Country", "label": "Country", "content": "United Kingdom"
} ] }

USA:

{
  "fields": [
     {
      "id": "",
      "label": "",
      "content": "121 Massol Ave Apt 103"
     },
{ "id": "", "label": "", "content": "" },
{ "id": "", "label": "", "content": "" },
{ "id": "City name", "label": "City name", "content": "Los Gatos" },
{ "id": "State code", "label": "State code", "content": "CA" },
{ "id": "ZIP Code, +4 code", "label": "ZIP Code, +4 code", "content": "95030-5903" },
{ "id": "Country", "label": "Country", "content": "United States of America"
} ] }

Canada:

{
  "fields": [
     {
      "id": "",
      "label": "",
      "content": "Genesee View Condominiums"
     },
{ "id": "", "label": "", "content": "101-351 Saguenay Dr" },
{ "id": "", "label": "", "content": "" },
{ "id": "Municipality name", "label": "Municipality name", "content": "SASKATOON" },
{ "id": "Province code", "label": "Province code", "content": "SK" },
{ "id": "Postal Code", "label": "Postal Code", "content": "S7K 5T4" },
{ "id": "Country", "label": "Country", "content": "Canada"
} ] }

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. 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 certificate might have expired. To manually update your deployment:
  1. Download the update files.
  2. Extract the files.
  3. Install Root.crt in the Trusted Root Certificates Authorities Store.
  4. Install Intermediate1.crt and Intermediate2.crt  in the Intermediate Certificate Authorities Store.
  5. Install api.experianmarketingservices.com.cer in the Personal Certificate Store.

For further help contact Experian support.