# Insurance VIN lookup API

Find the insurer vehicle model for a vehicle from its VIN (chassis number). The VIN is decoded to a make, model, year, engine size and seats, and matched to the insurer vehicle list, giving the modelno, modeldesc, bodytype, engcc, tonnage and noseats a motor policy needs. Nothing is charged.

## Endpoint
- **Method**: POST
- **URL**: https://sandbox.moolre.com/open/sales/insurance/vin

## 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. |
| vin | string | Yes | The 17-character vehicle identification number: letters and digits, never I, O or Q. Case and spaces are ignored. The check digit is not enforced. |
| seats | integer | No | Number of seats, a whole number from 1 to 100. Optional: a VIN almost never gives the seats, so 5 is assumed and reported in warnings when you leave it out. |

## Response (200 Vehicle found (IQ23))
The VIN was decoded and matched. The values shown are examples. data.confident tells whether the match can be used without a person checking it.

```json
{
  "status": "1",
  "code": "IQ23",
  "message": "Vehicle found",
  "data": {
    "vin": "JTDKN3DU0A0000001",
    "decoded": {
      "vin": "JTDKN3DU0A0000001",
      "make": "TOYOTA",
      "model": "PRIUS",
      "year": 2010,
      "engcc": 1800,
      "seats": 5,
      "seats_defaulted": true,
      "body": "Hatchback/Liftback/Notchback",
      "fuel": "Gasoline",
      "drive": null,
      "doors": null,
      "cylinders": 4,
      "vehicle_type": "PASSENGER CAR",
      "manufacturer": "TOYOTA MOTOR CORPORATION, JAPAN",
      "plant_country": "JAPAN"
    },
    "decoded_partial": false,
    "warnings": [
      {
        "code": "1",
        "message": "Check Digit (9th position) does not calculate properly"
      },
      {
        "code": "seats_defaulted",
        "message": "The VIN does not give the number of seats, 5 is assumed. Pass seats to use another number."
      }
    ],
    "best_match": {
      "modelno": "TO23",
      "modeldesc": "TOYOTA PRIUS 1800",
      "bodytype": "SALOON",
      "engcc": 1800,
      "tonnage": ".00",
      "noseats": 5,
      "match": "model"
    },
    "candidates": [
      {
        "modelno": "TO23",
        "modeldesc": "TOYOTA PRIUS 1800",
        "bodytype": "SALOON",
        "engcc": 1800,
        "tonnage": ".00",
        "noseats": 5,
        "match": "model"
      }
    ],
    "confident": true,
    "search_term": "TOYOTA PRIUS 1800",
    "fallback": null
  },
  "go": null,
  "meta": {
    "requestid": "req_c68f4c66115c26725c796242",
    "notices": []
  }
}
```

## Response (200 Several close matches (IQ23, confident false))
More than one vehicle fits and the first is not clearly better. Show the candidates.

```json
{
  "status": "1",
  "code": "IQ23",
  "message": "Vehicle found",
  "data": {
    "vin": "JTMHY7AJ5E4000000",
    "decoded": {
      "vin": "JTMHY7AJ5E4000000",
      "make": "TOYOTA",
      "model": "LAND CRUISER",
      "year": 2014,
      "engcc": 5700,
      "seats": 7,
      "seats_defaulted": false,
      "body": "Hatchback/Liftback/Notchback",
      "fuel": "Gasoline",
      "drive": null,
      "doors": null,
      "cylinders": 4,
      "vehicle_type": "PASSENGER CAR",
      "manufacturer": "TOYOTA MOTOR CORPORATION, JAPAN",
      "plant_country": "JAPAN"
    },
    "warnings": [
      {
        "code": "1",
        "message": "Check Digit (9th position) does not calculate properly"
      }
    ],
    "best_match": {
      "modelno": "T900",
      "modeldesc": "TOYOTA LAND CRUISER 5700",
      "bodytype": "SUV",
      "engcc": 5700,
      "tonnage": ".00",
      "noseats": 7,
      "match": "model"
    },
    "candidates": [
      {
        "modelno": "T900",
        "modeldesc": "TOYOTA LAND CRUISER 5700",
        "bodytype": "SUV",
        "engcc": 5700,
        "tonnage": ".00",
        "noseats": 7,
        "match": "model"
      },
      {
        "modelno": "T901",
        "modeldesc": "TOYOTA LAND CRUISER PRADO 5700",
        "bodytype": "SUV",
        "engcc": 5700,
        "tonnage": ".00",
        "noseats": 7,
        "match": "model"
      }
    ],
    "decoded_partial": false,
    "confident": false,
    "search_term": "TOYOTA LAND CRUISER 5700",
    "fallback": {
      "reason": "low_confidence",
      "message": "Several vehicles fit, or the closest is not clearly right. Let the person choose from the candidates, or refine with the vehicles search.",
      "endpoint": "/open/sales/insurance/vehicles",
      "method": "POST",
      "suggested": {
        "search_term": "TOYOTA LAND CRUISER",
        "engcc": 5700,
        "seats": 7
      },
      "engcc_options": [
        5700
      ],
      "ask_user": []
    }
  },
  "go": null,
  "meta": {
    "requestid": "req_c68f4c66115c26725c796242",
    "notices": []
  }
}
```

## Response (200 Partly decoded (IQ24))
NHTSA named the make but not the model (or the make and model but not the engine size). status is 1: use data.decoded, data.candidates (vehicles of the make, match make) and data.fallback to let the person choose with Insurance Vehicles. best_match is null and confident is false.

```json
{
  "status": "1",
  "code": "IQ24",
  "message": "The VIN was only partly decoded. Choose the model with the vehicles search.",
  "data": {
    "vin": "WVWZZZ1KZ6W000001",
    "decoded": {
      "vin": "WVWZZZ1KZ6W000001",
      "make": "VOLKSWAGEN",
      "model": null,
      "year": 2006,
      "engcc": null,
      "seats": 5,
      "seats_defaulted": true,
      "body": null,
      "fuel": null,
      "drive": null,
      "doors": null,
      "cylinders": null,
      "vehicle_type": "PASSENGER CAR",
      "manufacturer": "VOLKSWAGEN AG",
      "plant_country": "GERMANY"
    },
    "decoded_partial": true,
    "warnings": [
      {
        "code": "1",
        "message": "Check Digit (9th position) does not calculate properly"
      },
      {
        "code": "seats_defaulted",
        "message": "The VIN does not give the number of seats, 5 is assumed. Pass seats to use another number."
      },
      {
        "code": "model_unknown",
        "message": "The VIN gives the make but not the model, which is common for vehicles built for other markets."
      },
      {
        "code": "engcc_unknown",
        "message": "The VIN does not give the engine size, so the engine size could not be used to pick the model."
      }
    ],
    "best_match": null,
    "candidates": [
      {
        "modelno": "V390",
        "modeldesc": "Volkswagen 1500",
        "bodytype": "Saloon",
        "engcc": 1500,
        "tonnage": ".00",
        "noseats": 5,
        "match": "make"
      }
    ],
    "confident": false,
    "search_term": "VOLKSWAGEN",
    "search": {
      "search_term": "VOLKSWAGEN",
      "engcc": 1500,
      "engcc_assumed": true
    },
    "fallback": {
      "reason": "model_unknown",
      "message": "The VIN names the make but not the model. Search the vehicle with its make and model and let the person choose.",
      "endpoint": "/open/sales/insurance/vehicles",
      "method": "POST",
      "suggested": {
        "search_term": "VOLKSWAGEN",
        "engcc": null,
        "seats": 5
      },
      "engcc_options": [],
      "ask_user": [
        "model",
        "engcc"
      ]
    }
  },
  "go": null,
  "meta": {
    "requestid": "req_c68f4c66115c26725c796242",
    "notices": []
  }
}
```

## Response (200 Decoded, no insurer match (IQ13))
The VIN decoded, with an engine size, but the insurer lists no model for it. status is 0. data.candidates may hold other models of the make at that engine size. Search with Insurance Vehicles using data.fallback.suggested.

```json
{
  "status": "0",
  "code": "IQ13",
  "message": "The VIN was decoded but the insurer lists no matching model. Search the vehicle with its make and model.",
  "data": {
    "vin": "JTJBM7FX5B5000001",
    "decoded": {
      "vin": "JTJBM7FX5B5000001",
      "make": "LEXUS",
      "model": "GX",
      "year": 2011,
      "engcc": 4600,
      "seats": 5,
      "seats_defaulted": true,
      "body": "Sport Utility Vehicle (SUV)/Multi-Purpose Vehicle (MPV)",
      "fuel": "Gasoline",
      "drive": null,
      "doors": null,
      "cylinders": 4,
      "vehicle_type": "PASSENGER CAR",
      "manufacturer": "TOYOTA MOTOR CORPORATION, JAPAN",
      "plant_country": "JAPAN"
    },
    "decoded_partial": false,
    "warnings": [
      {
        "code": "seats_defaulted",
        "message": "The VIN does not give the number of seats, 5 is assumed. Pass seats to use another number."
      }
    ],
    "best_match": null,
    "candidates": [
      {
        "modelno": "L100",
        "modeldesc": "LEXUS RX 4600",
        "bodytype": "SUV",
        "engcc": 4600,
        "tonnage": ".00",
        "noseats": 5,
        "match": "make"
      }
    ],
    "confident": false,
    "fallback": {
      "reason": "no_insurer_match",
      "message": "The insurer lists no model for this vehicle. Search it with its make and model (and the engine size options) and let the person choose.",
      "endpoint": "/open/sales/insurance/vehicles",
      "method": "POST",
      "suggested": {
        "search_term": "LEXUS GX",
        "engcc": 4600,
        "seats": 5
      },
      "engcc_options": [
        4600
      ],
      "ask_user": []
    }
  },
  "go": null,
  "meta": {
    "requestid": "req_c68f4c66115c26725c796242",
    "notices": []
  }
}
```

## Response (200 Not decoded (IQ12))
NHTSA named no make for this VIN. data.warnings explains why. status is 0. Ask the person for the make, model and engine size and search with Insurance Vehicles (data.fallback.ask_user lists them).

```json
{
  "status": "0",
  "code": "IQ12",
  "message": "We could not decode this VIN. Check each character, or search the vehicle with its make and model.",
  "data": {
    "vin": "JMBXTGF2W7Z000001",
    "warnings": [
      {
        "code": "1",
        "message": "Check Digit (9th position) does not calculate properly"
      },
      {
        "code": "7",
        "message": "Manufacturer is not registered with NHTSA for sale or importation in the U.S. for use on public roads"
      },
      {
        "code": "400",
        "message": "Invalid Characters Present"
      }
    ],
    "decoded": null,
    "decoded_partial": false,
    "best_match": null,
    "candidates": [],
    "confident": false,
    "fallback": {
      "reason": "not_decoded",
      "message": "The VIN names no make or model. Ask the person for the make, model and engine size and search with the vehicles search.",
      "endpoint": "/open/sales/insurance/vehicles",
      "method": "POST",
      "suggested": {
        "search_term": null,
        "engcc": null,
        "seats": 5
      },
      "engcc_options": [],
      "ask_user": [
        "make",
        "model",
        "engcc"
      ]
    }
  },
  "go": null,
  "meta": {
    "requestid": "req_c68f4c66115c26725c796242",
    "notices": []
  }
}
```

## Response (200 Invalid VIN (ASN01))
Nothing is looked up. The VIN is not 17 letters and digits, or uses I, O or Q.

```json
{
  "status": "0",
  "code": "ASN01",
  "message": "vin must be 17 letters and digits (never I, O or Q), as printed on the vehicle registration.",
  "data": "vin",
  "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.

## How the lookup works

The VIN is decoded with the public NHTSA vehicle database, then matched to the insurer vehicle list. NHTSA mostly knows vehicles built for the US market, so some Japanese and European imports decode only in part. A warning from NHTSA, such as 1 (the check digit does not calculate, common on imports), is returned in warnings and does not fail the lookup; the lookup fails only when no make or model can be decoded. NHTSA rarely gives the number of seats, so 5 is assumed and a warning says so: send seats when you know it. confident is true only when the whole model name matched, the engine size is within 100 cc and no other vehicle matched equally well; when it is false, show the candidates and let a person choose. A partly decoded VIN is not a dead end. When NHTSA names the make but not the model (common for vehicles built for other markets), or the make and model but no engine size, the reply is a success with code IQ24: data.decoded holds what was decoded, data.candidates lists vehicles of the make, and data.fallback says what to search with Insurance Vehicles (fallback.suggested) and what the person still has to give (fallback.ask_user). IQ12 (not decoded) and IQ13 (no insurer model) carry the same fallback.

Use best_match (or the candidate the person chose) in policy.motor when you sell: modelno, modeldesc, bodytype, engcc, tonnage and noseats unchanged, the VIN as chasno and decoded.year as yrmanuf once checked against the registration. Use the same seats in Quote and in policy.motor.noseats. When data.fallback is not null, call Insurance Vehicles with fallback.suggested (and ask the person for whatever fallback.ask_user names). Decodes are kept for a long time and searches for several days, so a repeat lookup is fast.

## Codes

Application codes, not HTTP status codes. Codes starting IQ come from the sales server and are returned unchanged.

| Code | Meaning | Next step |
| --- | --- | --- |
| ASN00 | Authentication error (VIN). | Check X-API-USER, X-API-KEY and accountnumber. |
| ASN01 | vin is missing or not 17 letters and digits (never I, O or Q). | Send the VIN as printed on the registration or chassis plate. Spaces and case are ignored. |
| ASN02 | seats, when sent, is not a whole number from 1 to 100. | Send a valid seats or leave it out. |
| ASN04 | Request incomplete (VIN). | Send accountnumber and vin. |
| ASN05 | No readable answer for the VIN lookup. | Wait a moment and ask again, or search the vehicle with Insurance Vehicles. Nothing is charged. |
| ASN06 | Unknown error (VIN). | Ask again. Nothing is charged. |
| IQ02 | Not authorised. | accountnumber must be your own insurance agent wallet and the request must use your API user and key. |
| 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. |
| IQ09 | The insurer (for a VIN lookup, or the VIN decoder) could not be reached, try again. | Ask again after a moment. |
| IQ11 | vin is missing or not a valid 17-character VIN. | Send the VIN as printed on the registration or chassis plate. |
| IQ12 | The VIN could not be decoded. | NHTSA named no make. data holds the vin, warnings, decoded (null, or only what little was decoded such as the year), decoded_partial and a fallback. Check each character, or ask the person for the make, model and engine size and use Insurance Vehicles. |
| IQ13 | The VIN was decoded but the insurer lists no matching model. | data holds the decoded vehicle, warnings, candidates (other models of the make at that engine size, when the insurer lists any) and a fallback. Search with Insurance Vehicles using fallback.suggested. |
| IQ23 | Vehicle found for the VIN. | Read data.best_match, data.candidates, data.confident, data.warnings and, when confident is false, data.fallback. |
| IQ24 | The VIN was only partly decoded (status 1). | The make is known but not the model, or the make and model but not the engine size. Read data.decoded, data.candidates and data.fallback, then let the person choose with Insurance Vehicles. |
| IQ30 | Unknown error (quote or vehicle search). | Ask again. Nothing is charged. |

[Search by make and model instead](https://docs.moolre.com/api/sales/insurance/vehicles), [quote the cover](https://docs.moolre.com/api/sales/insurance/quote) or follow the [motor insurance guide](https://docs.moolre.com/use-cases/sell-motor-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).
