| Info |
|---|
From 1st March 10th May 2023, greenID Production will return 'expanded responses' in the API results for DVS data source attempts. Whilst this change should not have a technical impact, we highly recommend you undertake testing to ensure your system is able to receive this new data. More information about testing expanded responses is available here. |
| Info |
Update 7 March 2023 - DVS have advised that Expanded Responses are now available for the Commonwealth Electoral Roll. If a check against the Commonwealth Electoral Roll fails to match, users will now be able to receive one of two responses in addition to the ‘N’ or ‘not matched’ response, advising that either the address is not known or is invalid or that the individual’s name or date of birth did not match against the address providedgreenID Audit Logs, via Admin Panel in addition to API. See here for how to access Audit Logs. |
What are expanded responses?
Expanded responses are a DVS initiative to provide more information about an individual’s document verification outcome. An expanded response is a brief explanation provided by the document issuer, on why the individual's information did not match the document being verified. The purpose of expanded responses is to assist you in making more informed decisions when assessing verification outcomes.
For example, if an individual provides their driver licence for verification but fails to enter their middle name, the match will error and a brief response will be provided:
Document type: Driver Licence
Document field: First Name
DVS Expanded Response: First name does not match
What are the limitations of expanded responses?
There are some limitations to the data provided in the expanded response, these include:
Not all document issuers are providing expanded responses. See details here.
Only one expanded response will be returned per document. This means if there are several matching errors only one will be explained. See details here.
Expanded responses are returned as a free text field, controlled by the document issuers, and may change without notice.
There is no unique code associated with each response.
Note that DVS are still in the process of reviewing the responses they get back from their various document issuers.
Do I have to do anything?
No, you can choose not to take any action if you do not wish to use the expanded response information.
We recommend that you test your systems can receive the new data without impact.Where will Expanded Responses be available in greenID?
Expanded responses will be returned:
In the API results (sample below)
In Audit Logs via greenID Admin Panel (see below)
When will expanded responses be available in greenID?
Expanded responses will only be are returned in the API results (sample below) it now.
Expanded responses will not be available in the greenID Admin panel. The changes will be available in Test and Production Admin Panel Audit Logs on the following dates:
Environment | Availability |
|---|---|
Test | 1st February 28th April 2023 |
Production | 1st March 2023 |
10th May 2023 |
How do I get to Expanded Responses in the Audit Logs?
The Audit Logs are accessed via the greenID Admin Panel, by clicking the ‘Audit Logs’ button from the ‘Verification Results’ screen:
What will expanded responses look like in the Audit Logs?
The Expanded Responses will be displayed in a new Audit Log entry, which will appear following the existing entry that shows the DVS data source result. These will be available for both interactive data source checks and background data source checks. The entry will include which data source the Expanded Response is for, the verification request number for the check, and the ‘expanded response’ message returned by the DVS for the check.
If the DVS do not return an Expanded Response for a data source check, then there will be no Expanded Response audit log entry displayed for that check.
The below is an example of the Expanded Response audit log entry for an interactive source check for the ACT Driver’s Licence:
How do expanded responses appear in my API results?
Below are samples where an expanded response result has been sent in the extra data section.
Method | Source | Response |
|---|---|---|
setFields | Visa |  |
setFields | Marriage Certificate |  |
setFields | Birth Certificate |  |
registerVerification | NSW DL |  |
registerVerification | ACT DL |  |
registerVerification | ACT DL |  |
registerVerification | Passport |  |
How
willdo expanded responses impact my API results?
Expanded responses will be are sent in the ‘Extra Data’ section of the API results and therefore should not impact a your integration with greenID. You can review and make changes to your workflow (as necessary) to utilise expanded responses in your business process.
Should I test expanded responses in API prior to the Production release?Yes, while we are utilising existing fields in the API response, you should check that your system is able to receive the new data without impact.
Which versions of the API
willreturn Expanded Responses
be returned in?
Expanded Response will be returned in version 2 onwards. Version 1 of the greenID API does not support this feature.
WillDo expanded responses impact verification workflows in greenID?
No, expanded responses will do not impact workflows. They will are only be returned as extra data or additional information associated with a DVS data source outcome.
Will there be changes in other interfaces for expanded responses (eg. admin panel)?
No, the expanded responses will only be available in the API results.
What are the expanded response messages?
For a full list of messages please see below.
IMPORTANT: This is a DVS list, is not definitive and may change without notice. We will update this as DVS advise.
Last update from DVS .
| View file | ||
|---|---|---|
|
What message is returned in the event of a MAPS lockout?
We are seeing the response Document Temporarily Locked for MAPS lockouts.
How many responses are returned?
DVS will return only one response per document to provide guidance without providing a level of information that could assist fraud. Multiple attempts of a document validation will be prevented by the MAPS functionality.
This means that if multiple fields provided do not match fields held by the document issuer, only one of the un-matched fields will be flagged by expanded response.
e.g:
Field | Data provided | Data held | Result | Expanded response |
|---|---|---|---|---|
Given Name | Bob | Robert | No match | Not provided |
Family Name | Jones | Jones | Match | Not expected |
DOB | 12/07/1988 | 15/08/1988 | No match | “Date of birth does not match” |
Licence Number | 1234567890 | 1234567890 | Match | Not expected |
Card Number | D85945 | T54869 | No match | Not provided |
There is no specified field order in which the messages will be returned.
Does this mean I won’t have to contact DVS to explain why my document has failed?
In some cases it could should help narrow down the reason why a document has failed, however there will be cases where DVS can provide more details.
Which DVS document issuers are returning expanded responses?
The below table shows which documents provide expanded responses. Last update from DVS 1107/0103/2023.
IMPORTANT: This is a DVS list, may not be definitive and may change without notice, we will update as changes are advised by DVS.
Document issuer | Document type | Provides expanded responses? |
|---|---|---|
ACT BDM | Birth, Marriage, Change of Name and Death Certificates | Yes |
NT BDM | Birth, Marriage, Change of Name and Death Certificates | Yes |
QLD BDM | Birth, Marriage, Change of Name and Death Certificates | Yes |
SA BDM | Birth, Marriage, Change of Name and Death Certificates | Yes |
TAS BDM | Birth, Marriage, Change of Name and Death Certificates | Yes |
VIC BDM | Birth, Marriage, Change of Name and Death Certificates | Yes |
WA BDM | Birth, Marriage, Change of Name and Death Certificates | Yes |
NEVDIS | Driver Licences | Yes |
DFAT | Passport | Yes |
Department of Home Affairs | Citizenship Certificates, Registration by Descent, ImmiCards, Visas | Yes |
Australian Electoral Commission | Commonwealth Electoral Roll | Yes |
Medicare | Medicare Card | No |
Centrelink | Centrelink Concession Cards | No |
How can I use expanded responses?
The purpose of expanded responses is to provide greater insight into why the data provided did not match the data held by the document issuer. The data could be used to assist with assessment of failed identity verifications. Note the limitations of expanded responses here.
| Panel | ||||||
|---|---|---|---|---|---|---|
| ||||||
How should I test my system can receive Expanded Responses?Testing Guidelines Use one of the document types enabled for expanded responses. Refer to the list here. Supply the document details with one or two fields incorrectly entered. Ensure that the fields incorrectly entered have associated Expanded Responses, you can check this here. Expanded response data will return in the Extra Data section of the API response. Testing Steps
Note: Disabling stubs mode does incur a live call and associated charge to check DVS. |
Glossary
Document Issuer - The government body who issues the document, e.g. the Australian Passport Office issues passports, the various state and territory Roads Authorities issue Driver Licences.
DVS - Document Verification Service, the government agency who centralises and manages the connection to the various document issuers for the purpose of identity verification.
| Table of Contents | ||||
|---|---|---|---|---|
|