When a search has been performed by our service, the list of suggestions that is returned contains many properties and flags, the can_step_in property can be used to simplify the address validation process for your user. The flag should be checked after the search has been performed, but before the results are presented to the user.
Use the /suggestions/stepin/ endpoint when your list of suggestions contains a single match, with a high match score and the can_step_in property set to true. In this case, we suggest that your integration automatically steps into that single match, without displaying the suggestion to the user.

Headers

Name Type Description
Auth-Token string Input your unique token here. This is required to submit an API request.
x-app-key
(Optional)
string Alternative authentication header. Auth-Token takes precedence.
Reference-Id
(Optional)
string Identifier that will be returned to the response to help you track the request.
Timeout-Seconds
(Optional)
integer Maximum time you are prepared to wait for a response, expressed in seconds.
Acceptable values: 2-15. If a timeout occurs, an HTTP status code of 408 - Request Timeout will be returned.

The default value of this setting is 15.

Path

Name Type Description
global_address_key string Global address key of the suggestion you want to step into.

Headers

Name Type Description
Reference-Id
(Optional)
String Identifier that was supplied by you in the request header to help you track the request.

Body

The response from the API returns the below fields within a result object. Should an error occur, an error object is returned instead.

Name Type Description
more_results_available boolean To indicate that there are more suggestions available than returned in this request.
confidence string The confidence level of the search result.
  • Verified match: The input was matched to a single deliverable address in our data. This result may be slightly different from the provided address because we corrected formatting/spelling errors and added any missing address elements.
  • Multiple matches: The input was matched to more than one deliverable address in our data. This can happen when the provided address doesn't contain enough information to return just one match. As a result, the returned addresses may or may not be deliverable addresses. Therefore, a list of suggestions containing all the matches will be returned and the user has to select the required address.
  • Too many matches: The input was too broad and matched too many addresses in our data. The user should be further prompted to provide additional information.
  • Interaction required: The input was matched to a single deliverable address in our data. However, user interaction is recommended as the confidence in the validity of this address is not high enough for it to be classed as a *Verified match*.
  • Premises partial: The input was partially matched to a deliverable address in our data. For example, a search on "Flat A, 63 Southerton Road, London" could be matched to "63 Southerton Road, London" only. Therefore, a list of suggestions containing all the partial matches will be returned and the user has to select the required address.
  • Street partial: The input was partially matched to a deliverable address in our data. For example, a search on "63 Southerton Road, London" could be matched to "Southerton Road, London" only. Therefore, a list of suggestions containing all the partial matches will be returned and the user has to select the required address.
  • Verified place: The input was matched to a single deliverable address in our data but the street information is missing. This result may be slightly different from the provided address because we corrected formatting/spelling errors and added any missing address elements.
  • Verified street: The input was matched to a single deliverable address in our data but the building information is missing. This result may be slightly different from the provided address because we corrected formatting/spelling errors and added any missing address elements.
  • Incomplete address: The input was matched to an address in our data, but is not deliverable. This is commonly returned when searching within data that does not contain building level information. If the user selects a suggestion with this attribute set, then they should be further prompted to provide additional building level information so that the address is deliverable.
  • Insufficient search terms: The input did not contain enough characters to provide a meaningful result.
  • No matches: The input could not be matched to any deliverable results in our data. Therefore, address validation is not possible and the address provided by the user should be used.
suggestions_key string The suggestions key for address suggestion refinement.
suggestions_prompt string The prompt to display to the user, indicating what information they should enter next.
suggestions collection The collection of the suggestions that match the address search input.
global_address_key string The ID of the address matched as part of a search.
text string The suggestion that should be presented to the user as a possible match to their input.
matched collection A collection of the characters in the suggestion that have been matched. Integrators can use this information to highlight matched text.
format string The format URL of the suggested address.
dataset string The dataset of the suggestion.
additional_attributes collection The additional attributes of the suggestion.

The following response codes can be returned by the API:

Status Code Reason phrase Description
200 Success 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 this service.
406 Not Acceptable Request is not in an acceptable format.
408 Request Timeout Response was not returned within the timeout allowance.
415 Unsupported Media Type Request is not using a Media type that is recognized by the server.
429 Too many requests Too many requests were sent. To protect all customers, your account has been temporarily throttled. Check our rate limiting for more details.
500 Internal Server Error The server has encountered an error.
503 Service Unavailable Service unavailable. Check service status for up-to-date information.

Request

The /Suggestions/Stepin method can be used in your addess validation workflow to produce a list of suggestions that contains more detail than the current item, e.g. a suggestion that represents a street can be stepped into to produce a new list of suggestions that contain premises within the street.

Given the response contains the following suggestion:

{
  "global_address_key": "dWc1ltOTFjbTVsQUEtLX45fjc",
  "text": "Mary Street, HAWTHORN  VIC  3122",
  "additional_attributes": [
    { "name": "picklist_display", "value": "Mary Street, HAWTHORN  VIC" },
    { "name": "score", "value": "100" },
    { "name": "postcode", "value": "3122" },
    { "name": "can_step_in", "value": "true" },
    { "name": "multiples", "value": "true" }
  ]
}

You can step into it to produce a list of premises within Mary Street by passing the returned global_address_key to the /Suggestions/Stepin method:

GET /address/suggestions/stepin/v1/dWc1ltOTFjbTVsQUEtLX45fjc HTTP/1.1

Response

The returned list of suggestions can include full addresses as well as items that need further steping into or refinement.

{
  "result": {
    "more_results_available": true,
    "confidence": "Multiple matches",
    "suggestions_key": "VBQUFBQkxkYktKaEVBQlJHQUlBQUFB",
    "suggestions_prompt": "Enter building number/name",
    "suggestions": [
      {
        "global_address_key": "UFBQUFBQUFBQUFBQUFBQS0tfjIxfjc",
        "text": "1 ... 5 Mary Street, HAWTHORN  VIC  3122",
        "additional_attributes": [
          { "name": "picklist_display", "value": "1 ... 5" },
          { "name": "score", "value": "0" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      },
      {
        "global_address_key": "QVVTfjcuNzMwNU9BVVNIQVBtQnd",
        "text": "21a Mary Street, HAWTHORN  VIC  3122",
        "format": "https://api.experianaperture.io/address/format/v1/QVVTfjcuNzMwNU9BVVNIQVBtQnd",
        "additional_attributes": [
          { "name": "picklist_display", "value": "21a" },
          { "name": "score", "value": "0" },
          { "name": "full_address", "value": "true" }
        ]
      }
    ]
  }
}

Request

The /Suggestions/Stepin method can be used in your addess validation workflow to produce a list of suggestions that contains more detail than the current item, e.g. a suggestion that represents a street can be stepped into to produce a new list of suggestions that contain premises within the street.

Given the response contains the following suggestion:

{
  "global_address_key": "zTnlBeGNtWUFBQUFBQUEtLX43fjc",
  "text": "Valley Road, PLYMOUTH PL7 1RF",
  "additional_attributes": [
    { "name": "picklist_display", "value": "Valley Road, PLYMOUTH" },
    { "name": "score", "value": "100" },
    { "name": "postcode", "value": "PL7 1RF" },
    { "name": "can_step_in", "value": "true" },
    { "name": "multiples", "value": "true" }
  ]
}

You can step into the it to produce a list of premises within Valley Road by passing the returned global_address_key to the /Suggestions/Stepin method:

GET /address/suggestions/stepin/v1/zTnlBeGNtWUFBQUFBQUEtLX43fjc HTTP/1.1
Host: api.experianaperture.io
Content-Type: application/json

Response

The returned list of suggestions can include full addresses as well as items that need further steping into or refinement.

{
  "result": {
    "more_results_available": true,
    "confidence": "Multiple matches",
    "suggestions_key": "R0JSfjcuNzMwRU9HQlJFZ0xtQndBQUFBQUJBQUVBQUFBQVkwWlRrZ0FnQ",
    "suggestions_prompt": "Enter building number/name or organisation",
    "suggestions": [
      {
        "global_address_key": "R0JSfjcuNzMwOU9HQlJFZ0xtQndBQU",
        "text": "Wise Road Management Ltd, Valley Road, PLYMOUTH PL7 1RF",
        "format": "https://api.experianaperture.io/address/format/v1/R0JSfjcuNzMwOU9HQlJFZ0xtQndBQU",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Wise Road Management Ltd" },
          { "name": "score", "value": "0" },
          { "name": "full_address", "value": "true" }
        ]
      },
      {
        "global_address_key": "BQUFBQUFBQUFBQX43fjc",
        "text": "Alan Jeffery Engineering, 1 Valley Road, PLYMOUTH PL7 1RF",
        "format": "https://api.experianaperture.io/address/format/v1/BQUFBQUFBQUFBQX43fjc",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Alan Jeffery Engineering, 1" },
          { "name": "score", "value": "0" },
          { "name": "full_address", "value": "true" }
        ]
      }
    ]
  }
}

Request

The /Suggestions/Stepin method can be used in your addess validation workflow to produce a list of suggestions that contains more detail than the current item, e.g. a suggestion that represents a street can be stepped into to produce a new list of suggestions that contain premises within the street.

Given the response contains the following suggestion:

{
  "global_address_key": "pXVjBMQ0JTU1VOSVRVOU9SQUFBQUFBQX4yNH43",
  "text": "Charles St, Richmond IL 60071",
  "additional_attributes": [
    { "name": "picklist_display", "value": "Charles St, Richmond IL" },
    { "name": "score", "value": "100" },
    { "name": "postcode", "value": "60071" },
    { "name": "can_step_in", "value": "true" },
    { "name": "multiples", "value": "true" }
  ]
}

You can step into the it to produce a list of premises within Charles St by passing the returned global_address_key to the /Suggestions/Stepin method:

GET /address/suggestions/stepin/v1/pXVjBMQ0JTU1VOSVRVOU9SQUFBQUFBQX4yNH43 HTTP/1.1
Host: api.experianaperture.io
Content-Type: application/json

Response

The returned list of suggestions can include full addresses as well as items that need further steping into or refinement.

{
  "result": {
    "more_results_available": false,
    "confidence": "Multiple matches",
    "suggestions_key": "VVNBfjcuNzMwdk9VU0FEd1BtQndBQUFBQUJBQUVBQUFBQzQzT3ZVWUFoTV3",
    "suggestions_prompt": "Enter building number/name or organisation",
    "suggestions": [
      {
        "global_address_key": "VVNBfjcuNzMwbk9VU0FEd1BtQndBQUFBQUJBZ0VBQ",
        "text": "10001 ... 10099 Charles St, Richmond IL 60071-9589",
        "additional_attributes": [
          { "name": "picklist_display", "value": "10001 ... 10099   [odd]" },
          { "name": "score", "value": "0" },
          { "name": "postcode", "value": "60071-9589" },
          { "name": "multiples", "value": "true" },
          { "name": "unresolvable_range", "value": "true" }
        ]
      },
      {
        "global_address_key": "BQUFBQUFBQUFBQUFBQUFBQX4yNH43",
        "text": "10101 ... 10199 Charles St, Richmond IL 60071-9590",
        "additional_attributes": [
          { "name": "picklist_display", "value": "10101 ... 10199   [odd]" },
          { "name": "score", "value": "0" },
          { "name": "postcode", "value": "60071-9590" },
          { "name": "multiples", "value": "true" },
          { "name": "unresolvable_range", "value": "true" }
        ]
      }
    ]
  }
}

Special items in the response

Experian Address Validation can return 2 special items in the response and your integration should handle them according to our best practises.

Should you encounter the below response, capture more input from the user to refine the selected suggestion.

{
  "result": {
    "more_results_available": true,
    "confidence": "Multiple matches",
    "suggestions_key": "F3QUJ3QUFBQUFBMng4TUFBQUFBQUFBQUVFZURBUEtLX45fjc",
    "suggestions_prompt": "Enter street name or PO Box type",
    "suggestions": [
      {
        "text": "Continue typing (too many matches)",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Continue typing (too many matches)" },
          { "name": "score", "value": "0" },
          { "name": "information", "value": "true" }
        ]
      }
    ]
  }
}

Should you encounter the below response, capture more input from the user to refine the selected suggestion.

{
  "result": {
    "more_results_available": true,
    "confidence": "Multiple matches",
    "suggestions_key": "F3QUJ3QUFBQUFBMng4TUFBQUFBQUFBQUVFZURBUEtLX45fjc",
    "suggestions_prompt": "Enter street name, organisation or PO Box type",
    "suggestions": [
      {
        "text": "Continue typing (or select to show all matches)",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Continue typing (or select to show all matches)" },
          { "name": "score", "value": "0" },
          { "name": "multiples", "value": "true" },
          { "name": "information", "value": "true" }
        ]
      }
    ]
  }
}

Should you encounter a response that only includes a single item with the can_step_in attribute set to true that is not a informational item, we suggest to have your integration step into the item automatically and display the returned suggestions.

{
  "result": {
    "more_results_available": false,
    "confidence": "Multiple matches",
    "suggestions_key": "QVVTfjcuNzMwUFRBVVNIQVBtQndBQUFBQUNBUUFBTUFBUUFBRUFBQUF1SHd3QUFBQUFBRzFsYkdKdmRYSnVaUUEtfjl-Nw",
    "suggestions_prompt": "Enter street name or PO Box type",
    "suggestions": [
      {
        "global_address_key": "QVVTfjcuNzMwWlRBVVNIQVBtQndBQUFBQUNBUUlBTUFBUUFBRUFBQUF1SHd3QUFBQUFBRzFsYkdKdmRYSnVaUUEtfjl-Nw",
        "text": "<PO Box types>",
        "additional_attributes": [
            { "name": "picklist_display", "value": "<PO Box types>" },
            { "name": "score", "value": "0" },
            { "name": "can_step_in", "value": "true" },
            { "name": "multiples", "value": "true" },
            { "name": "dummy_po_box", "value": "true" }
        ]
      }
    ]
  }
}