Global Data
Browse endpoints
View as Markdown OpenAPI spec

NZ Driver Licence Check

POST /api/v2/nz_driver_licence operationId: nz_driver_licence

Live: https://gdapi.globaldata.net.au/api/v2/nz_driver_licence · Sandbox: https://sandbox-gdapi.globaldata.net.au/api/v2/nz_driver_licence

Verifies an individual's identity against the New Zealand NZTA Driver Licence database.

Input

  • last_name is required.
  • first_name is optional - omit for single-name (mononym) licence holders.
  • middle_name is optional.
  • birth_date must be in YYYY-MM-DD format.
  • licence_number must be a valid NZ driver licence number (2 uppercase letters followed by 6 digits with a valid check digit).
  • licence_version is the 3-digit version number from the front of the licence.
  • consent must be true.

Output

Returns:

  • reporting_reference - unique transaction identifier
  • match_status - "Match" or "NoMatch"
  • document_verified - boolean indicating whether the supplied licence details were verified by NZTA
  • additional_information - only present when the data source returned an explanatory message alongside a NoMatch result

Sandbox environment data

When simulating queries in the sandbox environment, the following record will return a match:

First Name Last Name Date of Birth Licence Number Licence Version
Dana Mitchell 1965-09-13 DB512036 001

Name matching is case insensitive, and licence_number is converted to upper case before it is validated, so db512036 is also accepted. Any other otherwise-valid identity returns a match_status of NoMatch with document_verified set to false.

The following sentinel values simulate the remaining outcomes:

Field Value Sandbox result
licence_number DB111112 200 - a NoMatch result carrying additional_information.
licence_number DB000000 503 - the licence source is unavailable.
licence_version 999 400 - the request was rejected as invalid.

Request body

Content type application/json. NZ Driver Licence verification request.

FieldDescription
first_name string [max 60 characters] or null

First name as it appears on the licence. Omit for single-name (mononym) licence holders.

Example: Dana
middle_name string [max 60 characters] or null

Middle name if present on the licence.

Example:

last_namerequired string [max 60 characters]

Last name as it appears on the licence.

Example: Mitchell
birth_daterequired string (date)

Date of birth in YYYY-MM-DD format.

Example: 1965-09-13
licence_numberrequired string

NZ driver licence number.

Example: DB512036
licence_versionrequired string [max 60 characters]

3-digit version number from the front of the licence.

Example: 001
consentrequired boolean

Must be true. Confirms consent has been obtained.

Example: true

Responses

200

NZ Driver Licence verification result.

application/json
FieldDescription
message string

Example: Ok
function string

Example: nz_driver_licence
api_reference string (uuid)

Example: fe4291ca-d831-4760-96df-c9cb03b3cd95
data object
data.reporting_reference string

Unique transaction identifier.

Example: 8a2439b6-b8a4-450c-9ef0-ca382ceb482e
data.match_status string

Overall match result. Match indicates the supplied identity was fully verified; NoMatch indicates verification failed.

Enum: Match, NoMatch

Example: Match
data.document_verified boolean

Whether NZTA reports the supplied licence details as verified. Defaults to false when the source did not return a verification verdict.

Example: true
data.additional_information string

An explanatory message returned by the data source about the result. Only present when the source supplied one - typically alongside a NoMatch result.

Example: driversLicenceVersion does not match driversLicenceNo
Standard error responses: 400 401 402 403 429 5XX See common error responses
Previous Retrieve a Liveness Check Result Next Payroll Check