Data Quality user documentation
home/Address validation/Experian Address Validation/Get started/Upgrading

Upgrading

If you are looking to upgrade from Pro Web, Address Validate SOAP, Global Intuitive, or a combination of these to Experian Address Validation, you will need to understand the differences in integration approach and how to prepare for this.

If you are looking to upgrade from an on premises installation of Pro Web or our hosted Address Validate SOAP service to Experian Address Validation you will need to understand the differences in integration approach and how to prepare for this.

  • Supports Autocomplete search type for 245 countries and territories.

  • Along with custom address formatting, Experian Address validation offers a global 7 line address collection, a full component breakdown, and available metadata for the selected address. The 7 lines are for displaying back to the end user in a consistent manner for all countries and territories across the world, while the component collection allows for specific components to be entered into your database.

  • Enrich your data with global geolocation as well as business and consumer demographic data with Experian Enrichment.

  • Experian Address Validation can be much more interactive compared with Address Validate SOAP, therefore more requests may be made, when using the Autocomplete search type.

  • You might need additional licenses and new authentication tokens to take advantage of all available datasets.

  • You need to re-integrate your solution against our REST API. Use the below mapping of the requests and have a look at our sample code to get started.

    Address Validate SOAP and Pro Web request Experian Address Validation request
    DoSearch using Singleline /address/search/v1
    DoSearch using Typedown /address/search/v1
    DoSearch using Verification /address/validate/v1
    DoSearch using Keyfinder /address/lookup/v1
    DoRefine /address/suggestions/stepIn
    /address/suggestions/refine
    DoGetAddress /address/format/v1

  • Experian Address Valdation uses token based authentication. Customers will not be able to use existing username/password credentials from Address Validate SOAP when using Experian Address Validation. Existing Auth-Tokens are compatiable when used against the same datasets.

  • Pro Web customers should understand that Experian Address Validation is a multi-tenant API service and uses rate limiting to ensure our service is available for all our customers at all times. Additionally, you should consider the additional security implications of calling out to an external API, for example firewalls changes.

  • Supports Autocomplete search type for 245 countries and territories.

  • By upgrading to Experian Address Validation, you can take advantage of additional search types that are optimized for different use cases, from supplying a few search terms to full address validation.

  • Along with custom address formatting, Experian Address Validation offers a global 7 line address collection, a full component breakdown, and available metadata for the selected address. The 7 lines ensure that, for all countries and territories across the world, the formatted addresses are returned to the end user in a consistent manner, while the component collection allows for specific address components to be entered into your database.

  • Enrich your data with global geolocation data, as well as business and consumer demographic data, with Experian Enrichment.

  • You might need additional licenses and new authentication tokens to take advantage of all available datasets.

  • All query parameters of the requests, for example the country and query, have to be updated and moved to the request body. You'll find multiple examples in the API specification.
  • With moving the query parameters to the request body, your search request needs to be updated.
  • You will need to update your parsing of the formatted address. You can find examples in the API specification as well as additional information in the Format response.

Address Validation REST supports validating a Canadian address via /verify-address/. Use the below mapping of the requests and have a look at our sample code to get started. We also provide like-for-like example request/response pairs below.

Usecase Address Validation REST request Experian Address Validation request
Validate an address /capture/v1/verify-address/text/ /address/validate/v1/
Refine a list of addresses /capture/v1/verify-address/text/ /address/suggestions/refine/v1/
Format an address /capture/v1/address-layout/{id}/ /address/format/v1/{global_address_key}/

Validate an address - /verify-address/

Address Validation REST

Currently, when validating an address, for example "20615 main st se, t3m3g4" your integration will create a request similar to the below. The country and search terms gets passed to Experian as a query parameter, while your authentication token is passed in the header.

GET /capture/v1/verify-address/text?query=20615%20main%20st%20se,%20t3m3g4&country=can HTTP/1.1
Host: https://api.experianmarketingservices.com
Auth-Token: <YOUR_AUTH_TOKEN>

The response will contain the address match level in the verifylevel attribute. When a full address is returned, the formatted address is returned as part of a 7 line fields array.

{
  "verifylevel": "Verified",
  "fields": [
    { "id": "", "label": "", "content": "20615 Main St SE" },
    { "id": "", "label": "", "content": "" },
    { "id": "", "label": "", "content": "" },
    { "id": "Municipality name", "label": "Municipality name", "content": "CALGARY" },
    { "id": "Province code", "label": "Province code", "content": "AB" },
    { "id": "Postal code", "label": "Postal code", "content": "T3M 3G4" },
    { "id": "Country", "label": "Country", "content": "Canada" }
  ]
}

Experian Address Validation

The same validation request against Experian Address Validation needs to create a request like the below. The query parameters query and country do not exist anymore. Their values need to be supplied in the body of the request as country_iso and unspecified. Your authentication token is still submitted in the header. We suggest you also parse a UUID as the reference ID in the header to enable end to end request traceability between your systems and ours.

POST /address/validate/v1 HTTP/1.1
Host: https://api.experianaperture.io
Auth-Token: <YOUR_AUTH_TOKEN>
Reference-Id: <YOUR_REFERENCE_ID>
Content-Type: application/json

{
  "country_iso": "can",
  "components": {
    "unspecified": [ "20615 main st se, t3m3g4" ]
  },
  "datasets": [ "ca-address" ]
}

In Experian Address Validation, the address match level is returned in the confidence attribute. More information on the address components that had to be corrected to achieve the match can be found in the validation_detail object. When a full address is returned, the formatted address is returned as part of a 7 line address object. In addition, with Experian Address Validation, you have the ability to customize the returned address to fit with your schema, or to return the address broken down into its components and metadata.

{
  "result": {
    "validation_detail": {
      "city_name_corrected": true,
      "state_corrected": true
    },
    "global_address_key": "aWQ9MjA2MTUgbWFpbiBzdC",
    "confidence": "Verified match",
    "address": {
      "address_line_1": "20615 Main St SE",
      "address_line_2": "",
      "address_line_3": "",
      "locality": "CALGARY",
      "region": "AB",
      "postal_code": "T3M 3G4",
      "country": "CANADA"
    }
  }
}

Refine a list of addresses - /verify-address/

Address Validation REST

To refine a list of addresses, your integration passes the country, the id of the address, and the refinement terms to Experian as query parameters, while your authentication token is passed in the header. Your integration will create a request similar to the below.

GET /capture/v1/verify-address/text?country=can&id=<ID_OF_THE_ADDRESS>&query=<REFINEMENT> HTTP/1.1
Host: https://api.experianmarketingservices.com
Auth-Token: <YOUR_AUTH_TOKEN>

Given the truncated response of a previous request:

...
  {
    "id": "762CAN-GOCANDwLoBwAAA",
    "text": "20568 ... 20636 Main St SE, CALGARY AB   [even] T3M 3G4",
    "grouped": true,
    "url": "/capture/v1/verify-address/text?country=can&id=762CAN-GOCANDwLoBwAAA&query=Please%20enter%20refinement%20text"
  },
...

The value of the id parameter is taken from the response to /verify-address/ and the refinement term is passed in as the query parameter. The below request will drill down into the above range to building number 20630.

GET /capture/v1/verify-address/text?country=can&id=762CAN-GOCANDwLoBwAAA&query=20630 HTTP/1.1
Host: https://api.experianmarketingservices.com
Auth-Token: <YOUR_AUTH_TOKEN>

The response contains the ID of the validated address, which you should use to format the address.

{
  "prompt": "Enter selection",
  "verifylevel": "None",
  "count": 1,
  "results": [
    {
      "id": "762CAN-0OCANDwfoBwAAAAAEAwEAAABXG",
      "text": "20630 Main St SE, CALGARY AB",
      "grouped": false,
      "url": "/capture/v1/address-layout/762CAN-0OCANDwfoBwAAAAAEAwEAAABXG/"
    }
  ]
}

Experian Address Validation

To refine a list of suggestions in Experian Address Validation, you need to use the /suggestions/refine/v1/ method. The method's path parameter includes the global_address_key of the suggestion to refine. The body specifies the refinement terms.

Given the truncated response of a previous request:

...
  {
    "global_address_key": "aWQ9MjA1NjggLi4uIDIwNjM2IE1haW4gU3QgU0UsIENBTEdBUlkgQUIgIF",
    "text": "20568 ... 20636 Main St SE, CALGARY AB  T3M 3G4",
    "additional_attributes": [
      { "name": "picklist_display", "value": "20568 ... 20636 Main St SE, CALGARY AB   [even]" },
      { "name": "score", "value": "100" },
      { "name": "postcode", "value": "T3M 3G4" },
      { "name": "multiples", "value": "true" },
      { "name": "unresolvable_range", "value": "true" }
    ]
  },
...

Refining an address range with Experian Address Validation requires the integration to create a request like the below. You still pass in the ID of the address as part of the url path. You obtain the ID, called global_address_key, by using the /search/v1/ or /validate/v1/ methods. The refinement terms are passed in the request body. Your authentication token is still submitted in the header. We suggest you also parse a UUID as the reference ID in the header to enable end to end request traceability between your systems and ours.

POST /address/suggestions/refine/v1/<GLOBAL_ADDRESS_KEY_OF_THE_ADDRESS> HTTP/1.1
Host: https://api.experianaperture.io
Auth-Token: <YOUR_AUTH_TOKEN>
Reference-Id: <YOUR_REFERENCE_ID>
Content-Type: application/json

{
  "refinement": "20630"
}

The response contains the global address key of the validated address, which you should use to format the address.

{
  "result": {
    "more_results_available": false,
    "confidence": "Verified match",
    "suggestions_key": "aWQ9fmFsdF9rZXk9fmRhdGFzZXQ",
    "suggestions_prompt": "Enter selection",
    "suggestions": [
      {
        "global_address_key": "aWQ9MjA2MzAgTWFpbiBTdCB",
        "text": "20630 Main St SE, CALGARY AB  T3M 3G4",
        "format": "https://api.experianaperture.io/address/format/v1/aWQ9MjA2MzAgTWFpbiBTdCB",
        "additional_attributes": [
          { "name": "picklist_display", "value": "20630 Main St SE, CALGARY AB" },
          { "name": "score", "value": "0" },
          { "name": "full_address", "value": "true" }
        ]
      }
    ]
  }
}

Format an address - /address-layout/

Address Validation REST

Currently, when formatting an address, your integration will create a request similar to the below. The ID of the address to format is passed in. You obtained this ID by using /search-address/ or under certain circumstances /verify-address/. Your authentication token is passed in the header.

GET /capture/v1/address-layout/<ID_OF_THE_ADDRESS> HTTP/1.1
Host: https://api.experianmarketingservices.com
Auth-Token: <YOUR_AUTH_TOKEN>

The response will contain the selected address in the fields array and format it into its default 7 line structure.

{
  "fields": [
    { "id": "", "label": "", "content": "20630 Main St SE" },
    { "id": "", "label": "", "content": "" },
    { "id": "", "label": "", "content": "" },
    { "id": "Municipality name", "label": "Municipality name", "content": "CALGARY" },
    { "id": "Province code", "label": "Province code", "content": "AB" },
    { "id": "Postal code", "label": "Postal code", "content": "T3M 3G4" },
    { "id": "Country", "label": "Country", "content": "Canada" }
  ]
}

Experian Address Validation

Formatting an address with Experian Address Validation requires the integration to create a request like the below. You still pass in the ID of the address as part of the url path. You obtain the ID, called global_address_key, by using the /search/v1/ or /validate/v1/ methods. Your authentication token is still submitted in the header. We suggest you also parse a UUID as the reference ID in the header to enable end to end request traceability between your systems and ours.

GET /address/format/v1/<GLOBAL_ADDRESS_KEY_OF_THE_ADDRESS> HTTP/1.1
Host: https://api.experianaperture.io
Auth-Token: <YOUR_AUTH_TOKEN>
Reference-Id: <YOUR_REFERENCE_ID>
Content-Type: application/json

By default, Experian Address Validation formats the address into a similar structure. The address in contained in a 7 line address object. However, you have the option to customize the response to a format that adheres with your website or database schema. A partial, truncated response is shown below.

{
  "result": {
    "global_address_key": "aWQ9MjA2MTUgbWFpbiBzdC",
    "confidence": "Verified match",
    "address": {
      "address_line_1": "20630 Main St SE",
      "address_line_2": "",
      "address_line_3": "",
      "locality": "CALGARY",
      "region": "AB",
      "postal_code": "T3M 3G4",
      "country": "CANADA"
    }
  }
}

Address Validation REST consists of three GET methods - /search-address/, /verify-address/, and /address-layout/. Use the below mapping of the requests and have a look at our sample code to get started. We also provide like-for-like example request/response pairs below.

Usecase Address Validation REST request Experian Address Validation request
Search for an address /capture/v1/search-address/text/ /address/search/v1/
Validate an address /capture/v1/verify-address/text/ /address/validate/v1/
Format an address /capture/v1/address-layout/{id}/ /address/format/v1/{global_address_key}/

Search for an address - /search-address/

Address Validation REST

Currently, when searching on "1 thompson st, nottingh" your integration will create a request similar to the below. The country and search terms gets passed to Experian as a query parameter, while your authentication token is passed in the header.

GET /capture/v1/search-address/text?query=1%20thompson%20st,%20nottingh&country=gbr HTTP/1.1
Host: https://api.experianmarketingservices.com
Auth-Token: <YOUR_AUTH_TOKEN>

Potential results will be returned in the results array. A partial, truncated response is shown below.

{
  "count": 35,
  "results": [
    {
      "id": "762GBR-7OGBREQXoBwAAAAABAwEAAAA",
      "text": "1 Thompson Street, Langley Mill, NOTTINGHAM NG16 4DD",
      "grouped": false,
      "url": "/capture/v1/address-layout/762GBR-7OGBREQXoBwAAAAABAwEAAAA/"
    },
    {
      "id": "762GBR-IOGBREQXoBwAAAAABAwEAAAABEoo",
      "text": "1a Thompson Street, Langley Mill, NOTTINGHAM NG16 4DD",
      "grouped": false,
      "url": "/capture/v1/address-layout/762GBR-IOGBREQXoBwAAAAABAwEAAAABEoo/"
    }
  ]
}

Experian Address Validation

The same search request against Experian Address Validation needs to create a request like the below. The query parameters query and country do not exist anymore. Their values need to be supplied in the body of the request as country_iso and unspecified. Your authentication token is still submitted in the header. We suggest you also parse a UUID as the reference ID in the header to enable end to end request traceability between your systems and ours.

POST /address/search/v1 HTTP/1.1
Host: https://api.experianaperture.io
Auth-Token: <YOUR_AUTH_TOKEN>
Reference-Id: <YOUR_REFERENCE_ID>
Content-Type: application/json

{
  "country_iso": "gbr",
  "components": {
    "unspecified": [ "1 thompson st, nottingh" ]
  },
  "datasets":[ "gb-address" ],
  "options":[
    {"name":"search_type", "value":"singleline"}
  ]
}

Similar to Address Validate REST, potential results will be returned in the suggestions array. In addition, the response contains the global_address_key - an ID to use within your workflow to retrieve the address selected by your end user. A partial, truncated response is shown below.

{
  "result": {
    "more_results_available": false,
    "confidence": "Multiple matches",
    "suggestions_key": "aWQ9fmFsdF9rZXk9fmRhdGFzZXQ9R0JSfmZvcm1hdF9rZXk9R0JSJEdCUiQ3LjczMFhTR0JSR",
    "suggestions_prompt": "Enter selection",
    "suggestions": [
      {
        "global_address_key": "aWQ9Um9iaW4gSG9vZCAmIExpdHRsZS",
        "text": "1 Thompson Street, Langley Mill, NOTTINGHAM NG16 4DD",
        "format": "https://api.experianaperture.io/address/format/v1/aWQ9Um9iaW4gSG9vZCAmIExpdHRsZS",
        "additional_attributes": [
          { "name": "picklist_display", "value": "1 Thompson Street, Langley Mill, NOTTINGHAM" },
          { "name": "score", "value": "86" },
          { "name": "postcode", "value": "NG16 4DD" },
          { "name": "full_address", "value": "true" }
        ]
      },
      {
        "global_address_key": "aWQ9MSBPbGQgQ3Jvc3MgSG91c2",
        "text": "1a Thompson Street, Langley Mill, NOTTINGHAM NG16 4DD",
        "format": "https://api.experianaperture.io/address/format/v1/aWQ9MSBPbGQgQ3Jvc3MgSG91c2",
        "additional_attributes": [
          { "name": "picklist_display", "value": "1a Thompson Street, Langley Mill, NOTTINGHAM" },
          { "name": "score", "value": "83" },
          { "name": "postcode", "value": "NG16 4DD" },
          { "name": "full_address", "value": "true" }
        ]
      }
    ]
  }
}

Validate an address - /verify-address/

Address Validation REST

Currently, when validating an address, for example "35 Douglas st, de238lh" your integration will create a request similar to the below. The country and search terms gets passed to Experian as a query parameter, while your authentication token is passed in the header.

GET /capture/v1/verify-address/text?query=35%20Douglas%20st,%20de238lh&country=gbr HTTP/1.1
Host: https://api.experianmarketingservices.com
Auth-Token: <YOUR_AUTH_TOKEN>

The response will contain the address match level in the verifylevel attribute. When a full address is returned, the formatted address is returned as part of a 7 line fields array.

{
  "verifylevel": "Verified",
  "fields": [
    { "id": "", "label": "", "content": "35 Douglas Street" },
    { "id": "", "label": "", "content": "" },
    { "id": "", "label": "", "content": "" },
    { "id": "Town", "label": "Town", "content": "Derby" },
    { "id": "County", "label": "County", "content": "" },
    { "id": "Postcode", "label": "Postcode", "content": "DE23 8LH" },
    { "id": "Country", "label": "Country", "content": "United Kingdom" }
  ]
}

Experian Address Validation

The same validation request against Experian Address Validation needs to create a request like the below. The query parameters query and country do not exist anymore. Their values need to be supplied in the body of the request as country_iso and unspecified. Your authentication token is still submitted in the header. We suggest you also parse a UUID as the reference ID in the header to enable end to end request traceability between your systems and ours.

POST /address/validate/v1 HTTP/1.1
Host: https://api.experianaperture.io
Auth-Token: <YOUR_AUTH_TOKEN>
Reference-Id: <YOUR_REFERENCE_ID>
Content-Type: application/json

{
  "country_iso": "gbr",
  "components": {
    "unspecified": [ "35 Douglas st, de238lh" ]
  },
  "datasets":[ "gb-address" ]
}

In Experian Address Validation, the address match level is returned in the confidence attribute. When a full address is returned, the formatted address is returned as part of a 7 line address object. In addition, with Experian Address Validation, you have the ability to customize the returned address to fit with your schema, or to return the address broken down into its components and metadata.

{
  "result": {
    "global_address_key": "aWQ9MzUgRG91Z2xhcyBzdCwgZGUyMzhsaCwgVW5p",
    "confidence": "Verified match",
    "address": {
      "address_line_1": "35 Douglas Street",
      "address_line_2": "",
      "address_line_3": "",
      "locality": "DERBY",
      "region": "",
      "postal_code": "DE23 8LH",
      "country": "UNITED KINGDOM"
    }
  }
}

Format an address - /address-layout/

Address Validation REST

Currently, when formatting an address, your integration will create a request similar to the below. The ID of the address to format is passed in. You obtained this ID by using /search-address/ or under certain circumstances /verify-address/. Your authentication token is passed in the header.

GET /capture/v1/address-layout/<ID_OF_THE_ADDRESS> HTTP/1.1
Host: https://api.experianmarketingservices.com
Auth-Token: <YOUR_AUTH_TOKEN>

The response will contain the selected address in the fields array and format it into its default 7 line structure.

{
  "fields": [
    { "id": "", "label": "", "content": "35 Douglas Street" },
    { "id": "", "label": "", "content": "" },
    { "id": "", "label": "", "content": "" },
    { "id": "Town", "label": "Town", "content": "Derby" },
    { "id": "County", "label": "County", "content": "" },
    { "id": "Postcode", "label": "Postcode", "content": "DE23 8LH" },
    { "id": "Country", "label": "Country", "content": "United Kingdom" }
  ]
}

Experian Address Validation

Formatting an address with Experian Address Validation requires the integration to create a request like the below. You still pass in the ID of the address as part of the url path. You obtain the ID, called global_address_key, by using the /search/v1/ or /validate/v1/ methods. Your authentication token is still submitted in the header. We suggest you also parse a UUID as the reference ID in the header to enable end to end request traceability between your systems and ours.

GET /address/format/v1/<GLOBAL_ADDRESS_KEY_OF_THE_ADDRESS> HTTP/1.1
Host: https://api.experianaperture.io
Auth-Token: <YOUR_AUTH_TOKEN>
Reference-Id: <YOUR_REFERENCE_ID>
Content-Type: application/json

By default, Experian Address Validation formats the address into a similar structure. The address in contained in a 7 line address object. However, you have the option to customize the response to a format that adheres with your website or database schema. A partial, truncated response is shown below.

{
  "result": {
    "global_address_key": "aWQ9MSBSaXZlciBSZCwgU2NoZW5lY3RhZHkgTlkgMTIzMDUsIFVua",
    "confidence": "Verified match",
    "address": {
      "address_line_1": "35 Douglas Street",
      "address_line_2": "",
      "address_line_3": "",
      "locality": "DERBY",
      "region": "",
      "postal_code": "DE23 8LH",
      "country": "UNITED KINGDOM"
    }
  }
}

Address Validation REST consists of three GET methods - /search-address/, /verify-address/, and /address-layout/. Use the below mapping of the requests and have a look at our sample code to get started. We also provide like-for-like example request/response pairs below.

Usecase Address Validation REST request Experian Address Validation request
Search for an address /capture/v1/search-address/text/ /address/search/v1/
Validate an address /capture/v1/verify-address/text/ /address/validate/v1/
Refine a list of addresses /capture/v1/verify-address/text/ /address/suggestions/refine/v1/
Format an address /capture/v1/address-layout/{id}/ /address/format/v1/{global_address_key}/

Search for an address - /search-address/

Address Validation REST

Currently, when searching on "1 river rd, sch" your integration will create a request similar to the below. The country and search terms gets passed to Experian as a query parameter, while your authentication token is passed in the header.

GET /capture/v1/search-address/text?query=1%20river%20rd,%20sch&country=usa HTTP/1.1
Host: https://api.experianmarketingservices.com
Auth-Token: <YOUR_AUTH_TOKEN>

Potential results will be returned in the results array. A partial, truncated response is shown below.

{
  "count": 5,
  "results": [
    {
      "id": "762USA-4OUSADwHoBwAAAAAIAgEAAAAF7WPCUAAgAA",
      "text": "1 River Rd, Schenectady, NY, 12305",
      "grouped": false,
      "url": "/capture/v1/verify-address/text?query=1%20River%20Rd%2C%20Schenectady%2C%20NY%2C%2012305&country=USA"
    },
    {
      "id": "762USA-0OUSADwHoBwAAAAAIAgEAAAAF7Yx40AAgAAAAAAAAAA",
      "text": "1 River Rd, Schenectady, NY, 12345",
      "grouped": false,
      "url": "/capture/v1/verify-address/text?query=1%20River%20Rd%2C%20Schenectady%2C%20NY%2C%2012345&country=USA"
    }
  ]
}

Experian Address Validation

The same search request against Experian Address Validation needs to create a request like the below. The query parameters query and country do not exist anymore. Their values need to be supplied in the body of the request as country_iso and unspecified. Your authentication token is still submitted in the header. We suggest you also parse a UUID as the reference ID in the header to enable end to end request traceability between your systems and ours.

POST /address/search/v1 HTTP/1.1
Host: https://api.experianaperture.io
Auth-Token: <YOUR_AUTH_TOKEN>
Reference-Id: <YOUR_REFERENCE_ID>
Content-Type: application/json

{
  "country_iso": "usa",
  "components": {
    "unspecified": [ "1 river rd, sch" ]
  },
  "datasets":[ "us-address" ]
}

Similar to Address Validate REST, potential results will be returned in the suggestions array. In addition, the response contains the global_address_key - an ID to use within your workflow to retrieve the address selected by your end user. A partial, truncated response is shown below.

{
  "result": {
    "more_results_available": true,
    "confidence": "Multiple matches",
    "suggestions": [
      {
        "global_address_key": "aWQ9MSBSaXZlciBSZCwgU2NoZW5lY3RhZHkgTlkgMTIzND",
        "text": "1 River Rd, Schenectady NY 12345",
        "matched": [ [27, 28], [12, 15], [8, 10], [2, 7], [0, 1] ],
        "format": "https://api.experianaperture.io/address/format/v1/aWQ9MSBSaXZlciB"
      },
      {
        "global_address_key": "aWQ9MSBSaXZlciBSZCwgU2NoZW5lY3RhZHkgT",
        "text": "1 River Rd, Schenectady NY 12305",
        "matched": [ [27, 28], [12, 15], [8, 10], [2, 7], [0, 1] ],
        "format": "https://api.experianaperture.io/address/format/v1/aWQ9MSBSaXZlciBSZC"
      }
    ]
  }
}

Validate an address - /verify-address/

Address Validation REST

Currently, when validating an address, for example "1 river rd,ny,12345" your integration will create a request similar to the below. The country and search terms gets passed to Experian as a query parameter, while your authentication token is passed in the header.

GET /capture/v1/verify-address/text?query=1%20river%20rd,ny,12345&country=usa HTTP/1.1
Host: https://api.experianmarketingservices.com
Auth-Token: <YOUR_AUTH_TOKEN>

The response will contain the address match level in the verifylevel attribute. When a full address is returned, the formatted address is returned as part of a 7 line fields array.

{
  "fields": [
    { "id": "", "label": "", "content": "1 River Rd" },
    { "id": "", "label": "", "content": "" },
    { "id": "", "label": "", "content": "" },
    { "id": "City name", "label": "City name", "content": "Schenectady" },
    { "id": "State code", "label": "State code", "content": "NY" },
    { "id": "ZIP Code, +4 code", "label": "ZIP Code, +4 code", "content": "12345-6000" },
    { "id": "Country", "label": "Country", "content": "United States of America" }
  ]
}

Experian Address Validation

The same validation request against Experian Address Validation needs to create a request like the below. The query parameters query and country do not exist anymore. Their values need to be supplied in the body of the request as country_iso and unspecified. Your authentication token is still submitted in the header. We suggest you also parse a UUID as the reference ID in the header to enable end to end request traceability between your systems and ours.

POST /address/validate/v1 HTTP/1.1
Host: https://api.experianaperture.io
Auth-Token: <YOUR_AUTH_TOKEN>
Reference-Id: <YOUR_REFERENCE_ID>
Content-Type: application/json

{
  "country_iso": "usa",
  "components": {
    "unspecified": [ "1 river rd,ny,12345" ]
  },
  "datasets":[ "us-address" ]
}

In Experian Address Validation, the address match level is returned in the confidence attribute. More information on the address components that had to be corrected to achieve the match can be found in the validation_detail object. When a full address is returned, the formatted address is returned as part of a 7 line address object. In addition, with Experian Address Validation, you have the ability to customize the returned address to fit with your schema, or to return the address broken down into its components and metadata.

{
  "result": {
    "validation_detail": {
      "city_name_corrected": true,
      "zip_code_corrected": true
    },
    "global_address_key": "gU2NoZW5lY3RhZHkgTlkgMTI",
    "confidence": "Verified match",
    "address": {
      "address_line_1": "1 River Rd",
      "address_line_2": "",
      "address_line_3": "",
      "locality": "Schenectady",
      "region": "NY",
      "postal_code": "12345-6000",
      "country": "UNITED STATES OF AMERICA"
    }
  }
}

Refine a list of addresses - /verify-address/

Address Validation REST

To refine a list of addresses, your integration passes the country, the id of the address, and the refinement terms to Experian as query parameters, while your authentication token is passed in the header. Your integration will create a request similar to the below.

GET /capture/v1/verify-address/text?country=usa&id=<ID_OF_THE_ADDRESS>&query=<REFINEMENT> HTTP/1.1
Host: https://api.experianmarketingservices.com
Auth-Token: <YOUR_AUTH_TOKEN>

Given the truncated response of a previous request:

...
  {
    "id": "762USA-POUSADwboBwAAAAAEAwE",
    "text": "29 Broadway Apt 1A ... B, Haverstraw NY 10927-1186",
    "grouped": true,
    "url": "/capture/v1/verify-address/text?country=usa&id=762USA-POUSADwboBwAAAAAEAwE&query=Please%20enter%20refinement%20text"
  },
...

The value of the id parameter is taken from the response to /verify-address/ and the refinement term is passed in as the query parameter. The below request will drill down into the above range to apartment 1a.

GET /capture/v1/verify-address/text?country=usa&id=762USA-POUSADwboBwAAAAAEAwE&query=1a HTTP/1.1
Host: https://api.experianmarketingservices.com
Auth-Token: <YOUR_AUTH_TOKEN>

The response contains the ID of the validated address, which you should use to format the address.

{
  "prompt": "Enter selection",
  "verifylevel": "None",
  "count": 1,
  "results": [
    {
      "id": "762USA-pOUSADwboBwAAAAAEAwEAAAA",
      "text": "29 Broadway Apt 1A, Haverstraw NY",
      "grouped": false,
      "url": "/capture/v1/address-layout/762USA-pOUSADwboBwAAAAAEAwEAAAA/"
    }
  ]
}

Experian Address Validation

To refine a list of suggestions in Experian Address Validation, you need to use the /suggestions/refine/v1/ method. The method's path parameter includes the global_address_key of the suggestion to refine. The body specifies the refinement terms.

Given the truncated response of a previous request:

...
  {
    "global_address_key": "aWQ9MjA1NjggLi4uIDIwNjM2IE1haW4gU3QgU0UsIENBTEdBUlkgQUIgIF",
    "text": "29 Broadway Apt 1A ... B, Haverstraw NY 10927-1186",
    "additional_attributes": [
      { "name": "picklist_display", "value": "29 Broadway Apt 1A ... B, Haverstraw NY" },
      { "name": "score", "value": "95" },
      { "name": "postcode", "value": "10927-1186" },
      { "name": "multiples", "value": "true" },
      { "name": "unresolvable_range", "value": "true" }
    ]
  },
...

Refining an address range with Experian Address Validation requires the integration to create a request like the below. You still pass in the ID of the address as part of the url path. You obtain the ID, called global_address_key, by using the /search/v1/ or /validate/v1/ methods. The refinement terms are passed in the request body. Your authentication token is still submitted in the header. We suggest you also parse a UUID as the reference ID in the header to enable end to end request traceability between your systems and ours.

POST /address/suggestions/refine/v1/<GLOBAL_ADDRESS_KEY_OF_THE_ADDRESS> HTTP/1.1
Host: https://api.experianaperture.io
Auth-Token: <YOUR_AUTH_TOKEN>
Reference-Id: <YOUR_REFERENCE_ID>
Content-Type: application/json

{
  "refinement": "1a"
}

The response contains the global address key of the validated address, which you should use to format the address.

{
  "result": {
    "more_results_available": false,
    "confidence": "Verified match",
    "suggestions_key": "aWQ9fmFsdF9rZXk9fmRhdGFzZXQ",
    "suggestions_prompt": "Enter selection",
    "suggestions": [
      {
        "global_address_key": "aWQ9MjkgQnJvYWR3YXkgQXB0IDFBLCBIYX",
        "text": "29 Broadway Apt 1A, Haverstraw NY 10927-1186",
        "format": "https://api.experianaperture.io/address/format/v1/aWQ9MjkgQnJvYWR3YXkgQXB0IDFBLCBIYX",
        "additional_attributes": [
          { "name": "picklist_display", "value": "29 Broadway Apt 1A, Haverstraw NY" },
          { "name": "score", "value": "0" },
          { "name": "full_address", "value": "true" }
        ]
      }
    ]
  }
}

Format an address - /address-layout/

Address Validation REST

Currently, when formatting an address, your integration will create a request similar to the below. The ID of the address to format is passed in. You obtained this ID by using /search-address/ or under certain circumstances /verify-address/. Your authentication token is passed in the header.

GET /capture/v1/address-layout/<ID_OF_THE_ADDRESS> HTTP/1.1
Host: https://api.experianmarketingservices.com
Auth-Token: <YOUR_AUTH_TOKEN>

The response will contain the selected address in the fields array and format it into its default 7 line structure.

{
  "fields": [
    { "id": "", "label": "", "content": "1 River Rd" },
    { "id": "", "label": "", "content": "" },
    { "id": "", "label": "", "content": "" },
    { "id": "City name", "label": "City name", "content": "Schenectady" },
    { "id": "State code", "label": "State code", "content": "NY" },
    { "id": "ZIP Code, +4 code", "label": "ZIP Code, +4 code", "content": "12345-6000" },
    { "id": "Country", "label": "Country", "content": "United States of America" }
  ]
}

Experian Address Validation

Formatting an address with Experian Address Validation requires the integration to create a request like the below. You still pass in the ID of the address as part of the url path. You obtain the ID, called global_address_key, by using the /search/v1/ or /validate/v1/ methods. Your authentication token is still submitted in the header. We suggest you also parse a UUID as the reference ID in the header to enable end to end request traceability between your systems and ours.

GET /address/format/v1/<GLOBAL_ADDRESS_KEY_OF_THE_ADDRESS> HTTP/1.1
Host: https://api.experianaperture.io
Auth-Token: <YOUR_AUTH_TOKEN>
Reference-Id: <YOUR_REFERENCE_ID>
Content-Type: application/json

By default, Experian Address Validation formats the address into a similar structure. The address in contained in a 7 line address object. However, you have the option to customize the response to a format that adheres with your website or database schema. A partial, truncated response is shown below.

{
  "result": {
    "global_address_key": "aWQ9MSBSaXZlciBSZCwgU2NoZW5lY3RhZHkgTlkgMTIzMDUsIFVua",
    "confidence": "Verified match",
    "address": {
      "address_line_1": "1 River Rd",
      "address_line_2": "",
      "address_line_3": "",
      "locality": "Schenectady",
      "region": "NY",
      "postal_code": "12345-6000",
      "country": "UNITED STATES OF AMERICA"
    }
  }
}

  • By updating to Experian Address Validation you can take advantage of additional search types that are optimized for different use cases, from supplying a few search terms to full address validation.

  • You might need additional licenses and new authentication tokens to take advantage of all available datasets.

  • While Global Intuitive only supports a fixed response layout, you can define and use your own custom layout with Experian Address Validaton.

  • To protect your authentication token from being used fraudulently, Experian Address Validation accepts the auth-token in the request header only. Update your integration to send the auth-token in the header instead of a plain text query parameter.

  • All query parameters of the /search request, for example the search term, have been moved to the request body. You'll find multiple examples in the API specification.

  • With moving the query parameters to the request body, the HTTP method for the /search endpoint needs to be updated from GET to POST.

  • You will need to update the parsing of the /format response as new objects have been created for related elements within the components collection. You can find examples in the API specification as well as additional information in the Format response.

You will be able to continue to user your existing REST/SOAP hybrid solution, however you will have the option to use a single modern REST API going forward.

  • Simplify your solution by integrating against a single REST API that has all the functionality of previous REST and SOAP APIs.

  • You need to re-integrate your solution against our REST API. Use the below mapping of the requests and have a look at our sample code to get started.

    Address Validate SOAP and Pro Web request Experian Address Validation request
    DoSearch using Singleline /address/search/v1
    DoSearch using Typedown /address/search/v1
    DoSearch using Verification /address/validate/v1
    DoSearch using Keyfinder /address/lookup/v1
    DoRefine /address/suggestions/stepIn
    /address/suggestions/refine
    DoGetAddress /address/format/v1
Experian Address Validation

Get started

Related Resources