Vehicle Insurance Integration Guide¶

Covers both Third-party (vhcl-tprt-1111) and Comprehensive (vhcl-cmpr-1111) products.

Product Overview¶

	Third-party	Comprehensive
Product code	`vhcl-tprt-1111`	`vhcl-cmpr-1111`
Coverage	Damage to third-party vehicle in an accident	Third-party + own vehicle damage, theft, fire
Cover period	1 year	1 year
Premium basis	Fixed	Based on vehicle value

Integration Flow¶

Both products use the standard 4-step flow. See the Quickstart Guide for a complete walkthrough using third-party insurance.

Returning customer? If this customer has purchased insurance through your platform before, you already have their consumer_id — skip Step 2 and use it directly in Step 3. See the Consumer Management Guide.

Step 1 — Get Premium Quote¶

Third-party (fixed premium — no extra fields needed):

curl -X POST https://octamile-api.azurewebsites.net \
  -H "Content-Type: application/json" \
  -d '{
    "userInfo": {
      "id": "YOUR_PARTNER_ID",
      "athrzt": { "id": "YOUR_AUTH_ID", "key": "YOUR_AUTH_KEY" }
    },
    "cmmnd": {
      "cmmnd": "dump ipck_vhcl-tprt-1111*PRMM",
      "seed": {
        "insrncDrtn": "1y"
      }
    }
  }'

Comprehensive (premium depends on vehicle value):

curl -X POST https://octamile-api.azurewebsites.net \
  -H "Content-Type: application/json" \
  -d '{
    "userInfo": {
      "id": "YOUR_PARTNER_ID",
      "athrzt": { "id": "YOUR_AUTH_ID", "key": "YOUR_AUTH_KEY" }
    },
    "cmmnd": {
      "cmmnd": "dump ipck_vhcl-cmpr-1111*PRMM",
      "seed": {
        "vhclValueForInsrnc": 4500000,
        "insrncDrtn": "1y"
      }
    }
  }'

vhclValueForInsrnc is the vehicle's insured value in Naira. Send as a number (e.g., 4500000). Minimum: 500000. Use the Vehicle Valuation Service if the consumer does not provide a value — see the Vehicle Valuation Guide.

Response:

{
  "exctnFdbck": { "id": 75 },
  "prmm": 85000
}

Step 2 — Register Consumer¶

Third-party (minimum required fields):

{
  "cmmnd": {
    "cmmnd": "prfl entity",
    "seed": {
      "type": "s",
      "class": "h",
      "name": { "first": "Chidi", "last": "Nwosu" },
      "gender": "m",
      "dob": { "date": "1985-11-20" },
      "addrss": { "addrss": "45 Broad Street, Lagos Island" },
      "phoneNo": "+2348031234567",
      "eMail": "chidi.nwosu@email.com"
    }
  }
}

Comprehensive (requires government ID in addition to the above):

{
  "cmmnd": {
    "cmmnd": "prfl entity",
    "seed": {
      "type": "s",
      "class": "h",
      "name": { "first": "Chidi", "last": "Nwosu" },
      "gender": "m",
      "dob": { "date": "1985-11-20" },
      "socialID": {
        "type": "nidd",
        "id": "12345678901",
        "image": "BASE64_ENCODED_ID_SCAN"
      },
      "addrss": { "addrss": "45 Broad Street, Lagos Island" },
      "phoneNo": "+2348031234567",
      "eMail": "chidi.nwosu@email.com"
    }
  }
}

socialID.type accepted values: "nidd" (NIN), "dlcn" (driver's licence), "ipss" (passport), "vcrd" (voter's card), "bvnn" (BVN).

Response: Returns a 32-character id. Store this as the consumer's ID.

Step 3 — Request Policy¶

Third-party:

{
  "cmmnd": {
    "cmmnd": "entt_{CONSUMER_ID}: insure",
    "seed": {
      "ctgry": "vhcl",
      "type": "tprt",
      "pckg": "1111",
      "id": "YOUR_32_CHAR_TRANSACTION_REF",
      "insrncDrtn": "1y",
      "addtnlFact": {
        "brand": "Toyota",
        "model": "Camry",
        "year": "2019",
        "chsssId": "JTDBE32KX30123456",
        "engineId": "2AR1234567",
        "rgstrtId": "KJA123BC"
      }
    }
  }
}

Comprehensive (additionally requires vehicle value and proof of ownership):

{
  "cmmnd": {
    "cmmnd": "entt_{CONSUMER_ID}: insure",
    "seed": {
      "ctgry": "vhcl",
      "type": "cmpr",
      "pckg": "1111",
      "id": "YOUR_32_CHAR_TRANSACTION_REF",
      "insrncDrtn": "1y",
      "addtnlFact": {
        "brand": "Toyota",
        "model": "Camry",
        "year": "2019",
        "chsssId": "JTDBE32KX30123456",
        "engineId": "2AR1234567",
        "rgstrtId": "KJA123BC",
        "vhclValueForInsrnc": 4500000,
        "proofOfOwnrsh": "BASE64_ENCODED_OWNERSHIP_DOC"
      }
    }
  }
}

Required Fields — Both Products¶

Field	Type	Description
`ctgry`	string	`"vhcl"`
`type`	string	`"tprt"` (third-party) or `"cmpr"` (comprehensive)
`pckg`	string	Always `"1111"`
`id`	string	Your 32-char lowercase alphanumeric transaction ref
`addtnlFact.brand`	string	Vehicle make (e.g., `"Toyota"`)
`addtnlFact.model`	string	Vehicle model (e.g., `"Camry"`)
`addtnlFact.year`	string	Year of manufacture
`addtnlFact.chsssId`	string	Chassis / VIN number
`addtnlFact.engineId`	string	Engine number
`addtnlFact.rgstrtId`	string	Registration plate — no hyphens (e.g. `KJA123BC`)
`insrncDrtn`	string	Cover duration: `"7d"`, `"1m"`, `"3m"`, `"6m"`, `"1y"`

Additional Fields — Comprehensive Only¶

Field	Type	Description
`addtnlFact.vhclValueForInsrnc`	number (float)	Insured vehicle value in Naira — e.g., `4500000`
`addtnlFact.proofOfOwnrsh`	string	Base64-encoded ownership document (e.g., vehicle licence scan). Optional. If provided, the policy is auto-approved and a certificate issued immediately. If omitted, the policy is placed in Pending status and requires manual review before the certificate is issued.

Type notes: vhclValueForInsrnc must be a number, not a string — send 4500000, not "4500000". Minimum value is 500000. year must be a string (e.g., "2019", not 2019). proofOfOwnrsh is optional — omit the field entirely if the document is not available at checkout. Do not send "" or null. All other blank or missing optional fields should also be omitted entirely.

Response¶

A successful policy request returns:

{
  "exctnFdbck": {
    "id": 75,
    "id_v4": 200
  }
}

id: 75 means the request was accepted for processing. The policy is now queued — proceed to Step 4 to poll for the outcome and retrieve the certificate.

Step 4 — Check Policy Status¶

Third-party:

dump entt_{CONSUMER_ID}|insr_vhcl-tprt-1111-{TX_ID}*STATUS

Comprehensive:

dump entt_{CONSUMER_ID}|insr_vhcl-cmpr-1111-{TX_ID}*STATUS

Full request:

curl -X POST https://octamile-api.azurewebsites.net \
  -H "Content-Type: application/json" \
  -d '{
    "userInfo": {
      "id": "YOUR_PARTNER_ID",
      "athrzt": { "id": "YOUR_AUTH_ID", "key": "YOUR_AUTH_KEY" }
    },
    "cmmnd": {
      "cmmnd": "dump entt_{CONSUMER_ID}|insr_vhcl-tprt-1111-{TX_ID}*STATUS"
    }
  }'

Status values¶

`status`	Meaning	Next step
`"p"`	Pending — NSIA is processing the policy	Continue polling
`"a"`	Approved — policy number in response	Done
`"d"`	Declined — see `statusNote` for the reason	Do not retry; contact Octamile

Polling: In test mode, approval is instant — status is "a" on the first check. In live mode, poll every 5–10 seconds; vehicle policies typically approve within 60 seconds.

Approved response (live mode):

{
  "exctnFdbck": { "id": 75, "id_v4": 200 },
  "status": "a",
  "policyNo": "NSIA-MOTOR-2024-XXXXXXXX"
}

In test mode, the response also includes certUrl — a demo certificate link for integration testing. In live mode, only policyNo is returned.

Common Decline Reasons¶

Issue	Likely cause	Fix
Policy declined	Vehicle details don't match national vehicle records	Verify chassis, engine, and plate numbers against physical documents
Comprehensive declined	Proof of ownership unclear	Re-scan the vehicle licence, ensure image is readable
Premium mismatch	Vehicle value changed between quote and purchase	Re-run Step 1 before collecting payment