NIID Vehicle Insurance Check¶

The NIID Checker API lets you verify whether a Nigerian vehicle has valid insurance by querying the Nigerian Insurance Industry Database (askniid.org) programmatically.

Base URL

This API runs as a separate service from the main Octamile AIMS API.

https://niid-checker.azurewebsites.net

Overview¶

Property	Value
Endpoint	`POST /verify/vehicle`
Auth	None (internal use)
Response time	~12–17 seconds (first lookup); instant for cached repeats
Coverage	Single vehicles only
Data source	askniid.org — NIID live database

Check by Plate Number or Policy Number¶

cURLPythonNode.js

curl -X POST https://niid-checker.azurewebsites.net/verify/vehicle \
  -H "Content-Type: application/json" \
  -d '{
    "search_type": "registration",
    "value": "ABC-123-XY"
  }'

import requests

res = requests.post(
    "https://niid-checker.azurewebsites.net/verify/vehicle",
    json={"search_type": "registration", "value": "ABC-123-XY"},
    timeout=30,
)
data = res.json()

const res = await fetch("https://niid-checker.azurewebsites.net/verify/vehicle", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ search_type: "registration", value: "ABC-123-XY" }),
});
const data = await res.json();

Request fields¶

Field	Type	Required	Values	Description
`search_type`	string	No	`"registration"` \| `"policy"`	Default: `"registration"`
`value`	string	Yes	—	Plate number or policy number. Case-insensitive.

Responses¶

Policy found¶

{
  "status": "found",
  "details": {
    "Policy Number": "FCS/PM/2026/04/20373",
    "ECOWAS Brown Card Certificate Number": "EBC/NG/NICO/2026/9628297",
    "New Registration Number": "KRD671GT",
    "Registration Number": "KRD671GT",
    "Type of Cover": "Third Party & Theft",
    "Vehicle Type": "Camry",
    "Vehicle Make": "Toyota",
    "Vehicle Model": "Camry",
    "Color": "Black",
    "Chassis Number": "4t1bf1fk2gu133282",
    "Issue Date": "11 APR 2026",
    "Expiry Date": "10 APR 2027",
    "License Status": "Policy is active"
  },
  "message": ""
}

Policy not found¶

{
  "status": "not_found",
  "details": {},
  "message": "Your Policy is not found !!!!"
}

Response fields¶

Field	Type	Description
`status`	string	`"found"` — policy exists and is registered in NIID. `"not_found"` — no matching policy. `"error"` — service unavailable.
`details`	object	Key/value pairs from NIID. Only present when `status` is `"found"`.
`details["License Status"]`	string	`"Policy is active"` or expired status.
`details["Expiry Date"]`	string	Date in `DD MMM YYYY` format, e.g. `"10 APR 2027"`.
`message`	string	Human-readable message when `status` is `"not_found"` or `"error"`.

Error responses¶

HTTP status	Meaning
`400`	Invalid request — `search_type` not `"registration"` or `"policy"`, or `value` is empty.
`502`	NIID returned an unexpected response.
`503`	Service not configured (missing API key).
`504`	Token pool timed out — CAPTCHA service unavailable. Retry.

How it works¶

The NIID portal does not expose a public API. Each call to /verify/vehicle:

Fetches the NIID form page to retrieve ASP.NET session tokens.
Submits the plate/policy number with a programmatically solved reCAPTCHA token.
Parses and returns the result.

The bottleneck is NIID's server-side database search (~15 seconds for the final POST). Steps 1 and 2 (fetching ViewState and selecting the search type) together take ~2 seconds. Total first-lookup time is typically 12–17 seconds.

A background token pre-solver pool keeps 3 reCAPTCHA tokens solved in advance, so token solving adds zero time to a warm request. A 5-minute response cache means repeat lookups for the same plate or policy number return instantly.

Health check¶

curl https://niid-checker.azurewebsites.net/health

{
  "status": "ok",
  "pool_tokens_ready": 3
}

pool_tokens_ready shows how many pre-solved tokens are queued. If this is 0, the first request after server start will be slower while the pool fills.

Self-service frontend¶

A web form is available at:

https://niid-checker.azurewebsites.net/static/

Partners and agents can use this directly without calling the API.

Integrating via the AIMS API¶

Partners with the NIID Vehicle Check enrichment service activated can call the check directly through the main Octamile AIMS API — no separate base URL or authentication to manage.

Activation required

This service is disabled by default. Contact support@octamile.com to activate it on your account. Pricing is per call, invoiced monthly.

Request¶

POST https://octamile-api.azurewebsites.net
Content-Type: application/json

{
  "userInfo": {
    "id": "your-partner-uuid",
    "athrzt": {
      "id": "your-auth-id",
      "key": "your-api-key"
    }
  },
  "cmmnd": {
    "cmmnd": "enrch niid_vehicle",
    "seed": {
      "search_type": "registration",
      "value": "KRD671GT"
    }
  }
}

seed fields are identical to the standalone API — search_type is "registration" (default) or "policy", and value is the plate number or policy number.

Response — policy found¶

{
  "status": "found",
  "details": {
    "Policy Number": "FCS/PM/2026/04/20373",
    "New Registration Number": "KRD671GT",
    "Type of Cover": "Third Party & Theft",
    "Vehicle Make": "Toyota",
    "Vehicle Model": "Camry",
    "Expiry Date": "10 APR 2027",
    "License Status": "Policy is active"
  },
  "from_cache": false,
  "message": "",
  "exctnFdbck": { "id": 75, "id_v4": 200 }
}

Response — policy not found¶

{
  "status": "not_found",
  "details": {},
  "from_cache": false,
  "message": "Your Policy is not found !!!!",
  "exctnFdbck": { "id": 75, "id_v4": 200 }
}

Response fields¶

Field	Description
`status`	`"found"` \| `"not_found"`. `"error"` is never returned — on transient failures the call is not logged or billed.
`details`	NIID key/value pairs. See standalone API response for the full field list.
`from_cache`	`true` if this result was served from a 5-minute response cache. Cached results are not billed.

Error responses¶

HTTP / `exctnFdbck.id_v4`	Meaning
HTTP 403	Service not activated on your account. Contact support to enable.
HTTP 400	Missing or invalid `seed` fields (`search_type` or `value`).
HTTP 504 / `id_v4: 504`	NIID check timed out. Retry — this is rare.

Billing¶

Calls are billed per successful response (status: "found" or "not_found").
Cache hits (from_cache: true) are free — the same plate or policy number looked up within 5 minutes is returned instantly at no charge.
Usage is aggregated and invoiced monthly. Your current-month totals are visible in the Services section of your dashboard.