> 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/motorweb-reports.md). # About This section documents the MotorWeb New Zealand B2B API. These endpoints return vehicle registration data, ownership data, security interests and vehicle specifications as XML. ## Authentication All B2B endpoints use **mutual TLS (mTLS)** with a MotorWeb-issued client certificate. You must present your certificate on every request. There is no API key and no password. See [Authentication](/motorweb/motorweb-reports/authentication.md). ## Base URLs | Environment | Base URL | | ----------- | ---------------------------------- | | Production | `https://robot.motorweb.co.nz` | | UAT | `https://robot.uat.motorweb.co.nz` | {% hint style="warning" %} Certificates are issued per environment. A UAT certificate does not work in Production, and the reverse is also true. Ask your account manager for a UAT certificate before you start testing. {% endhint %} ## Available endpoints ### Vehicle reports | Report | Endpoint | Returns | | -------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | [VIR](/motorweb/motorweb-reports/vir.md) | `GET /action/robotVir/{version}` | The full report. Vehicle, owner, odometer history, security interests, valuation and listing history. | | [Asset Check](/motorweb/motorweb-reports/asset-check.md) | `GET /b2b/robotAssetCheck/{version}` | Everything VIR returns, plus RedBook valuation and the fuel economy label. | | [Motor Check](/motorweb/motorweb-reports/motor-check.md) | `GET /b2b/motorcheck/generate/{version}` | Vehicle and current owner. No history, no security interests. | | [Motor Check + RedBook](/motorweb/motorweb-reports/motor-check-redbook.md) | `GET /b2b/mc2rb/{version}` | Motor Check plus RedBook codes. | | [Chassis Check](/motorweb/motorweb-reports/chassis-check.md) | `GET /b2b/chassischeck/generate/{version}` | Vehicle only. No dynamic data such as WOF, COF or RUC. | | [Chassis Check + RedBook](/motorweb/motorweb-reports/chassis-check-redbook.md) | `GET /b2b/cc2rb/generate/{version}` | Chassis Check plus RedBook codes. | | [Chassis Check + RedBook Valuation](/motorweb/motorweb-reports/chassis-check-redbook-valuation.md) | `GET /b2b/cc2rbv/valuation/{version}` | RedBook wholesale and retail values. | | [BVI](/motorweb/motorweb-reports/bvi.md) | `GET /b2b/bvi/generate/{version}` | Vehicle only. No owner information. | | [Current Owner Check](/motorweb/motorweb-reports/current-owner-check.md) | `GET /b2b/currentOwnerCheck/generate/{version}` | Basic vehicle data and the current owner. | | [Advanced Vehicle Check](/motorweb/motorweb-reports/advanced-vehicle-check.md) | `GET /b2b/advancedvehiclecheck/generate/{version}` | Specifications, odometer history, fuel, safety and emissions. | | [Current Owner Average Km Usage](/motorweb/motorweb-reports/current-owner-average-km-usage.md) | `GET /b2b/averageusage/generate/{version}` | An annualised distance estimate for the current owner. | ### Utility | Endpoint | Path | Purpose | | ---------------------------------------------------------------------------------- | ------------------------------------ | ---------------------------------------------------------- | | [Ping](/motorweb/motorweb-reports/ping.md) | `GET /action/robotPing/1.0` | Service availability for the products you can access. | | [Retrieve Existing Report](/motorweb/motorweb-reports/retrieve-existing-report.md) | `GET /action/robotLoadXml/{version}` | Fetch a report you already generated, as XML, HTML or PDF. | See also [Additional Services](/motorweb/additional-services/driver-check.md) for driver licence products, Fines Check, Window Card, Fuel Economy Labels and more. ## Identifying the vehicle Most report endpoints accept these parameters. Use one identifier per request. | Parameter | Description | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `plateOrVin` | A registration plate (6 characters or fewer) or a VIN (exactly 17 characters). A new vehicle record is created in MotorWeb and linked to the report. | | `vehicleId` | The ID of a vehicle that already exists in MotorWeb under your account. Usually taken from a previous response. A new report is generated against that vehicle. | | `stockNumber` | Your own reference for a vehicle that already exists under your account. Shown in the MotorWeb interface as "Stock number". | | `specificReason` | Why private owner information is being requested. Required on some reports. See below. | Sending both `vehicleId` and `plateOrVin` returns `Cannot specify both vehicleId and plateOrVin`. Sending none returns `No vehicle identifiers specified`. ## specificReason Section 241 of the Land Transport Act requires a stated reason before private owner information is released. Reports that return owner data accept a `specificReason` parameter. Valid reasons are listed in section 4 of these notices: * * {% 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 %} ## Response format Successful responses are `text/xml`. Every report shares a common set of attributes on its root element. | Attribute | Required | Description | | -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- | | `reference` | Yes | The unique reference for this transaction. Always 8 characters. Use it to retrieve the report later and when contacting support. | | `id` | Yes | The internal transaction ID. Prefer `reference`. | | `timestamp` | Yes | When the transaction started. | | `user` | Yes | The user who owns the transaction. | | `billing-user` | Yes | The account the transaction is billed to. | | `vehicle-id` | No | The MotorWeb vehicle ID this transaction is attached to. | | `stock-number` | No | Your own reference for this vehicle, if you supplied one. | These are defined in [transaction-2.0.xsd](https://www.motorweb.co.nz/action/robotSchema/transaction-2.0.xsd). ## Error handling Errors return `text/plain` with the message in the body. A `MotorWeb-Error-Code` response header carries a machine-readable code. | HTTP | Meaning | | ----- | ---------------------------------------------------------------- | | `400` | Bad parameters, missing privilege, or the vehicle was not found. | | `401` | Certificate authentication failed. | | `500` | An error on MotorWeb's side, including an unrecognised version. | {% hint style="warning" %} **Send a version from the documented list.** An unrecognised version in the path returns `500` with `MotorWeb-Error-Code: EXTERNAL-ISSUE`, not a `400`. On report endpoints the report is generated **before** the version is checked, so a bad version still costs you a transaction and you do not get the reference back. Pin the version you have tested against. {% endhint %} ### MotorWeb error codes | Code | Meaning | | ---------------- | --------------------------------------------------------------------------- | | `BAD-PARAM` | A parameter is missing, malformed or contradictory. | | `NOT-FOUND` | No matching vehicle or transaction. | | `NO-MATCH` | No matching RedBook model. | | `NO-VALUATION` | RedBook models matched but none carry valuation data. | | `NO-OWNER-INFO` | No prior report on this vehicle holds owner information. | | `NO-WOF-EXPIRY` | No WOF expiry date is available. | | `BAD-ACCOUNT` | Authentication or authorisation failed, or a transaction limit was reached. | | `EXTERNAL-ISSUE` | An upstream system is unavailable, or an unexpected error occurred. | | `MC-…` | An error passed through from NZTA. See below. | | `CDI-…` | An error passed through from the driver licence register. | ### Common NZTA errors | Code | Description | | ------- | -------------------------------------- | | `MC-21` | Invalid plate number or VIN | | `MC-22` | No vehicle found matching plate or VIN | | `MC-23` | Confidential owner | | `MC-44` | Plate has not been used | | `MC-…` | Other errors returned from NZTA | ## Comparing reports To see field by field what each report returns, download the data matrix: `https://robot.motorweb.co.nz/action/robot-vehicle-report-data-matrix.xls` ## XSD schemas Schemas are published at: ``` https://www.motorweb.co.nz/action/robotSchema/{schema-name}.xsd ``` Each report page links its own schema. The schemas also document the codes returned for coded fields. ## Getting started 1. **Get your certificate.** Contact MotorWeb for a `motorweb.p12` file and its password. Ask for UAT and Production separately. 2. **Choose your report.** Use the table above, or the data matrix, to pick the one that returns what you need. 3. **Read the schema.** Check the XSD for the fields and codes you must handle. 4. **Test in UAT.** Point at `https://robot.uat.motorweb.co.nz`. 5. **Monitor with Ping.** Use [Ping](/motorweb/motorweb-reports/ping.md) to check availability before you transact. 6. **Go live.** Change the base URL and the certificate. ## Support Contact your MotorWeb account manager for certificates, privileges and test data. Include the `reference` value from the response when you report a problem with a specific transaction.