Data Quality user documentation
home/Address validation/Pro Web/API reference (REST)/Bulk

Bulk

The /format endpoint is used in the Verification search type.

Headers

Name Type Description
Timeout-Seconds
(Optional)		 integer Maximum time you are prepared to wait for a response, expressed in seconds.
Acceptable values: 1-60. If a timeout occurs, an HTTP status code of 408 - Request Timeout will be returned.

The default value of this setting is 15.
Diagnostics
(Optional)		 boolean Enable diagnostic info

The default value of this setting is False.

Body parameters

In the request body you can specify:

Name Type Description
components string Address input components.
dataset_code string Dataset code being used for this request.
layout string The layout being used for this request.
options string For information on options see the option elements.

Option elements

Name Type Description
engine_timeout integer Allows you to limit Intuitive engine results to certain values of address element.
The default value of this setting is True.
threshold integer This defines the threshold that is used to decide whether results will be returned in the picklist, or whether an informational picklist result will be returned, requiring further refinement.This element is only relevant when using hierarchical mode.
The standard setting is 25 items.
flatten boolean 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.
constraint string Allows you to limit Intuitive engine results to certain values of address element.
intensity 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.
picklist_size integer Defines the number of results that will be returned by the Singleline search (any further matches will be truncated). The minimum value that can be assigned is 1 and the maximum is 100. When no value is set (or is 0), this setting will not be applied.
prompt_set 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).
  • Alternate3 - A different alternative prompt set where not all address elements are present.

The default value of this setting is Default.

Headers

Name Type Description
Timeout-Seconds
(Optional)		 integer Maximum time you are prepared to wait for a response, expressed in seconds.
Acceptable values: 1-60. If a timeout occurs, an HTTP status code of 408 - Request Timeout will be returned.

The default value of this setting is 15.
Diagnostics
(Optional)		 boolean Enable diagnostic info

The default value of this setting is False.

Body

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

Confidence

The confidence level of the Search result are:

Name Type Description
verified string 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 string 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.
Interaction required string 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 string 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 string 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 string 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 string 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.
Place partial string The input was matched to a single deliverable address in our data but some 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.
NA string The input could not be matched as results are not available. Therefore, address validation is not possible and the address provided by the user should be used.
None string The input could not be matched as it does not exist to any deliverable results in our data. Therefore, address validation is not possible and the address provided by the user should be used.

Address

The address elements of the Search result are:

Name Type Description
address_lines collection Collection of address lines.
label string This defines a text label for the line, which will describe the contents of the line.
line string This defines the final formatted address line, as described by the layout that was used to format the address result.
has_overflown_to_other_line boolean This element signifies that some address elements could not be formatted upon this line, and so had to overflow onto other lines.
line_content string This describes the elements that are found upon the address line. For example "Name". The following values may be returned:
  • none: There was no content specified for this line.
  • address: There are address elements specified upon this line.
  • name: There is name information specified upon this line.
  • ancillary: There is ancillary data specified upon this line.
  • dataplus: There is DataPlus information specified on this line.
is_truncated boolean This element signifies that some address elements were truncated.
has_overflow_lines boolean This element signifies that at least one line in the layout has overflown onto other lines.
has_truncated_lines boolean This element signifies that at least one line in the layout was truncated.
dpv_status string The dpv status of the Search result are:
  • DPVNotConfigured: DPV is not configured for this combination of data mapping/engine/layout.
  • DPVConfirmed: All address components (primary and secondary) are DPV confirmed.
  • DPVConfirmedMissingSec: Primary number was DPV confirmed but secondary is incorrect or missing.
  • DPVNotConfirmed: Primary number was not DPV confirmed.
  • DPVLocked: DPV retrieval has been locked by a previous search on a seed address.
  • DPVSeedHit: This address is a seed address. DPV retrieval has been locked an an unlock code must be supplied to reactivate it.
has_missing_sub_premise boolean This attribute indicates that the address is a large volume receiver and may be missing subpremises information.

Validation detail

The validation_detail elements of the Search result are:

Name Type Description
buidling_firm_name_corrected boolean Building or Firm name has been added or changed.
primary_number_corrected boolean Primary Number has been added or changed.
street_corrected boolean Street has been (non-trivially) corrected.
rural_route_highway_contract_matched boolean Rural Route or Highway Contract has been matched.
city_name_corrected boolean City name has been added or changed.
city_name_alias_matched boolean City name has been alias matched.
state_corrected boolean State or Province has been added or changed.
zip_code_corrected boolean Post code has been added or corrected.
secondary_num_retained boolean Secondary number has been retained.
iden_pre_st_info_retained boolean Identifiable pre-street information has been retained
gen_pre_st_info_retained boolean General pre-street information has been retained.
post_st_info_retained boolean Post-street information has been retained.

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.
408 Request Timeout Response was not returned within the timeout allowance.
500 Internal Server Error The server has encountered an error.
Pro Web

API reference (REST)