Data Quality user documentation

The collection of /layouts endpoints provides functionality to list your available layouts as well as to create a custom layout that suits your solution.

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.

Body

In the request body you can specify the country and dataset you want layout availability information on.

Name	Type	Description
country_iso	string	This is the Country ISO3 code.
datasets	string	The dataset that the response layouts are available for.

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.

Body

Name	Type	Description
id	string	The layout ID.
name	string	The layout name. This should be between 1-100 characters in length.
comment	string	The layout comment giving a short description of what the layout is.
applies_to	array	An array of settings that define which datasets the layout applies to. Every array element is defined by: country_iso: The Country ISO3 code. datasets: A collection of datasets you want the layout to be available for. language: The language that the address should be returned in. script: The script that the address should be returned in.
options	object	An object containing various settings for the layout. See Options object for detailed information on all available settings.
lines	array	Every array element is defined by: line_name: Indicates the custom line name of the address line. max_width: The maximum number of characters that fit on the line. elements: A collection of names of elements to be placed on the address line.

Options object

Name	Type	Description
variations	integer	Defines which form of address to use when automatically fitting address element into the returned address. This is for datasets which include more than one Form of address, such as the Netherlands, Belgium and Finland datasets.
flatten_diacritics	boolean	When set to true, it will replace all diacritic characters, such as accents and umlauts, with their non-diacritic equivalents. For example, the Danish address "Degnsgårdvej 1 7840 Højslev" would change to "Degnsgardvej 1 7840 Hojslev" if the FlattenDiacritics keyword is set to Yes.
use_secondary_postcode	string	This setting allows you to specify when postcodes from the secondary dataset should be used in place of postcodes in the primary dataset. The setting determines the data source for the postcode in the final returned address. The dataset must be an LPG with GBR dual search data mapping. The default value is `blank`, or else, the value must be either `Always` or `Never`
enable_enhanced_layout	boolean	When set to true, it will prepend unmatched leading information to address lines.
display_enhanced_info_on_picklist	boolean	When set to true, it will define whether any leading unmatched text before the actual address elements are retained in the picklist. This setting will only take effect if the `enable_enhanced_layout` setting is set to true.
enable_intelligent_layout	boolean	When set to true, the intelligent layout will be enabled for the created layout. If the intelligent layout is enabled, the PAF or G-NAF address which most closely matches the entered address will be returned, regardless of the default layout.
capitalise_unused	boolean	When set to true, this will change the case of unmatched leading information.
separate_elements	boolean	When set to true, the address elements on a single line are separated, usually by commas. Set this to false if you do not want to comma-separate address elements. Example: If set to true - Chester Road, Ash. If set to false - Chester Road Ash
element_separator	string	This defines which address elements should be separated by additional characters in the formatted address. This setting will only take effect if the `separate_elements` setting is set to true. Example: Here the element separator would be blank before and after the postcode. Element separators take precedence right over left.
retention_element_separator	string	This defines which retention address elements should be separated by additional characters in the formatted address. This setting will only take effect if the `separate_elements` & `use_extended_retention` settings are set to true.
prepend_element_separator	string	This defines which prepend address elements should be separated by additional characters in the formatted address. This setting will only take effect if the `separate_elements` & `use_extended_retention` settings are set to true.
separate_element_separator	string	This defines which separate address elements should be separated by additional characters in the formatted address. This setting will only take effect if the `separate_elements` & `use_extended_retention` settings are set to true.
terminate_lines	boolean	When set to true, the address lines are ended with an additional character. Example: If set to true: 6 Cedar Grove, Bisley, WOKING, Surrey, GU24 9EF If set to false, the additional characters would not appear.
line_terminator	string	This defines the additional character(s) for the `terminate_lines`. Example:
conditional_format	string	This setting has a different function depending on the dataset being used. For the GBR with additional Business dataset this setting allows the user to specify whether to display the PAF or Experian organisation data, or a combination of both. There are four possible values for this settings: ExperianOrgPref: The Experian organisation name takes priority, but the PAF organisation name will be used if there is no Experian equivalent for the address. ExperianOrgOnly: Only Experian organisation names will be returned, and PAF organisation names will be suppressed if there is no Experian equivalent for the address. PostOrgPref: The PAF organisation name takes priority, but the Experian organisation name will be used if there is no PAF equivalent for the address. PostOrgOnlyOnly PAF organisation names will be returned, and Experian organisation names will be suppressed if there is no PAF equivalent for the address. For the USA dataset this setting allows the user to specify whether to return the full city name or the abbreviated city name. NormCityThe full city name will be returned. AbbCityThe abbreviated city name will be returned. This will have a maximum of 13 characters.
pad_lines	boolean	If set to true, it populates the line to the maximum width with empty spaces, or, the character defined in the `padding_character` setting.
padding_character	string	This defines the single character used to pad an address line to its width. The default value is a space.
multiple_dataplus_delimiter	string	This defines the delimiter used to separate returned multiple DataPlus values.
abbreviate_item	string	This defines which address elements should be abbreviated in the formatted address. The value is a list of element names, which differ from dataset to dataset.
capitalise_item	string	This defines which address elements should appear in upper case in the formatted address. The value is a list of element names.

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.

Query

Name	Type	Description
country_iso (Optional)	string	Filters by Country ISO3.
datasets (Optional)	array[string]	FIlters by datasets.
name_contains (Optional)	string	Filters by layout name contains text.

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
name	string	The layout name.

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
name	string	The name of the address layout.
country_iso_3	string	This is the Country ISO3 code.
datasets	string	The dataset that the response layouts are available for.

Name	Type	Description
id	string	The layout ID.

Name	Type	Description
id	string	The layout ID.
name	string	The layout name. This should be between 1-100 characters in length.
applies_to	array	An array of settings that define which datasets the layout applies to. Every array element is defined by: country_iso: The Country ISO3 code. datasets: A collection of datasets you want the layout to be available for. language: The language that the address should be returned in. script: The script that the address should be returned in.
status	string	The current status of the layout creation. Available values: CreationInProgress: The layout is still being created. Completed: The layout has been created and is ready to use.

The result object contains a layout object whose properties are listed below:

Name	Type	Description
id	string	The layout ID.
name	string	The layout name. This should be between 1-100 characters in length.
comment	string	The layout comment giving a short description of what the layout is.
applies_to	array	An array of settings that define which datasets the layout applies to. Every array element is defined by: country_iso: The Country ISO3 code. datasets: A collection of datasets you want the layout to be available for. language: The language that the address should be returned in. script: The script that the address should be returned in.
options	object	An object containing various settings for the layout. See Options object for detailed information on all available settings.
lines	array	Every array element is defined by: line_name: Indicates the custom line name of the address line. max_width: The maximum number of characters that fit on the line. elements: A collection of names of elements to be placed on the address line.
status	string	The current status of the layout creation. Available values: CreationInProgress: The layout is still being created. Completed: The layout has been created and is ready to use.

Options object

Name	Type	Description
variations	integer	Defines which form of address to use when automatically fitting address element into the returned address. This is for datasets which include more than one Form of address, such as the Netherlands, Belgium and Finland datasets.
flatten_diacritics	boolean	When set to true, it will replace all diacritic characters, such as accents and umlauts, with their non-diacritic equivalents. For example, the Danish address "Degnsgårdvej 1 7840 Højslev" would change to "Degnsgardvej 1 7840 Hojslev" if the FlattenDiacritics keyword is set to Yes.
use_secondary_postcode	string	This setting allows you to specify when postcodes from the secondary dataset should be used in place of postcodes in the primary dataset. The setting determines the data source for the postcode in the final returned address. The dataset must be an LPG with GBR dual search data mapping. The default value is `blank`, or else, the value must be either `Always` or `Never`
enable_enhanced_layout	boolean	When set to true, it will prepend unmatched leading information to address lines.
display_enhanced_info_on_picklist	boolean	When set to true, it will define whether any leading unmatched text before the actual address elements are retained in the picklist. This setting will only take effect if the `enable_enhanced_layout` setting is set to true.
enable_intelligent_layout	boolean	When set to true, the intelligent layout will be enabled for the created layout. If the intelligent layout is enabled, the PAF or G-NAF address which most closely matches the entered address will be returned, regardless of the default layout.
capitalise_unused	boolean	When set to true, this will change the case of unmatched leading information.
separate_elements	boolean	When set to true, the address elements on a single line are separated, usually by commas. Set this to false if you do not want to comma-separate address elements. Example: If set to true - Chester Road, Ash. If set to false - Chester Road Ash
element_separator	string	This defines which address elements should be separated by additional characters in the formatted address. This setting will only take effect if the `separate_elements` setting is set to true. Example: Here the element separator would be blank before and after the postcode. Element separators take precedence right over left.
retention_element_separator	string	This defines which retention address elements should be separated by additional characters in the formatted address. This setting will only take effect if the `separate_elements` & `use_extended_retention` settings are set to true.
prepend_element_separator	string	This defines which prepend address elements should be separated by additional characters in the formatted address. This setting will only take effect if the `separate_elements` & `use_extended_retention` settings are set to true.
separate_element_separator	string	This defines which separate address elements should be separated by additional characters in the formatted address. This setting will only take effect if the `separate_elements` & `use_extended_retention` settings are set to true.
terminate_lines	boolean	When set to true, the address lines are ended with an additional character. Example: If set to true: 6 Cedar Grove, Bisley, WOKING, Surrey, GU24 9EF If set to false, the additional characters would not appear.
line_terminator	string	This defines the additional character(s) for the `terminate_lines`. Example:
conditional_format	string	This setting has a different function depending on the dataset being used. For the GBR with additional Business dataset this setting allows the user to specify whether to display the PAF or Experian organisation data, or a combination of both. There are four possible values for this settings: ExperianOrgPref: The Experian organisation name takes priority, but the PAF organisation name will be used if there is no Experian equivalent for the address. ExperianOrgOnly: Only Experian organisation names will be returned, and PAF organisation names will be suppressed if there is no Experian equivalent for the address. PostOrgPref: The PAF organisation name takes priority, but the Experian organisation name will be used if there is no PAF equivalent for the address. PostOrgOnlyOnly PAF organisation names will be returned, and Experian organisation names will be suppressed if there is no PAF equivalent for the address. For the USA dataset this setting allows the user to specify whether to return the full city name or the abbreviated city name. NormCityThe full city name will be returned. AbbCityThe abbreviated city name will be returned. This will have a maximum of 13 characters.
pad_lines	boolean	If set to true, it populates the line to the maximum width with empty spaces, or, the character defined in the `padding_character` setting.
padding_character	string	This defines the single character used to pad an address line to its width. The default value is a space.
multiple_dataplus_delimiter	string	This defines the delimiter used to separate returned multiple DataPlus values.
abbreviate_item	string	This defines which address elements should be abbreviated in the formatted address. The value is a list of element names, which differ from dataset to dataset.
capitalise_item	string	This defines which address elements should appear in upper case in the formatted address. The value is a list of element names.

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. Sign in to the Self Service Portal to find the right token.
403	Forbidden	Request is not authorized to use this service.
404	Not Found	Request is not found.
406	Not Acceptable	Request is not in an acceptable format.
408	Request Timeout	Your request has timed out (the web server failed to respond in the specified time frame). Try submitting another request. If the issue persists, contact support.
415	Unsupported Media Type	You've specified an invalid Content-Type header. Try submitting another call and make sure you specify a valid Content-Type value.
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	An unexpected server error was encountered. Try submitting another request. If the issue persists, contact support.
503	Service Unavailable	Service unavailable. Check service status for up-to-date information.

Australia

Request

{
  "country_iso": "AUS",
  "datasets": [
    "au-address-gnaf"
  ]
}

Response

{
  "result": [
    {
      "name": "Default",
      "country_iso_3": "AUS",
      "datasets": [
        "au-address-gnaf"
      ]
    },
    {
      "name": "JB Hifi",
      "country_iso_3": "AUS",
      "datasets": [
        "au-address-gnaf"
      ]
    },
    {
      "name": "JB Hifi_all",
      "country_iso_3": "AUS",
      "datasets": [
        "au-address-gnaf"
      ]
    }
  ]
}

United Kingdom

Request

{
  "country_iso": "GBR",
  "datasets": [
    "gb-additional-multipleresidence"
  ]
}

Response

{
  "result": [
    {
      "name": "Default",
      "country_iso_3": "GBR",
      "datasets": [
        "gb-additional-multipleresidence"
      ]
    },
    {
      "name": "Selfridges",
      "country_iso_3": "GBR",
      "datasets": [
        "gb-additional-multipleresidence"
      ]
    },
    {
      "name": "Selfridges_2",
      "country_iso_3": "GBR",
      "datasets": [
        "gb-additional-multipleresidence"
      ]
    }
  ]
}

Request

{
  "layout": {
    "name": "United Kingdom with DataPlus",
    "comment": "United Kingdom with DataPlus",
    "applies_to": [
      {
        "country_iso": "GBR",
        "datasets": [
          "gb-address"
        ]
      }
    ],
    "options": {
      "variation": 1,
      "flatten_diacritics": false,
      "enable_enhanced_layout": false,
      "display_enhanced_info_on_picklist": false,
      "enable_intelligent_layout": false,
      "capitalise_unused": false,
      "separate_elements": true,
      "element_separator": {
        "default": ", ",
        "configuration_by_element": {
          "buildingNumber": ", ^ ",
          "subBuildingNumber": ", ^ ",
          "postcode": " ^ ",
          "deliveryPointSuffix": " ^ ",
          "country": " ^ ",
          "pafAddressKey": "^",
          "pafOrganisationKey": "^"
        }
      },
      "terminate_lines": false,
      "line_terminator": {
        "default": ", ",
        "configuration_by_element": {
          "postcode": "^",
          "deliveryPointSuffix": "^",
          "country": ".^."
        }
      },
      "pad_lines": false,
      "multiple_dataplus_delimiter": "|",
      "abbreviate_item": [
        "thoroughfareName",
        "county"
      ],
      "capitalise_item": [
        "postcode",
        "country"
      ]
    },
    "lines": [
      {
        "line_name": "Line 1",
        "max_width": 255
      },
      {
        "line_name": "Line 2",
        "max_width": 255
      },
      {
        "line_name": "Line 3",
        "max_width": 255
      },
      {
        "line_name": "Locality",
        "max_width": 255,
        "elements": [
          {
            "element_name": "town"
          }
        ]
      },
      {
        "line_name": "Region",
        "max_width": 255
      },
      {
        "line_name": "Postal Code",
        "max_width": 255,
        "elements": [
          {
            "element_name": "postcode"
          }
        ]
      },
      {
        "line_name": "Country",
        "max_width": 255,
        "elements": [
          {
            "element_name": "country"
          }
        ]
      },
      {
        "line_name": "MOSAIC Household Type Code",
        "max_width": 255,
        "elements": [
          {
            "element_name": "mosaicHouseholdTypeCode"
          }
        ]
      },
      {
        "line_name": "UDPRN",
        "max_width": 255,
        "elements": [
          {
            "element_name": "udprnKey"
          }
        ]
      }
    ]
  }
}

Response

{
  "result": {
    "id": "f98ecf74-de87-4ee8-b732-87d474c9d2b0"
  }
}

Request

{
  "layout": {
    "name": "United Kingdom without DataPlus",
    "comment": "United Kingdom without DataPlus",
    "applies_to": [
      {
        "country_iso": "GBR",
        "datasets": [
          "gb-address"
        ]
      }
    ],
    "options": {
      "variation": 1,
      "flatten_diacritics": false,
      "enable_enhanced_layout": false,
      "display_enhanced_info_on_picklist": false,
      "enable_intelligent_layout": false,
      "capitalise_unused": false,
      "separate_elements": true,
      "element_separator": {
        "default": ", ",
        "configuration_by_element": {
          "buildingNumber": ", ^ ",
          "subBuildingNumber": ", ^ ",
          "postcode": " ^ ",
          "deliveryPointSuffix": " ^ ",
          "country": " ^ ",
          "pafAddressKey": "^",
          "pafOrganisationKey": "^"
        }
      },
      "terminate_lines": false,
      "line_terminator": {
        "default": ", ",
        "configuration_by_element": {
          "postcode": "^",
          "deliveryPointSuffix": "^",
          "country": ".^."
        }
      },
      "pad_lines": false,
      "multiple_dataplus_delimiter": "|",
      "abbreviate_item": [
        "thoroughfareName",
        "county"
      ],
      "capitalise_item": [
        "postcode",
        "country"
      ]
    },
    "lines": [
      {
        "line_name": "Line 1",
        "max_width": 255
      },
      {
        "line_name": "Line 2",
        "max_width": 255
      },
      {
        "line_name": "Line 3",
        "max_width": 255
      },
      {
        "line_name": "Locality",
        "max_width": 255,
        "elements": [
          {
            "element_name": "town"
          }
        ]
      },
      {
        "line_name": "Region",
        "max_width": 255
      },
      {
        "line_name": "Postal Code",
        "max_width": 255,
        "elements": [
          {
            "element_name": "postcode"
          }
        ]
      },
      {
        "line_name": "Country",
        "max_width": 255,
        "elements": [
          {
            "element_name": "country"
          }
        ]
      }
    ]
  }
}

Response

{
  "result": {
    "id": "f98ecf74-de87-4ee8-b732-87d474c9d2b0"
  }
}

United States

Request

{
  "country_iso": "USA",
  "datasets": [
    "us-address"
  ]
}

Response

{
  "result": [
    {
      "name": "Default",
      "country_iso_3": "USA",
      "datasets": [
        "us-address"
      ]
    },
    {
      "name": "AMEX_1",
      "country_iso_3": "USA",
      "datasets": [
        "us-address"
      ]
    },
    {
      "name": "AMEX_alternate",
      "country_iso_3": "USA",
      "datasets": [
        "us-address"
      ]
    }
  ]
}

Previous: Suggestions/Format

Next: Datasets and prompt sets

Experian Address Validation

Address API reference

Next topic:
API specification
Previous topic:
Prerequisites

Layout

Headers

Body

Headers

Body

Options object

Header

Query

Header

Path

Headers

Body

Options object

Australia

Request

Response

United Kingdom

Request

Response

Request

Response

Request

Response

United States

Request

Response

Experian Address Validation

Address API reference