> 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/retrieve-existing-report.md).

# Retrieve Existing Report

Fetch a report you already generated, as XML, HTML or PDF.

Retrieve a vehicle report you have already generated, either through this API or through the MotorWeb web interface. Three formats are available.

Retrieving a report does not generate a new one and is not charged as a new transaction.

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

### **Formats**

<table><thead><tr><th width="120">Format</th><th width="300">Path</th><th width="120" align="center">Version</th><th>Content type</th></tr></thead><tbody><tr><td>XML</td><td><code>/action/robotLoadXml/{version}</code></td><td align="center">4.0</td><td><code>text/xml</code></td></tr><tr><td>HTML</td><td><code>/action/robotVirHtml/{version}</code></td><td align="center">2.0</td><td><code>text/html</code></td></tr><tr><td>PDF</td><td><code>/action/robotVirPdf/{version}</code></td><td align="center">2.0</td><td><code>application/pdf</code></td></tr></tbody></table>

`/action/robotLoadVir/{version}` is a legacy alias for the XML endpoint. It behaves identically.

### **Versions**

The XML endpoint accepts the same versions as [VIR](/motorweb/motorweb-reports/vir.md).

<table><thead><tr><th width="150" align="center">Version</th><th>Notes</th></tr></thead><tbody><tr><td align="center"><strong>4.0</strong></td><td><strong>Current version.</strong></td></tr><tr><td align="center">1.0, 2.0, 2.5, 2.6, 2.7, 2.8, 2.9, 3.0, 3.1</td><td>Earlier versions, still accepted.</td></tr></tbody></table>

{% hint style="warning" %}
These ten values are the complete list. It is **not** a range. Values such as `1.5`, `2.1` and `3.5` do not exist and are rejected.
{% endhint %}

{% hint style="info" %}
The version you request controls the shape of the response, not the data. Retrieving a report at 2.9 returns the same transaction rendered against the 2.9 schema.
{% endhint %}

### **Access**

No specific privilege is required. You can only retrieve reports on vehicles held under your own account, with one exception: lookup by `reference` loads a specific report belonging to **any** account.

### **Headers**

No request headers are required.

### **Body**

```
< no body required >
```

### **Query Parameters**

Supply exactly one identifier.

<table><thead><tr><th width="180">Name</th><th>Value</th></tr></thead><tbody><tr><td><code>reference</code></td><td>The 8-character reference from the original response. Loads that specific report. Unlike the other identifiers, this works across accounts and returns the report as it was, not the latest one on the vehicle.</td></tr><tr><td><code>vehicleId</code></td><td>Returns the latest report against the vehicle with this ID.</td></tr><tr><td><code>stockNumber</code></td><td>Returns the latest report against the vehicle with this stock number. If more than one vehicle shares a stock number, the most recently transacted vehicle is used.</td></tr><tr><td><code>plateOrVin</code></td><td>Returns the latest report matching that plate or VIN. This searches plates and VINs recorded <em>inside</em> reports, not only the value used to generate them.</td></tr><tr><td><code>plate</code></td><td>As above, restricted to a plate.</td></tr><tr><td><code>vin</code></td><td>As above, restricted to a VIN.</td></tr><tr><td><code>transactionType</code></td><td>Optional. Narrows the search to one report type. See below.</td></tr></tbody></table>

#### transactionType

<table><thead><tr><th width="200">Value</th><th>Report</th></tr></thead><tbody><tr><td><code>vir</code></td><td><a href="/motorweb/motorweb-reports/vir.md">VIR</a></td></tr><tr><td><code>vdr</code></td><td><a href="/motorweb/motorweb-reports/motor-check.md">Motor Check</a></td></tr><tr><td><code>vdnor</code></td><td><a href="/motorweb/motorweb-reports/bvi.md">BVI</a></td></tr><tr><td><code>chassisCheck</code></td><td><a href="/motorweb/motorweb-reports/chassis-check.md">Chassis Check</a></td></tr></tbody></table>

Without `transactionType`, the most recent report of any supported type is returned.

These four are the supported values. Other internal transaction types exist and may be accepted, but they are not part of the published interface and can change without notice.

{% hint style="warning" %}
Do not send more than one identifier. Sending both `plate` and `plateOrVin`, or two different identifiers, is rejected.
{% endhint %}

### **Response**

{% tabs %}
{% tab title="200 XML" %}
The same document the original report returned, rendered at the version you requested.

```xml
<vir vehicle-id="-285694250" billing-user="MotorWeb Development" id="-285694711" reference="43888db2" timestamp="2024-10-16T09:27:44.295" user="MotorWeb Development">
    <vir-analysis version="4.0">
        <vehicle>
            <!-- the full vehicle tree, as generated -->
        </vehicle>
        <security-interests>
            <number-of-security-interests>0</number-of-security-interests>
        </security-interests>
    </vir-analysis>
</vir>
```

See [VIR](/motorweb/motorweb-reports/vir.md) for the full response shape.
{% endtab %}

{% tab title="200 HTML" %}
An HTML document suitable for displaying to a user. Returned with `Content-Type: text/html`.
{% endtab %}

{% tab title="200 PDF" %}
A PDF document suitable for printing. Returned with `Content-Type: application/pdf`.
{% endtab %}

{% tab title="400" %}

```
Please identify the vehicle transaction
```

or

```
No transactions found for plate: ABC123
```

or

```
Transaction is not of the appropriate type
```

{% endtab %}
{% endtabs %}

### **Which reports can be retrieved**

The XML endpoint returns vehicle reports and [Asset Check](/motorweb/motorweb-reports/asset-check.md) reports.

The HTML and PDF endpoints return vehicle reports only. Use the dedicated Asset Check render endpoints for Asset Check in those formats.

{% hint style="info" %}
Not every MotorWeb transaction is retrievable here. Driver licence products, Fines Check, Window Card and Confirm Vehicle Owner are separate transaction types and are not returned by this endpoint.
{% endhint %}

### **XSD**

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

### **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>Please identify the vehicle transaction</code> — no identifier was supplied.</td></tr><tr><td>400</td><td><code>NOT-FOUND</code></td><td><code>No transactions found for plate: ABC123</code> — no report matched. The value is labelled, for example <code>VIN: …</code> or <code>plate: …</code>.</td></tr><tr><td>400</td><td><code>NOT-FOUND</code></td><td><code>No transactions of correct type found on vehicle</code> — the vehicle exists but has no report of the requested type.</td></tr><tr><td>400</td><td><code>NOT-FOUND</code></td><td><code>Transaction is not of the appropriate type</code> — the reference points at a transaction this endpoint does not serve.</td></tr><tr><td>400</td><td><code>BAD-PARAM</code></td><td><code>Please only specify one transaction identifier</code></td></tr><tr><td>400</td><td><code>BAD-PARAM</code></td><td><code>Don't specify both plate or vin and plateOrVin</code></td></tr><tr><td>401</td><td>—</td><td>Certificate authentication failed.</td></tr></tbody></table>

**Example cURL command:**

```bash
# XML by reference
curl --cert-type P12 --cert motorwebnz.p12:<CERTPASSWORD> \
  "https://robot.motorweb.co.nz/action/robotLoadXml/4.0?reference=43888db2"

# XML by plate, Motor Check only
curl --cert-type P12 --cert motorwebnz.p12:<CERTPASSWORD> \
  "https://robot.motorweb.co.nz/action/robotLoadXml/4.0?plateOrVin=ABC123&transactionType=vdr"

# HTML
curl --cert-type P12 --cert motorwebnz.p12:<CERTPASSWORD> \
  "https://robot.motorweb.co.nz/action/robotVirHtml/2.0?reference=43888db2"

# PDF
curl --cert-type P12 --cert motorwebnz.p12:<CERTPASSWORD> \
  "https://robot.motorweb.co.nz/action/robotVirPdf/2.0?reference=43888db2" \
  --output report.pdf
```

**Notes:**

* Authentication is mutual TLS with a MotorWeb-issued client certificate
* Retrieving a report is not charged as a new transaction
* Store the `reference` from every report you generate. It is the most reliable way to fetch the report again
* Lookup by `reference` works across accounts. The other identifiers are scoped to your own account
* Private owner information is suppressed on reports older than 30 days. Regenerate the report to see current owner data