> For the complete documentation index, see [llms.txt](https://motorweb.gitbook.io/motorweb/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://motorweb.gitbook.io/motorweb/additional-services/driver-check.md).

# Driver Check

Retrieve a driver licence record, including classes, conditions and endorsements.

<mark style="color:green;">`GET`</mark> `https://robot.motorweb.co.nz/action/robotDriverCheck/{version}`

Returns the driver licence record held by NZTA for a given licence number, version and surname. The response includes the licence status, the classes the holder can drive, any conditions, and any endorsements.

### **Environments**

<table><thead><tr><th width="214" align="center">Environment</th><th>Base URL</th></tr></thead><tbody><tr><td align="center">UAT</td><td><code>https://robot.uat.motorweb.co.nz</code></td></tr><tr><td align="center">Production</td><td><code>https://robot.motorweb.co.nz</code></td></tr></tbody></table>

### **Versions**

<table><thead><tr><th width="150" align="center">Version</th><th>Notes</th></tr></thead><tbody><tr><td align="center"><strong>1.1</strong></td><td><strong>Current version.</strong> Adds licence condition codes <code>ZL</code>, <code>AL</code> and <code>M1</code>.</td></tr><tr><td align="center">1.0</td><td>Earlier version, still accepted.</td></tr></tbody></table>

Calling `/action/robotDriverCheck` without a version returns version 1.1.

{% hint style="info" %}
Only `1.0` selects the older response. Any other value, including an unrecognised one, returns 1.1. Send the version you want explicitly.
{% endhint %}

### **Access**

Your account must hold the Driver Check privilege **and** be a billing point. Without both the request returns `400` with `MotorWeb-Error-Code: BAD-ACCOUNT`.

### **Headers**

No request headers are required.

| Result  | Content type |
| ------- | ------------ |
| Success | `text/xml`   |
| Error   | `text/plain` |

### **Body**

```
< no body required >
```

### **Query Parameters**

<table><thead><tr><th width="180">Name</th><th>Value</th></tr></thead><tbody><tr><td><code>licenceNumber</code></td><td><strong>Required.</strong> Field 5a on the physical licence. Exactly 8 characters, two letters followed by six digits, for example <code>AB123456</code>.</td></tr><tr><td><code>licenceVersion</code></td><td><strong>Required.</strong> Field 5b on the physical licence. 3 digits, for example <code>001</code>. Shorter values are left-padded with zeros, so <code>1</code> is treated as <code>001</code>. Version numbers were originally sequential but are now effectively random.</td></tr><tr><td><code>lastName</code></td><td><strong>Required.</strong> The licence holder's surname. Checked against the record.</td></tr><tr><td><code>vehicleId</code></td><td>Optional. Links the transaction to a vehicle already held under your account.</td></tr><tr><td><code>stockNumber</code></td><td>Optional. Links the transaction to a vehicle by your own reference.</td></tr></tbody></table>

### **Response**

{% tabs %}
{% tab title="200" %}

```xml
<driver-check version="1.1" billing-user="MotorWeb Development" id="-448120311" reference="c1e7d904" timestamp="2025-04-02T11:18:03.221" user="MotorWeb Development">
    <nzta-statement>Information supplied by the NZ Transport Agency.</nzta-statement>
    <licence>
        <full-name>JOE AVERAGE PUBLIC</full-name>
        <name>
            <first>JOE</first>
            <middle>AVERAGE</middle>
            <last>PUBLIC</last>
        </name>
        <number>AB123456</number>
        <version>001</version>
        <status code="C">Current</status>
        <classes>
            <class code="1">
                <description>Car/Van</description>
                <start-date value="2005-03-14">14-Mar-2005</start-date>
                <stage code="F">Full</stage>
            </class>
            <class code="6">
                <description>Motorcycle</description>
                <start-date value="2008-11-02">2-Nov-2008</start-date>
                <stage code="F">Full</stage>
            </class>
        </classes>
        <conditions>
            <condition code="B">
                <description>Correcting lenses must be used at all times while driving</description>
            </condition>
        </conditions>
        <endorsements>
            <endorsement code="P">
                <description>Paying passengers</description>
                <start-date value="2019-06-01">1-Jun-2019</start-date>
                <end-date value="2029-06-01">1-Jun-2029</end-date>
                <status code="C">Current</status>
            </endorsement>
        </endorsements>
    </licence>
</driver-check>
```

{% endtab %}

{% tab title="400" %}

```
Invalid Driver Licence details entered
```

or

```
Driver's Licence number does not match name entered
```

{% endtab %}
{% endtabs %}

### **Licence status codes**

<table><thead><tr><th width="120" align="center">Code</th><th>Meaning</th></tr></thead><tbody><tr><td align="center"><code>C</code></td><td>Current</td></tr><tr><td align="center"><code>N</code></td><td>Cancelled, for example the driver has passed away</td></tr><tr><td align="center"><code>D</code></td><td>Disqualified</td></tr><tr><td align="center"><code>E</code></td><td>Expired</td></tr><tr><td align="center"><code>R</code></td><td>Requalify</td></tr><tr><td align="center"><code>S</code></td><td>Suspended, for example a roadside suspension or exceeded demerit points</td></tr><tr><td align="center"><code>V</code></td><td>Voluntarily surrendered</td></tr><tr><td align="center"><code>L</code></td><td>Limited, for example a court has allowed limited driving after disqualification</td></tr><tr><td align="center"><code>X</code></td><td>Revoked, for example for medical reasons</td></tr><tr><td align="center"><code>Y</code></td><td>Surrendered</td></tr><tr><td align="center"><code>Z</code></td><td>Not upgraded, for example the driver has not moved off an old paper licence</td></tr><tr><td align="center"><code>P</code></td><td>Prohibit passengers, for example a paying passenger endorsement is prohibited</td></tr><tr><td align="center"><code>A</code></td><td>Reinstate, for example the driver must re-apply after disqualification</td></tr><tr><td align="center"><code>NAS</code></td><td>No active status. Contact NZTA</td></tr></tbody></table>

### **Licence classes**

<table><thead><tr><th width="120" align="center">Code</th><th>Meaning</th></tr></thead><tbody><tr><td align="center"><code>1</code></td><td>Car/Van</td></tr><tr><td align="center"><code>2</code></td><td>Heavy vehicle</td></tr><tr><td align="center"><code>3</code></td><td>Heavy vehicle</td></tr><tr><td align="center"><code>4</code></td><td>Heavy vehicle</td></tr><tr><td align="center"><code>5</code></td><td>Heavy vehicle</td></tr><tr><td align="center"><code>6</code></td><td>Motorcycle</td></tr></tbody></table>

Each class carries a `stage` element.

<table><thead><tr><th width="120" align="center">Stage</th><th>Meaning</th></tr></thead><tbody><tr><td align="center"><code>L</code></td><td>Learner</td></tr><tr><td align="center"><code>R</code></td><td>Restricted</td></tr><tr><td align="center"><code>F</code></td><td>Full</td></tr></tbody></table>

### **Endorsement codes**

<table><thead><tr><th width="120" align="center">Code</th><th>Meaning</th></tr></thead><tbody><tr><td align="center"><code>D</code></td><td>Dangerous goods</td></tr><tr><td align="center"><code>F</code></td><td>Forklift</td></tr><tr><td align="center"><code>P</code></td><td>Paying passengers</td></tr><tr><td align="center"><code>R</code></td><td>Vehicle on rollers</td></tr><tr><td align="center"><code>T</code></td><td>Vehicle on tracks</td></tr><tr><td align="center"><code>V</code></td><td>Recover vehicles (tow truck operator)</td></tr><tr><td align="center"><code>W</code></td><td>Specialist wheeled vehicle (not forklift)</td></tr><tr><td align="center"><code>I</code></td><td>Driving instructor</td></tr><tr><td align="center"><code>O</code></td><td>Testing officer</td></tr></tbody></table>

### **Condition codes**

<details>

<summary>Expand to see all 39 condition codes</summary>

<table><thead><tr><th width="120" align="center">Code</th><th>Meaning</th></tr></thead><tbody><tr><td align="center"><code>1</code></td><td>Must be accompanied by supervisor (except moped/ATV)</td></tr><tr><td align="center"><code>2</code></td><td>Must display an approved 'L' plate</td></tr><tr><td align="center"><code>3</code></td><td>Must display an approved 'R' plate</td></tr><tr><td align="center"><code>4</code></td><td>No driving between 10pm and 5am</td></tr><tr><td align="center"><code>5</code></td><td>Must not drive at a speed exceeding 70kph</td></tr><tr><td align="center"><code>6</code></td><td>Must not drive a motorcycle with engine capacity > 250cc</td></tr><tr><td align="center"><code>7</code></td><td>Must not carry passengers on motorcycle or sidecar</td></tr><tr><td align="center"><code>8</code></td><td>No carriage of passengers if not accompanied by supervisor</td></tr><tr><td align="center"><code>9</code></td><td>Must not drive between 10pm and 5am without a supervisor</td></tr><tr><td align="center"><code>99</code></td><td>Other</td></tr><tr><td align="center"><code>A</code></td><td>Vehicle to have external rear vision mirror on drivers side</td></tr><tr><td align="center"><code>B</code></td><td>Correcting lenses must be used at all times while driving</td></tr><tr><td align="center"><code>C</code></td><td>Specially adapted or equipped vehicles to be used</td></tr><tr><td align="center"><code>D</code></td><td>A hearing aid must be worn at all times while driving</td></tr><tr><td align="center"><code>E</code></td><td>Artificial limb or limbs to be worn while driving</td></tr><tr><td align="center"><code>F</code></td><td>No night driving</td></tr><tr><td align="center"><code>G</code></td><td>Limited Licence - Court Order must be carried at all times</td></tr><tr><td align="center"><code>H</code></td><td>Only vehicles with hand operated controls to be used</td></tr><tr><td align="center"><code>I</code></td><td>Only vehicle with automatic transmission to be used</td></tr><tr><td align="center"><code>J</code></td><td>Must show medical certificate before licence renewal</td></tr><tr><td align="center"><code>K</code></td><td>Correcting lenses required for this class/endorsement</td></tr><tr><td align="center"><code>L</code></td><td>Distance Restriction</td></tr><tr><td align="center"><code>M</code></td><td>Subject to 3 monthly medical reports</td></tr><tr><td align="center"><code>N</code></td><td>Subject to annual specialist assessment</td></tr><tr><td align="center"><code>O</code></td><td>Must work regular shifts</td></tr><tr><td align="center"><code>P</code></td><td>Must have regular meals</td></tr><tr><td align="center"><code>Q</code></td><td>Driving hours restriction</td></tr><tr><td align="center"><code>R</code></td><td>Vehicle weight restriction</td></tr><tr><td align="center"><code>S</code></td><td>Must drive with an adult Supervisor</td></tr><tr><td align="center"><code>T</code></td><td>Subject to 6 monthly medical reports</td></tr><tr><td align="center"><code>U</code></td><td>Both sides of vehicle require external rear vision mirrors</td></tr><tr><td align="center"><code>V</code></td><td>Subject to Annual Medical Report</td></tr><tr><td align="center"><code>W</code></td><td>Carry and regularly use Glucometer while driving</td></tr><tr><td align="center"><code>X</code></td><td>No alcohol for 12 hours preceding driving</td></tr><tr><td align="center"><code>Y</code></td><td>Not to drive when blood sugar 4.2 or below</td></tr><tr><td align="center"><code>Z</code></td><td>No ambulance driving</td></tr><tr><td align="center"><code>ZL</code></td><td>Subject to Zero Alcohol Level</td></tr><tr><td align="center"><code>AL</code></td><td>Only drive vehicles with alcohol interlock device</td></tr><tr><td align="center"><code>M1</code></td><td>Unfit for Commercial Classes</td></tr></tbody></table>

</details>

### **XSD**

{% embed url="<https://www.motorweb.co.nz/action/robotSchema/driver-check-1.1.xsd>" %}

### **Errors**

Errors return `text/plain` with the message in the body. A `MotorWeb-Error-Code` response header carries a machine-readable code.

{% hint style="info" %}
`CDI-` errors are passed through from the driver licence register. The message text comes from that system, not from MotorWeb, and is prefixed with the raw code, for example `ERROR 59038: ...`. Branch on the `MotorWeb-Error-Code` header rather than on the message text.
{% endhint %}

<table><thead><tr><th width="80">HTTP</th><th width="180">Error code header</th><th>Message and cause</th></tr></thead><tbody><tr><td>400</td><td><code>CDI-59038</code></td><td>The number and version do not identify a licence.</td></tr><tr><td>400</td><td><code>CDI-59034</code></td><td>The surname does not match the record.</td></tr><tr><td>400</td><td><code>BAD-PARAM</code></td><td>A required parameter is missing or malformed.</td></tr><tr><td>400</td><td><code>BAD-ACCOUNT</code></td><td>Your account is missing the Driver Check privilege, or is not a billing point.</td></tr><tr><td>400</td><td><code>EXTERNAL-ISSUE</code></td><td>The driver licence register is unavailable. Check <a href="/motorweb/motorweb-reports/ping.md">Ping</a> and retry.</td></tr><tr><td>401</td><td>—</td><td>Certificate authentication failed.</td></tr></tbody></table>

**Example cURL command:**

```bash
# Production
curl --cert-type P12 --cert motorwebnz.p12:<CERTPASSWORD> \
  "https://robot.motorweb.co.nz/action/robotDriverCheck/1.1?licenceNumber=AB123456&licenceVersion=001&lastName=PUBLIC"

# UAT
curl --cert-type P12 --cert motorwebnz-uat.p12:<CERTPASSWORD> \
  "https://robot.uat.motorweb.co.nz/action/robotDriverCheck/1.1?licenceNumber=AB123456&licenceVersion=001&lastName=PUBLIC"
```

**Notes:**

* Authentication is mutual TLS with a MotorWeb-issued client certificate
* Your account must hold the Driver Check privilege and be a billing point
* Display the `nzta-statement` text alongside any licence data you show
* To confirm identity fields without retrieving the full record, use [Licence Verification](/motorweb/additional-services/licence-verification.md)
* To also verify a date of birth, use [Driver Check Plus](/motorweb/additional-services/driver-check-plus.md)