Insurance Vehicles API
Environment: Sandbox
Search the insurer vehicle list by make and model to get the model details a motor policy needs.
# Insurance Vehicles API
Search the insurer vehicle list by make and model. Each result gives the modelno, modeldesc, bodytype, engcc, tonnage and noseats a motor policy needs in policy.motor.
## Endpoint
- **Method**: POST
- **URL**: https://sandbox.moolre.com/open/sales/insurance/vehicles
## Headers
| Header | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| Content-Type | string | Yes | Send application/json. |
| X-API-USER | string | Yes | Your Moolre username. |
| X-API-KEY | string | Yes | Your Private API Key for the paying wallet. |
## Request Body
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| accountnumber | string | Yes | Your insurance agent wallet account number. |
| search_term | string | Yes | Make and model to look for, 2 to 60 characters. |
| seats | integer | Yes | Number of seats of the vehicle, a whole number from 1 to 100. |
| engcc | integer | Yes | Engine capacity in cc, a whole number from 1 to 20000. |
## Response (200 Vehicles (IQ21))
Matching vehicles, at most 100. The values shown are examples.
```json
{
"status": "1",
"code": "IQ21",
"message": "Vehicles",
"data": {
"search_term": "TOYOTA COROLLA",
"count": 1,
"vehicles": [
{
"modelno": "1234",
"modeldesc": "TOYOTA COROLLA",
"bodytype": "SALOON",
"engcc": 1600,
"tonnage": null,
"noseats": 5
}
]
},
"go": null,
"meta": {
"requestid": "req_c68f4c66115c26725c796242",
"notices": []
}
}
```
## Response (200 No vehicles found (IQ22))
Nothing matched. Try a shorter or different search_term.
```json
{
"status": "1",
"code": "IQ22",
"message": "No vehicles found",
"data": {
"search_term": "TOYOTA COROLLA",
"count": 0,
"vehicles": []
},
"go": null,
"meta": {
"requestid": "req_c68f4c66115c26725c796242",
"notices": []
}
}
```
## Before you begin
Insurance is sold from a wallet that Moolre has registered as an insurance sales agent (the Insurance sales product). Register it in the Moolre App by creating a Sell on Our Platform service, choosing the Insurance product and linking your GHS wallet, or contact Moolre Support to be set up. The accountnumber you send must be your own GHS wallet; any other wallet is refused. Insurance is sold in GHS only.
Call these endpoints from your server with your Moolre username as X-API-USER and your Private API Key as X-API-KEY: never put the private key in a browser or a mobile app. Quote, Vehicles, VIN lookup and Covers only read: nothing is charged and no externalref is needed. Only Sell Insurance charges the wallet.
## Using the result
Pick the matching vehicle and copy its modelno, modeldesc, bodytype, engcc, tonnage and noseats into policy.motor when you sell the policy. Searches are kept and reused for several days. Start broad, for example the make and model, and narrow down if there are many results. If you have the VIN, [Insurance VIN lookup](https://docs.moolre.com/api/sales/insurance/vin) finds the vehicle for you and, when it cannot, tells you what to send here in its fallback field.
## Codes
Application codes, not HTTP status codes. Codes starting IQ come from the sales server and are returned unchanged.
| Code | Meaning | Next step |
| --- | --- | --- |
| ASV00 | Authentication error (Vehicles). | Check X-API-USER, X-API-KEY and accountnumber. |
| ASV01 | search_term is missing or not 2 to 60 characters. | Send the make and model of the vehicle, for example TOYOTA COROLLA. |
| ASV02 | seats is missing or not a whole number from 1 to 100. | Send the number of seats. |
| ASV03 | engcc is missing or not a whole number from 1 to 20000. | Send the engine capacity in cc. |
| ASV04 | Request incomplete (Vehicles). | Send accountnumber, search_term, seats and engcc. |
| ASV05 | No readable answer from the insurer. | Wait a moment and search again. |
| ASV06 | Unknown error (Vehicles). | Search again. |
| IQ02 | Not authorised. | accountnumber must be your own insurance agent wallet and the request must use your API user and key. |
| IQ03 | type must be 1 (quote), 2 (vehicle search) or 3 (VIN lookup). | Use the Quote, Vehicles or VIN endpoint. |
| IQ04 | This wallet is not registered as an insurance sales agent. | Contact Moolre Support to register the wallet. |
| IQ06 | seats is missing or not a whole number from 1 to 100. | Send the number of seats. |
| IQ07 | search_term is missing or not 2 to 60 characters. | Send the make and model of the vehicle. |
| IQ08 | engcc is missing or not a whole number from 1 to 20000. | Send the engine capacity in cc. |
| IQ09 | The insurer (for a VIN lookup, or the VIN decoder) could not be reached, try again. | Ask again after a moment. |
| IQ21 | Vehicles. | Matching vehicles returned in data.vehicles. |
| IQ22 | No vehicles found. | Try a shorter or different search_term, or another engcc. |
| IQ30 | Unknown error (quote or vehicle search). | Ask again. Nothing is charged. |
[Quote the cover](https://docs.moolre.com/api/sales/insurance/quote) or [sell the policy](https://docs.moolre.com/api/sales/insurance).
## Fields every response can carry
These fields are additive: existing fields keep their names, order and types.
| Field | Meaning |
| :--- | :--- |
| meta | Always present, last in the object. meta.replayed is true only when the response is the stored answer to a repeated Idempotency-Key (absent otherwise). meta.requestid is the unique id of the request (also the X-Request-Id response header): quote it when you contact support. meta.notices is always an array, empty when there is nothing to report; each notice is { code, message, docs? }, for example that a deprecated way of sending credentials was used. See [Deprecations](https://docs.moolre.com/guides/deprecations). |
There is no outcome field. Decide the result from status, code and, on payment and transfer endpoints, data.txstatus (0 pending, 1 succeeded, 2 failed). These codes mean the result is unknown and may still succeed, so treat them as pending and check the status: PY01, PY02, TR01, TR02, TP11, TP18, APY10, APY16, ASL06, IS30, SYS500. Status 1 with TR08, OBGH01, OTGH01, OBNG01, GHQ03 or OM03 is final success; any other status 1 is an accepted, unfinished request.
Send X-Moolre-Http-Status: strict to receive real HTTP status codes (400, 401, 403, 404, 409, 422, 429, 5xx) instead of HTTP 200. See [Responses and request IDs](https://docs.moolre.com/guides/responses).