Quickstart

Get a working policy in under 20 minutes. This guide uses Vehicle Insurance — Third-party as the example. The same 4-step pattern works for every product.

Try it without code first: The Partner Dashboard lets you run a live quote, buy a policy, and download a certificate through a UI. Useful for understanding the flow before you build.

---

What You Need

Three credentials from Octamile:

PARTNER_ID=your_partner_id        # UUID v4 format, e.g. ac346b72-e8fe-4677-b9e2-dc6a763fba82
AUTH_ID=your_auth_id              # UUID v4 format
AUTH_KEY=your_auth_key            # Base64 string

Important: PARTNER_ID and AUTH_ID are UUID v4 — the standard 8-4-4-4-12 hex format. Random alphanumeric strings that look like UUIDs but aren't will be rejected. Use the exact values Octamile provides.

Store these as environment variables. Every request uses them.

Your account starts in TEST mode. In test mode, all policies are auto-approved instantly and the certificate response returns a demo policy number and URL instead of a real certificate. No real insurer is contacted and no premium is billed. This lets you build and test the full flow end-to-end before going live. When you're ready to issue real policies, toggle the environment badge in the Partner Dashboard — see Going Live.

---

The Pattern

One endpoint. One method. Every time.

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

Every request body follows this shape:

{
  "userInfo": {
    "id": "YOUR_PARTNER_ID",
    "athrzt": {
      "id": "YOUR_AUTH_ID",
      "key": "YOUR_AUTH_KEY"
    }
  },
  "cmmnd": {
    "cmmnd": "the-command-string",
    "seed": { }
  }
}

Every response includes exctnFdbck:

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

exctnFdbck.id	Meaning
75	Success
55	Error — read exctnFdbck.elbrtn for the reason
35	API at capacity — wait 2–5 seconds and retry

The API always returns HTTP 200. Never check the HTTP status code — check exctnFdbck.id instead.

---

The 4-Step Flow

Step 1  Get premium quote      → how much to charge the consumer
Step 2  Register consumer      → get their consumer_id
                 ↓
        Collect payment from consumer
                 ↓
Step 3  Request policy         → submit the insurance request
Step 4  Check status / get certificate

Collect payment before Step 3. The policy request processes regardless — but you must have the premium in hand before submitting.

---

Step 1 — Get Premium Quote

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

Response:

{
  "currency": "NGN",
  "prmm": 15000,
  "exctnFdbck": { "id": 75, "id_v4": 200 }
}

prmm is the premium in whole Naira. Display this to your user and collect payment before continuing.

How duration works — it varies by product:

Product group	How to specify cover period
Vehicle, Device Warranty, Health, Laptop	"insrncDrtn" string in seed — e.g. "1y", "6m", "3m", "1m"
Loan Repayment Guaranty	"LoanTenure" (months) in seed — no insrncDrtn
Travel Insurance	"insrncDrtn" string in seed — e.g. "7d", "15d", "30d", "62d", "92d", "6m", "12m". "departureDate" + "returnDate" go in Step 3 addtnlFact, not the quote.
Goods-in-Transit	"dprtrDateTime" + "estmtdArrvlDateTime" in addtnlFact — per shipment, no insrncDrtn
Marine Export / Import	Per voyage — no insrncDrtn

Premium quick-reference:

Indicative rates. Premiums shown are examples and subject to change. Always use Step 1 (SR10) to get the current rate before collecting payment from your customer.

Product	Code	Pricing	Notes
Vehicle — Third-party	vhcl-tprt-1111	₦15,000 / year	Fixed rate
Vehicle — Comprehensive	vhcl-cmpr-1111	5% of vehicle value / year	Min ₦500,000
Device Warranty — Basic	phnn-flx1-1111	₦3,600 / 6m · ₦7,200 / 1y	Pass insrncDrtn
Device Warranty — Comprehensive	phnn-flx2-1111	₦10,800 / 6m · ₦21,600 / 1y	Pass insrncDrtn
Loan Repayment Guaranty	lrgg-stnd-1111	LoanAmount × 0.5% × tenure_months	Pass LoanAmount + LoanTenure
Health Insurance	hlth-axam-1111	₦1,250/m · ₦7,500/6m · ₦15,000/1y	Pass insrncDrtn
Travel Insurance	ltix-stnd-1111	Varies by trip duration and plan	Pass departureDate + returnDate in addtnlFact
Goods-in-Transit	gtrn-stnd-1111	Tiered by goodsValue	Pass shipment datetimes
Marine Export	mexx-stnd-1111	0.25% of cargo value · min ₦5,000	Per voyage
Marine Import	mrnn-stnd-1111	0.25% of cargo value · min ₦5,000	Per voyage

---

Step 2 — Register Consumer

Create a profile for the consumer. If they've purchased through your platform before, you already have their consumer_id — skip this step.

curl -X POST https://octamile-api.azurewebsites.net \
  -H "Content-Type: application/json" \
  -d '{
    "userInfo": {
      "id": "'"$PARTNER_ID"'",
      "athrzt": { "id": "'"$AUTH_ID"'", "key": "'"$AUTH_KEY"'" }
    },
    "cmmnd": {
      "cmmnd": "prfl entity",
      "seed": {
        "class": "h",
        "name": { "first": "Amaka", "last": "Okafor" },
        "gender": "f",
        "dob": { "date": "1990-05-15" },
        "addrss": { "addrss": "12 Marina Road, Lagos Island, Lagos" },
        "phoneNo": "+2348012345678",
        "eMail": "amaka.okafor@email.com"
      }
    }
  }'

Response:

{
  "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "id_uuid": "a1b2c3d4-e5f6-a1b2-c3d4-e5f6a1b2c3d4",
  "exctnFdbck": { "id": 75, "id_v4": 200 }
}

Save id in your database. This is the consumer_id — a 32-character hex string (no hyphens) that identifies this person permanently in the AIMS system. id_uuid is the same value in standard UUID format — either form is accepted in the entt_ command.

Consumer fields:

Field	Type	Required	Notes
class	string	Yes	Always "h"
name.first	string	Yes
name.last	string	No	Recommended
name.middle	string	No
gender	string	No	"f" or "m"
dob.date	string	No	YYYY-MM-DD
dob.proof	string	No	Base64-encoded image or PDF
addrss.addrss	string	No	Full contact address
phoneNo	string	Yes (for individuals)	International format (+234...)
eMail	string	No
ntnlty	string	No	Nationality
stateOfOrigin	string	No	Nigerian state
mrtlStatus	string	No	"single" · "married" · "divorced" · "widowed"
socialID.type	string	No	"nidd" (NIN) · "bvnn" (BVN) · "ipss" (passport) · "dlcn" (driver's licence) · "vcrd" (voter's card)
socialID.id	string	No	The ID number
socialID.image	string	No	Base64 image of the ID document

---

Step 3 — Request Policy

Submit the insurance request. Only call this after collecting payment.

Generate a transaction reference — a UUID identifying this policy in your system:

TX_ID=$(python3 -c "import uuid; print(uuid.uuid4())")
# example: 550e8400-e29b-41d4-a716-446655440000

curl -X POST https://octamile-api.azurewebsites.net \
  -H "Content-Type: application/json" \
  -d '{
    "userInfo": {
      "id": "'"$PARTNER_ID"'",
      "athrzt": { "id": "'"$AUTH_ID"'", "key": "'"$AUTH_KEY"'" }
    },
    "cmmnd": {
      "cmmnd": "entt_a1b2c3d4-e5f6-a1b2-c3d4-e5f6a1b2c3d4: insure",
      "seed": {
        "ctgry": "vhcl",
        "type": "tprt",
        "pckg": "1111",
        "id": "'"$TX_ID"'",
        "insrncDrtn": "1y",
        "addtnlFact": {
          "brand": "Toyota",
          "model": "Camry",
          "year": "2019",
          "chsssId": "JTDBE32KX30123456",
          "engineId": "2AR1234567",
          "rgstrtId": "KJA123BC"
        }
      }
    }
  }'

Replace a1b2c3d4-e5f6-a1b2-c3d4-e5f6a1b2c3d4 in the cmmnd string with the actual consumer_id UUID from Step 2. Both hyphenated and un-hyphenated forms are accepted.

Response:

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

A 75 here means the request was accepted and is being processed. Move to Step 4.

Instant approval: Some requests are approved immediately and include crtfct in this response. If crtfct is present, you can skip Step 4 — the certificate is already in hand.

Idempotency: The id (transaction reference) must be unique per policy. If Step 3 fails due to a network error, do not reuse the same TX_ID — generate a new one. The API rejects duplicate IDs with "Data cmmnd.seed.id already in use". Store your TX_ID before calling Step 3 so you can track the issuance even if the response is lost. If you get exctnFdbck.id: 35 (capacity), retry the same TX_ID with exponential backoff — that error means the request was not stored.

Policy seed fields:

Field	Value
ctgry	Product category (see table below)
type	Product type (see table below)
pckg	Always "1111"
id	Your UUID transaction reference
insrncDrtn	Cover duration — only for Vehicle, Device Warranty, Health, Laptop. Omit for Travel, GIT, Marine, and Loan (each uses its own date/tenure fields).
addtnlFact	Product-specific fields (see each product guide)

ctgry and type by product:

Product	ctgry	type
Vehicle — Third-party	vhcl	tprt
Vehicle — Comprehensive	vhcl	cmpr
Device Warranty — Basic	phnn	flx1
Device Warranty — Comprehensive	phnn	flx2
Device Warranty — Flex	phnn	flx3
Loan Repayment Guaranty	lrgg	stnd
Goods-in-Transit	gtrn	stnd
Health Insurance	hlth	axam
Travel Insurance	ltix	stnd
Marine Export	mexx	stnd
Marine Import	mrnn	stnd

---

Step 4 — Get Certificate

Poll for the policy status. If you provided a webHook URL in addtnlFact during Step 3, you can wait for the notification instead of polling.

curl -X POST https://octamile-api.azurewebsites.net \
  -H "Content-Type: application/json" \
  -d '{
    "userInfo": {
      "id": "'"$PARTNER_ID"'",
      "athrzt": { "id": "'"$AUTH_ID"'", "key": "'"$AUTH_KEY"'" }
    },
    "cmmnd": {
      "cmmnd": "dump entt_CONSUMER_ID|insr_vhcl-tprt-1111-TX_ID*STATUS"
    }
  }'

Replace CONSUMER_ID with the consumer's id from Step 2, and TX_ID with your transaction reference from Step 3.

Response — approved (live mode, real certificate):

{
  "status": "a",
  "crtfct": "/9j/4AAQSkZJRgABAQAA...",
  "crtfctType": "jpg",
  "exctnFdbck": { "id": 75, "id_v4": 200 }
}

Response — approved (test mode, sample certificate):

{
  "status": "a",
  "certUrl": "https://octamile-dashboard.azurewebsites.net/demo-cert?product=vhcl-tprt-1111&txId=...",
  "exctnFdbck": { "id": 75, "id_v4": 200 }
}

In test mode the response returns certUrl (a URL to a sample certificate page) instead of crtfct (base64). In live mode, crtfct is a base64-encoded image or PDF issued by the insurer. Some products additionally return policyNo instead of a certificate — see the product-specific guide.

Response — still processing:

{
  "status": "p",
  "tmstmp": "2025-01-15 09:20:00",
  "exctnFdbck": { "id": 75, "id_v4": 200 }
}

status	Meaning	What to do
"p"	Processing	Wait 10–30 seconds and poll again
"a"	Approved	Decode crtfct and deliver to consumer
"d"	Declined	Check statusNote for the reason

Decode the certificate:

// Node.js
const fs = require('fs');
const buf = Buffer.from(response.crtfct, 'base64');
fs.writeFileSync(`certificate.${response.crtfctType}`, buf);

# Python
import base64
data = base64.b64decode(response['crtfct'])
with open(f"certificate.{response['crtfctType']}", 'wb') as f:
    f.write(data)

---

What to Store

Value	Why
consumer_id	Required for all future requests for this consumer — never re-register the same person
Transaction reference (tx_id)	Required to check status and for claims
Premium amount	Reconciliation
Certificate (decoded)	Re-deliver to consumer on demand

---

Troubleshooting

exctnFdbck.id is 55 with a field name in elbrtn. A required field is missing or the wrong type. Numeric fields (LoanAmount, goodsValue, vhclValueForInsrnc) must be numbers — not strings. LoanTenure must be a number too.

exctnFdbck.id is 35. The API is temporarily at capacity. Wait 2–5 seconds and retry. Do not submit a duplicate policy — use the same tx_id.

exctnFdbck.elbrtn says "Your authorization is not genuine". Your AUTH_KEY is wrong. Keys are base64-encoded — make sure you're sending the full string including any trailing = padding.

Status stays "p" for more than a few minutes. This is normal for some products (especially vehicle and marine). Add "webHook": "https://yourplatform.com/webhooks/octamile" inside addtnlFact in Step 3 to receive a push notification instead of polling.

Step 4 returns certUrl instead of crtfct, or the dashboard shows "Not Ready". Your account is in test mode. certUrl points to a sample certificate — this is correct test-mode behaviour. To get real insurer-issued certificates, switch to live mode: send set env_live (see Going Live). Do not go live until you have confirmed the full flow works end-to-end in test mode.

Policies approved but certificate is a sample / watermarked "DEMO". Same as above — account is in test mode. All test-mode policies auto-approve with a sample cert regardless of the data submitted.

"Data cmmnd.seed.id is invalid" in Step 3. The id field in seed must be a valid UUID v4 (e.g., 550e8400-e29b-41d4-a716-446655440000). Use a UUID generator — do not use a random string or truncate a UUID.

---

Next Steps

• API Reference — full command reference
• Authentication Guide — credential rotation and error handling
• Product guides in guides/ — required addtnlFact fields for each product