API Reference — Overview¶

The Single Endpoint¶

All AIMS API requests go to one URL:

POST https://octamile-api.azurewebsites.net

There are no separate endpoints per resource or product. Everything is controlled by the cmmnd field in your request body. The HTTP method is always POST. The Content-Type is always application/json.

Request Structure¶

Every request shares the same top-level structure:

{
  "userInfo": {
    "id": "YOUR_PARTNER_ID",
    "athrzt": {
      "id": "YOUR_AUTHORIZATION_ID",
      "key": "YOUR_AUTHORIZATION_KEY"
    }
  },
  "cmmnd": {
    "cmmnd": "<COMMAND_STRING>",
    "seed": {
      // command-specific parameters
    }
  }
}

Field	Type	Required	Description
`userInfo.id`	string	Yes	Your partner ID assigned by Octamile
`userInfo.athrzt.id`	string	Yes	Your authorization ID
`userInfo.athrzt.key`	string	Yes	Your authorization key
`cmmnd.cmmnd`	string	Yes	The command to execute (see Commands below)
`cmmnd.seed`	object	Varies	Parameters for the command. Not required for status checks

Response Structure¶

Every response returns HTTP 200, regardless of success or failure. Check exctnFdbck.id in the response body to determine the outcome:

{
  "exctnFdbck": {
    "id": 75,
    "id_v4": 200
  },
  "...additional fields depending on the command..."
}

On error:

{
  "exctnFdbck": {
    "id": 55,
    "id_v4": 406,
    "elbrtn": "human-readable error message"
  }
}

Execution Status Codes¶

`exctnFdbck.id`	`exctnFdbck.id_v4`	Meaning	What to do
`75`	`200`	Success	Continue to next step
`35`	`503`	API at capacity	Retry with backoff (2s → 4s → 8s)
`55`	`4xx` / `5xx`	Error — read `elbrtn` for the reason	Fix the request; do not retry blindly

elbrtn contains a plain-English explanation of what went wrong (e.g. "Data cmmnd.seed.LoanAmount not a number"). Log it during development — it tells you exactly which field has the problem.

Field Name Glossary¶

The AIMS API uses abbreviated field names throughout. This table maps every abbreviation to its meaning.

Abbreviation	Full name	Where used
`cmmnd`	command	Top-level wrapper; also the command string field
`userInfo`	user information	Auth wrapper on every request
`athrzt`	authorization	Auth key container
`exctnFdbck`	execution feedback	Response status wrapper
`elbrtn`	elaboration	Human-readable error message
`id_v4`	id (v4 format)	HTTP-equivalent status code in the response
`seed`	seed data	Command parameters
`entt`	entity	Consumer/policy identifier prefix
`ipck`	insurance package	Product quote command prefix
`insr`	insurance	Policy identifier component
`prmm`	premium	Policy cost
`nett`	net premium	Premium after fees
`insrncDrtn`	insurance duration	Cover period (e.g. `"1y"`, `"30d"`)
`drtn`	duration	Alias for `insrncDrtn` on some products
`addtnlFact`	additional facts	Product-specific fields for quoting and issuance
`prfl`	profile	Consumer registration command prefix
`crtfct`	certificate	Base64-encoded policy document
`crtfctType`	certificate type	File format of the certificate (`"pdf"`, `"docx"`, `"jpg"`)
`certUrl`	certificate URL	URL to a hosted certificate (travel, test mode)
`policyNo`	policy number	Insurer-assigned policy reference
`tmstmp`	timestamp	Issuance date and time
`ctgry`	category	Product category
`pckg`	package	Product tier/package
`enrch`	enrichment	Data lookup command prefix (e.g. NIID vehicle check)
`niid`	NIID	Nigeria Insurance Industry Database
`vhcl`	vehicle	Vehicle insurance product prefix
`phnn`	phone	Device warranty product prefix
`lapt`	laptop	Laptop warranty product prefix
`ltix`	land travel international	Travel insurance product prefix
`hlth`	health	Health insurance product prefix
`gtrn`	goods in transit	Goods-in-transit product prefix
`mexx`	marine export	Marine export insurance product prefix
`mrnn`	marine	Marine import insurance product prefix
`allr`	all risk	All Risk insurance product prefix
`firb`	fire and burglary	Fire & Burglary insurance product prefix
`lrgg`	loan repayment guaranty	Loan protection product prefix
`pacc`	personal accident	Personal Accident insurance product prefix
`plby`	public liability	Public Liability insurance product prefix
`pind`	professional indemnity	Professional Indemnity insurance product prefix

Command Reference¶

All commands are sent as the cmmnd.cmmnd string. Replace {PLACEHOLDERS} with your actual values.

Command	`cmmnd.cmmnd` value	Handler	Auth
Register / update consumer	`prfl entity`	SR05	Partner
Get premium quote	`dump ipck_{PRODUCT_CODE}*PRMM`	SR10	Partner
Issue policy	`entt_{CONSUMER_ID}: insure`	SR15	Partner
Check policy status	`dump entt_{CONSUMER_ID}\\|insr_{PRODUCT_CODE}-{TX_ID}*STATUS`	SR20	Partner
List my transactions	`dump entt_*`	SR25	Partner
List all partners' transactions	`dump entt_*ADMIN`	SR25	SuperAdmin only
List my consumers	`dump entt_*CSTMRS`	SR26	Partner
List all partners' consumers	`dump entt_*CSTMRS_ADMIN`	SR26	SuperAdmin only
AXA hospital list	`dump hlth_*HSPTLS`	SR27	Partner
Manually approve a transaction	`appr entt_{CONSUMER_ID}\\|insr_{PRODUCT_CODE}-{TX_ID}`	SR30	SuperAdmin only
NIID vehicle enrichment	`enrch niid_vehicle`	SR_ENRCH	Partner (activated per account)

Notes: - {CONSUMER_ID} — UUID returned by prfl entity, with or without hyphens (auto-formatted) - {PRODUCT_CODE} — e.g. vhcl-tprt-1111 (see Product Codes table below) - {TX_ID} — the UUID you generated when issuing the policy - SuperAdmin commands are available to Octamile's internal partner account only - NIID vehicle enrichment must be activated for your account; billed at ₦150 per lookup

The standard 4-step flow¶

Most integrations follow this sequence:

prfl entity — register the consumer once; store the returned id
dump ipck_{code}*PRMM — fetch the premium to display to the consumer
entt_{id}: insure — submit the policy after collecting payment
dump entt_{id}|insr_{code}-{txId}*STATUS — poll until status: "a" and retrieve the certificate

Check the Step 3 response before polling. For some products the issuance response includes crtfct (base64 certificate) and crtfctType immediately. If present, skip Step 4. See the product guide for which products support instant issuance.

Product Codes¶

Product	Code
Vehicle Insurance — Third-party	`vhcl-tprt-1111`
Vehicle Insurance — Comprehensive	`vhcl-cmpr-1111`
Phone Warranty — Basic	`phnn-flx1-1111`
Phone Warranty — Comprehensive	`phnn-flx2-1111`
Phone Warranty — Premium	`phnn-flx3-1111`
Laptop Warranty — Basic	`lapt-flx1-1111`
Laptop Warranty — Comprehensive	`lapt-flx2-1111`
Travel Insurance (International)	`ltix-stnd-1111`
Goods-in-Transit Insurance	`gtrn-stnd-1111`
Health Insurance — AXA	`hlth-axam-1111`
Loan Repayment Guaranty	`lrgg-stnd-1111`
Marine Export Insurance	`mexx-stnd-1111`
Marine Import Insurance — Basic (ICC C)	`mrnn-stnd-1111`
Marine Import Insurance — Comprehensive (ICC A)	`mrnn-cmpr-1111`
All Risk Insurance	`allr-stnd-1111`
Fire & Burglary Insurance	`firb-stnd-1111`

Policy Status Values¶

When checking policy status (Step 4), the status field returns:

Value	Meaning
`"p"`	Processing — policy is under review
`"a"`	Approved — policy is active; certificate included in response
`"d"`	Declined — see `statusNote` for the reason

Cover Duration Format¶

The insrncDrtn and drtn fields accept durations in this format:

Format	Meaning	Used by
`"7d"`	7 days	Travel Insurance
`"15d"`	15 days	Travel Insurance (standard + Hajj)
`"25d"`	25 days	Travel Insurance — Hajj & Umrah only
`"30d"`	30 days	Travel Insurance
`"45d"`	45 days	Travel Insurance — Hajj & Umrah only
`"62d"`	62 days	Travel Insurance
`"92d"`	92 days	Travel Insurance
`"1m"`	1 month	Health, Marine, All Risk, Fire & Burglary, Loan Repayment Guaranty
`"3m"`	3 months	Health, Marine, All Risk, Fire & Burglary
`"6m"`	6 months	Device Warranty, Travel Insurance, Marine, All Risk, Fire & Burglary, Loan
`"1y"`	1 year	Vehicle, Device Warranty, Health, All Risk, Fire & Burglary
`"12m"`	12 months	Travel Insurance, Loan Repayment Guaranty

Transaction Reference Requirements¶

When submitting a policy request (Step 3), you must generate a transaction reference (id in the seed). This is your internal identifier for the policy.

Rules: - Must be a valid UUID (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) - A 32-character hex string without hyphens is also accepted and auto-formatted - Must be globally unique across all your transactions - Store it — you need it to check status and for claims

How to generate:

// Node.js (built-in, v14.17+)
const { randomUUID } = require('crypto');
const txId = randomUUID(); // e.g. 550e8400-e29b-41d4-a716-446655440000

# Python
import uuid
tx_id = str(uuid.uuid4())  # e.g. 550e8400-e29b-41d4-a716-446655440000

# Shell
python3 -c "import uuid; print(uuid.uuid4())"

Consumer ID¶

⚠️ Create each consumer once. Store their consumer_id. Reuse it for every future purchase.

Calling prfl entity on every checkout creates duplicate consumer records, breaks policy history, and inflates your customer count. See the Consumer Management Guide for the correct integration pattern.

When you register a consumer (Step 2), the response returns an id field. This is the consumer's permanent ID in the AIMS system — a UUID that links all their policies across all products.

Store this ID mapped to your own customer identifier. You need it to: - Purchase any insurance product for this consumer (SR15) - Check policy status (SR20) - Process claims (when available)

Returning customers: Look up the consumer_id from your own database and skip Step 2 entirely. Go straight to Step 3.

Idempotency safety net: If you call prfl entity again with the same email address under the same partner account, the API returns the existing consumer's ID rather than creating a new record. This handles edge cases (e.g., lost database records) but should not replace storing the ID in your system.

For a complete guide including code examples, anti-patterns, and the consumer lifecycle: Consumer Management Guide →

Certificate Delivery¶

When a policy is approved, the certificate is returned in one of two forms depending on the product.

Inline Base64 certificate — crtfct + crtfctType in the response body:

{
  "exctnFdbck": { "id": 75, "id_v4": 200 },
  "status": "a",
  "crtfct": "<base64-encoded-bytes>",
  "crtfctType": "pdf"
}

`crtfctType`	Format	Products
`"pdf"`	PDF document	Most products
`"docx"`	Word document	Marine Export, Goods-in-Transit

Decoding the certificate:

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

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

URL redirect certificate — certUrl in the response body (some products in live mode):

{
  "exctnFdbck": { "id": 75, "id_v4": 200 },
  "status": "a",
  "certUrl": "https://..."
}

When certUrl is present, redirect the user to that URL to view or download the certificate directly.

Date and Time Formats¶

Use case	Format	Example
Date of birth, loan dates	`YYYY-MM-DD`	`1990-05-15`
Transit departure / arrival	`YYYY-MM-DD HH:MM:SS`	`2024-03-20 08:30:00`

All times are in local Nigerian time (WAT, UTC+1).

Phone Number Format¶

Phone numbers must use international format with a + prefix:

Country	Format	Example
Nigeria	`+234XXXXXXXXXX`	`+2348012345678`

Do not include leading zeros after the country code. +2340812345678 is wrong; +2348012345678 is correct.

Common Errors¶

Error	Cause	Fix
`exctnFdbck.id: "55"` with a field name in the message	Numeric field sent as string	Cast to number before sending: `vhclValueForInsrnc`, `goodsValue`, `LoanAmount`, `sumInsured` → float; `year`, `goodsQuantity`, `LoanTenure` → integer
406 response	Blank field (`""` or `null`) included in `addtnlFact`	Strip all empty fields before sending — omit rather than send blank
`exctnFdbck.id: "55"` immediately	Bad credentials or malformed JSON	Validate `userInfo` values; check JSON syntax
`exctnFdbck.id: "35"`	API at capacity	Retry with exponential backoff: 2s → 4s → 8s

Rate Limits¶

Limit	Value
Requests per minute (per partner)	60
Burst allowance	10 additional requests
Response when exceeded	`429 Too Many Requests`

If you exceed the limit you will receive:

{
  "exctnFdbck": { "id_v4": 429, "id": 55, "elbrtn": "Rate limit exceeded" }
}

Back off and retry after 1–2 seconds. The limit resets on a rolling per-minute window. For batch workflows (e.g. issuing many policies in sequence), add a small delay between requests to stay within the limit.

Test vs Live Mode¶

Every partner account operates in either test or live mode. You can switch modes via the dashboard or the API.

In test mode: All policies are auto-approved and return a demo certificate URL. No real insurer is contacted. Safe for development and integration testing.

In live mode: Policies are routed to real insurers. Certificates are real and legally valid. Premiums are billable.

Switching mode¶

Toggle the environment badge in the top-right corner of the Partner Dashboard. The change takes effect immediately for all subsequent API calls from your account.

Next Steps¶

Quickstart Guide — complete walkthrough with working examples
Authentication Guide — credentials and error handling
Product guides in guides/ — per-product integration flows