SOAP actions

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.

Input XML document: QASearch

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

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:

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 Singleline and Typedown engines. This has the following properties:

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:

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:

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 QASearch document.

When searching using the Singlelineengine, and when the Verification engine produces other VerifyLevels, then this structure will not be returned by the SOAP action DoSearch. The properties are as follows:

Structure: AddressLineType

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

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 (Search Point Monikers) 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 (Search Point Monikers) contained within a PicklistType structure, and a refinement string that is not blank.

Input XML Document: QARefine

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

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:

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:

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 (Search Point Monikers) 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.

Input XML Document: QAGetAddress

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

Output XML Document: QAAddressType

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

Structure: AddressLineType

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

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:

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>

This action performs а postcode search and returns a list of different localities' records that the provided postcode covers.

Input XML document: QAPostcodeLookup

The DoPostcodeLookup takes as input County code and Postcode:

Output XML Document: QAPostcodeLookupResult

The DoPostcodeLookup action returns a list with localities records that the input postcode covers.

Structure: QAPostcodeLookupPicklistType

This type defines the result list from the postcode lookup.

Structure: QAPostcodeLookupPicklistEntryType

The individual postcode lookup result record has the following 3 properties:

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

To obtain a list of installed data resources and their respective license status, the SOAP action DoGetLicenseInfo can be used instead. The DoGetLicenseInfo action returns information about all datasets, including DataPlus files.

Input XML Document: None

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

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:

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:

This action is performed to obtain a list of additional datasets, DataPlus sets and other resources that are within a data mapping. This also includes any relevant licensing information such as days until data expiry and data versions for each dataset or DataPlus set.

Input XML Document: DoGetDataMapDetail

The DoGetDataMapDetail action takes a QAGetDataMapDetail document as input. This has the following properties:

Output XML Document: QALicensedSet

The DoGetData action returns a QALicensedSet document which defines all of the additional datasets and DataPlus sets within a data mapping. This has the following properties:

Structure: QALicensedSet

This structure gives licensing information about a specific data file within the data mapping. The properties are as follows:

Element: WarningLevel

List of the warning levels that can be returned.

This action is performed to obtain a list of installed data, and any relevant licensing information such as days until data expiry, and data versions. Unlike the action DoGetData, this will return information about all datasets, including DataPlus files.

This action is designed for the integrator to access information regarding the data files. It is not suitable for display to web users. Pro Web can configured to warn a user automatically when data files are about to expire. If you wish to obtain a list of data mappings that can be searched against, then the action DoGetData should be used instead.

Input XML Document: None

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

Output XML Document: QALicenceInfo

The DoGetLicenceInfo action returns a QALicenceInfo document which defines all of the installed datasets, including DataPlus.

The properties are as follows:

Structure: QALicensedSet

This structure gives licensing information about a specific data file. The properties are as follows:

Element: WarningLevel

List of the warning levels that can be returned.

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

Input XML Document: None

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

Output XML Document: QASystemInfo

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

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.

Input XML Document: QAGetExampleAddresses

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

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:

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:

Structure: QAAddressType

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

Structure: AddressLineType

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

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.

Input XML Document: QAGetLayouts

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

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:

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:

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

When searching with the Verification engine, the Default prompt set should always be used. The reported number of input lines will be set if an input line restriction is specified within the configuration file using the setting InputLineCount. If there is no restriction applies, there is no defined number of input lines and the integrator can create the input fields in any manner.

For all other prompt sets, a prompt set may have a different number of input lines depending upon the data mapping being searched upon. 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

Input XML Document: QAGetPromptSet

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

Output XML Document: QAPromptSet

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

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:

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.

Input XML Document: QACanSearch

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

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:

This action is designed to verify a batch of addresses using the verification engine. A bulk search must be performed against a specific data mapping and will produce an array of bulk search items, each consisting of:

• A verification level
• A formatted final address if the address was verified
• The original input address

Input XML Document: QABulkSearch

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

<qas:BulkSearchTerm>
    <qas:Search>555 Ellis St| Mountain View| CA| 94043</qas:Search>
    <qas:Search>222 Charles St| Cambridge| MA| 01241</qas:Search>
</qas:BulkSearchTerm>

Output XML Document: QABulkSearchResult

The DoBulkSearch action returns a QABulkSearchResult document which defines the result of the verification process. The QABulkSearchResult element will consist of BulkAddress elements one for each address specified in the BulkSearchTerm.

Structure: QABulkSearchItemType

The properties are as follows:

|Attribute| Description|
|VerifyLevel|qas:VerifyLevelType|

This action is performed to obtain the DPV status of the Pro Web server.

Input XML Document: None

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

Output XML document: QADPVStatus

The DoGetDPVStatus action returns a QADPVStatus document which provides the DPV status of the server and any relevant additional information of DPV is locked. The properties are as follows:

Structure: QADPVLockDetailsType

This structure contains information about the search which caused DPV to lock. This is held in the QADPVStatus structure, defined previously. The structure has the following properties:

This action is performed to reactivate DPV after it has been locked following a search on a seed address.

Input XML Document: QAUnlockDPV

The DoUnlockDPV action takes a QAUnlockDPV document as input. It has the following properties:

Output XML Document: QAUnlockDPVOk

The DoUnlockDPV action returns a QADPVUnlockOk document which contains the result of the DPV unlock attempt. The properties are as follows:

The SOAP fault structure is passed back if an error occurs on the server during a transaction. This contains server-specific information concerning the origin of the error, which may be useful to determine the issue.
The properties are as follows: