Skip to main content

Address Validate SOAP


Are you compatible with TLS 1.2?
Test your connections as soon as possible to avoid service disruptions. 

.

Overview

Address Validate API provides a SOAP interface for global address searching and validation. We currently support over 160 countries.

This guide is for integrators who want to access our service directly, instead of using our SOAP sample code. It also assumes that you are familiar with our address search functionality. 

Alternatively, REST API is also available for the GBRUSA and CAN datasets.

 

Workflows

The following operations make up our address search and validation functionality:

OperationSOAP ActionDescription
1. Can Search DoCanSearch Checks whether the combination of data mapping, engine and layout are valid for search.
2. Initial Search DoSearch Performs the initial search.
3. 'Step In' DoRefine 'Steps into' a picklist that was created during the previous search.
4. Refine DoRefine Refines the picklist that was created during the previous search.
5. Get Final Address DoGetAddress  Creates a final formatted address from a previously created picklist item.

The localisation attribute is not used for any of the operations. 

Validate one address element at a time

Typically, the process of searching with the SingleLine engine follows this format:

1. Pre-search: an optional check on the validity of a search using the DoCanSearch action.

2. Initial search: the DoSearch action can be used for the initial search. It returns a Picklist object which contains PicklistItems that can be displayed. Each item can remain merely informational, be expanded or formatted into a final address.

3. Handling picklists and monikers: the picklist items are displayed to the user. Depending on the user's actions, one of the following will occur:

  • The DoRefine action can be used to 'step into' a picklist result (for example, a street name will show a picklist of premises). This hierarchical picklist behaviour is the default. If a single flattened picklist is required, the flatten flag has to be set before the initial search is performed.
  • The DoRefine action can be used to narrow down the current picklist to one with a subset of items (for example, using "high" on street names will return another picklist containing only streets starting with "high").

    The DoRefine action is also called in certain special cases. For example, when an item is an unresolvable range (certain countries) or a Phantom Primary Point (AUS only).
  • The DoGetAddress action can be used to format a final address. A call to stepIn, refine or DoGetAddress requires a moniker from either the Picklist or a PicklistItems returned by a previous call. These monikers encode the information required to recreate a particular picklist/picklist item, and are the means by which any integration navigates the search process.

4. Format the final address: once the final address has been identified, the DoGetAddress action will apply a layout to this item, returning a FormattedAddress object that contains the final formatted address. 

Validate using the full address

The Verification engine is designed to require minimal, if any, interaction from the user. This can be defined by the integrator.

The user should enter the full address in the same format that they would write it on an envelope, and the entire address is submitted to the engine.

Picklists are only returned by verification searches where the verification level is high enough to match to at least one address, but not high enough to confidently match a single address, for example PremisesPartial, StreetPartial or Multiple.

In such cases, the integrator may decide to offer the user a picklist and let them proceed in a similar fashion to the address search process above or simply to ignore the picklist and use the address as originally entered (in order to minimise user interaction).

The DoCanSearch action may be called for the Verification engine, but it is unlikely that this extra step in the workflow will be useful: the page can simply perform a search and process the results as required.

The typical search process for verification is as follows:

1. Pre-check: an optional check on the validity of a search using the DoCanSearch action.

2. Initial search: call the DoSearch action which returns a SearchResult object that may contain a FormattedAddress object and/or a Picklist object, as well as VerifyLevel.  
If picklists are not being handled, the integrator may simply check that the VerifyLevel is high enough before using FormattedAddress.

3. (Optional step) if required, you can handle the picklist using the DoRefine action.

4. Format the final address: once the final address has been identified, the DoGetAddress action will apply a layout to this item, returning a FormattedAddress object that contains the final formatted address.

Sample code

To better understand how Address Validate SOAP works, check out our sample code. The sample code guide will help you get set up and test out the API.

Get sample code

Postman collections

We now have pre-configured Postman collections for our APIs.

You can quickly test out the requests and responses and see how the API behaves. Simply import the relevant collections, add your token as a variable and start making requests with your desired parameters.

Get Postman collections

Authentication

In order to access address searching and verification functionality, the request has to be authenticated. 

 Migrated from On Demand?

Your existing integration will not be affected. 

Use your current integration username and password or the SAML header.  Refer to SOAP sample code for details.

For increased security, you will not be able to change your email/username or the security question.

New User?

Token is a unique alphanumeric code that allows you to use the products covered by your license. It can be retrieved from Self Service Portal > Licenses. 

You have to use the provided token:

  1. Retrieve your token from Self Service Portal > Licenses. 

    If you don't have one yet, go to Self Service Portal > Licenses, click Add a Token and enter the required details.

  2. Enter your token as the value for "auth-token" field under the HTTP Header.

 

Refer to sample code for details:

C#

 

 

JSP

 

 

PHP

Changing integration password

Note that changing the integration password will automatically re-generate  the token linked to it which means you may also have to manually modify your setup. 

  1. Go to Self Service Portal > Licenses.
  2. Click Change integration password.
  3. Enter a new password and save changes.
  4. Check your integration for the old password (as it can be hard coded in some files): 
    • config files
    • Javascript
    • database

Security

Address Validate SOAP supports Cross Origin Resource Sharing (CORS). This is a specification developed by W3C that allows browsers to make cross-domain requests thus enabling client-side integrations. When making a request, the browser will add an origin request header. The API will then respond with a CORS specific response header denoting the origin domains allowed to make requests to the API.

CORS Supported OS and Browsers:

  • iOS devices (iOS 8 or later)
  • Safari, IE and Chrome

Permitted URLs

We strongly recommend that you specify the permitted URLs to be used for address capture. This is essential to prevent fraudulent use of your token on another domain by ensuring that only requests made from your specified URLs are authenticated. See Self Service Portal help for more information about tokens and full instructions on how to set your permitted URLs. 

SOAP API Reference

All SOAP endpoints

Please ensure your IT infrastructure allows access to these endpoints (firewall exceptions might need to be added).

We recommend connecting to your regional endpoint (e.g. UK endpoint for UK customers) as that will reduce latency. We also recommend using V3 endpoints, although previous versions are supported as well.

V3: supports the username/password, token and SAML authentication

RegionSOAP EndpointPortProtocol
UK/EMEA  https://ws.ondemand.qas.com/ProOnDemand/V3/ProOnDemandService.asmx


 443 

  
HTTPS 

USA  https://ws2.ondemand.qas.com/ProOnDemand/V3/ProOnDemandService.asmx
APAC  https://ws3.ondemand.qas.com/ProOnDemand/V3/ProOnDemandService.asmx

V2: supports username/password and SAML authentication

RegionSOAP EndpointPortProtocol
UK/EMEA https://ws.ondemand.qas.com/ProOnDemand/V2/ProOnDemandService.asmx
  443 
 
 HTTPS 
USA https://ws2.ondemand.qas.com/ProOnDemand/V2/ProOnDemandService.asmx
APAC https://ws3.ondemand.qas.com/ProOnDemand/V2/ProOnDemandService.asmx

V1: supports username/password authentication only

RegionSOAP EndpointPortProtocol
UK/EMEA https://ws.ondemand.qas.com/ProWebIntermediary/OnDemandProWebIntermediary.asmx


443 

  
HTTPS

USA https://ws2.ondemand.qas.com/ProWebIntermediary/OnDemandProWebIntermediary.asmx
APAC https://ws3.ondemand.qas.com/ProWebIntermediary/OnDemandProWebIntermediary.asmx

Supported versions

  • SOAP v1.1 and 1.2
  • HTTP v1.0 and 1.1 

The following actions are available:

DoCanSearch

Checks that the combination of data mapping, engine and layout are valid for searching.

This action is performed to check that the combination of data mapping, engine and layout are valid to search on. Only some data mappings can be used with the Verification engine. Layouts can also be defined for specific data mappings, and so may not always be valid for other sets.

Request

Input XML Document: QACanSearch

The DoCanSearch action takes QACanSearch document as input. The properties are as follows:

ElementDescription
qas:DataIDType Country

This defines the data mapping that should be checked against. The available data mappings can be accessed using the SOAP action DoGetData.

For example, "GBR" checks against the United Kingdom.

qas:EngineType Engine

This defines whether the search engine can be used with the data mapping specified previously.

The engine options do not have to be specified if this is not required.

xs:string Layout

This is an optional setting.

This is used to check whether the layout has been specified.

Response

Output XML Document: QASearchOK

This document returns information about whether the search parameters that were specified can be used together for searching. The properties are as follows:

ElementDescription
xs:boolean IsOK

This defines whether the search parameters can be used together for searching.

ErrorCode

If IsOk is set to FALSE, this element is present and contains the error code that would be returned in a fault message if a search was attempted.

ErrorMessage

If IsOk is set to FALSE, this element is present and contains the error description that would be returned in a fault message if a search was attempted.

DoSearch

Submits an initial search to the server.

This action is the first stage of the address capture process and is used to submit an initial search to the server. A search must be performed against a specific data mapping and engine combination and will produce either:

  • A formatted final address, with match information;
  • A picklist of results from which to choose, with match information.

Request

Input XML document: QASearch

The DoSearch action takes a QASearch document as input. This has the following properties:  

ElementDescription
qas:DataIDType Country This defines the data mapping to be used to search against.The available data mappings can be accessed using the SOAP action DoGetData. For example, "GBR" would search for addresses in the United Kingdom data.
qas:EngineType Engine This defines the search engine to be used to perform the initial search, and the engine options that will be used.
xs:string Layout For Verification searches this element is required, since the result may be returned directly as a final formatted address. This means that you have to specify which layout will be used to format the results. For searches with other engines, this is an optional element. It is used with the AUE dataset to return picklists using the correct Form of address for the layout.
xs:string Search This defines the search string that will be submitted to the server. Different address information should be entered, depending on which search engine is being used. 

Structure: EngineType

The engine type enables you to specify the engine, and any engine options, that will be used to perform the search. This has the following properties:

ElementDescription
qas:EngineEnumType Engine Type

This specifies the engine that will be used to perform the search. The available values are:

  • Singleline uses the SingleLine engine to perform the search.
  • Typedown uses the Typedown engine to perform the search.
  • Verification uses the Verification engine to perform the search.
  • Intuitive uses the Intuitive engine to perform the search.
  • Keyfinder uses the Keyfinder engine to perform the search.
xs:boolean Flatten 

This defines whether the search results will be 'flattened' to a single picklist of deliverable results, or output as (potentially multiple) hierarchical picklists of results that can be stepped into. 

Picklists resulting from searches against Partner Sourced datasets will always be flattened regardless of the setting specified here. 

qas:ThresholdType Threshold 

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. 

Picklists resulting from searches against Partner Sourced datasets will return up to 20 matches regardless of the setting specified here. 

Intuitive specific behaviour:

  • This defines the maximum picklist size which is returned by the intuitive search engine. 
  • This element is always relevant when used with the intuitive engine.
  • It defaults to the value set for the IntuitiveSearchMaxPicklist configuration but will override that configuration if provided.

Due to the algorithms used to return result picklists, this value is used only as an approximation. 

qas:EngineIntensityType Intensity 

The standard setting is Close. This 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. 
qas:PromptSetType PromptSet 

The prompt set depends on the search engine used.  

A prompt set must be used if you are using a Partner Sourced dataset with the Single Line engine. 

qas:TimeoutType Timeout

The standard setting is 10000 milliseconds. This defines the time threshold in milliseconds after which a search will abort. A value of 0 signifies that searches will not timeout. 

The time threshold for searches against Partner Sourced datasets is fixed at 10000 milliseconds, regardless of the setting specified here.

Response

Output XML Document: QASearchResult

The DoSearch action returns a QASearchResult document, which defines the result of the search process. The verification engine will return results in a different manner to the Single Line and Typedown engines. This has the following properties:

ElementDescription
qas:QAPicklistType QAPicklist

This may not be returned by a search, depending upon the engine and the number of results.
This contains information about a picklist of results. Picklists are returned when searching with the Typedown and SingleLine engines, and may be returned from the Verification and Keyfinder engines.

qas:QAAddressType QAAddress This contains a final formatted address result for specific Verification engine result types.
qas:VerificationFlagsType VerificationFlags This contains the matching flags associated with Verification searches. For more information and examples see the USA Data Guide.
qas:VerifyLevelType VerifyLevel

This will only be returned for searches from the Verification engine. The verification level specifies how well the search has been matched, and the appropriate action that can be taken upon the result.
The Verification engine will return one of a set of VerifyLevels for a search, each of which may be treated differently by the integrator depending upon the amount of user interaction that is required.

Structure: QAPicklistType

The picklist type defines a set of result items and properties that are returned from a search. The picklist PicklistEntry will be sorted in the order that the entries must be displayed in. This may not be populated when using the Verification engine, when a formatted address may be instead returned. This has the following properties:

ElementDescription
xs:string FullPicklistMoniker

This is the SPM (search point moniker) that can be used to replicate the given picklist. Full picklist monikers are typically used when you refine a picklist further, using search text to filter the results. Picklist refinement is performed using the SOAP action DoRefine.

qas:PicklistEntryType PicklistEntry

This contains the individual search results as a picklist. Each picklist item represents a separate result and has different information associated with it.

xs:string Prompt

This defines a short text prompt that may be displayed to the user in an interactive scenario. This prompts the user as to what should be entered next. For example: "Enter building number/name or organization".

xs:nonNegativeInteger Total

This defines the total number of results that were matched by the search. This number should only be used for display purposes and should not be assumed to be the size of the returned picklist, which will often contain informational items and is restricted by a threshold.

xs:boolean AutoFormatSafe

Searches that return a single deliverable result will have this element set to TRUE. We recommend that the integrator should automatically format the result without user interaction. This aids address capture efficiency. Formatting address results is performed using the SOAP action DoGetAddress.

xs:boolean AutoformatPastClose

Searches that return a single deliverable result, but also produce other lesser matches, will have this element set to TRUE. This signifies that the integrator may choose to format the first picklist result automatically, without user interaction, to aid address efficiency. Formatting address results is performed using the SOAP action DoGetAddress.

xs:boolean AutoStepInSafe

Searches that return a single non-deliverable result that can be stepped into will have this element set to TRUE. We recommend that the integration should automatically step into the result, without user interaction. this aids address capture efficiency. Stepping into address results is performed using the SOAP action DoRefine.

xs:boolean AutoStepInPastClose

Searches that return a single non-deliverable result that can be stepped into, but that also produce other lesser matches, will have this element set to TRUE. This signifies that the integrator may choose to step into the first picklist result, without user interaction. This aids address capture efficiency. Stepping into address results is performed using the SOAP action DoRefine.

xs:boolean LargePotential

Searches that return too many results to be contained in a picklist will have this element set to TRUE. This signifies that further refinement is required before a picklist containing all of the results can be returned. Picklist refinement is performed using the SOAP action DoRefine.

xs:boolean MaxMatches

Searches that produce more than the maximum number of matches allowed will have this element set to TRUE. This signifies that the search was too broad to match and that a new search should be performed with more information specified.

xs:boolean MoreOtherMatches

Searches that produce in excess of the picklist threshold may return a subset of the matches in the picklist, plus an informational picklist item that allows the user to access the others. In this situation, this element is set to TRUE.

xs:boolean OverThreshold

Searches that produce in excess of the picklist threshold may only return a single informational picklist item that allows the user to access the full results. In this situation, this element is set to TRUE.

xs:boolean Timeout

This signifies that the search exceeded the specified timeout value. If this is unexpected for the given search, this could either signify that the timeout is set too low, or that the search was too broad.

Structure: PicklistEntryType

The PicklistEntryType structure defines the properties of a single picklist result from a search. These are contained in the PicklistType structure. The properties are as follows:

ElementDescription
xs:string Moniker

This is the SPM (search point moniker) that can be used to perform actions upon the picklist item, such as stepping in or formatting the item into a final address. Stepping into picklist items is performed using the SOAP action DoRefine. Formatting picklist items is performed using the SOAP action DoGetAddress.

xs:string PartialAddress

This picklist item is partially formatted into a single string, which may be useful for display in user interactive environments. This string is not suitable to be displayed as the picklist text: the Picklist element must be used instead.

xs:string Picklist

This is the string that must be displayed to the user for the picklist text. This should be combined with the Postcode element. The main picklist text and postcode have been separated to facilitate integration formatting.

xs:string Postcode

This is a postcode string and should be used in conjunction with the Picklistelement, defined previously, for the picklist text. This string is for display purposes only and may be returned blank if no postcode is associated with the picklist string.

xs:nonNegativeInteger Score

This is the percentage score that is given to each match returned from a search. This can be used as a guide to the quality of the match produced.

qas:QAAddressType QAAddress

This is the full formatted address for the picklist entry. This will be null if the search was submitted without the FormattedAddressInPicklist option set, or if the picklist entry does not correspond to a full formatted address.

xs:boolean FullAddress

This element signifies that the picklist item represents a deliverable address. If the user selects this picklist item, then it should be formatted into a final address, indicating the end of the address capture process. Formatting picklist items is performed using the SOAP action DoGetAddress.

xs:boolean Multiples

This element signifies that the picklist item represents multiple addresses, merged into a single entry. This element allows the integrator to display the picklist item with a different icon than a non-multiple entry if required.

xs:boolean CanStep

This element is only relevant when searching with the engine option Flatten set to FALSE. This element signifies that the picklist item can be stepped into, to produce a new picklist with more detail. For example, a picklist item that represents a street can be stepped into to produce a new picklist containing premises within the street. Stepping into picklist items is performed using the SOAP action DoRefine.

xs:boolean AliasMatch

This element signifies that the picklist item has been produced by a match to an alias of the item. This element allows the integrator to display the picklist item with a different icon to a non-alias match if required.

xs:boolean PostcodeRecoded

This element signifies that a postcode was searched on and that the match was made to a newer recorded version of the postcode. This element allows the integrator to display the picklist item with a different icon to a non-alias match if required.

xs:boolean CrossBorderMatch

This element signifies that a place such as a town was searched upon and that the match was made to an adjacent place. This element allows the integrator to display the picklist item with a different icon to a non-alias match if required. Cross Border Matches are only returned from bordering locality matches in the AUS data.

xs:boolean DummyPOBox

This element is only relevant when searching with the engine option Flatten set to FALSE. This element signifies that the picklist item represents a set of PO Boxes. If this entry is stepped into, the resulting picklist will contain all PO Boxes. This element allows the integrator to display the picklist item with a different icon to a normal match if required.

xs:boolean Name

This element is only relevant when searching within data mappings that contain Names information, such as GBN. This element signifies that the picklist item contains names information. It allows the integrator to display the picklist item with a different icon to a non-name match if required.

xs:boolean Information

This element is only relevant when searching with the engine option Flatten set to FALSE. This element signifies that the picklist item is an informational item. This means that the entry does not correspond to any particular address item. Informational picklist items are designed to help the user complete the address capture process, and must be displayed in the picklist. This element allows the integrator to display the picklist item with a different icon to a noninformational entry if required.

xs:boolean WarnInformation

This element is only relevant when searching with the engine option Flatten set to FALSE. This element signifies that the picklist item is a warning informational item. Unlike a normal informational entry, this will normally be displayed in the picklist when the user should be warned of a situation, such as a search yielding no matches. Informational picklist items are designed to help the user complete the address capture process, and must be displayed in the picklist. This element allows the integrator to display the picklist item with a different icon to a noninformational entry if required.

xs:boolean IncompleteAddr

This element signifies that the picklist item does not contain all of the information required to make it a deliverable address. This is commonly returned when searching within data mappings that do not contain premises information. If the user selects a picklist item with this element set, then they should be further prompted to provide additional premises information so that the address is deliverable.

xs:boolean UnresolvableRange

This element signifies that the picklist item is a range of premises which cannot be expanded, due to a lack of information about the possible elements within the range. If the user selects a picklist item with this element set, then they should be further prompted to provide additional premises information so that the address is deliverable.

xs:boolean PhantomPrimaryPoint

This element is only relevant when searching within the AUS data. This element signifies that the picklist item is a phantom primary point. A phantom primary point is a premises which is non-deliverable unless the user enters further secondary information. This secondary information may or may not be in the actual data. The user must enter this sub-premises information in order to complete a final address match. If the user selects a picklist item with this element set then they should be further prompted to provide additional premises information so that the address is deliverable.

Structure: QAAddressType

The QAAddressType structure specifies a formatted address result that is returned directly from a search. This will only occur when the Verification engine is used, and when the search produces one of the following VerifyLevels:

  • Verified;
  • InteractionRequired.

A search result is formatted using the layout that was specified in the Layout element of the QASearchdocument. When searching using the Single Line engine, and when the Verification engine produces otherVerifyLevels, then this structure will not be returned by the SOAP action DoSearch. The properties are as follows:

ElementDescription
qas:AddressLineType AddressLine

This defines the individually formatted address lines that have been returned by a search.

xs:boolean Overflow

This indicates that some address elements could not fit in the final address and these elements are not displayed (even partially). In order to avoid this, configure the layout to ensure that there are enough lines, and sufficient line width, to accommodate the elements you are returning.  

This property is not available when you are using Partner Sourced datasets, and a value of "False" is always returned.

xs:boolean Truncated

This indicates that some address elements could not completely fit on the address line and were cut short. In order to avoid this, configure the layout to ensure that there are enough lines, and sufficient line width, to accommodate the elements you are returning.  

This property is not available when you are using Partner Sourced datasets, and a value of "False" is always returned.

qas:DPVStatusType DPVStatus

This returns the DPV status of the server after performing the search. The following values can be returned:

  • DPVNotConfigured. DPV is not configured for this combination of data mapping/engine/layout.
  • DPVConfirmed. All address components (primary and secondary) are DPV confirmed.
  • DPVConfirmedMissingSec. The primary number was DPV confirmed but the secondary is incorrect or missing.
  • DPVNotConfirmed. The 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 and an unlock code must be supplied to reactivate it.
xs:boolean MissingSubPremise

 This attribute indicates that the address is a large volume receiver and may be missing subpremises information.

This is currently only relevant when using Canada data. 

Structure: AddressLineType

This structure defines an individually formatted address line and the properties that it contains. This is held in the QAAddresType structure defined previously. The properties are as follows:

ElementDescription
xs:string Label

This defines a text label for the line, which will describe the contents of the line. For example: "Town". Line labels may not be returned if multiple elements are fixed to a single line in the layout.

xs:string Line

This defines the final formatted address line, as described by the layout that was used to format the address result.

xs:boolean Overflow

This element signifies that some address elements could not be formatted upon this line, and so had to overflow onto other lines. If this element is set, then you should either add more output address lines in the specified layout, or specify larger widths.

xs:boolean Truncated

This element signifies that some address elements were truncated when formatted upon this line. If this element is set, then you should either add more output address lines in the specified layout, or specify larger widths.

qas:LineContentType LineContent

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.

DoRefine

Used to step into and refine a picklist result.

This action is used after a DoSearch action has been performed. It is used to step into a picklist result, and also to refine a picklist.

A picklist item is stepped into when the user selects an entry that can be expanded into elements "beneath" it. For example, a picklist item that represents a street can often be stepped into so that a picklist of the premises beneath the street are displayed. A picklist should be refined when the user enters text to be used to filter the picklist, creating a smaller set of picklist results. For example, a picklist that contains a set of streets can be refined with the text "ba" to generate a new picklist that only contains entries beginning with the letters "ba".

If you wish to step into a picklist result, you should use the SOAP action DoRefine with the picklist item SPM contained within a PicklistEntryType structure, and a blank refinement string.

If you wish to refine the current picklist, you should use the SOAP action DoRefine with the entire picklist SPM contained within a PicklistType structure, and a refinement string that is not blank.

Request

Input XML Document: QARefine

The DoRefine action takes a QARefine document as input. The properties are as follows:

ElementDescription
xs:string Moniker

This is the moniker that will have the action performed upon it. To step into a picklist item, use the moniker returned within the appropriate PicklistEntryType element moniker. To refine a picklist, use the moniker returned from the PicklistType element FullPicklistMoniker.

xs:string Refinement

This is the refinement string to be used. If you are stepping into a picklist item, then this should be blank.

xs:string Layout

For Verification searches this element is required, since the result may be returned directly as a final formatted address. This means that you have to specify which layout will be used to format the results. For searches with other engines this is an optional element. It is used with the AUE dataset to return picklists using the correct Form of address for the layout.

xs:boolean FormattedAddressInPicklist

This specifies whether final addresses should be returned with picklist entries. Searches may be slower with this option, but another server request may not be required. The Layout should be specified if you enable this option.

qas:ThresholdType Threshold

The standard setting is 25 items.

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 more refinement.

This is an alert box.Picklists resulting from searches against Partner Sourced datasets will return up to 20 matches regardless of the setting specified here. 

Due to the algorithms used with returning result picklists, this value is used only as an approximation.

qas:TimeoutType Timeout

The standard setting is 10000 milliseconds.

This defines the time threshold in milliseconds after which a refinement or stepin will abort. A value of 0 signifies that the action will not timeout. The time threshold for searches against Partner Sourced datasets is fixed at 10000 milliseconds, regardless of the setting specified here.

Response

Output XML Document: QAPicklist

The picklist type defines a set of result items and properties that are returned from a stepin or refine. The picklist PicklistEntry will be sorted in the order that the entries must be displayed in.

This has the following properties:

ElementDescription
xs:string FullPicklistMoniker

This is the SPM that can be used to replicate the given picklist, without any refinement text that has been specified. Full picklist monikers are typically used when further refining a picklist using search text to filter the results.

qas:PicklistEntryType PicklistEntry

This contains the individual search results as a picklist. Each picklist item represents a separate result, and has different information associated with it.

xs:string Prompt

This defines a short text prompt that may be displayed to the user in an interactive scenario. This prompts the user as to what should be entered next. For example "Enter building number / name or organization".

xs:nonNegativeInteger Total

This defines the total number of results that are present in the picklist. This number should only be used for display purposes and should not be assumed to be the size of the returned picklist, which will often contain informational items and is restricted by a threshold.

xs:boolean AutoFormatSafe

This element will only be specified after stepping into a result. Step-ins that return a single deliverable result will have this element set to TRUE.

We recommend that the integrator should automatically format the result without user interaction. This aids address capture efficiency. Formatting address results is performed using the SOAP action DoGetAddress.

xs:boolean AutoFormatPastClose

This element will only be specified after stepping into a result.

Searches that return a single deliverable result, but also produce other lesser matches, will have this element set to TRUE. This signifies that the integrator may choose to format the first picklist result automatically, without user interaction, to aid address efficiency. Formatting address results is performed using the SOAP action DoGetAddress.

xs:boolean AutoStepInSafe

This element will only be specified after stepping into a result.

Step-ins that return a single non-deliverable result that can be stepped into will have this element set to TRUE. We recommend that the integration should automatically step into the result, without user interaction. This aids address capture efficiency. Formatting address results is performed using the SOAP action DoGetAddress.

xs:boolean AutoStepInPastClose

This element will only be specified after stepping into a result.

Step-ins that return a single non-deliverable result that can be stepped into, but that also produce other lesser matches, will have this element set to TRUE. This signifies that the integrator may choose to step into the first picklist result, without user interaction. This aids address capture efficiency. Stepping into address results is performed using the SOAP action DoRefine.

xs:boolean LargePotential

Searches that return too many results to be contained in a picklist will have this element set to TRUE.

This signifies that further refinement is required before a picklist containing all of the results can be returned. Picklist refinement is performed using the SOAP action DoRefine.

xs:boolean MaxMatches

This will only be returned if the user is attempting to refine a picklist that had the MaxMatches element set.

Searches that produce more than the maximum number of matches allowed will have this element set to TRUE. This signifies that the search was too broad to match, and that a new search should be performed with more information specified.

xs:boolean MoreOtherMatches

Searches that produce in excess of the picklist threshold may return a subset of the matches in the picklist, plus an informational picklist item that allows the user to access the others. In this situation, this element is set to TRUE.

xs:boolean OverThreshold

Searches that produce in excess of the picklist threshold may only return a single informational picklist item that allows the user to access the full results. In this situation, this element is set to TRUE.

xs:boolean Timeout

This signifies that the stepin or refinement exceeded the specified timeout value. If this is unexpected for the given action, this could either signify that the timeout is set too low, or that the original search was too broad.

 

Structure: PicklistEntryType

The PicklistEntryType defines the properties of a single picklist result that is returned from a search. These are contained in the PicklistType structure.

The properties are as follows:

ElementDescription
xs:string Moniker

This is the SPM that can be used to perform actions upon the picklist item, such as stepping in or formatting the item into a final address. Stepping into picklist items is performed using the SOAP action DoRefine. Formatting picklist items is performed using the SOAP action DoGetAddress.

xs:string PartialAddress

This picklist item is partially formatted into a single string, which may be useful for display in user interactive environments. This string is not suitable to be displayed as the picklist text: the Picklist element must be used instead.

xs:string Picklist

This is the string that must be displayed to the user for the picklist text.  This should be combined with the Postcode element. The main picklist text and postcode have been separated to facilitate integration formatting.

xs:string Postcode

This is a postcode string and should be used in conjunction with the Picklistelement, defined previously, for the picklist text. This string is for display purposes only, and may be returned blank if no postcode is associated with the picklist string.

xs:nonNegativeInteger Score

This is the percentage score that is given to each match returned from a search. This can be used as a guide to the quality of the match produced.

qas:QAAddressType QAAddress

This is the full formatted address for the picklist entry. This will be null if the search was submitted without the FormattedAddressInPicklist option set, or if the picklist entry does not correspond to a full formatted address.

xs:boolean FullAddress

This element signifies that the picklist item represents a deliverable address.

If the user selects this picklist item, then it should be formatted into a final address, indicating the end of the address capture process. Formatting picklist items is performed using the SOAP action DoGetAddress.

xs:boolean Multiples

This element signifies that the picklist item represents multiple addresses, merged into a single entry. This element allows the integrator to display the picklist item with a different icon than a non-multiple entry, if required.

xs:boolean CanStep

This element is only relevant when searching with the engine option Flatten set to FALSE.

This element signifies that the picklist item can be stepped into, to produce a new picklist with more detail. For example, a picklist item that represents a street can be stepped into to produce a new picklist containing premises within the street. Stepping into picklist items is performed using the SOAP action DoRefine.

xs:boolean AliasMatch

This element signifies that the picklist item has been produced by a match to an alias of the item. This element allows the integrator to display the picklist item with a different icon to a non-alias match, if required.

xs:boolean PostcodeRecoded

This element signifies that a postcode was searched on, and that the match was made to a newer recoded version of the postcode. This element allows the integrator to display the picklist item with a different icon to a non-alias match, if required.

xs:boolean CrossBorderMatch

This element signifies that a place such as a town was searched upon, and that the match was made to an adjacent place. This element allows the integrator to display the picklist item with a different icon to a non-alias match, if required. Cross Border Matches are only returned from bordering locality matches in the AUS data.

xs:boolean DummyPOBox

This element is only relevant when searching with the engine option Flatten set to FALSE. This element signifies that the picklist item represents a set of PO Boxes. If this entry is stepped into, the resulting picklist will contain all PO Boxes. This element allows the integrator to display the picklist item with a different icon to a normal match, if required.

xs:boolean Name

This element is only relevant when searching within data mappings that contain Names information, such as GBN. This element signifies that the picklist item contains names information. It allows the integrator to display the picklist item with a different icon to a non-name match, if required.

xs:boolean Information

This element is only relevant when searching with the engine option Flatten set to FALSE. This element signifies that the picklist item is an informational item. This means that the entry does not correspond to any particular address item. Informational picklist items are designed to help the user complete the address capture process, and must be displayed in the picklist.

This element allows the integrator to display the picklist item with a different icon to a noninformational entry, if required.

xs:boolean WarnInformation

This element is only relevant when searching with the engine option Flatten set to FALSE. This element signifies that the picklist item is a warning informational item. Unlike a normal informational entry, this will normally be displayed in the picklist when the user should be warned of a situation, such as a search yielding no matches.

Informational picklist items are designed to help the user complete the address capture process, and must be displayed in the picklist. This element allows the integrator to display the picklist item with a different icon to a noninformational entry, if required.

xs:boolean IncompleteAddr

This element signifies that the picklist item does not contain all of the information required to make it a deliverable address. This is commonly returned when searching within data mappings that do not contain premises information.

This element will not be set for searches against Partner Sourced datasets. 

If the user selects a picklist item with this element set, then they should be further prompted to provide additional premises information so that the address is deliverable.

xs:boolean UnresolvableRange

This element signifies that the picklist item is a range of premises which cannot be expanded, due to a lack of information about the possible elements within the range. 

This element will not be set for searches against Partner Sourced datasets. 

If the user selects a picklist item with this element set, then they should be further prompted to provide additional premises information so that the address is deliverable.

xs:boolean PhantomPrimaryPoint

This element is only relevant when searching within the AUS data.

This element signifies that the picklist item is a phantom primary point. A phantom primary point is a premises which is non-deliverable unless the user enters further secondary information. This secondary information may or may not be in the actual data. The user must enter this sub-premises information in order to complete a final address match.

If the user selects a picklist item with this element set then they should be further prompted to provide additional premises information so that the address is deliverable.

DoGetAddress

Formats a picklist item to obtain a final, formatted address.

This action is performed to format a picklist item in order to obtain the final formatted address. This will typically be when the user selects a picklist item that has the FullAddress element set to TRUE in the associated PicklistEntryType structure.

The formatting of a picklist item is performed using the SPM of the specified picklist item. This is contained within the Moniker element of the PicklistEntryType structure. A picklist item is formatted against a specified layout.

Request

Input XML Document: QAGetAddress

The DoGetAddress SOAP action takes a QAGetAddress document as input. This has the following properties:

ElementDescription
xs:string Layout

This defines the layout that will be used to format the SPM.

xs:string Moniker

The defines the SPM of the picklist item that will be formatted. This is contained within the Moniker element of the PicklistEntryType structure.

Response

Output XML Document: QAAddressType

The QAAddressType structure specifies a formatted address result that is returned from a DoGetAddressaction. The properties are as follows:

ElementDescription
qas:AddressLineType AddressLine

This defines the individual formatted address lines that have been returned by a search.

xs:boolean Overflow

This element signifies that there were not enough layout lines to contain all of the address line, and that some elements had to overflow onto other lines. If this element is set, then you should either add more output address lines in the specified layout or specify larger widths.

This property is not available when you are using Partner Sourced datasets, and a value of "False" is always returned. 

xs:boolean Truncated

This element signifies that some of the address lines were too short to accommodate all of the formatted address, and so truncation has occurred. If this element is set, then you should either add more output address lines in the specified layout, or specify larger widths.  

This property is not available when you are using Partner Sourced datasets, and a value of "False" is always returned. 

qas:DPVStatusType DPVStatus

This returns the DPV status of the server after performing the search. The following values can be returned:

  • 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 and an unlock code must be supplied to reactivate it.
xs:boolean MissingSubPremise

  

This is currently only relevant when using Canada data. 

This attribute indicates that the address is a large volume receiver and may be missing subpremises information.

Structure: AddressLineType

This structure defines an individually formatted address line, and the properties that it contains. This is held in the QAAddressType structure outlined previously. The properties are as follows:

ElementDescription
xs:string Label

This defines a text label for the line, which will describe the contents of the line. For example "Town".

Line labels may not be returned if multiple elements are fixed to a single line in the layout.

xs:string Line

This defines the final formatted address line, as described by the layout that was used to format the address result.

xs:boolean Overflow

This element signifies that some address elements could not be formatted upon this line, and so had to overflow onto other lines.

If this element is set, then you should either add more output address lines in the specified layout, or specify larger widths.

xs:boolean Truncated

This element signifies that some address elements were truncated when formatted upon this line.

If this element is set, then you should either add more output address lines in the specified layout, or specify larger widths.

qas:LineContentType LineContent

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.
qas:DataPlusGroupType DataplusGroup

This contains any groups of multiple DataPlus items that are associated with the line, broken down into individual DataPlus items.

Structure: DataPlusGroupType

This structure contains any groups of multiple DataPlus items that are associated with the formatted address line. This is held in the AddressLineType structure outlined previously. The properties are as follows:

ElementDescription
xs:string DataPlusGroupItem

This element contains a single DataPlus value.

 

AttributeDescription
xs:string GroupName

DataPlus values are grouped according to the DataPlus set they belong to. GroupName identifies the source DataPlus set.

The following shows an extract of an AddressLine SOAP message returned by the server when both Gas and Electricity meter numbers are configured to appear on the same address line:

<qas:AddressLine LineContent="DataPlus" Truncated="True">
  <qas:Label>Gas and Electricity Meter Numbers</qas:Label>
  <qas:Line>2408630034|2408630036,1508436932|1508436943</qas:Line>
  <qas:DataplusGroup GroupName="GBRGAS">
   <qas:DataplusGroupItem>2408630034</qas:DataplusGroupItem>
   <qas:DataplusGroupItem>2408630036</qas:DataplusGroupItem>
 </qas:DataplusGroup>
 <qas:DataplusGroup GroupName="GBRELC">
  <qas:DataplusGroupItem>1508436932</qas:DataplusGroupItem>
  <qas:DataplusGroupItem>1508436943</qas:DataplusGroupItem>
</qas:DataplusGroup>
</qas:AddressLine>

DoGetData

Obtains a list of available data mappings.

This action is performed to obtain a list of available data mappings that can be searched on. Specifically, this action will return a set of qas:DataIDType elements that are valid to be passed to the DoSearch action. 

Request

Input XML Document: None

There is no XML document that needs to be passed for this SOAP action.

Response

Output XML Document: QAData

The DoGetData action returns a QAData document which defines all of the available data mappings that can be searched against. The properties are as follows:

ElementDescription
qas:QADataSet DataSet This defines the data mappings that are available for searching.

Structure: QADataSet

This structure contains information about a specific data mapping that can be searched on. This is held in the QAData structure, defined previously. The structure has the following properties:

ElementDescription
qas:DataIDType ID

This defines the data mapping identifier. This is the string that should be passed in the Country element of the QASearch structure for the DoSearch action. For example, "AUS".

xs:string Name

This defines the name of the data mapping as text that can be displayed to users. This allows users to select the data mapping they will search against. For example, "Australia".

This string is defined within the DataMappings configuration setting.

DoGetSystemInfo

Obtains information about the server.

This action is performed to access a list of system information text which may be useful to integrators.

Request

Input XML Document: None

There is no XML document that needs to be passed for this SOAP action.

Response

Output XML Document: QASystemInfo

This structure gives system information about the server. The properties are as follows:

ElementDescription
xs:string SystemInfo

This contains the individual lines of the system information for integrators.

The lines are returned with a tab character to allow the integrator to separate keywords from values if required.

DoGetExampleAddresses

Returns fully formatted example addresses.

This action is performed to return fully formatted example addresses. This may commonly be used to preview a given layout with a set of addresses. 

Not all Partner Sourced datasets are supplied with example addresses. Please check the relevant data guide for more information on which datasets support example addresses. 

Request

Input XML Document: QAGetExampleAddresses

The DoGetExampleAddresses action takes a QAGetExampleAddresses document as input. The properties are as follows:

ElementDescription
qas:DataIDType Country

This defines the data mapping that you want to return example addresses for. The available data mappings can be accessed using the SOAP action DoGetData. For example, "GBR" will obtain example addresses for the United Kingdom.

xs:string Layout

This specifies the layout that will be used to format the example addresses.

Response

Output XML Document: QAExampleAddresses

This document returns all of the example addresses for a given country, formatted using the specified layout. The properties are as follows:

ElementDescription
qas:ExampleAddress ExampleAddress

This contains the set of example addresses.

Structure: QAExampleAddress

This structure contains a single formatted example address. The structure is contained within a QAExampleAddresses document, defined previously. The properties are as follows:

ElementDescription
qas:QAAddressType Address

This contains the formatted example address.

xs:string Comment

This contains a text description of the example address. For example "A typical residential address".

Structure: QAAddressType

The QAAddressType structure specifies a formatted address result that is returned from a DoGetAddress action.

The properties are as follows:

ElementDescription
qas:AddressLineType AddressLine

This defines the individually formatted address lines that have been returned by a search.

xs:boolean Overflow

This element signifies that there were not enough layout lines to contain all of the address line, and that some elements had to overflow onto other lines. If this element is set, then you should either add more output address lines in the specified layout, or specify larger widths. 

This property is not available when using Partner Sourced datasets, and a value of "False" is always returned. 

xs:boolean Truncated

This element signifies that some of the address lines were too short to accommodate all of the formatted address, and so truncation has occurred.

If this element is set, then you should either add more output address lines in the specified layout, or specify larger widths.  

This property is not available when using Partner Sourced datasets, and a value of "False" is always returned. 

qas:DPVStatusType DPVStatus

This returns the DPV status of the server after performing the search. The following values can be returned:

  • 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 and an unlock code must be supplied to reactivate it.

Structure: AddressLineType

This structure defines an individually formatted address line and the properties that it contains. This is held in the QAAddressType structure defined previously. The properties are as follows:

ElementDescription
xs:string Label

This defines a text label for the line, which will describe the contents of the line. For example "Town". Line labels may not be returned if multiple elements are fixed to a single line in the layout.

xs:string Line

This defines the final formatted address line, as described by the layout that was used to format the address result.

xs:boolean Overflow

This element signifies that some address elements could not be formatted upon this line, and so had to overflow onto other lines. If this element is set, then you should either add more output address lines in the specified layout or specify larger widths.

xs:boolean Truncated

This element signifies that some address elements were truncated when formatted upon this line. If this element is set, then you should either add more output address lines in the specified layout or specify larger widths.

qas:LineContentType LineContent

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.

DoGetLayouts

Obtains a list of layouts that have been configured within the configuration file.

This action is performed to obtain a list of layouts that have been configured within the configuration file, and can be used to format address results.

A list of layouts is useful for situations where the integration would give the user a choice of which layout to use to format an address result. If only one layout is ever used within an integration, it is more common to code the layout name.

Request

Input XML Document: QAGetLayouts

The DoGetLayouts action takes a QAGetLayouts document as input. The properties are as follows:

ElementDescription
qas:DataIDType Country

This defines the data mapping for which the returned layouts are valid. The available data mappings can be accessed using the SOAP action DoGetData.

Response

Output XML Document: QALayouts

This document returns all of the layouts that are valid to be used against the provided data mapping. The properties are as follows:

ElementDescription
qas:QALayout Layout

This contains the set of layouts that are valid.

Structure: QALayout

This structure contains the information about a specific layout. The layouts are contained within the QALayouts document, defined previously. The properties are as follows:

ElementDescription
xs:string Name

This returns the name of a layout. The name of a layout is defined by the configuration section that it is defined within.

The layout name needs to be passed to format a picklist item, using the DoGetAddress action.

xs:string Comment

This returns the layout description. Layouts can have comments defined using the configuration setting Comment.

DoGetPromptSet

Obtains information regarding a prompt set.

This action obtains information regarding a prompt set, such as the number of lines and the suggested input.

Prompt sets are employed to manage the way in which users enter addresses. An address can be submitted as one or as many text fields; a prompt set defines which address elements can be entered in each field. E.g.: a text field might be constrained so that it only accepts postcodes.

For example, the alternate prompt set for GBR has three input lines:

  • Building number or name
  • Street
  • Town

While the alternate prompt set for USA has four input lines:

  • Street address
  • City
  • State
  • ZIP Code

Request

Input XML Document: QAGetPromptSet

The DoGetPromptSet action takes a QAGetPromptSet document as input. The properties are as follows:

ElementDescription
qas:PromptSetType PromptSet

This defines the prompt set that you wish to obtain information about. The available prompt sets 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).
qas:DataIDType Country

This defines the data mapping that will be used to search against. The available data mappings can be accessed using the SOAP action DoGetData. For example, "GBR" returns information about the prompt set suitable for searching within United Kingdom data.

qas:EngineType

This specifies the engine type to be used to perform the subsequent search.

Response

Output XML Document: QAPromptSet

This document returns information about the specific prompt set that was requested with the country. The properties are as follows:

ElementDescription
qas:PromptLine Line

This defines the set of lines that the prompt set contains.

Each prompt set line should correspond to a separate input field for the user to enter their search terms.

AttributeDescription
xs:boolean Dynamic

This returns true if the specified search engine requires dynamic refinement at the first search stage.

Structure: PromptLine

This structure contains information regarding a specific prompt set line. this is contained within the QAPromptSet document defined previously. The properties are as follows:

ElementDescription
xs:string PromptLine

This provides a text hint about what should be entered into the input field associated with this prompt line. For example, "Building number or name".

xs:nonNegativeInteger SuggestedInputLength

This provides the suggested maximum length of the input field.

xs:string Example

This provides an example of what could be entered into the prompt line, to aid the user. For example, "12".

Server operation examples

Each Address Validate SOAP API request requires username and password or the token to be submitted as part of the communication. Examples below use a sample username and password.

For examples with token authentication please refer to our sample code: 

List of examples

CanSearch

An optional stage of the address search process is to check that the combination of data mapping, engine and layout is valid by using the DoCanSearch action. 

This is an essential stage if you are using metered datasets. The operation returns an error if the value of the meter is less than or equal to zero.

SOAP ActionInput XML DocumentOutput XML Document
 /DoCanSearch  QACanSearch  QASearchOK

Description

Returns False if you specify a data mapping:

  • that is not supported
  • for which you do not have a valid licence
  • for which the specified layout has not been defined (specifying a layout is optional)

It also returns False if the credits have run out, or if the requested engine is not appropriate or available (for example, verification is only available for some data mappings).

The operation also returns information as to why a value of False was returned.

Example

The following example shows the combination of the GBR data mapping, Single Line engine and the layout "QADefault" being verified as valid.

Request

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ond="http://www.qas.com/OnDemand-2011-03">
   <soapenv:Header>
      <ond:QAQueryHeader>
         <ond:QAAuthentication>
            <ond:Username />
            <ond:Password />
         </ond:QAAuthentication>
         <ond:Security>
            <!--You may enter ANY elements at this point-->
         </ond:Security>
      </ond:QAQueryHeader>
   </soapenv:Header>
   <soapenv:Body>
      <ond:QACanSearch>
         <ond:Country>GBR</ond:Country>
         <ond:Engine>Singleline</ond:Engine>
         <!--Optional:-->
         <ond:Layout>QADefault</ond:Layout>
      </ond:QACanSearch>
   </soapenv:Body>
</soapenv:Envelope>

 Response

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soap:Header>
      <QAInformation xmlns="http://www.qas.com/OnDemand-2011-03">
         <StateTransition>Unknown</StateTransition>
         <CreditsUsed>0</CreditsUsed>
      </QAInformation>
   </soap:Header>
   <soap:Body>
      <QASearchOk xmlns="http://www.qas.com/OnDemand-2011-03">
         <IsOk>true</IsOk>
      </QASearchOk>
   </soap:Body>
</soap:Envelope>

Initial Search

The next stage is to submit an initial search to the server using the DoSearch action.

SOAP ActionInput XML DocumentOutput XML Document
 /DoSearch  QASearch  QASearchResult

Description

Performs an address search that returns one or more results. Result(s) can be in the form of a picklist or a single final address. 

Sending a layout for DoSearch is optional but recommended for verification searches where a final address can be returned.

 Example

The following example submits the search string "s87bw" against the GBR data using the Single Line engine, and specifies the "( QAS Standard Layout )" layout. The response is in the form of a picklist item consisting of a single entry.

Request

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ond="http://www.qas.com/OnDemand-2011-03">
   <soapenv:Header>
      <ond:QAQueryHeader>
         <ond:QAAuthentication>
            <ond:Username />
            <ond:Password />
         </ond:QAAuthentication>
         <ond:Security>
            <!--You may enter ANY elements at this point-->
         </ond:Security>
      </ond:QAQueryHeader>
   </soapenv:Header>
   <soapenv:Body>
      <ond:QASearch>
         <ond:Country>USA</ond:Country>
         <ond:Engine>Singleline</ond:Engine>
         <!--Optional:-->
         <ond:Layout>QADefault</ond:Layout>
         <ond:Search>1 alpine ave,10301</ond:Search>
         <!--Optional:-->
         <ond:FormattedAddressInPicklist>false</ond:FormattedAddressInPicklist>
      </ond:QASearch>
   </soapenv:Body>
</soapenv:Envelope>

 Response

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soap:Header>
      <QAInformation xmlns="http://www.qas.com/OnDemand-2011-03">
         <StateTransition>PickList</StateTransition>
         <CreditsUsed>0</CreditsUsed>
      </QAInformation>
   </soap:Header>
   <soap:Body>
      <QASearchResult xmlns="http://www.qas.com/OnDemand-2011-03">
         <QAPicklist AutoFormatSafe="true">
            <FullPicklistMoniker>USA|524b8f58-12d9-4103-b762-6a0ff017df48|6MUSADwvfBwEBAQABAAWcHJ4AAAAAADEAZA--</FullPicklistMoniker>
            <PicklistEntry FullAddress="true">
               <Moniker>USA|524b8f58-12d9-4103-b762-6a0ff017df48|vOUSADwvfBwEDAQAFnByeAAAAAAAxAGQA</Moniker>
               <PartialAddress>1 Alpine Ave, Staten Island NY 10301-4001</PartialAddress>
               <Picklist>1 Alpine Ave, Staten Island NY</Picklist>
               <Postcode>10301-4001</Postcode>
               <Score>100</Score>
            </PicklistEntry>
            <Prompt>Enter selection</Prompt>
            <Total>1</Total>
         </QAPicklist>
         <VerificationFlags>
            <PostCodeCorrected>true</PostCodeCorrected>
         </VerificationFlags>
      </QASearchResult>
   </soap:Body>
</soap:Envelope>

'Step In'

If you want to 'step into' a picklist result, you should use the DoRefine action with the picklist item SPM (Search Point Moniker - used to store the state of a search that is in progress; each picklist item has a SPM) contained within a PicklistEntryType structure and a blank refinement string.

SOAP ActionInput XML DocumentOutput XML Document
 /DoRefine  QARefine  QAPicklist

Description

Refines a picklist that was created during a search.

Example

The following example shows a refinement request using a moniker (name used to uniquely identify each object) returned from the initial search example. The refinement request consists of the street picklist item for "Westwick Road" moniker and the refinement text is blank. The response is in the form of a picklist item containing 3 entries.

Request

POST / HTTP/1.0
Content-Type: text/xml
Content-Length: 374
SOAPAction: "http://www.qas.com/OnDemand-2010-01/DoRefine"

<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soapenv:Header>
    <ond:QAAuthentication>
      <ond:Username>572c3-8b4</ond:Username>
      <ond:Password>YourPassw0rd</ond:Password>
    </ond:QAAuthentication>
  </soapenv:Header>
  <soap:Body>
    <QARefine Threshold="50" xmlns="http://www.qas.com/OnDemand-2010-01">
      <Moniker>ZOGBREwPUBwMBAAEQeX2AAAA-</Moniker>
      <Refinement/>
    </QARefine>
  </soap:Body>
</soap:Envelope> 

 Response

HTTP/1.0 200 OK
Content-Length: 1339
Content-Type: text/xml
<?xml version="1.0" encoding="UTF-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Header> <QAInformation xmlns="http://www.qas.com/OnDemand-2010-01"> <CreditsUsed>1</CreditsUsed> </QAInformation> </soap:Header> <soap:Body> <qas:QAPicklist xmlns:qas="http://www.qas.com/OnDemand-2010-01"> <qas:Total>3</qas:Total> <qas:FullPicklistMoniker>ZOGBREwPUBwMBAAEQeX2AAAA-</qas:FullPicklistMoniker> <qas:Prompt>Enter building number/name or organisation</qas:Prompt> <qas:PicklistEntry Multiples="true" CanStep="true"> <qas:Picklist>121 ... 161 [odd]</qas:Picklist> <qas:PartialAddress>Westwick Road, SHEFFIELD, S8 7BW</qas:PartialAddress> <qas:Score>0</qas:Score> <qas:Moniker>dOGBREwPUBwMBAAEQeX_AAAA-</qas:Moniker> </qas:PicklistEntry> <qas:PicklistEntry FullAddress="true"> <qas:Picklist>161a</qas:Picklist> <qas:PartialAddress>161a Westwick Road,SHEFFIELD, S8 7BW</qas:PartialAddress> <qas:Score>0</qas:Score> <qas:Moniker>0OGBREwPUBwMBAAEQeYYAAAA-</qas:Moniker> </qas:PicklistEntry> <qas:PicklistEntry Multiples="true" CanStep="true"> <qas:Picklist>163 ... 207 [odd]</qas:Picklist> <qas:PartialAddress>Westwick Road, SHEFFIELD, S8 7BW</qas:PartialAddress> <qas:Score>0</qas:Score> <qas:Moniker>HOGBREwPUBwMBAAEQeYdAAAA-</qas:Moniker> </qas:PicklistEntry> </qas:QAPicklist> </soap:Body> </soap:Envelope>

Refine

If you want to refine a picklist, you should use the DoRefine action with the full picklist moniker contained within a picklist structure and a non-blank refinement string.

SOAP ActionInput XML DocumentOutput XML Document
 /DoRefine  QARefine  QAPicklist

Description

Refines a picklist that was created during a search.

Example

Continuing from the above 'step in' example, the user has entered refinement text of "205". In this case, the refinement request uses the moniker of the full picklist from the previous operation and the refinement text "205" in the refinement field. The response is a picklist item containing a single entry.

Request

POST / HTTP/1.0
Content-Type: text/xml
Content-Length: 388
SOAPAction: "http://www.qas.com/OnDemand-2010-01/DoRefine"
<?xml version="1.0"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <soapenv:Header> <ond:QAAuthentication> <ond:Username>572c3-8b4</ond:Username> <ond:Password>YourPassw0rd</ond:Password> </ond:QAAuthentication> </soapenv:Header> <soap:Body> <QARefine Threshold="50" xmlns="http://www.qas.com/OnDemand-2010-01"> <Moniker>ZOGBREwPUBwMBAAEQeX2AAAA-</Moniker> <Refinement>205</Refinement> </QARefine> </soap:Body> </soap:Envelope>

 Response

HTTP/1.0 200 OK
Content-Length: 705
Content-Type: text/xml

<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <QAInformation xmlns="http://www.qas.com/OnDemand-2010-01">
      <CreditsUsed>1</CreditsUsed>
    </QAInformation>
  </soap:Header>
  <soap:Body>
    <qas:QAPicklist xmlns:qas="http://www.qas.com/OnDemand-2010-01">
      <qas:Total>1</qas:Total>
      <qas:FullPicklistMoniker>ZOGBREwPUBwMBAAEQeX2AAAA-</qas:FullPicklistMoniker>
      <qas:Prompt>Enter building number/name or organisation</qas:Prompt>
      <qas:PicklistEntry FullAddress="true">
        <qas:Picklist>205</qas:Picklist>
        <qas:PartialAddress>205 Westwick Road,SHEFFIELD, S8 7BW</qas:PartialAddress>
        <qas:Score>0</qas:Score>
        <qas:Moniker>JOGBREwPUBwMBAAEQeYdAMjA1AAA-</qas:Moniker>
      </qas:PicklistEntry>
    </qas:QAPicklist>
  </soap:Body>
</soap:Envelope> 

Get Final Address

The last stage is to obtain the final address using the DoGetAddress action. As input, the picklist item SPM of the PicklistEntry that you want to format should be passed.

SOAP ActionInput XML DocumentOutput XML Document
 /DoGetAddress  QAGetAddress  QAAddress

Description

Creates a final, formatted address from a previously-created picklist item.

Example

Continuing from the above refine example, the moniker of the single picklist entry for "205 Westwick Road" is passed along with the "QADefault" layout. The response contains the address formatted according to the specified layout.

Request

POST / HTTP/1.0
Content-Type: text/xml
Content-Length: 383
SOAPAction: "http://www.qas.com/OnDemand-2010-01/DoGetAddress"

<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soapenv:Header>
    <ond:QAAuthentication>
      <ond:Username>572c3-8b4</ond:Username>
      <ond:Password>YourPassw0rd</ond:Password>
    </ond:QAAuthentication>
  </soapenv:Header>
  <soap:Body>
    <QAGetAddress xmlns="http://www.qas.com/OnDemand-2010-01">
      <Moniker>JOGBREwPUBwMBAAEQeYdAMjA1AAA-</Moniker>
      <Layout>QADefault</Layout>
    </QAGetAddress>
  </soap:Body>
</soap:Envelope> 

 Response

HTTP/1.0 200 OK
Content-Length: 927
Content-Type: text/xml

<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <QAInformation xmlns="http://www.qas.com/OnDemand-2010-01">
      <CreditsUsed>1</CreditsUsed>
    </QAInformation>
  </soap:Header>
  <soap:Body>
    <qas:QAAddress xmlns:qas="http://www.qas.com/OnDemand-2010-01">
      <qas:AddressLine LineContent="None">
        <qas:Label></qas:Label>
        <qas:Line>205 Westwick Road</qas:Line>
      </qas:AddressLine>
      <qas:AddressLine LineContent="None">
        <qas:Label></qas:Label>
        <qas:Line></qas:Line>
      </qas:AddressLine>
      <qas:AddressLine LineContent="Address">
        <qas:Label>Town</qas:Label>
        <qas:Line>SHEFFIELD</qas:Line>
      </qas:AddressLine>
      <qas:AddressLine LineContent="Address">
        <qas:Label>County</qas:Label>
        <qas:Line></qas:Line>
      </qas:AddressLine>
      <qas:AddressLine LineContent="Address">
        <qas:Label>Postcode</qas:Label>
        <qas:Line>S8 7BW</qas:Line>
      </qas:AddressLine>
    </qas:QAAddress>
  </soap:Body>
</soap:Envelope> 

Address searching

Depending on your integration and requirements, Address Validate API provides several different ways of searching for addresses:

SingleLine searching requires a user to type in two or three address elements, each separated by a comma, in the order, they would appear on an envelope (for example, the street name followed by the town). SingleLine searches can use a variety of techniques to return the correct address from incomplete or misspelled information.

Typedown searching starts with the most general address element and, once that has been found, moves on to more specific parts of the address. Typedown is the more useful search option when a user is certain of the address information.

Verification searching requires the user to type in the complete address, as it would appear on an envelope. The entire address is submitted to the engine, and a verification level is returned. The verification level corresponds to the degree of confidence in the returned address. If an accurate match could not be found, the integrator can choose whether to return the address as it was entered by the user or to return a prompt requesting more user interaction.

Intuitive searching has elements of both Single Line and Typedown searching. The user enters an address in the format they are familiar with, and with each extra letter typed, the picklist narrows down the result until a final address is selected.

Keyfinder searching works in a similar way to Single Line searching. The user types in the key reverse search term, and Pro Web returns the address that matches the search in the picklist.

SingleLine

The SingleLine engine is designed so that the user can enter minimal information in order to produce a list of matching and close-matching addresses from which they can select the required one.

The SingleLine engine works in the opposite way to the Typedown engine, in that the user enters address elements, starting with the most specific (for example, a house number and/or a street name) and then moves on to more general elements (for example, a town or postcode in the United Kingdom). When the user has entered all the information, they should start the search manually.

The search term entered can contain elements such as wildcards.

A prompt set can be used to guide the user as to what information should be entered at each stage. Ideally, the user will always enter information that generates the smallest number of matches. This makes the search more efficient and makes it easier for the user to select the final address. Which prompt set should be used depends on whether the Flatten engine mode is set to Yes or No.

The SingleLine scenario for address capture commonly requires user interaction after the initial search has been submitted, in order to select a matching address from the returned set of picklist items.

There are two ways in which the engine will return the picklist: in a hierarchical or flattened mode.

Setting the mode is controlled through the Flatten engine option. This does not affect the way in which the initial search is performed, but does affect the number and type of picklist items that are returned.

Hierarchical mode

The following diagram demonstrates the flow of searching using this mode:

The shaded boxes represent user actions; all other boxes are integration actions.

The user has control over the address capture process, but this scenario is dependent on:

  • Users who are familiar with address capture process
  • A responsive connection between the client and the integration.

This scenario is therefore more suitable for internal applications such as an intranet site than for public website address capture.

Searches performed using this mode will create a picklist which may have one or more of the following properties:

  • Hierarchical picklist items which can be 'stepped into' to produce new picklists
  • Picklist items that may contain 'informational' picklist items
  • Picklists that will commonly contain fewer items than if the search was performed with the flattened mode, due to their hierarchical nature.

The hierarchical mode of the SingleLine engine is designed to allow users to enter any search terms that they feel are appropriate.

We recommend that you use the OneLine prompt set. This prompt set specifies a single unconstrained input line that will accept any address elements. It is designed to be used with the SingleLine engine in hierarchical mode (i.e., the Flatten engine option set to False) or the Typedown engine.

Due to the hierarchical nature of the picklist returned, and the fact that the user can step into entries to obtain more detail, there is not a requirement to use the more restrictive prompt sets to minimise picklist size.

Auto Step-In

Typedown

The Typedown engine is designed to allow the user to drill down through a series of picklists to select the required address.

This is the fastest method of searching for address data.

When a user enters text into the search field, the picklist is updated a short period after the user stops typing (this period is currently 300 milliseconds). This means that a picklist is generated as the user types. The more characters that the user enters, the more refinement is shown in the picklist. This 'dynamic refinement' enables searches to be initiated without the user having to type 'Enter' or click the Search button.

Prompt Sets

Prompt sets are used to guide the user as to what information should be entered at each stage. Ideally, the user will always enter information that generates the smallest number of matches. This makes the search more efficient, and makes it easier for the user to select the final address.

Typedown and Fuzzy Matching

Typedown searching does not have fuzzy matching capability. Therefore, if you misspell an address element when searching for an address in Typedown, the engine will not be able to find it.

For example, with United Kingdom data, if the user enters "depn", the Typedown search engine cannot find any address elements beginning with that combination of letters and the "No matches" message will be returned. However, deleting the last character will return a choice of places beginning with "dep", and the user can continue searching.

Hierarchical Mode

The Typedown method of address capture usually requires user interaction after the initial search has been submitted, in order to select a final address from the returned set of picklist items.

The manner in which the engine will return the picklist is determined by a hierarchical mode of searching.

  

 

The shaded boxes represent user actions; all other boxes are integration actions.

The user has control over the address capture process, but this scenario is dependent on:

  • Users who are familiar with address capture process
  • A responsive connection between the client and the integration.

This scenario is therefore more suitable for internal applications such as an intranet site than for public website address capture.

Searches performed using this mode will create a picklist which may have one or more of the following properties:

  • Hierarchical picklist items which can be 'stepped into' to produce new picklists
  • Picklist items that may contain 'informational' picklist items
  • Picklists will update as the user enters more characters in the search field

Typedown generally involves two, three or four stages. When searching for a United Kingdom address, users should first enter the postcode, county, town or locality.

The Typedown engine usually returns a picklist choice after three or four characters, from which the user can select a place name.

Auto Step-In

Verification

The Verification engine is designed so that only minimal interaction, or none at all, is required from the user (this can be decided by the integrator).

The user enters the whole address in the same way that it would be written on an envelope, and the entire address is submitted to the engine.

The engine returns a verification level which corresponds to the degree of confidence in the returned (and reformatted) match. For addresses that could not be matched with confidence, it is up to the integrator whether to return a prompt for more user interaction, or whether to return the address as it was entered.

Unlike the other engines, the Verification engine does not require prompt sets to be used to constrain the manner in which the search term is submitted; instead, it expects a complete address to be submitted. The prompt set that should be used for searching with the Verification engine is the Default prompt set which does not apply any restrictions.

Using Verification

There are three ways to use Verification after submitting the search:

No user interaction

The Verification engine may be used with no user interaction required after an initial search has been submitted. This allows an integrator to hide the fact that there is any address management occurring within an application from the user.

This method of using the Verification engine means that addresses that are entered will be simply verified as being correct or not verified as being correct.

If a search results in a VerifyLevel of Verified,VerifiedStreet or VerifiedPlace, then the final formatted address that is returned from the Search call can be used as the captured address. If a search results in any other type of VerifyLevel, then the original address as entered by the user must be used as the captured address.

Minimal user interaction

VerifyLevels

The Verification engine will return one of the following VerifyLevels for a search.

Each level may be treated differently by the integrator depending on the amount of user interaction that is required and indicates the degree of confidence in the returned result.

Intuitive

The Intuitive engine is designed so that the user can enter addresses quickly and easily, using a real-time picklist, fuzzy matching and delimiters such as commas and dashes are handled accurately and transparently.

The Intuitive Search engine has aspects of both the SingleLine and Typedown engines in its operation: the user types the address similarly to how they would use the SingleLine engine and selects the correct address from the Typedown style picklist. 

Wildcards are not supported by this engine. 

The Intuitive search scenario does not require further refinement after the address has been entered as it starts with the most specific address elements. As the user types, the picklist automatically updates with suggestions. The Intuitive Search mode only supports picklists returned in a flattened mode.

Flattened Mode

The following diagram demonstrates the flow of searching using this mode:

The shaded boxes represent user actions; all other boxes are integration actions.

The first search is performed after a minimum of three alphanumeric characters, not including the Premises or Sub-Premises address elements, have been entered.

From this point a search will be carried out with each additional character added to the input line, though a delay may be set so fast typists do not perform many unnecessary searches.

A picklist will be displayed when an address match is found. This can then be selected and sent to be formatted. Alternatively, if an address is not found or the found addresses are not correct, the uncaptured address will be classified and standardised.

Keyfinder

The Keyfinder engine is designed to enable the user to enter a key search term to produce the correct address.

This engine is only available for use with certain data mappings which include datasets that contain a logical reverse search key.

The Keyfinder engine works in a similar way to the SingleLine engine, in that the user enters the key search term and the engine returns the address that matches the search term. If the key search term matches multiple addresses, a drop-down list of addresses is produced, from which the user can select the required one. When the user has entered the key search term, they should start the search manually.

This search scenario normally requires minimal user interaction, as in most cases the key search term only matches one address. However, in some cases it is possible that the key search term matches more than one address, in which case the engine will return a flattened picklist.

Flattened Mode

Picklist results for the Keyfinder engine are always returned in flattened mode:

The shaded boxes represent user actions; all other boxes are integration actions. 

Some special matches will require a refinement step. 

Searches performed using this mode will create a flattened picklist which may have one or more of the following properties:

  • Picklist items can't be refined (except for certain special cases)
  • Picklists will not contain any 'informational' picklist items other than 'No Matches'

Supported countries

Supported countries and territories:

A+ Street or Building coverage for more than 98% of the country A Street, Building or Block coverage for major parts of the country B Locality and Postal Code (where used)

Troubleshooting

Account management 

Forgot my password

  1. Go to Self Service Portal.
  2. Click on the Forgotten your password? link.
  3. Enter your email address and click Submit.

You will then be sent an email with a link to the Password Reset Page. Answer your security questions and you will be able to reset your password.

How do I switch to token authentication?

You don't need to remove your username/password credentials from the code to use token authentication. 

The token will overwrite any other credentials (username/password or SAML header).

 To switch to token authentication:

 1. Retrieve your token from Self Service Portal > Licenses.

     If you don't have one yet, go to Self Service Portal > Licenses, click Add a Token and enter the required details.

  2. Enter your token as the value for "auth-token" field under the HTTP Header. 

Errors

SSL certificate errors

Your SSL certificate might have expired. To manually update your deployment:
  1. Download the update files.
  2. Extract the files.
  3. Install Root.crt in the Trusted Root Certificates Authorities Store.
  4. Install Intermediate1.crt and Intermediate2.crt  in the Intermediate Certificate Authorities Store.
  5. Install api.experianmarketingservices.com.cer in the Personal Certificate Store.

For further help contact support. 

Authentication failed

This error is most likely caused when invalid login or token information is provided. Ensure you're using valid credentials. You can change your password and retrieve the token using the Self Service Portal.

Not licensed

This error can occur:
  • when you're trying to use a dataset that you're not licensed for

To fix this, ensure you're using the datasets you are licensed for: go to Self Service Portal > Licenses.

  • when using an address layout that contains DataPlus you're not licensed for

To fix this, try another layout or contact support for help with creating a new layout.

Searching

DPV functionality locked

The DPV lock occurs when a seed address is returned. A seed address is a non-existent address that will deactivate DPV functionality if it's searched upon. Seed addresses are used to prevent the illegal creation of verified address lists. Please log in to Self Service Portal to unlock DPV functionality. Find out more about DPV.