the reference
The vehicle registration API, field by field.
Send an Indian registration number to POST /v1/vehicle/rc and get the vehicle's registration record back as JSON. This page lists the request, each group of fields, the envelope around every answer and the thirteen error codes.
POST /v1/vehicle/rc X-API-Key: your_sandbox_key Content-Type: application/json { "registration_number": "KA01AB1234" } HTTP/1.1 200 OK X-Request-Id: req_sample_000001 Cache-Control: no-store { "request_id": "req_sample_000001", "status": "success", "code": "OK", "data": { the record, below }, "meta": { "environment": "sandbox", "source": "sample", "cached": false, "billable": false } }
Sample data. Nothing was looked up.
One call, one field, one key.
The whole request is a number plate. There are no options to set and no fields to choose: the answer always has the same shape.
The sandbox returns a sample record in the live shape, so an integration can be finished before a live key is issued.
- Method and path
POST /v1/vehicle/rc- Body
- JSON with one field,
registration_number. - Accepted numbers
- Indian registration numbers, including BH-series. Spaces, hyphens and letter case are ignored.
- Authentication
- A key in the
X-API-Keyheader, or as a Bearer token. - Sandbox key
- Works from any address and is never billed.
- Live key
- Works only from the addresses on your allow-list.
What comes back in data.
The record has three values at the top and eight groups under them. Every key is always present. A value the record does not hold comes back as null, never guessed.
| Group | Keys | What it tells you |
|---|---|---|
| Top level | registration_number rc_status status_as_on | The plate, the status of the registration and the date that status was read. |
vehicle | manufacturer model class category body_type fuel_type emission_norms colour manufactured cubic_capacity_cc cylinders seating_capacity unladen_weight_kg gross_weight_kg wheelbase_mm is_commercial | What the vehicle is. |
registration | date authority valid_upto tax_valid_upto | When and where it was registered, and how long the registration and the tax are valid. |
insurance | company policy_number valid_upto | The insurer and the date the policy runs to. |
pucc | number valid_upto | The pollution certificate and its validity. |
finance | is_financed financier | Whether the vehicle is under a loan. |
permit | number type issued_on valid_from valid_upto | The permit, for commercial vehicles. National permit details sit in the same group. |
blacklist | status details | Whether a flag is held against the registration. |
non_use | status from to | Whether the vehicle is declared as not in use, and for which period. |
Dates are written year, month, day: YYYY-MM-DD. The month of manufacture is YYYY-MM. This page lists the fields that describe the vehicle and its papers. The full reference comes with sandbox access.
Every answer arrives in the same envelope.
A success and an error have the same outer shape, so one piece of code can read both. Check status, then read data or message.
Keep the request id. Quote it when you ask about a call.
request_id- Unique to the call. Also sent as the
X-Request-Idheader. statussuccessorerror.codeOK, or the name of the error.data- The record, on a success. An error carries a
messagethat says what to do. metaenvironment,source,fetched_at,cachedandbillable. In the sandbox,sourcereadssampleandbillableis false.- Headers
X-Request-Id, andCache-Control: no-store.
Thirteen errors, each with a name.
The HTTP status tells you the kind of problem. The code tells you exactly which one. The two errors that come from the registry source are safe to retry.
| HTTP | Code | What it means |
|---|---|---|
| 400 | INVALID_REQUEST | The body is not JSON, or registration_number is missing. |
| 401 | MISSING_API_KEY | No key was sent. |
| 401 | INVALID_API_KEY | The key is wrong or has been revoked. |
| 403 | IP_NOT_WHITELISTED | A live key was used from an address that is not on your allow-list. |
| 403 | CLIENT_SUSPENDED | The account is suspended. |
| 403 | PRODUCT_NOT_ENABLED | This API is not part of your plan. |
| 404 | VEHICLE_NOT_FOUND | The registry holds no vehicle under this number. |
| 422 | INVALID_REGISTRATION_NUMBER | The value is not an Indian registration number. |
| 429 | RATE_LIMITED | Too many calls in one minute. |
| 429 | DAILY_QUOTA_EXCEEDED | The day's quota is used up. It resets at midnight, India time. |
| 429 | MONTHLY_QUOTA_EXCEEDED | The month's quota is used up. |
| 502 | SOURCE_ERROR | The registry source answered with an error. Safe to retry. |
| 503 | SOURCE_UNAVAILABLE | The registry source cannot be reached. Safe to retry. |
The sandbox has a reserved test number that returns VEHICLE_NOT_FOUND, so the error path can be tested before going live.
Limits you can read before you hit them.
Each account has a rate limit per minute, and can have a daily and a monthly quota. Your own limits are readable through the API, and every call is logged in your portal.
- Rate limit
- Per minute, for each account. Over it, the answer is
429 RATE_LIMITED. - Daily quota
- Optional. Resets at midnight, India time.
- Monthly quota
- Optional.
- Usage
- Read your limits at
GET /v1/usage. - Retries
502and503are safe to retry.- Logs
- Every call is logged with the plate, the result, the time taken and the caller. The answer itself is not stored.
About the reference.
What is a vehicle registration (RC) API?
An API that takes a vehicle's registration number and returns its registration record: the status of the registration, what the vehicle is, and the validity of its registration, tax, insurance and pollution certificate.
What do I send?
One field, registration_number, as JSON, to POST /v1/vehicle/rc, with your key in the X-API-Key header.
Which fields come back?
The registration number and its status, then eight groups: vehicle, registration, insurance, PUC, finance, permit, blacklist and non-use.
What happens when a value is not on record?
The key is still present and its value is null. Nothing is guessed or filled in.
What format are dates in?
YYYY-MM-DD. The month of manufacture is YYYY-MM.
Which errors can I retry?
502 SOURCE_ERROR and 503 SOURCE_UNAVAILABLE. Both mean the registry source had a problem, not your request.
Is the sandbox billed?
No. Sandbox calls are never billed, and meta.billable says so on each answer.
How do I get a key and the full reference?
Ask for sandbox access. You get a portal login, a sandbox key and the API reference.
Start in the sandbox.
Tell us what you are building and which vehicles you handle. We will set up a sandbox key and the API reference.