# NZ Driver Licence Check

`POST /nz_driver_licence`

- Live: `POST https://gdapi.globaldata.net.au/api/v2/nz_driver_licence`
- Sandbox: `POST 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

NZ Driver Licence verification request.

| Field | Type | Description |
|-------|------|-------------|
| `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_name` | string [max 60 characters] | **Required.** Last name as it appears on the licence. Example: `Mitchell` |
| `birth_date` | string (date) | **Required.** Date of birth in YYYY-MM-DD format. Example: `1965-09-13` |
| `licence_number` | string | **Required.** NZ driver licence number. Example: `DB512036` |
| `licence_version` | string [max 60 characters] | **Required.** 3-digit version number from the front of the licence. Example: `001` |
| `consent` | boolean | **Required.** Must be true. Confirms consent has been obtained. Example: `true` |

**Sample request**

```json
{
    "first_name": "Dana",
    "middle_name": "",
    "last_name": "Mitchell",
    "birth_date": "1965-09-13",
    "licence_number": "DB512036",
    "licence_version": "001",
    "consent": true
}
```

## Responses

### 200 NZ Driver Licence verification result.

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `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` |

**Sample response**

```json
{
    "message": "Ok",
    "function": "nz_driver_licence",
    "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "data": {
        "reporting_reference": "8a2439b6-b8a4-450c-9ef0-ca382ceb482e",
        "match_status": "Match",
        "document_verified": true,
        "additional_information": "driversLicenceVersion does not match driversLicenceNo"
    }
}
```

Standard error responses: 400, 401, 402, 403, 429, 5XX (see [Common error responses](/docs/reference/general/common-error-responses.md))