> 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/ping.md).

# Ping

Check whether MotorWeb services are available before you transact.

<mark style="color:green;">`GET`</mark> `https://robot.motorweb.co.nz/action/robotPing/1.0`

Ping reports the availability of the services your account can access. It is not a transaction and is not billed.

As far as possible it is an end to end test. Every external party needed to complete a transaction is checked, not just MotorWeb itself. With this information you can disable a feature in your own product before a user hits an error.

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

### **Paths**

<table><thead><tr><th width="320">Path</th><th>Notes</th></tr></thead><tbody><tr><td><code>/action/robotPing/1.0</code></td><td>Use this path.</td></tr><tr><td><code>/b2b/ping/1.0</code></td><td>Alias. Same response.</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.0</strong></td><td><strong>Current version.</strong></td></tr></tbody></table>

### **Access**

No privilege is required. The list of services you receive matches the products your account can access.

### **Headers**

No request headers are required.

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

### **Body**

```
< no body required >
```

### **Query Parameters**

None. This endpoint takes no parameters.

### **Response**

{% tabs %}
{% tab title="200 All services up" %}

```xml
<ping>
    <service name="Vir" status="up"/>
    <service name="Vdr" status="up"/>
    <service name="Bvi" status="up"/>
    <service name="ChassisCheck" status="up"/>
    <service name="DriverCheck" status="up"/>
    <service name="FinesCheck" status="up"/>
</ping>
```

{% endtab %}

{% tab title="200 A service is down" %}

```xml
<ping>
    <service name="Vir" status="down">
        <notice>The NZTA registry is currently unavailable.
We are working with NZTA to restore the service.
Please try again shortly.</notice>
    </service>
    <service name="Vdr" status="down">
        <notice>The NZTA registry is currently unavailable.
We are working with NZTA to restore the service.
Please try again shortly.</notice>
    </service>
    <service name="Bvi" status="up"/>
    <service name="ChassisCheck" status="up"/>
    <service name="DriverCheck" status="up"/>
    <service name="FinesCheck" status="up"/>
</ping>
```

{% endtab %}
{% endtabs %}

### **Fields**

<table><thead><tr><th width="200">Element or attribute</th><th>Description</th></tr></thead><tbody><tr><td><code>service</code></td><td>Repeats. One per product your account can access.</td></tr><tr><td><code>service/@name</code></td><td>The service name. See the table below.</td></tr><tr><td><code>service/@status</code></td><td>Either <code>up</code> or <code>down</code>.</td></tr><tr><td><code>service/notice</code></td><td>A multi-line description of the problem, suitable for showing to your end users. Present only when the status is <code>down</code>.</td></tr></tbody></table>

### **Service names**

You only receive the services your account can access, so most callers see a subset of this list.

<table><thead><tr><th width="260">Name</th><th>Product</th></tr></thead><tbody><tr><td><code>Vir</code></td><td>VIR</td></tr><tr><td><code>VirPublic</code></td><td>Public VIR</td></tr><tr><td><code>Vdr</code></td><td>Motor Check</td></tr><tr><td><code>Bvi</code></td><td>BVI</td></tr><tr><td><code>ChassisCheck</code></td><td>Chassis Check</td></tr><tr><td><code>MotorCheckPlus</code></td><td>Motor Check Plus</td></tr><tr><td><code>DriverCheck</code></td><td>Driver Check</td></tr><tr><td><code>LicenceVerification</code></td><td>Licence Verification</td></tr><tr><td><code>FinesCheck</code></td><td>Fines Check</td></tr><tr><td><code>VehicleLicence</code></td><td>Vehicle Licence</td></tr><tr><td><code>VehicleRUC</code></td><td>Vehicle RUC</td></tr><tr><td><code>VehiclePopulateStatic</code></td><td>Vehicle Populate</td></tr><tr><td><code>Mr13cRequest</code></td><td>MR13C request</td></tr><tr><td><code>Mr13cReversal</code></td><td>MR13C reversal</td></tr><tr><td><code>Mr13cReport</code></td><td>MR13C report</td></tr><tr><td><code>TradeMeValuation</code></td><td>Trade Me valuation</td></tr><tr><td><code>MotorwebValuation</code></td><td>MotorWeb valuation</td></tr></tbody></table>

{% hint style="info" %}
A product configured with no privilege requirement is visible to every account, so the list is not strictly limited to products you hold.
{% endhint %}

### **What each service depends on**

<table><thead><tr><th width="300">Service</th><th>Upstream</th></tr></thead><tbody><tr><td><code>Vir</code></td><td>NZTA and PPSR</td></tr><tr><td><code>Vdr</code>, <code>Bvi</code>, <code>ChassisCheck</code>, <code>MotorCheckPlus</code></td><td>NZTA</td></tr><tr><td><code>DriverCheck</code></td><td>Driver licence register</td></tr><tr><td><code>LicenceVerification</code></td><td>Driver licence verification service and the register</td></tr><tr><td><code>FinesCheck</code></td><td>Ministry of Justice</td></tr><tr><td><code>TradeMeValuation</code></td><td>Market data</td></tr></tbody></table>

{% hint style="info" %}
Ping data is refreshed at most once a minute. Polling faster than that returns the same result and gains you nothing.
{% endhint %}

### **XSD**

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

### **Errors**

<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>401</td><td>—</td><td>Certificate authentication failed.</td></tr><tr><td>500</td><td><code>EXTERNAL-ISSUE</code></td><td>An error on MotorWeb's side.</td></tr></tbody></table>

**Example cURL command:**

```bash
# Production
curl --cert-type P12 --cert motorwebnz.p12:<CERTPASSWORD> \
  "https://robot.motorweb.co.nz/action/robotPing/1.0"

# UAT
curl --cert-type P12 --cert motorwebnz-uat.p12:<CERTPASSWORD> \
  "https://robot.uat.motorweb.co.nz/action/robotPing/1.0"
```

**Notes:**

* Authentication is mutual TLS with a MotorWeb-issued client certificate
* No privilege is required. You see the products your account holds, plus any product configured with no privilege requirement
* Poll no more than once a minute
* Show the `notice` text to your users. It is written for that purpose
* A service showing `up` is not a guarantee. Handle `EXTERNAL-ISSUE` errors on transactions regardless
* For a public view of current and past incidents, see the [MotorWeb Status Page Hub](/motorweb/other-products-and-resources/status-page.md)