# Validate a drivers licence

`POST /dvs/drivers_licence`

- Live: `POST https://gdapi.globaldata.net.au/api/v2/dvs/drivers_licence`
- Sandbox: `POST https://sandbox-gdapi.globaldata.net.au/api/v2/dvs/drivers_licence`

Validates a drivers licence number against the Australian Document Verification Service (DVS).

**N.B.** Middle names will not be checked if not supplied so it is optional to supply it.

Victorian driver licences sometimes only print an initial for the middle name.
However the full first middle name will be on record and must be entered if the middle name is supplied.

For this reason, DVS advise not to send the middle name for a licence check.
This will work for all states and territories.

If a middle name is supplied then it will be checked.
An initial entered for the middle name will likely result in a failed matched.

## Sandbox environment

When simulating queries in the sandbox environment, a specific set of drivers licence numbers will return a
specific result. The response will be determined by the drivers licence number:

[DVS sandbox responses for this document](/docs/guides/dvs/sandbox-responses#dvs-drivers-licence)

## Request body

The licence details to validate

| Field | Type | Description |
|-------|------|-------------|
| `preflight` | boolean | When set to true, the request will only perform a preflight check to validate the input parameters. No actual verification will be performed. Example: `false` |
| `consent` | boolean | The individual's consent to perform the check Example: `true` |
| `first_name` | string | The first name of the licence holder Example: `John` |
| `middle_name` | string or null | The middle name of the licence holder. This field is optional and can be left blank. It will not be checked if not supplied. However, if supplied, it will be checked. Example: `James` |
| `last_name` | string | The last name of the licence holder Example: `Smith` |
| `birth_date` | string (date) | The date of birth of the licence holder Example: `1980-01-01` |
| `licence_number` | string | The drivers licence number to be validated Example: `1234567890` |
| `card_number` | string | The card number of the licence to be validated Example: `P0001282` |
| `state` | string | The state of issue for the drivers licence Enum: `NSW`, `VIC`, `QLD`, `SA`, `WA`, `TAS`, `NT`, `ACT` Example: `VIC` |

**Sample request**

```json
{
    "preflight": false,
    "consent": true,
    "first_name": "John",
    "middle_name": "James",
    "last_name": "Smith",
    "birth_date": "1980-01-01",
    "licence_number": "1234567890",
    "card_number": "P0001282",
    "state": "VIC"
}
```

## Responses

### 200 Result of licence validation

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | A message indicating the result of the request. This will be `Ok` if the request was successful. Example: `Ok` |
| `function` | string | The function that was called Example: `dvs_drivers_licence` |
| `api_reference` | string (uuid) | A unique identifier for this request. This can be used to track the request in the logs. Example: `fe4291ca-d831-4760-96df-c9cb03b3cd95` |
| `data` | object | The check data |
| `data.response_type` | string | The type of response Example: `DriverLicenceResponse` |
| `data.activity_id` | string | A reference ID for this activity. This ID can be used to track the activity in the logs. Example: `sandbox-d06ed58a-b279-4f50-9b6e-5a0a26b4e87d` |
| `data.verification_request_number` | string | A unique reference number for this request Example: `dec306ed-7cff-41c0-b02f-889e430f5309` |
| `data.verification_result_code` | string | The result of the verification * `Y` - The licence is valid * `N` - The licence is invalid * `D` - The licence is unknown * `S` - An error occurred during the check Enum: `Y`, `N`, `S`, `D` Example: `N` |
| `data.additional_information` | array of objects | An array of expanded responses returned from the DVSHub or Document Issuer for N or D results |
| `data.additional_information[].message` | string | A message indicating the reason for the N or D result. Example: `Document invalid.` |
| `data.additional_information[].code` | string | A code number associated with the corresponding message. Example: `DL-001` |

**Sample response**

```json
{
    "message": "Ok",
    "function": "dvs_drivers_licence",
    "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "data": {
        "response_type": "DriverLicenceResponse",
        "activity_id": "sandbox-d06ed58a-b279-4f50-9b6e-5a0a26b4e87d",
        "verification_request_number": "dec306ed-7cff-41c0-b02f-889e430f5309",
        "verification_result_code": "N",
        "additional_information": [
            {
                "message": "Document invalid.",
                "code": "DL-001"
            }
        ]
    }
}
```

### 202 A successful preflight check. A 400 will be returned if the preflight check fails.

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | A message indicating the result of the request. This will be `Ok` if the request was successful. Example: `Ok` |
| `function` | string | The function that was called Example: `dvs_aec` |
| `api_reference` | string (uuid) | A unique identifier for this request. This can be used to track the request in the logs. Example: `fe4291ca-d831-4760-96df-c9cb03b3cd95` |
| `data` | null | For preflight checks this is null |

**Sample response**

```json
{
    "message": "Ok",
    "function": "dvs_aec",
    "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "data": null
}
```

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