From 1st March 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.
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 provided.
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.
When will expanded responses be available in greenID?
Expanded responses will only be returned in the API results (sample below) it will not be available in the greenID Admin panel. The changes will be available in Test and Production on the following dates:
Environment | Availability |
|---|---|
Test | 1st February 2023 |
Production | 1st March 2023 |
How the 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 will expanded responses impact my API results?
Expanded responses will be 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 will 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.
Will expanded responses impact verification workflows in greenID?
No, expanded responses will not impact workflows. They will 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 .
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 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 11/01/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.
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
Ensure that stubs mode is disabled (
Make a registerVerification or setFields call (depending on data configuration) for a State Driver’s Licence that you have access to.
Use a valid Driver’s Licences - use genuine details from Driver’s Licence but modify the DOB.
Send the request.
The result should return an expanded response in Extra Data stating that ‘Date of birth does not match.’
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.