Skip to content

Insurance VIN lookup

POST
/open/sales/insurance/vin

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.

history

Request History

Your request history will appear here.

Headers

X-API-USER stringrequired

Your Moolre username.

X-API-KEY stringrequired

Your Private API Key for the paying wallet.

Content-Type stringrequired

Send application/json.

Body Params

accountnumberstringrequired

Your insurance agent wallet account number.

vinstringrequired

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.

seatsintegeroptional

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.

Responses

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.

{
  "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": []
  }
}
statusstring
1 when a vehicle was found.
codestring
IQ23.
data.vinstring
The VIN as looked up: upper case, no spaces.
data.decodedobject
What the VIN decoded to: make, model, year, engcc (null when unknown), seats, seats_defaulted (true when 5 was assumed), body, fuel, drive, doors, cylinders, vehicle_type, manufacturer and plant_country. A value the VIN does not give is null.
data.warningsarray
Each item has a code and a message. A code from NHTSA (for example 1, the check digit does not calculate) or one of seats_defaulted and engcc_unknown. A warning never fails the lookup.
data.best_matchobject
The closest vehicle: modelno, modeldesc, bodytype, engcc, tonnage (string or null), noseats, and match (model when the whole model name matched, model_word when only its first word did). Send these values in policy.motor.
data.candidatesarray
Up to 5 matching vehicles, best first, with the same fields as best_match. The first is best_match.
data.confidentboolean
true when the whole model name matched, the engine size is within 100 cc and no other vehicle matched equally well. When false, let a person choose from the candidates.
data.search_termstring
The insurer search that found the vehicles.
data.decoded_partialboolean
true when the VIN lacked the make, the model or the engine size. Always present.
data.fallbackobject or null
null when confident is true. Otherwise how to continue with Insurance Vehicles: reason (low_confidence, engcc_unknown, no_insurer_match, model_unknown or not_decoded), message, endpoint (/open/sales/insurance/vehicles), method, suggested (search_term built from what is known or null, engcc, seats), engcc_options (the decoded engine size and the nearest catalogue size) and ask_user (make, model and engcc: what the person still has to give).

More than one vehicle fits and the first is not clearly better. Show the candidates.

{
  "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": []
  }
}

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.

{
  "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": []
  }
}
codestring
IQ24.
data.decodedobject
What was decoded. model is null when NHTSA gave none, engcc is null when it gave no engine size, and the other values are as for IQ23.
data.decoded_partialboolean
true.
data.candidatesarray
Up to 10 vehicles of the make, from one insurer search, with the fields of best_match and match set to make. Empty when the insurer lists none at that engine size.
data.searchobject
The insurer search the candidates came from: search_term, engcc and engcc_assumed (true when the VIN gave no engine size and 1500 was used).
data.fallbackobject
How to continue: see Insurance Vehicles. fallback.suggested is ready to send as search_term, engcc and seats (engcc is null when it must be asked for).

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.

{
  "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": []
  }
}

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).

{
  "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": []
  }
}

Nothing is looked up. The VIN is not 17 letters and digits, or uses I, O or Q.

{
  "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": []
  }
}

Fields every response can carry

On failures, read code, message and data (the first failing field). meta is always present and holds requestid (also the X-Request-Id header), notices and, only on idempotent replays, replayed. There is no outcome field: use status, code and data.txstatus. Send X-Moolre-Http-Status: strict to receive real HTTP status codes. See Responses and request IDs and Errors and status codes.

Language

curl --request POST \     --url 'https://api.moolre.com/open/sales/insurance/vin' \     --header 'X-API-USER: Your Username' \     --header 'X-API-KEY: YOUR_API_KEY' \     --header 'Content-Type: application/json' \     --data '{  "accountnumber": "",  "vin": "",  "seats": 5}'

Response

Body

{  "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": []  }}