Data Quality user documentation

The /validate endpoint is used in the Validate search type.

Credit usage

If you have a per-click license, each successful request will deduct one or more credits. Please contact your account manager or contact support for more information. You can also log in to Experian's Self Service Portal to review your product usage.

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.
Add-Components (Optional)	boolean	Specifies if the response should contain the address broken down into its components. The default value of this setting is false.
Add-Metadata (Optional)	boolean	Specify whether the response should return all fields and values, in addition to the main core information. The default value of this setting is false.
Add-Enrichment (Optional)	boolean	Specifies if the response should contain additional enrichment attributes. The default value of this setting is false.
Add-ExtraMatchInfo (Optional)	boolean	Specify if the response should include validation match info details. The default value of this setting is false.

Body

In the request body you can specify:

Name		Type	Description
country_iso		string	The ISO3 code of the country you want to search against.
datasets		collection	The collection of datasets you want to search against (multiple datasets are currently only supported for UK).
components		object	Object defining the input components.
	unspecified	collection	Collection of unspecified text inputs.
options (Optional)		collection	Additional options. See options for more detailed information.
max_suggestions (Optional)		integer	The maximum number of suggestions you want to get returned. Acceptable values: 1-100 The default value of this setting is 7.
layouts (Optional)		collection	Collection of layout names. The default value of this setting is default which will return a predefined 7 line layout.
layout_format (Optional)		string	The format of the customized address layout. The available values are: default: Address line label and content is presented as key value pairs. address_lines: Address format to ease migration from other address validation services. The separate address lines follow the same structure as in Address Validate SOAP and Pro Web. The default value of this setting is default.
attributes (Optional)		collection	Specifies the required attributes. There are specific attributes for each dataset - they can be found in the attribute Request Body parameter for the different datasets: Global Location Insights (geocodes) Premium Location Insights (premium_location_insight) What3words (what3words) Regional Geocodes for Australia (aus_regional_geocodes) Regional Geocodes for New Zealand (nzl_regional_geocodes) Regional Geocodes for United Kingdom - Essential (uk_location_essential) Regional Geocodes for United Kingdom - Complete (uk_location_complete) Regional Geocodes for United States (usa_regional_geocodes) Health (gbr_health) Government (gbr_government)

Options

Name	Type	Description
prompt_set (Optional)	string	An address can be submitted as one or as many fields; the `prompt_set` property defines which address elements can be entered in each field, for example a field might be constrained so that it only accepts postcodes. The prompt set definition depends on the search type used. You can view the definitions by using the Prompt sets API request. The available values are: OneLine - All search text to be submitted upon a single line. Default - The default prompt set for the engine. Generic - A general data-independent prompt set. Optimal - Requires the minimum possible amount of search text to perform a search. Alternate - An extended country-specific set for where the information required for an optimal search is not available. Alternate2 - A different alternative prompt set (USA only). The default value of this setting is Default.
flatten (Optional)	string	Defines whether the search results will be 'flattened' to a single list of deliverable results, or output a list of suggestions that can be stepped into. True - The list of suggestions will contain an item per address. False - The list of suggestions might contain items that cover more than one address, for example as range of building numbers that need to be refined further to retrieve a final address. The default value of this setting is True.
intensity (Optional)	string	Defines how hard the search engine will work to obtain a match. Higher intensity values may yield more results than lower intensity values, but will also result in longer search times. The available values are: Exact - This does not allow many mistakes in the search term, but is the fastest. Close - This allows some mistakes in the search term, and is the default setting. Extensive - This allows many mistakes in the search term, and will take the longest. The default value of this setting is Close.

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 validation.
	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.

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
validation_detail	object	Address validation details. building_firm_name_corrected: Building or Firm name has been added or changed. primary_number_corrected: Primary Number has been added or changed. street_corrected: Street has been (non-trivially) corrected. rural_route_highway_contract_matched: Rural Route or Highway Contract has been matched. city_name_corrected: City name has been added or changed. city_name_alias_matched: City name has been alias matched. state_corrected: State or Province has been added or changed. zip_code_corrected: Postal code has been added or corrected. secondary_num_retained: Secondary number has been retained. iden_pre_st_info_retained: Identifiable pre-street information has been retained. gen_pre_st_info_retained: General pre-street information has been retained. post_st_info_retained: Post-street information has been retained.
confidence	string	The confidence level of the validation 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.
address	object	The Address object comprises seven address lines representing the formatted address for a given country, each containing up to 256 characters. The first three address lines will be composed of a number of specific components relating to the premises and street. The next four lines contain the locality, province, postal code and country.
addresses_formatted	collection	Customized address layouts.
components	object	The Components object consists of all available address components. Each individual component can be added to relevant fields in your database. Components that do not contain any values for the selected address will not be returned by the API. This object is only returned when the `Add-Components` header is set to True on the request.
match_type	string	The possible values are: unprocessed: Result could not be returned for the input address. This reflects an internal processing issue. For example, if DPV processing has been locked because you encountered a seed address, then all US addresses will return an unprocessed. blank: This means that either no data was found in the input address or the amount of information found is too insignificant to return an address. unmatched: Experian Address Validation can't find any data which matches your input address. This `match_type` might be returned, if you only provide street information without any locality information. post_code_no_address: Experian Address Validation can derive a valid postal code from your input address, but no address information. multiple_no_post_code: Experian Address Validation matches the input address to more than one address in the dataset. multiple_with_post_code: Experian Address Validation finds more than one matching address within a postal code. This is most likely to occur where a country's postal codes cover large areas, such as in Australia. partial_no_post_code: Experian Address Validation finds a partial address which matches your input. However, it cannot return a full postal code with it because the partial address is covered by more than one postal code. This might occur if your input address has a missing or invalid property number. Experian Address Validation can't determine the correct property number and returns as much of the address as it can. partial_with_post_code: Experian Address Validation finds a partial address which matches your input. In addition, either the input postal code was valid, or a single postal code for the partial address is found. full_no_post_code: This occurs when Experian Address Validation finds a full address which matches your input data, but can't find a full postal code to go with it. This is most likely to happen if a dataset does not include postal codes for every address. full_with_post_code: Experian Address Validation has made a full match, either by simply verifying a correct input address, or by locating a full address from partial input data. However, this `match_type` only signifies that a full address and postal code have been returned; it does not necessarily mean that the address is the one you want. You can gauge the likelihood of a correct match from the match confidence level.
confidence	string	Possible values are: none medium high
match_info	object	The Match_info object contains addiitional validation details - generic and country specific flags.

Address object

The Address object comprises seven address lines representing the formatted address for a given country, each containing up to 256 characters. The first three address lines will be composed of a number of specific components relating to the premises and street. The next four lines contain the locality, province, postal code and country. Country specific information for our most popular countries is shown below:

Address lines
address_line_1	Auto Line	Auto Line	Auto Line	Auto Line	Auto Line	Auto Line	Auto Line
address_line_2	Auto Line	Auto Line	Auto Line	Auto Line	Auto Line	Auto Line	Auto Line
address_line_3	Auto Line	Auto Line	Auto Line	Auto Line	Auto Line	Auto Line	Auto Line
locality	Town	City name	Municipality	Locality	Suburb Lobby name Rural Delivery	Town	Locality*
region		State code	Province code	State code	City		Province*
postal_code	Postcode	ZIP+4	Postal code	Postcode	Postal code	Postcode	Postal code*
country	Country	Country	Country	Country	Country	Country	Country

* This element may not be applicable to every supported country and territory.

Addresses_formatted collection

The addresses_formatted collection is only returned if a custom layout has been supplied. To use our Utilities Enrichment, use the electricityutility and/or gasutility layout to return the relevant enrichment fields.

Name		Type	Description
addresses_formatted		collection	Collection of formatted addresses.
	layout_name	string	Name of the layout.
	address	object	This object is returned if `layout_format` is set to default or omitted from the request. This is where the electricity_meters and gas_meters fields will be returned.
	address_lines	collection	This object is returned if `layout_format` is set to address_lines.
	not_enough_lines	boolean	There are not enough address lines configured to display the whole address. This object can only be returned if `layout_format` is set to address_lines.
	has_truncated_lines	boolean	Truncation has occurred on one or more address lines. This object can only be returned if `layout_format` is set to address_lines.
	has_missing_sub_premises	boolean	The missing subpremise attribute specifies if the address is missing a subpremise when using the validate search type. It can be ignored when using all other engines. This object can only be returned if `layout_format` is set to address_lines.

Name	Description
mpan	Meter Point Administration Number
uprn	Unique Property Reference Number
address_line_1 – 9	Metering Point address line 1 – 9
address_postal_code	Metering Point postcode
trading_status	A status assigned to an MPAN that indicates whether the MPAN is currently being supplied with electricity or not: T: for Traded. C: for Closed. X: for Disconnected. S: for Standing. P: for Pending. D: for De-energised. R: for Rejected. U: for Unknown. M: for Metered. F: for Unmetered. E: for Energised. N: for Non-energised. A: for Abandoned. B: for Blocked. Z: for Inactive. Q: for Queried. V: for Void. W: for Withdrawn. Y: for Pending Closure. G: for Pending Disconnection. H: for Pending Reconnection. I: for Pending Energisation. J: for Pending De-energisation. K: for Pending Metering. L: for Pending Non-Energisation. O: for Pending Abandonment. X1: for Disconnected - No Meter. X2: for Disconnected - No Supply. X3: for Disconnected - No Connection. X4: for Disconnected - No MPAN. X5: for Disconnected - No MPRN. X6: for Disconnected - No Connection and No Meter. X7: for Disconnected - No Connection and No Supply. X8: for Disconnected - No Connection and No MPAN. X9: for Disconnected - No Connection and No MPRN.
trading_status_efd	MPAN trading status effective from date.
profile_class	Identifies the type of electricity metering system installed at a premises. It is used to determine the number of registers on the meter and the time. 1: domestic unregistered 2: domestic economy 7 3: non-domestic unrestricted 4: non-domestic economy 7 5: non domestic load factor 0-20% 6: non domestic load factor 20-30% 7: non domestic load factor 30-40% 8: non domestic load factor +40%
profile_class_efd	Profile class effective from date.
meter_timeswitch_class	A code that identifies the type of metering equipment installed at a Metering Point.
meter_timeswitch_class_efd	Meter time-switch class effective from date.
line_loss_factor	A measure of the energy lost in the distribution of electricity from the point of generation to the point of consumption.
line_loss_factor_efd	Line loss factor class effective from date.
standard_settlement_configuration	A term used in the UK electricity industry to describe the set of parameters that define how energy consumption is measured and billed for a particular metering point.
standard_settlement_configuration_efd	Standard Settlement Configuration effective from date.
energisation_status	Energisation status: E: Energised D De-energised
energisation_status_efd	Energisation status effective from date.
gsp_group_id	A unique identifier used to identify the location of the GSP (Grid Supply Point) Group, and used in the MPAN to identify the distribution network operator that supplies the electricity to the premises: A:Eastern B: East Midlands C: London D: Merseyside and North Wales E: Midlands F: Northern G: North Western H: Southern J:South Eastern K: South Wales L: South Western M: Yorkshire N: South Scotland P: North Scotland
gsp_group_efd	Grid Supply Point Group effective from date
data_aggregator_mpid	A unique identifier assigned to a Data Aggregator by the Code Manager. It is used to identify the Data Aggregator in the ECOES system.
data_aggregator_efd	Data Aggregator appointment effective from date
data_collector_mpid	A unique identifier assigned to a Data Collector by the Registration Authority. It is used to identify the Data Collector in communications with other market participants.
data_collector_efd	Data Collector appointment effective from date
supplier_mpid	A unique identifier assigned to each Supplier by the REC. It is used to identify the Supplier in the Central Switching System (CSS) and other industry systems.
supplier_efd Effective	From date of the current supplier
meter_operator_mpid	A unique identifier assigned to a Meter Operator (MOP) by ELEXON. The MOP MPID is used to identify the MOP in the BSC Central Systems and is used in the BSC processes to identify the MOP responsible for a Metering System.
meter_operator_efd	Meter Operator appointment effective from date.
measurement_class	Measurement class: A: Non-Half Hourly Metered B: Non-Half Hourly Unmetered C: HH metered in 100kW premises D: Half Hourly Unmetered E: HH metered sub 100kw CT F: Half Hourly Metering Equipment at sub 100kW premises with current transformer or whole current and at Domestic Premises G: Half Hourly Metering Equipment at sub 100kW premises with whole current and not at Domestic Premises
measurement_class_efd	Measurement Class effective from date.
green_deal_in_effect	An indicator (True/False) whether Green Deal is currently active for this MPAN.
smso_mpid	Smart Metering System Operator MPID.
smso_efd	Smart Metering System Operator effective from date.
dcc_service_flag	A Data Communications Company service flag that indicates whether a smart meter is SMETS comiant or not. A: Active N: Inactive I: Installed not commissioned
dcc_service_flag_efd	Data Communications Company Service Flag effective from date.
ihd_status	In Home Display Install status. This refers to the status of the IHD following a Smart or Dumb Meter exchange. Declined: Customer has chosen not to have an in home display from the supplier. Existing: Customer has an in home display when changing supplier. Installed: Customer has accpeted offer of in-home display from the supplier and ths has been installed.
ihd_status_efd	In Home Display Install status effective from date.
smets_version	Smart Metering Equipment Technical Specification version.
distributor_mpid	A unique identifier assigned to each Distribution Network Operator (DNO) and Independent Distribution Network Operator (IDNO) in the UK. It is used to identify the DNO or IDNO responsible for a particular electricity supply point.
metered_indicator	Identifies whether a supply is metered or unmetered (F).
metered_indicator_efd	Metered Indicator effective from date.
metered_indicator_etd	Metered Indicator effective to date
consumer_type	The classification of consumer based on their usage of energy, e.g. Domestic Consumer or Non-domenstic Consumer.
relationship_status_indicator	A flag that indicates whether a Meter Point is in a relationship with another Meter Point. It is used to identify the Meter Points that are in a relationship for the purposes of Data Cleanse Reports.
rmp_state	RMP State: Created, Registerd, Traded or Disconnected.
rmp_efd	RMP State effective from date
domestic_consumer_indicator	Domestic Consumer Indicator as supplied via CSS messages
css_supplier_mpid	Current supplier as supplied via CSS messages
css_supply_start_date	The date on which the CSS Provider has confirmed that the Gaining Supplier is the registered Supplier for the MPAN(s) and the supply of electricity to the MPAN(s) is to commence.
meter_serial_number	Meter Serial Number
meter_install_date	Meter Install Date
meter_type	Meter Type
map_mpid	Meter Asset Provider MPID
map_mpid_efd	Meter Asset Provider effective from date
installing_supplier_mpid	A unique identifier assigned to the energy supplier who installed the metering equipment at the premises.
rel_address_primary_name	The Primary Addressable Object description. This is normally the name and or number of the property.
rel_address_secondary_name	The Secondary Addressable Object description, e.g. the “Flat 2” in the address “Flat 2, London House, Exeter”. This is only relevant for a child property. “London House” in this case will the Primary Name of the parent property.
rel_address_street1	DPA – thoroughfare LPI – derived from street
rel_address_street2	DPA – dependent thoroughfare LPI – blank
rel_address_locality1	DPA – dependent locality LPI – derived from street
rel_address_locality2	DPA – double dependent locality LPI – blank
rel_address_town	DPA – post town LPI – derived from street
rel_address_postcode	Postcode associated with the address
rel_address_logical_status	The status of the address. 0: no logical status 1: approved (official version) 3: alternative (alias address e.g. house name added) 6: provisional (temporary for eg new builds) 8: historic
rel_address_language	The language of the address (ISO 639-2 Code). For example 'eng' stands for English and 'cym' stands for Welsh.
rel_address_organisation	Current organisation name of the property if one exists.
rel_address_address_type	The type of address of this entry: DPA – Delivery Point Address LPI – Local Property Identifier
rel_address_confidence_score	A relative confidence score on the match from MPL to REL. Scored 0-100.
rel_address_classification	Classification code of the property as per the AddressBase Premium classification scheme. Matched: an address is matched to the GB Standardised Address List Manual: a consumer insists the initial address is incorrect and the address is manually entered. MPL: the Gold Standard required to match the source address to Ordnance Survey AddressBase Premium has not been matched. The MPL address will be used until a Gold Standard match is made or it is manually updated in the enduring solution. Local UPRN is assigned.
rel_address_latitude	Latitude of the associated property, usually either the centroid of the building polygon or a general internal point within the building polygon.
rel_address_longitude	Longitude of the associated property, usually either the centroid of the building polygon or a general internal point within the building polygon.

Name	Description
mprn	Meter Point Reference Number.
uprn	Unique Property Reference Number.
rel_address_primary_name	The Primary Addressable Object description. This is normally the name and or number of the property.
rel_address_secondary_name	The Secondary Addressable Object description, e.g. the “Flat 2” in the address “Flat 2, London House, Exeter”. This is only relevant for a child property. “London House” in this case will the Primary Name of the parent property.
rel_address_street1	DPA – thoroughfare LPI – derived from street
rel_address_street2	DPA – dependent thoroughfare LPI – blank
rel_address_locality1	DPA – dependent locality LPI – derived from street
rel_address_locality2	DPA – double dependent locality LPI – blank
rel_address_town	DPA – post town LPI – derived from street
rel_address_postcode	Postcode associated with the address
rel_address_logical_status	The status of the address. 0: no logical status 1: approved (official version) 3: alternative (alias address e.g. house name added) 6: provisional (temporary for eg new builds) 8: historic
rel_address_language	The language of the address (ISO 639-2 Code). For example 'eng' stands for English and 'cym' stands for Welsh.
rel_address_organisation	Current organisation name of the property if one exists.
rel_address_address_type	The type of address of this entry: DPA – Delivery Point Address LPI – Local Property Identifier
rel_address_confidence_score	A relative confidence score on the match from MPL to REL. Scored 0-100.
rel_address_classification	Classification code of the property as per the AddressBase Premium classification scheme. Matched: an address is matched to the GB Standardised Address List Manual: a consumer insists the initial address is incorrect and the address is manually entered. MPL: the Gold Standard required to match the source address to Ordnance Survey AddressBase Premium has not been matched. The MPL address will be used until a Gold Standard match is made or it is manually updated in the enduring solution. Local UPRN is assigned.
rel_address_latitude	Latitude of the associated property, usually either the centroid of the building polygon or a general internal point within the building polygon.
rel_address_longitude	Longitude of the associated property, usually either the centroid of the building polygon or a general internal point within the building polygon.
meter_serial	The manufacturer's meter serial number as held on the physical meter currently installed on the supply point.
offtake_quantity_annual	The current annual offtake quantity (AQ) of a Supply Meter Point. Value in kWh.
meter_point_status	The current status of the operability of the supply meter point. LI = Live; DE = Dead; CA = Capped; CL = Clamped; PL = Planned.
installer_id	The smart meter Supplier ID.
network_name	Gas Distribution Network Name.
supplier_name	The name of the current Supplier.
last_meter_read_date	The date on which the last meter read recorded at the site.
last_meter_read_type	Latest meter read type.
last_meter_read_value	The last meter read value.

Components object

The Components object comprises seven address lines representing the formatted address for a given country, each containing up to 256 characters. The first three address lines will be composed of a number of specific components relating to the premises and street. The next four lines contain the locality, province, postal code and country. The full list of components with details for our most popular countries plus a rest of world column for all other supported countries can be found below.

Only returned if

This object is only returned when the Add-Components header is set to True on the request.

Name
language	Language	Language	Language	Language	Language	Language	Language
country_name	Country	Country	Country	Country	Country	Country	Country
country_iso_3	ISO 3166-1 alpha-3 country code	ISO 3166-1 alpha-3 country code	ISO 3166-1 alpha-3 country code	ISO 3166-1 alpha-3 country code	ISO 3166-1 alpha-3 country code	ISO 3166-1 alpha-3 country code	ISO 3166-1 alpha-3 country code
country_iso_2	ISO 3166-2 code*	ISO 3166-2 code*	ISO 3166-2 code*	ISO 3166-2 code*	ISO 3166-2 code*	ISO 3166-2 code*	ISO 3166-2 code*

/* ISO 3166-2 standard consists of two parts: the first part is the ISO 3166-1 alpha-2 country code, the second part (when present) is a string of up to three alphanumeric characters indicating country subdivision.

Name
full_name	Postcode	Zip code	Postal code	Postal code	Postcode	Postcode	Postcode
primary		ZIP		Postal code	Postcode	Postcode
secondary		Plus4

Name
full_name	Delivery service	Delivery service	Delivery service	All postal delivery types	All postal delivery types	All PO Box types
service_type	Delivery service type	Delivery service type	Delivery service type
service_number	Delivery service value	Delivery service value	Delivery service value
post_centre_name

Name
full_name	Station information	Delivery service
service_type	Station information type	Delivery service type
service_number	Station information value	Delivery service value
post_centre_name

Name
name					Building name / Flat / Unit name (GNAF)		AFNOR line 3
entrance
	full_name				Subbuilding number
	type
	value
floor
	full_name				Building level
	type				Building level type
	value				Building level number
door
	full_name	Extension designation	Secondary number	Suite name / number	Flat / Unit name	Unit textual + Unit alphanumeric		Secondary address unit
	type	Extension designation type	Secondary address identifier	Suite name	Flat / Unit type
	value	Extension designation value	Secondary address number	Suite number	Flat / Unit number

Name
building_name	Building name			Building name	Building name	Additional geographic data	Building name
secondary_name							Group building name (Ireland only)
building_number	Street number	Primary number	Street number and suffix	Building number	Street number	Number and number extension	Address/ house number
secondary_number						Secondary number and Secondary number extension
allotment_number				Allotment number

Name
department_name		Department	Department	Department
secondary _department_name
company_name		Organization name	Company name
business
	company_name	Business organization name

Name
full_name	Primary thoroughfare	Street	Street	Street	Street	Street	Street
prefix		Street prefix	Street prefix
name	Primary thoroughfare name	Street name	Street name	Street name			Street name
type	Primary thoroughfare type	Street type	Street type	Street type		Street type	Street type
suffix		Street suffix	Street suffix	Street suffix

Name
full_name	Secondary thoroughfare
prefix
name	Secondary thoroughfare name
type	Secondary thoroughfare type
suffix

Name
full_name	Rural route / General delivery	Route service type / number
service_type
service_number
delivery_name
qualifier

Name
region
	name	Constituent country			State name	Region	Département	Region
	code		State code	Province code	State code		INSEE code
	description
sub_region
	name	Geographic county	County					Subregion
	code
	description
town
	name	Town	City	Municipality	Locality	Suburb	Town / CEDEX office	Town
	code
	description
district
	name	Dependent locality	Urbanization	Delivery area installation		Lobby	Geographic town	Settlement
	code
	description
sub_district
	name	Double-dependent locality				PNR lobby	Postal locality / Geographic town
	code
	description

Name
town
	name	Town / City
	code
	description
district
	name	Suburb
	code
	description

Metadata

The Metadata object contains additional information about the returned address, such as deliverability indicators. The metadata can be stored in your database or used to decide if the address should be rejected.
Metadata is only supported for certain countries (see table below). For all other countries, an empty metadata object will be returned.

Only returned if

This object is only returned when the Add-Metadata header is set to True on the request.

The following metadata elements are currently available:

Name			Description
address_info
	sources		Indicates the source of address information: PAF: Australia Post's Postal Address File GNAF: Geoscape Australia's Geocoded National Address File If the address appears in both sources, both PAF and GNAF indicators will be returned.
	number_of_households		Number of households present at the address for Royal Mail's Multiple Residence and Not Yet Built addresses.
	just_built_date		Construction date of a property, if activated within the past six months.
	identifier
		udprn	Royal Mail's Unique Delivery Point Reference Number, an eight-digit code assigned to every delivery point in the Postcode Address File (PAF).
		umrrn	Royal Mail's Unique Multiple Residence Reference Number, an eight-digit code linked to UDPRNs in Royal Mail's Multiple Residence dataset.
		dpid	Delivery Point Identifier that uniquely identifies an address: Australia Post's Delivery Point Identifier, an eight-digit number that uniquely identifies a physical location to which Australia Post delivers mail. New Zealand Post's Delivery Point Identifier, a unique reference number of up to seven digits which is assigned to each delivery point address in the postal address file.
		gnafPid	Geoscape Australia's Geocoded National Address File Persistent Identifier (G-NAF ID).
		hin	Household Identification Number (HIN), unique reference ID for each household.
		paf_address_key	Royal Mail's PAF Address Key.
route_classification
	id		New Zealand Post's unique numeric identifier for a street, for example 1324.
	carrier_route		Code assigned by the USPS to a group of addresses to aid mail delivery within a ZIP code. Consists of a carrier route type and carrier route code (length: 4 bytes). For example, C001.
barcode
	sort_plan_number		Three-digit Barcode Sort Plan (BSP) number for each full address to facilitate pre-sorting of mail items.
	delivery_point_barcode		Australia: Customer barcode is a 37-digit string generated from the DPID. USA: Delivery point barcode (DPBC) consists of ZIP+4 followed by the last two digits of the house/box number, or if the match is made to a highrise record, the secondary unit number representing the delivery point information.
address_classification
	delivery_type		The type of mail delivery at the address: business residential mixed P (PO Box)
	address_type
		code	Record type code indicating the type of address. USA: F: Firm G: General Delivery H: High-rise P: PO Box R: Rural Route / Contract S: Street
		description	Description of the address type code.
	is_deliverable		Indicates whether the address can receive mail.
dpv
	cmra_indicator		Indicates whether selected address is a Commercial Mail Receiving Agency. Y: Address listed in the table of CMRA addresses. N: Address not listed in the table of CMRA addresses. Blank: Address not presented to hash table.
	seed_indicator		Indicates whether selected address is a seed address. Seed records are control records placed by the USPS to prevent unauthorized tampering (e.g., creation of lists containing every single delivery point in a geographical region). Y: Address matched to a seed record. N: Address did not match to a seed record. Blank: Address not presented to hash table.
	dpv_indicator		Indicates whether selected address is confirmed as deliverable via Delivery Point Validation process. Y: Address DPV confirmed for both primary and (if present) secondary numbers. D: Address DPV confirmed for the primary number only, and secondary number information was missing. S: Address DPV confirmed for the primary number only, and secondary number information was present but unconfirmed. N: Both primary and (if present) secondary number information failed to DPV Confirm.
	footnotes		Array containing zero or more of the following elements: AA: Input address matched to the ZIP+4 file. A1: Input address not matched to the ZIP+4 file. BB: Input address matched to DPV (all components). C1: Input address primary number matched, secondary number not matched, secondary number required. CC: Input address primary number matched, secondary number not matched, secondary number not required. F1: Input address matched to a military address. G1: Input address matched to a general delivery address. IA: Informed address identified. N1: Input address primary number matched, secondary number missing, secondary number required. M1: Input address primary number missing. M3: Input address primary number invalid. P1: Input address RR or HC Box number missing. P3: Input address PO, RR, or HC Box number Invalid. PB: Identified PO Box street address. R1: Input address matched to CMRA but PMB designator not present (PMB 123 or #123). R7: Addresses that are assigned to a phantom route of R777 or R779. RR: Input address matched to CMRA and PMB designator present (PMB 123 or #123). TA: Input address primary number matched to DPV by dropping trailing alpha. U1: Input address matched to a unique ZIP Code.
	vacancy_indicator		Indicates whether selected address is known to be vacant and not receiving mail deliveries: Y: Address listed in the table of vacant addresses. N: Address not listed in the table of vacant addresses. Blank: Address not presented to hash table.
	no_stats_indicator		Indicates whether selected address is not receiving mail deliveries. These addresses are not receiving delivery because a) delivery has not been established; b) customer receives mail as a part of a drop; or c) the address is no longer a possible delivery because the carrier destroys or returns all of the mail. Addresses for delivery points in gated communities may also be identified as No-Stats. Y: Address listed in the table of no-stats addresses. N: Address not listed in the table of no-stats addresses. Blank: Address not presented to hash table.
	pbsa_indicator		Indicates whether selected address is a Post Office Box Street Address, a USPS alternative to traditional PO BOX addresses for customers who require a formal street address for delivery (as opposed to a PO BOX number). Y: Address listed in the table of PBSA addresses N: Address not listed in the table of PBSA addresses Blank: Address not presented to hash table.
	lacs_indicator		Indicates whether selected address is present in the Locatable Address Conversion System table (LACSLink). LACSlink allows addresses that have been converted due to various USPS changes to be linked with their new addresses. This affects many of rural-style U.S. addresses that have been assigned city-style street names for 911 emergency response systems. Additionally, LACSLink covers street names that have been modified by municipalities in recognition of an individual or an event. Y: Address listed in the LACS record table N: Address not listed in the LACS record table Blank: Address not presented to hash table.
	lacs_code		Informational codes to go along with lacs_indicator (see above) A: New address could be furnished 09: Cannot Match LACS Record: Highrise Default – The input record matched to a record in the master file, but the old address is a highrise default. 14: New Address Would Not Convert at Run Time – The input record matched to a record in the master file. The new address could not be converted to a deliverable address Blank: Address not presented to hash table.
	urbanization		Urbanization (Puerto Rico specific)
	delivery_line_1		Primary address line that would appear on a piece of mail
	delivery_line_2		Secondary address line, typically only present in the case of dual addressing where a street address and a PO Box or Rural Route both appear on a piece of mail
	last_line		Last address line, containing city, state and ZIP Code information
	no_stat_reason_code		Informational codes to go along with no_stats_indicator (see above) 1: IDA (Internal Drop Address) – Addresses that do not receive mail directly from the USPS, but are delivered to a drop address that services them. 2: CDS No-Stat – Addresses that have not yet become deliverable. For example, a new subdivision where lots and primary numbers have been determined, but no structure exists yet for occupancy. 3: Collision – Addresses that do not actually DPV confirm. In this case, the ‘Y’ should be set to ‘N’ on the DPV ‘A’ table and all other table values should be blank. 4: CMZ (College, Military and Other Types) – ZIP + 4 records USPS has incorporated into the data. 5: Regular No-Stat – Indicates addresses not receiving delivery and the addresses are not counted as possible deliveries. 6: Secondary Required - The address requires secondary information.
	drop		Indicates whether mail is delivered to a single receptacle at a site. Y: Address listed in the table of drop addresses N: Address not listed in the table of drop addresses Blank: Address not presented to hash table.
	throwback		Indicates whether mail is not delivered to the street address. Y: Address listed in the table of throwback addresses N: Address not listed in the table of throwback addresses Blank: Address not presented to hash table.
	non_delivery_days_indicator		Indicates whether mail delivery is not performed every day of the week. Y: Address listed in the table of non-delivery days addresses N: Address not listed in the table of non-delivery days addresses Blank: Address not presented to hash table.
	non_delivery_days_value		Seven bytes representing the delivery days included for each address on the table
	no_secure_location		Indicates whether door is accessible, but package will not be left due to security concerns. Y: Address listed in the table of no-secure-location addresses N: Address not listed in the table of no-secure-location addresses Blank: Address not presented to hash table.
	door_not_accessible		Indicates addresses where USPS cannot knock on a door to deliver mail. Y: Address listed in the table of door-not-accessible addresses N: Address not listed in the table of door-not-accessible addresses Blank: Address not presented to hash table.
	enhanced_dpv_codes		Indicates whether selected address is confirmed as deliverable via Delivery Point Validation process. Y: Address was DPV confirmed for primary/secondary components necessary to determine a valid delivery point. D: Address was DPV confirmed for the primary number only, and the secondary number information was missing. S: Address was DPV confirmed for the primary number only, the secondary number information was present but not confirmed or a single trailing alpha on a primary number was dropped to make a DPV match and secondary information required. N: Primary number failed to DPV confirm. R: Address confirmed but assigned to phantom route R777 or R779 and USPS delivery is not provided. Blank: Address not presented to hash table.

Enrichment

The Enrichment object contains enriched data for the given specified attributes in the request body.

Only returned if

This object is only returned when the Add-Enrichment header is set to True on the request.

The available enrichment elements can be found in the response body for each dataset:

Global Location Insights (geocodes)

Premium Location Insights (premium_location_insight)

What3words (what3words)

Regional Geocodes for Australia (aus_regional_geocodes)

Regional Geocodes for New Zealand (nzl_regional_geocodes)

Regional Geocodes for United Kingdom - Essential (uk_location_essential)

Regional Geocodes for United Kingdom - Complete (uk_location_complete)

Regional Geocodes for United States (usa_regional_geocodes)

Health (gbr_health)

Government (gbr_government)

Match_info object

The match_info object contains a collection of additional generic and country specific validation flags.

Only returned if

This object is only returned when the Add-ExtraMatchInfo header is set to True on the request.

The following flags are currently available:

Name	Description
postcode_action	The action applied to the postal code of the validated address: none: No action was taken. ok: The existing postal code was already correct. added: A new postal code has been added. corrected: The existing postal code has been corrected.
address_action	The action applied to the validated address: none: No action was taken as the supplied address was not matched. reformatted: Part or all of the address has been reformatted. enhanced: The existing address was enhanced. No significant information has been removed, but some information has been added. corrected: The existing address has been corrected.
generic_info	Collection of strings corresponding to the following generic flags: bad_order: Elements out of expected order preferred_failed: Preferred priorities evaluated to FALSE close: Close Priorities evaluated to TRUE conditional_formatting: Highlighted conditional formatting rules were invoked extra_numbers: Additional numbers in input address before place numbers_split: Numbers were split from their expected companion no_place: No place element was matched in input address num_chum_missing: Item should associate with number is absent essential_failed: Essential priorities evaluated to FALSE timeout: A timeout occurred superset: Supplied address is a superset of PAF leading_number: Leading number unused in input address range_ambiguity: There was ambiguity in the range street_desc_changed: Street descriptor added or changed unignorable_text: Text in the input could not be ignored street_name_error: Street name difference place_name_error: Core place name difference premise_changed: Key premise level element differs leading_unmatched: There was leading unmatched text in the input address name_used: Name was used to secure an address match address_truncated: Output address element truncated (insufficient space) address_overflow: Output address element lost (insufficient space) dataplus_failure: Failed to generate one or more non address items enhance_overflow: Failed to fully enhance address (insufficient space) enhance_reformat: Address lines shunted during address enhancement address_cleaned: Address element altered/non-trivial formatting applied verified_correct: Input address content verified as effectively correct invalid_input_spec: Supplied input line count/search string total mismatch test_failed: Stricter match/certification test failure priorities evaluate to TRUE premise_partial: Partial address match to premise level street_partial: Partial address match to street level place_partial: Partial address match to place level
aus_info	Collection of strings corresponding to the following flags, specific for Australian datasets: street_alias_matched: Street alias matches and is retainable in output address. loc_alias_matched: Locality alias matches and is retainable in output address. bordering_loc_matched: Bordering locality matches and is retainable in output address. prem_matched: Match to premises-level (building number) only. Doesn't match to provided sub-premises. no_valid_secondary: Match to premises-level (building number) only. No secondary information provided in input address. (AUS dataset) secondary_unmatched: A building number and valid secondary information provided but neither matched. The unmatched information can be retained in output address. po_box_unmatched: Valid PO Box type provided but the address only matches to locality level. street_place_unclear: Exact street match isn't possible as more than one non-exact match is possible by changing provided street or place. street_type_unclear: Multiple or invalid street type(s) provided. Matching street elements are not unique for locality/state combination. invalid_postal_delivery: Multiple PO Box type(s) provided or required PO Box type conversion invalid given other changes to input address to obtain a match. bord_loc_match_prohibited: A bordering locality match is prohibited because a match is already available in provided locality. no_valid_secondary: No valid secondary information provided for Primary Point. (AUG dataset) real_primary_point: Real Primary Point matches. phantom_primary_point: Phantom Primary Point matches. user_info_blank: Provided Customer Barcode information is blank. user_info_invalid: Provided Customer Barcode information contains invalid character(s). user_info_too_long52: Provided Customer Barcode information is too long for AUSBAR.Ext52 format. user_info_too_long67: Provided Customer Barcode information is too long for AUSBAR.Ext67 format. build_num_changed: Provided building number changed (e.g. single number vs. range, number with suffix vs. number only). build_name_error: Building name is different from input address. floor_level_changed: Floor/level element added or changed. flat_unit_changed: Flat/unit element added or changed. street_name_error: Street name is different from input address. street_type_changed: Street type added or changed. street_suffix_changed: Street type suffix added or changed. street_alt_matched: An alternate street form matches and is retainable in output address. locality_error: Locality is different from input address. state_error: State is different from input address. secondary_type_retained: Secondary type is retained in output address. bord_locality_matched: Bordering locality and postcode combination matched and is retainable in output address. group_did_matched: Street level (DID) address matches the input address. locality_did_matched: Locality level (DID) address matches the input address. suppression_match: Address matches to a suppression set. bsp_state_nsw: BSP assigned State As NSW. bsp_state_act: BSP assigned State As ACT. bsp_state_vic: BSP assigned State As VIC. bsp_state_qld: BSP assigned State As QLD. bsp_state_sa: BSP assigned State As SA. bsp_state_wa: BSP assigned State As WA. bsp_state_tas: BSP assigned State As TAS. bsp_state_nt: BSP assigned State As NT.

The following response codes can be returned by the API:

Status Code	Reason phrase	Description
200	Success	Request processed successfully.
204	No Content	Request processed successfully, but there is no content to be returned.
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 us.
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 us.
503	Service Unavailable	Service unavailable. Check service status for up-to-date information.

Australia

Request

{
  "country_iso": "AUS",
  "components": {
    "unspecified": [
      "main ave",
      "lidcombe",
      "2141"
    ]
  },
  "datasets": [ "au-address-gnaf" ]
}

Response

{
  "result": {
    "more_results_available": true,
    "confidence": "Street partial",
    "suggestions_key": "QVVHfjcuNzMwYVNBVUdIQUxtQndBQUFBQUVBVzFoYVc0Z1lYWmxMR3hwWkdOdmJXSmxMREl4TkRFQUtnTUFBQS0tfjIyfjc",
    "suggestions_prompt": "Enter selection",
    "suggestions": [
      {
        "global_address_key": "2xrWTI5dFltVXNNakUwTVFBQUFBQUF-MjJ-Nw",
        "text": "1 Main Avenue, LIDCOMBE  NSW  2141",
        "format": "https://api.experianaperture.io/address/format/v1/2xrWTI5dFltVXNNakUwTVFBQUFBQUF-MjJ-Nw",
        "additional_attributes": [
          { "name": "picklist_display", "value": "1 Main Avenue, LIDCOMBE  NSW" },
          { "name": "score", "value": "100" },
          { "name": "postcode", "value": "2141" },
          { "name": "full_address", "value": "true" }
        ]
      },
      {
        "global_address_key": "BUC4uWkFBQUFBRC4uLi4uQUFBQUFBQUFBQUFBQUFBQUFBQUFiV0ZwYmlCaGRt",
        "text": "5 Main Avenue, LIDCOMBE  NSW  2141",
        "format": "https://api.experianaperture.io/address/format/v1/BUC4uWkFBQUFBRC4uLi4uQUFBQUFBQUFBQUFBQUFBQUFBQUFiV0ZwYmlCaGRt",
        "additional_attributes": [
          { "name": "picklist_display", "value": "5 Main Avenue, LIDCOMBE  NSW" },
          { "name": "score", "value": "100" },
          { "name": "postcode", "value": "2141" },
          { "name": "full_address", "value": "true" }
        ]
      }
    ]
  }
}

Request

POST /address/validate/v1 HTTP/1.1
Add-Enrichment: true
...

{
    "country_iso": "AUS",
    "components": {
        "unspecified": [
            "1 Main Street, BLACK HEAD, NSW 2430"
        ]
    },
    "datasets": [
        "au-address-gnaf"
    ],
    "attributes": {
        "geocodes": [
            "latitude",
            "longitude",
            "match_level"
        ]
    }
}

Response

{
    "result": {
        "global_address_key": "aWQ9MSBNYWluIFN0cmVldCwgQkxBQ0sgSEVBRCwgTlNXIDI0MzAsIEF1c3RyYWxpYX5hbHRfa2V5PX5kYXRhc2V0PUFVU19QQUZ-Zm9ybWF0X2tleT1BVVMkQVVTJH5RTD0zNX5tYXhfc3VnZ2VzdGlvbnM9Nw",
        "confidence": "Verified match",
        "address": {
            "address_line_1": "1 Main St",
            "address_line_2": "",
            "address_line_3": "",
            "locality": "BLACK HEAD",
            "region": "NSW",
            "postal_code": "2430",
            "country": "AUSTRALIA"
        }
    },
    "enrichment": {
        "transaction_id": "3b9a982e-9959-42e8-a185-41dfdb369f7d",
        "result": {
            "geocodes": {
                "latitude": -32.07049,
                "longitude": 152.54258,
                "match_level": "building"
            }
        },
        "metadata": {
            "code": "S200",
            "message": "Success",
            "detail": "All requested attribute(s) retrieved."
        }
    }
}

Request

POST /address/validate/v1 HTTP/1.1
Add-Enrichment: true
...

{
  "attributes": {
    "AUS_CV_Household": [
      "hin",
      "address",
      "suburb",
      "postcode",
      "state",
      "residential_flag",
      "gnaf_pid",
      "gnaf_latitude",
      "gnaf_longitude",
      "meshblock",
      "sa1",
      "local_government_area_code",
      "local_government_area_name",
      "mosaic_group_2018",
      "mosaic_type_2018",
      "mosaic_segment_2018",
      "affluence_code",
      "affluence_description",
      "adults_at_address_code",
      "adults_at_address_description",
      "children_at_address_code_0_10_years",
      "children_at_address_description_0_10_years",
      "children_at_address_code_11_18_years",
      "children_at_address_description_11_18_years",
      "credit_demand_code",
      "credit_demand_description",
      "household_income_code",
      "household_income_description",
      "household_composition_code",
      "household_composition_description",
      "head_of_household_age_code",
      "head_of_household_age_description",
      "lifestage_code",
      "lifestage_description",
      "length_of_residence_code",
      "length_of_residence_description",
      "mosaic_factor1_score_2018",
      "mosaic_factor2_score_2018",
      "mosaic_factor3_score_2018",
      "mosaic_factor4_score_2018",
      "mosaic_factor5_score_2018",
      "mosaic_factor1_percentile_2018",
      "mosaic_factor2_percentile_2018",
      "mosaic_factor3_percentile_2018",
      "mosaic_factor4_percentile_2018",
      "mosaic_factor5_percentile_2018",
      "risk_insight_code",
      "risk_insight_description",
      "channel_preference",
      "channel_preference_description",
      "mosaic_group",
      "mosaic_type",
      "mosaic_segment",
      "mosaic_group_2015",
      "mosaic_type_2015",
      "mosaic_segment_2015",
      "mosaic_factor1_score",
      "mosaic_factor2_score",
      "mosaic_factor3_score",
      "mosaic_factor4_score",
      "mosaic_factor5_score",
      "mosaic_factor1_percentile",
      "mosaic_factor2_percentile",
      "mosaic_factor3_percentile",
      "mosaic_factor4_percentile",
      "mosaic_factor5_percentile"
    ]
  },
  "country_iso": "AUS",
  "datasets": [
    "au-address"
  ],
  "components": {
    "unspecified": [
      "22 TOURMALINE DR, WEST WODONGA, 3690"
    ]
  },
  "layout_format": "default"
}

Response

{
  "result": {
    "confidence": "Verified match",
    "address": {
      "address_line_1": "22 Tourmaline Dr",
      "address_line_2": "",
      "address_line_3": "",
      "locality": "WEST WODONGA",
      "region": "VIC",
      "postal_code": "3690",
      "country": "AUSTRALIA"
    }
  },
  "enrichment": {
    "transaction_id": "3744bdf6-34ae-42ae-8bc3-522db47a4fc5",
    "result": {
      "aus_cv_household": {
        "hin": "987654326",
        "address": "8 COCHRANE ST",
        "suburb": "WEST KEMPSEY",
        "postcode": "2440",
        "state": "NSW",
        "residential_flag": "R",
        "gnaf_pid": "GANSW706268619",
        "gnaf_latitude": -31.06741807,
        "gnaf_longitude": 152.83314563,
        "meshblock": "10402970000",
        "sa1": "1115514",
        "local_government_area_code": "14350",
        "local_government_area_name": "Kempsey (A)",
        "affluence_code": "1",
        "affluence_description": "Low income Low assets",
        "adults_at_address_code": "5",
        "adults_at_address_description": "Five adults",
        "children_at_address_code_0_10_years": "06",
        "children_at_address_description_0_10_years": "Above average likelihood",
        "children_at_address_code_11_18_years": "06",
        "children_at_address_description_11_18_years": "Above average likelihood",
        "credit_demand_code": "9",
        "credit_demand_description": "Below average Likelihood of Credit Demand (bottom 30-40%)",
        "household_income_code": "2",
        "household_income_description": "$20800 - $41599",
        "household_composition_code": "6",
        "household_composition_description": "Homesharers",
        "head_of_household_age_code": "10",
        "head_of_household_age_description": "Age 60 to 64",
        "lifestage_code": "7",
        "lifestage_description": "Older Independence",
        "length_of_residence_code": "13",
        "length_of_residence_description": "12-13 yrs",
        "risk_insight_code": "5",
        "risk_insight_description": "High Likelihood of Credit Risk (top 20-30%)",
        "channel_preference": "5",
        "channel_preference_description": "Square Eyed Radioheads",
        "mosaic_group": "M",
        "mosaic_type": "M48",
        "mosaic_segment": "M48_2",
        "mail_suppression": "Y",
        "mosaic_factor1_score": "-68",
        "mosaic_factor2_score": "-1835",
        "mosaic_factor3_score": "-19625",
        "mosaic_factor4_score": "-6558",
        "mosaic_factor5_score": "1688",
        "mosaic_factor1_percentile": "47",
        "mosaic_factor2_percentile": "42",
        "mosaic_factor3_percentile": "3",
        "mosaic_factor4_percentile": "29",
        "mosaic_factor5_percentile": "62"
      }
    },
    "metadata": {
      "code": "S206",
      "message": "Success",
      "detail": "Some of the requested attribute(s) retrieved.",
      "datasets": {
        "aus_cv_household": {
          "hin": {
            "code": "S200",
            "message": "Match",
            "value": "987654326"
          },
          "address": {
            "code": "S200",
            "message": "Match",
            "value": "8 COCHRANE ST"
          },
          "suburb": {
            "code": "S200",
            "message": "Match",
            "value": "WEST KEMPSEY"
          },
          "postcode": {
            "code": "S200",
            "message": "Match",
            "value": "2440"
          },
          "state": {
            "code": "S200",
            "message": "Match",
            "value": "NSW"
          },
          "residential_flag": {
            "code": "S200",
            "message": "Match",
            "value": "R"
          },
          "gnaf_pid": {
            "code": "S200",
            "message": "Match",
            "value": "GANSW706268619"
          },
          "gnaf_latitude": {
            "code": "S200",
            "message": "Match",
            "value": "-31.06741807"
          },
          "gnaf_longitude": {
            "code": "S200",
            "message": "Match",
            "value": "152.83314563"
          },
          "meshblock": {
            "code": "S200",
            "message": "Match",
            "value": "10402970000"
          },
          "sa1": {
            "code": "S200",
            "message": "Match",
            "value": "1115514"
          },
          "local_government_area_code": {
            "code": "S200",
            "message": "Match",
            "value": "14350"
          },
          "local_government_area_name": {
            "code": "S200",
            "message": "Match",
            "value": "Kempsey (A)"
          },
          "mosaic_group_2018": {
            "code": "E404",
            "message": "Not found",
            "value": ""
          },
          "mosaic_type_2018": {
            "code": "E404",
            "message": "Not found",
            "value": ""
          },
          "mosaic_segment_2018": {
            "code": "E404",
            "message": "Not found",
            "value": ""
          },
          "affluence_code": {
            "code": "S200",
            "message": "Match",
            "value": "1"
          },
          "affluence_description": {
            "code": "S200",
            "message": "Match",
            "value": "Low income Low assets"
          },
          "adults_at_address_code": {
            "code": "S200",
            "message": "Match",
            "value": "5"
          },
          "adults_at_address_description": {
            "code": "S200",
            "message": "Match",
            "value": "Five adults"
          },
          "children_at_address_code_0_10_years": {
            "code": "S200",
            "message": "Match",
            "value": "06"
          },
          "children_at_address_description_0_10_years": {
            "code": "S200",
            "message": "Match",
            "value": "Above average likelihood"
          },
          "children_at_address_code_11_18_years": {
            "code": "S200",
            "message": "Match",
            "value": "06"
          },
          "children_at_address_description_11_18_years": {
            "code": "S200",
            "message": "Match",
            "value": "Above average likelihood"
          },
          "credit_demand_code": {
            "code": "S200",
            "message": "Match",
            "value": "9"
          },
          "credit_demand_description": {
            "code": "S200",
            "message": "Match",
            "value": "Below average Likelihood of Credit Demand (bottom 30-40%)"
          },
          "household_income_code": {
            "code": "S200",
            "message": "Match",
            "value": "2"
          },
          "household_income_description": {
            "code": "S200",
            "message": "Match",
            "value": "$20800 - $41599"
          },
          "household_composition_code": {
            "code": "S200",
            "message": "Match",
            "value": "6"
          },
          "household_composition_description": {
            "code": "S200",
            "message": "Match",
            "value": "Homesharers"
          },
          "head_of_household_age_code": {
            "code": "S200",
            "message": "Match",
            "value": "10"
          },
          "head_of_household_age_description": {
            "code": "S200",
            "message": "Match",
            "value": "Age 60 to 64"
          },
          "lifestage_code": {
            "code": "S200",
            "message": "Match",
            "value": "7"
          },
          "lifestage_description": {
            "code": "S200",
            "message": "Match",
            "value": "Older Independence"
          },
          "length_of_residence_code": {
            "code": "S200",
            "message": "Match",
            "value": "13"
          },
          "length_of_residence_description": {
            "code": "S200",
            "message": "Match",
            "value": "12-13 yrs"
          },
          "mosaic_factor1_score_2018": {
            "code": "E404",
            "message": "Not found",
            "value": ""
          },
          "mosaic_factor2_score_2018": {
            "code": "E404",
            "message": "Not found",
            "value": ""
          },
          "mosaic_factor3_score_2018": {
            "code": "E404",
            "message": "Not found",
            "value": ""
          },
          "mosaic_factor4_score_2018": {
            "code": "E404",
            "message": "Not found",
            "value": ""
          },
          "mosaic_factor5_score_2018": {
            "code": "E404",
            "message": "Not found",
            "value": ""
          },
          "mosaic_factor1_percentile_2018": {
            "code": "E404",
            "message": "Not found",
            "value": ""
          },
          "mosaic_factor2_percentile_2018": {
            "code": "E404",
            "message": "Not found",
            "value": ""
          },
          "mosaic_factor3_percentile_2018": {
            "code": "E404",
            "message": "Not found",
            "value": ""
          },
          "mosaic_factor4_percentile_2018": {
            "code": "E404",
            "message": "Not found",
            "value": ""
          },
          "mosaic_factor5_percentile_2018": {
            "code": "E404",
            "message": "Not found",
            "value": ""
          },
          "risk_insight_code": {
            "code": "S200",
            "message": "Match",
            "value": "5"
          },
          "risk_insight_description": {
            "code": "S200",
            "message": "Match",
            "value": "High Likelihood of Credit Risk (top 20-30%)"
          },
          "channel_preference": {
            "code": "S200",
            "message": "Match",
            "value": "5"
          },
          "channel_preference_description": {
            "code": "S200",
            "message": "Match",
            "value": "Square Eyed Radioheads"
          },
          "mosaic_group": {
            "code": "S200",
            "message": "Match",
            "value": "M"
          },
          "mosaic_type": {
            "code": "S200",
            "message": "Match",
            "value": "M48"
          },
          "mosaic_segment": {
            "code": "S200",
            "message": "Match",
            "value": "M482"
          },
          "mosaic_group_2015": {
            "code": "E404",
            "message": "Not found",
            "value": ""
          },
          "mosaic_type_2015": {
            "code": "E404",
            "message": "Not found",
            "value": ""
          },
          "mosaic_segment_2015": {
            "code": "E404",
            "message": "Not found",
            "value": ""
          },
          "mail_suppression": {
            "code": "S200",
            "message": "Match",
            "value": "Y"
          },
          "mosaic_factor1_score": {
            "code": "S200",
            "message": "Match",
            "value": "-68"
          },
          "mosaic_factor2_score": {
            "code": "S200",
            "message": "Match",
            "value": "-1835"
          },
          "mosaic_factor3_score": {
            "code": "S200",
            "message": "Match",
            "value": "-19625"
          },
          "mosaic_factor4_score": {
            "code": "S200",
            "message": "Match",
            "value": "-6558"
          },
          "mosaic_factor5_score": {
            "code": "S200",
            "message": "Match",
            "value": "1688"
          },
          "mosaic_factor1_percentile": {
            "code": "S200",
            "message": "Match",
            "value": "47"
          },
          "mosaic_factor2_percentile": {
            "code": "S200",
            "message": "Match",
            "value": "42"
          },
          "mosaic_factor3_percentile": {
            "code": "S200",
            "message": "Match",
            "value": "3"
          },
          "mosaic_factor4_percentile": {
            "code": "S200",
            "message": "Match",
            "value": "29"
          },
          "mosaic_factor5_percentile": {
            "code": "S200",
            "message": "Match",
            "value": "62"
          }
        }
      }
    }
  }
}

Request

{
  "country_iso": "AUS",
  "components": {
    "unspecified": [
      "unit 1, 8 main ave, lidcombe"
    ]
  },
  "datasets": [ "au-address" ]
}

Response

{
  "result": {
    "confidence": "Interaction required",
    "address": {
      "address_line_1": "U 1  8 Main Ave",
      "address_line_2": "",
      "address_line_3": "",
      "locality": "LIDCOMBE",
      "region": "NSW",
      "postal_code": "2141",
      "country": "AUSTRALIA"
    }
  }
}

Request

{
  "country_iso": "AUS",
  "components": {
    "unspecified": [
      "8 main ave",
      "lidcombe"
    ]
  },
  "datasets": [ "au-address" ],
  "layouts": [ "your layout name" ]
}

Response

{
  "result": {
    "confidence": "Verified match",
    "addresses_formatted": [
      {
        "layout_name": "your layout name",
        "address": {
          "Flat/Unit (Number)": "",
          "Building number": "8",
          "Street": "Main Ave",
          "Locality": "LIDCOMBE",
          "State code": "NSW",
          "Postcode": "2141"
        }
      }
    ]
  }
}

United Kingdom

Request

{
  "country_iso": "GBR",
  "components": {
    "unspecified": [
      "160 blackfriars rd, london"
    ]
  },
  "datasets": [ "gb-address" ]
}

Response

{
  "result": {
    "more_results_available": true,
    "confidence": "Premises partial",
    "suggestions_key": "R0JSfjcuNzMwNE1HQlJFZ0xtQndBQUFBQUVBUW9BQVFBQUFBR2RtR0NSQUNFZ0FnQUFBQUFBQUFBQUF",
    "suggestions_prompt": "Enter selection",
    "suggestions": [
      {
        "global_address_key": "R0JSfjcuNzMwN09HQlJFZ0xtQndBQUFBQUVBd0V",
        "text": "Axon Communications, 160 Blackfriars Road, LONDON SE1 8EZ",
        "format": "https://api.experianaperture.io/address/format/v1/R0JSfjcuNzMwN09HQlJFZ0xtQndBQUFBQUVBd0V",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Axon Communications, 160 Blackfriars Road, LONDON" },
          { "name": "score", "value": "100" },
          { "name": "postcode", "value": "SE1 8EZ" },
          { "name": "full_address", "value": "true" }
        ]
      },
      {
        "global_address_key": "R1g2fjcuNzMwQU9HWDZDZ3ps",
        "text": "Experian, 160 Blackfriars Road, LONDON SE1 8EZ",
        "format": "https://api.experianaperture.io/address/format/v1/R1g2fjcuNzMwQU9HWDZDZ3ps",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Experian, 160 Blackfriars Road, LONDON" },
          { "name": "score", "value": "100" },
          { "name": "postcode", "value": "SE1 8EZ" },
          { "name": "full_address", "value": "true" }
        ]
      }
    ]
  }
}

Request

POST /address/validate/v1 HTTP/1.1
Add-Enrichment: true
...

{
    "country_iso": "GBR",
    "datasets": [
        "gb-address"
    ],
    "components": {
        "unspecified": [
            "79 Station road, kelty"
        ]
    },
    "attributes": {
        "geocodes": [
            "latitude",
            "longitude",
            "match_level"
        ]
    }
}

Response

{
    "result": {
        "global_address_key": "aWQ9NzkgU3RhdGlvbiByb2FkLCBrZWx0eSwgVW5pdGVkIEtpbmdkb21-YWx0X2tleT1-ZGF0YXNldD1HQlJ-Zm9ybWF0X2tleT1HQlIkR0JSJH5RTD0yMn5tYXhfc3VnZ2VzdGlvbnM9Nw",
        "confidence": "Verified match",
        "address": {
            "address_line_1": "79 Station Road",
            "address_line_2": "",
            "address_line_3": "",
            "locality": "KELTY",
            "region": "",
            "postal_code": "KY4 0BL",
            "country": "UNITED KINGDOM"
        }
    },
    "enrichment": {
        "transaction_id": "63887cba-2993-4b24-94df-2a24303788c0",
        "result": {
            "geocodes": {
                "latitude": 56.13344,
                "longitude": -3.37654,
                "match_level": "building"
            }
        },
        "metadata": {
            "code": "S200",
            "message": "Success",
            "detail": "All requested attribute(s) retrieved."
        }
    }
}

Request

{
  "country_iso": "GBR",
  "components": {
    "unspecified": [
      "Experian Data",
      "160 blackfriars rd",
      "london"
    ]
  },
  "datasets": [ "gb-address" ]
}

Response

{
  "result": {
    "confidence": "Interaction required",
    "address": {
      "address_line_1": "Experian Data Quality",
      "address_line_2": "160 Blackfriars Road",
      "address_line_3": "",
      "locality": "LONDON",
      "region": "",
      "postal_code": "SE1 8EZ",
      "country": "UNITED KINGDOM"
    }
  }
}

Request

{
  "country_iso": "GBR",
  "components": {
    "unspecified": [
      "Experian Data, 160 blackfriars rd"
      "london"
    ]
  },
  "datasets": [ "gb-address" ],
  "layouts": [ "your layout name" ]
}

Response

{
  "result": {
    "confidence": "Interaction required",
    "addresses_formatted": [
      {
        "layout_name": "your layout name",
        "address": {
          "LINE_1": "Experian Data Quality",
          "LINE_2": "160 Blackfriars Road",
          "Town": "LONDON",
          "Postcode": "SE1 8EZ"
        }
      }
    ]
  }
}

United States

Request

{
  "country_iso": "USA",
  "components": {
    "unspecified": [
      "187th St",
      "Hollis, NY 11423"
    ]
  },
  "datasets": [ "us-address" ]
}

Response

{
  "result": {
    "more_results_available": true,
    "confidence": "Street partial",
    "suggestions_key": "VVNBfjcuNzMwNk1VU0FEd1BtQndBQUFBQUVBUW9BQVFBQUFBWFFmMTVTQ0NBQUFBQUFB",
    "suggestions_prompt": "Please confirm your building number",
    "suggestions": [
      {
        "global_address_key": "eE5ESXpBQUFBQUFBLX4yNn43",
        "text": "8800 ... 8898 187th St, Hollis NY 11423-1826",
        "format": "https://api.experianaperture.io/address/format/v1/VVNBfjcuNzMweE9VU0FEd1BtQndBQUFBQUJ",
        "additional_attributes": [
          { "name": "picklist_display", "value": "8800 ... 8898 187th St, Hollis NY   [even]" },
          { "name": "score", "value": "100" },
          { "name": "postcode", "value": "11423-1826" },
          { "name": "multiples", "value": "true" },
          { "name": "unresolvable_range", "value": "true" }
        ]
      },
      {
        "global_address_key": "JrZ2dnQUFBQUFBQUFBQUQuLjJRQUFBQUEuLi4uLndBQUFBQUFBQUFBQUFBQUFBQU",
        "text": "8801 ... 8899 187th St, Hollis NY 11423-1825",
        "format": "https://api.experianaperture.io/address/format/v1/VVNBfjcuNzMweE9VU0FEd1BtQndBQUFBQUJ",
        "additional_attributes": [
          { "name": "picklist_display", "value": "8801 ... 8899 187th St, Hollis NY   [odd]" },
          { "name": "score", "value": "100" },
          { "name": "postcode", "value": "11423-1825" },
          { "name": "multiples", "value": "true" },
          { "name": "unresolvable_range", "value": "true" }
        ]
      },
      {
        "global_address_key": "BQUFBQUFBQUFBQUFBQUFBREU0TjNSb0lGTjBMQ",
        "text": "9100 ... 9198 187th St, Hollis NY 11423-24ND",
        "format": "https://api.experianaperture.io/address/format/v1/VVNBfjcuNzMweE9VU0FEd1BtQndBQUFBQUJ",
        "additional_attributes": [
          { "name": "picklist_display", "value": "9100 ... 9198 187th St, Hollis NY   [even]" },
          { "name": "score", "value": "100" },
          { "name": "postcode", "value": "11423-24ND" },
          { "name": "multiples", "value": "true" },
          { "name": "unresolvable_range", "value": "true" }
        ]
      }
    ]
  }
}

Request

{
  "country_iso": "USA",
  "components": {
    "unspecified": [
      "77 Massachusetts Rd",
      "Cambridge, MA"
    ]
  },
  "datasets": [ "us-address" ]
}

Response

{
  "result": {
    "validation_detail": {
      "street_corrected": true,
      "zip_code_corrected": true
    },
    "confidence": "Verified match",
    "address": {
      "address_line_1": "77 Massachusetts Ave",
      "address_line_2": "",
      "address_line_3": "",
      "locality": "Cambridge",
      "region": "MA",
      "postal_code": "02139-4307",
      "country": "UNITED STATES OF AMERICA"
    }
  }
}

Request

{
  "country_iso": "USA",
  "components": {
    "unspecified": [
      "8801 187th St, Hollis, 11423"
    ]
  },
  "datasets": [ "us-address" ],
  "layouts": [ "your layout name" ]
}

Response

{
  "result": {
    "validation_detail": {
      "state_corrected": true,
      "zip_code_corrected": true
    },
    "confidence": "Verified match",
    "addresses_formatted": [
      {
        "layout_name": "your layout name",
        "address": {
          "Organisation": "",
          "Street 1": "8801 187th St",
          "Street 2": "",
          "Street 3": "",
          "City": "Hollis",
          "State/Province": "NY",
          "ZIP/Postal Code": "11423",
          "Country/Region": "UNITED STATES OF AMERICA"
        }
      }
    ]
  }
}

Was this helpful?

Previous: Search

Next: Lookup

Experian Address Validation

Address API reference

Next topic:
API specification
Previous topic:
Prerequisites