> 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/motorweb-reports/vir.md).

# VIR (Vehicle Information Report)

The full MotorWeb report. Vehicle, owners, history, securities and valuation.

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

The Vehicle Information Report™ is the most complete report MotorWeb produces. It returns registration and licensing data, WOF and COF status, RUC, full vehicle specifications, plate history, odometer history, owner details, PPSR security interests, a MotorWeb valuation and listing history.

{% hint style="info" %}
For any transaction generated more than **30 days ago**, private owner and personally identifiable information is suppressed to meet our privacy obligations. Regenerate the report to see current owner information.
{% endhint %}

### **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>

{% hint style="warning" %}
VIR is served from `/action/robotVir/` only. There is no `/b2b/` path for this report.
{% endhint %}

### **Versions**

<table><thead><tr><th width="170" align="center">Version</th><th>Notes</th></tr></thead><tbody><tr><td align="center"><strong>4.0</strong></td><td><strong>Current version.</strong> Adds <code>listing-history</code> and a RedBook-style <code>valuation</code> block inside <code>motorwebValuationResult</code>.</td></tr><tr><td align="center">3.1</td><td>Adds <code>sub-model-spec</code>.</td></tr><tr><td align="center">3.0</td><td>Adds <code>motorwebValuationResult</code> and <code>numberValuationResults</code>.</td></tr><tr><td align="center">2.9 and earlier</td><td>Legacy versions, still accepted: 2.9, 2.8, 2.7, 2.6, 2.5, 2.0 and 1.0. See below.</td></tr></tbody></table>

Each version has its own schema, `vir-{version}.xsd`. Send `4.0` unless you have a reason to pin an older version.

<details>

<summary>Legacy versions and what changed in each</summary>

<table><thead><tr><th width="170" align="center">Version</th><th>Notes</th></tr></thead><tbody><tr><td align="center">2.9</td><td>Adds <code>mvr-model</code>, and <code>year</code>, <code>make</code>, <code>family</code>, <code>description</code> to <code>redbook-ref</code>.</td></tr><tr><td align="center">2.8</td><td>Replaces <code>confirmed-owner-description</code> with <code>confirmed-owner</code>. Adds <code>redbook-codes</code>.</td></tr><tr><td align="center">2.7</td><td>Adds <code>owner/address-parts</code>, <code>owner/owner-name-parts</code> and <code>owner/@suppressed-reason</code>.</td></tr><tr><td align="center">2.6</td><td>Moves alert types into a shared schema. Removes <code>imported-damaged</code>, <code>reliable-odometer</code> and <code>reported-stolen</code>.</td></tr><tr><td align="center">2.5</td><td>Adds PPSR security interests, safety data and detailed specifications.</td></tr><tr><td align="center">2.0</td><td>Adds the fuel economy label.</td></tr><tr><td align="center">1.0</td><td>Original release. Different root structure.</td></tr></tbody></table>

</details>

### **Access**

Your account must hold the VIR privilege. Without it the request returns `400` with `MotorWeb-Error-Code: BAD-ACCOUNT` and the message `You are not permitted to perform a VIR`.

### **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>plateOrVin</code></td><td>A registration plate (6 characters or fewer) or a VIN (exactly 17 characters). Required unless you supply <code>vehicleId</code> or <code>stockNumber</code>.</td></tr><tr><td><code>vehicleId</code></td><td>The ID of a vehicle already held under your account. A new report is generated against that vehicle.</td></tr><tr><td><code>stockNumber</code></td><td>Your own reference for a vehicle already held under your account. Also accepted alongside <code>plateOrVin</code> to tag the new vehicle.</td></tr><tr><td><code>specificReason</code></td><td>Why private owner information is required, under section 241 of the Land Transport Act. Mandatory on most accounts.</td></tr><tr><td><code>datapack</code></td><td>Optional. Repeatable. Set to <code>listing-history</code> to include Trade Me listing history in the response. Unrecognised values are silently discarded, with no error.</td></tr></tbody></table>

{% hint style="warning" %}
VIR reads `plateOrVin` only. It does **not** accept separate `plate` or `vin` parameters, even though some other endpoints do.
{% endhint %}

### **Response**

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

```xml
<vir vehicle-id="-285694250" billing-user="MotorWeb Development" id="-285694711" reference="38c45f6d" timestamp="2024-10-16T09:27:44.295" user="MotorWeb Development">
    <vir-analysis version="4.0">
        <vehicle>
            <registration>
                <first-registration-date-in-new-zealand value="2011-04-05">5-Apr-2011</first-registration-date-in-new-zealand>
                <registration-status code="A">Active</registration-status>
                <cause-of-last-registration code="N">New</cause-of-last-registration>
                <registered-overseas value="false">No</registered-overseas>
                <last-registration-date value="2011-04-05">5-Apr-2011</last-registration-date>
            </registration>
            <licence>
                <expiry-date value="2025-01-04">4-Jan-2025</expiry-date>
                <licence-type code="L">Licence</licence-type>
                <issue-date value="2023-12-30">30-Dec-2023</issue-date>
                <issue-time value="22:27:00+13:00">22:27</issue-time>
                <continuous value="true">Yes</continuous>
            </licence>
            <wof>
                <last-inspection-date value="2024-02-29">29-Feb-2024</last-inspection-date>
                <last-inspection-result code="P">Passed</last-inspection-result>
                <expiry-date value="2025-02-28">28-Feb-2025</expiry-date>
                <is-subject-to value="true">Yes</is-subject-to>
            </wof>
            <cof>
                <is-subject-to value="false">No</is-subject-to>
            </cof>
            <ruc data-retrieved="false">
                <is-subject-to value="false">No</is-subject-to>
            </ruc>
            <year-of-manufacture value="2011">2011</year-of-manufacture>
            <make>Mitsubishi</make>
            <model>ASX 2WD 2.0P CVT Sport</model>
            <mvr-model>ASX</mvr-model>
            <body-style code="SW">Wagon</body-style>
            <vehicle-type code="7">Passenger Car/Van</vehicle-type>
            <vin>JMFXTGA2WBZ004048</vin>
            <engine-number>4B11 HH3609</engine-number>
            <main-colour>BLACK</main-colour>
            <cc-rating unit="cc" value="1998">1,998</cc-rating>
            <power unit="KW" value="112">112</power>
            <country-of-origin code="JPN">Japan</country-of-origin>
            <assembly-type code="1">Imported Built-Up</assembly-type>
            <gross-vehicle-mass unit="Kg" value="1970">1,970</gross-vehicle-mass>
            <number-of-seats value="5">5</number-of-seats>
            <fuel-type code="1">Petrol</fuel-type>
            <max-rated-towed-mass-for-unbraked-trailer unit="Kg" value="750">750</max-rated-towed-mass-for-unbraked-trailer>
            <max-rated-towed-mass-for-braked-trailer unit="Kg" value="1050">1,050</max-rated-towed-mass-for-braked-trailer>
            <wheelbase unit="mm" value="2670">2,670</wheelbase>
            <vehicle-usage code="1">Private Passenger</vehicle-usage>
            <odometer-unit code="K">Km</odometer-unit>
            <plate current="true" past-plate="0">
                <plate-number>888MIL</plate-number>
                <plate-type code="PP">Personalised</plate-type>
                <effective-date value="2011-04-06">6-Apr-2011</effective-date>
            </plate>
            <plate past-plate="1">
                <plate-number>ABC123</plate-number>
                <effective-date value="2011-04-05">5-Apr-2011</effective-date>
            </plate>
            <odometer-reading latest="true">
                <reading value="61824">61,824</reading>
                <reading-date value="2024-02-29">29-Feb-2024</reading-date>
                <reading-unit code="K">Km</reading-unit>
                <source code="IW">Warrant of Fitness Inspection</source>
            </odometer-reading>
            <odometer-reading latest="false">
                <reading value="59882">59,882</reading>
                <reading-date value="2023-02-28">28-Feb-2023</reading-date>
                <reading-unit code="K">Km</reading-unit>
                <source code="IW">Warrant of Fitness Inspection</source>
            </odometer-reading>
            <number-of-owners value="1">1</number-of-owners>
            <owner current="true" owner-number="1">
                <sex-company code="F">Female</sex-company>
                <owner-name>FullName</owner-name>
                <owner-name-parts>
                    <first-name>FirstName</first-name>
                    <middle-names>MiddleName</middle-names>
                    <last-name>LastName</last-name>
                </owner-name-parts>
                <address label="Street address" usage="physical">
                    <line-1>1 TEST RISE</line-1>
                    <line-2>RD 4</line-2>
                    <suburb>DAIRY FLAT</suburb>
                    <town>ALBANY</town>
                    <postcode>0794</postcode>
                </address>
                <address-parts usage="physical">
                    <street-number>1</street-number>
                    <street-name>TEST RISE</street-name>
                    <rd-number>4</rd-number>
                    <suburb>DAIRY FLAT</suburb>
                    <town>ALBANY</town>
                    <post-code>0794</post-code>
                </address-parts>
                <ownership-date value="2011-04-05">5-Apr-2011</ownership-date>
                <owner-status code="C">Complete</owner-status>
                <ownership-length days="4943">14 years</ownership-length>
            </owner>
            <transmission>
                <type code="C" has-gears="false">CVT</type>
                <speeds copy-to="transmission" value="6">6</speeds>
            </transmission>
            <model-code>BE4SP45;</model-code>
            <model-variant>0</model-variant>
            <sub-model-spec>2.0P/CVT/SV/5S</sub-model-spec>
            <fuel-economy>
                <star-rating max-stars="6" value="2">2</star-rating>
                <consumption unit="litres/100Km" value="8.8">8.8</consumption>
            </fuel-economy>
            <emissions>
                <co2>
                    <star-rating max-stars="6" value="2">2</star-rating>
                    <quantity unit="g/Km" value="212">212</quantity>
                </co2>
                <pollutants>
                    <star-rating max-stars="6" value="3">3</star-rating>
                    <test-regime>A79/02</test-regime>
                </pollutants>
            </emissions>
            <safety>
                <driver>
                    <star-rating max-stars="5" value="4">4</star-rating>
                    <test-regime>Based on 2023 UCSR rating for 16-19 models</test-regime>
                </driver>
                <abs value="true">Yes</abs>
                <airbags>
                    <value>1st Row Side</value>
                    <value>Driver Knee</value>
                    <value>Front Passenger</value>
                    <value>2nd Row Head</value>
                    <value>1st Row Head</value>
                    <value>Driver</value>
                </airbags>
                <traction-control value="true">Yes</traction-control>
                <brake-assist value="true">Yes</brake-assist>
                <electronic-brake-force-distribution value="true">Yes</electronic-brake-force-distribution>
            </safety>
            <security>
                <factory-alarm value="true">Yes</factory-alarm>
                <central-locking value="true">Yes</central-locking>
                <engine-immobiliser value="true">Yes</engine-immobiliser>
            </security>
            <number-of-doors value="5">5</number-of-doors>
            <number-of-cylinders value="4">4</number-of-cylinders>
            <engine-configuration>In-line</engine-configuration>
            <fuel-delivery>Multi-Point Injected</fuel-delivery>
            <cam-description>DOHC with VVT &#x26; Lift</cam-description>
            <induction>Aspirated</induction>
            <torque unit="Nm" value="200">200</torque>
            <engine-location>Front</engine-location>
            <fuel-capacity unit="litres" value="63">63</fuel-capacity>
            <height unit="mm" value="1615">1,615</height>
            <length unit="mm" value="4295">4,295</length>
            <width unit="mm" value="1770">1,770</width>
            <front-tyre-size>215/65 R16</front-tyre-size>
            <rear-tyre-size>215/65 R16</rear-tyre-size>
        </vehicle>
        <security-interests>
            <number-of-security-interests>0</number-of-security-interests>
        </security-interests>
    </vir-analysis>
    <motorwebValuationResult>
        <mwvaluation>
            <status>OK</status>
            <averagePrice>11000</averagePrice>
            <averagePriceDisp>$11,000</averagePriceDisp>
            <highPrice>12000</highPrice>
            <highPriceDisp>$12,000</highPriceDisp>
            <lowPrice>9850</lowPrice>
            <lowPriceDisp>$9,850</lowPriceDisp>
            <rrpPriceDisp>Not Recorded</rrpPriceDisp>
        </mwvaluation>
    </motorwebValuationResult>
    <numberValuationResults value="1">1</numberValuationResults>
    <listing-history/>
</vir>
```

{% endtab %}

{% tab title="200 With a security interest" %}

```xml
<vir vehicle-id="-285694250" billing-user="MotorWeb Development" id="-285694711" reference="9f1c3b70" timestamp="2024-10-16T09:27:44.295" user="MotorWeb Development">
    <vir-analysis version="4.0">
        <vehicle>
            <!-- vehicle elements as above -->
        </vehicle>
        <security-interests>
            <finance_statement fs_no="1A2B3C4D" version="1" version_date="12-Mar-2023" current="true">
                <fs_details>
                    <status>Registered</status>
                    <registered_date value="2023-03-12T09:15:00">12-Mar-2023</registered_date>
                    <expiry_date value="2028-03-12T23:59:59">12-Mar-2028</expiry_date>
                </fs_details>
                <secured_party_details>
                    <secured_party sp_group="1">
                        <address_details>
                            <address type="physical">
                                <line1>1 Example Street</line1>
                                <city_town>Auckland</city_town>
                                <postcode>1010</postcode>
                                <country_code>NZ</country_code>
                            </address>
                        </address_details>
                        <sp_organisation name="EXAMPLE FINANCE LIMITED"/>
                    </secured_party>
                </secured_party_details>
                <debtors_details>
                    <debtor type="person">
                        <address_details>
                            <address type="physical">
                                <line1>37 Public Road</line1>
                                <city_town>Auckland</city_town>
                                <postcode>0630</postcode>
                            </address>
                        </address_details>
                        <db_person>
                            <first_name>JOE</first_name>
                            <last_name>PUBLIC</last_name>
                        </db_person>
                    </debtor>
                </debtors_details>
                <collateral_details>
                    <collateral type="MV" type_description="Motor Vehicle">
                        <co_item>
                            <coi_description>2011 MITSUBISHI ASX</coi_description>
                            <make>MITSUBISHI</make>
                            <model>ASX</model>
                            <year>2011</year>
                            <vin>JMFXTGA2WBZ004048</vin>
                            <registration_number>888MIL</registration_number>
                        </co_item>
                    </collateral>
                </collateral_details>
            </finance_statement>
            <number-of-security-interests>1</number-of-security-interests>
        </security-interests>
    </vir-analysis>
</vir>
```

{% endtab %}

{% tab title="400" %}

```
plateOrVin search parameter not specified
```

or

```
plateOrVin does not look like a plate or VIN
```

or

```
specificReason not specified
```

{% endtab %}
{% endtabs %}

### **Fields worth noting**

<table><thead><tr><th width="260">Element</th><th>Description</th></tr></thead><tbody><tr><td><code>vir/@reference</code></td><td>The transaction reference. Use it to retrieve the report later and when contacting support.</td></tr><tr><td><code>security-interests</code></td><td>Present only when securities were checked. Read <code>number-of-security-interests</code> to decide whether the vehicle is clear.</td></tr><tr><td><code>owner/@suppressed-reason</code></td><td>Present when NZTA suppressed owner details. When present, <code>owner-name</code>, <code>sex-company</code>, <code>address</code>, <code>address-parts</code> and related elements are not returned. Values: <code>NotAuthorised</code>, <code>UnregisteredVehicle</code>, <code>OptedOut</code>, <code>PastIndividual</code>.</td></tr><tr><td><code>plate</code></td><td>Repeats. <code>@current="true"</code> marks the current plate; <code>@past-plate</code> counts back through history.</td></tr><tr><td><code>odometer-reading</code></td><td>Repeats. <code>@latest="true"</code> marks the most recent reading.</td></tr><tr><td><code>alert</code></td><td>Can appear at many points in the tree. See <a href="/motorweb/motorweb-reports/alerts.md">Alerts</a>.</td></tr></tbody></table>

### **XSD**

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

The schema documents every coded field, including registration status, cause of last registration, body style, vehicle type, fuel type, axle type, vehicle usage, plate type, owner status and country of origin.

### **Errors**

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

<table><thead><tr><th width="80">HTTP</th><th width="170">Error code header</th><th>Message and cause</th></tr></thead><tbody><tr><td>400</td><td><code>BAD-PARAM</code></td><td><code>plateOrVin search parameter not specified</code> — supply a vehicle identifier.</td></tr><tr><td>400</td><td><code>BAD-PARAM</code></td><td><code>plateOrVin does not look like a plate or VIN</code> — a plate is 6 characters or fewer, a VIN is exactly 17.</td></tr><tr><td>400</td><td><code>BAD-PARAM</code></td><td><code>specificReason not specified</code> — your account requires a section 241 reason.</td></tr><tr><td>400</td><td><code>BAD-PARAM</code></td><td><code>vehicleId not a number: {value}</code></td></tr><tr><td>400</td><td><code>NOT-FOUND</code></td><td><code>Vehicle not found for vehicle ID: {id}</code></td></tr><tr><td>400</td><td><code>BAD-ACCOUNT</code></td><td><code>You are not permitted to perform a VIR</code> — contact your account manager.</td></tr><tr><td>400</td><td><code>MC-21</code></td><td>Invalid plate number or VIN, returned by NZTA.</td></tr><tr><td>400</td><td><code>MC-22</code></td><td>No vehicle found matching plate or VIN.</td></tr><tr><td>400</td><td><code>MC-23</code></td><td>Confidential owner.</td></tr><tr><td>400</td><td><code>EXTERNAL-ISSUE</code></td><td>NZTA or PPSR 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, by plate or VIN
curl --cert-type P12 --cert motorwebnz.p12:<CERTPASSWORD> \
  "https://robot.motorweb.co.nz/action/robotVir/4.0?plateOrVin=ABC123&specificReason=state+your+specific+reason"

# UAT
curl --cert-type P12 --cert motorwebnz-uat.p12:<CERTPASSWORD> \
  "https://robot.uat.motorweb.co.nz/action/robotVir/4.0?plateOrVin=ABC123&specificReason=state+your+specific+reason"

# With listing history
curl --cert-type P12 --cert motorwebnz.p12:<CERTPASSWORD> \
  "https://robot.motorweb.co.nz/action/robotVir/4.0?plateOrVin=ABC123&specificReason=state+your+specific+reason&datapack=listing-history"

# Against an existing vehicle
curl --cert-type P12 --cert motorwebnz.p12:<CERTPASSWORD> \
  "https://robot.motorweb.co.nz/action/robotVir/4.0?vehicleId=-285694250&specificReason=state+your+specific+reason"
```

**Notes:**

* Authentication is mutual TLS with a MotorWeb-issued client certificate
* Your account must hold the VIR privilege
* Supply exactly one vehicle identifier. Sending both `vehicleId` and `plateOrVin` is rejected
* New alerts can be added without a version change. Handle any alert code you receive
* Use the `reference` from the response with [Retrieve Existing Report](/motorweb/motorweb-reports/retrieve-existing-report.md) to fetch the same report again as XML, HTML or PDF at no extra charge