Health Insurance Integration Guide¶

Health insurance. One product, fixed rates.

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	Cover periods	Monthly	Quarterly	6-month	Annual
`hlth-axam-1111`	`1m`, `3m`, `6m`, `1y`	₦1,250	₦3,750	₦7,500	₦15,000

Step 1 — Get Premium Quote¶

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_hlth-axam-1111*PRMM",
      "seed": {
        "insrncDrtn": "1m"
      }
    }
  }'

Seed field	Type	Description
`insrncDrtn`	string	Duration: `"1m"`, `"3m"`, `"6m"`, `"1y"`

Response:

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

Step 2 — Register Consumer¶

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

{
  "cmmnd": {
    "cmmnd": "prfl entity",
    "seed": {
      "type": "s",
      "class": "h",
      "name": { "first": "Adaeze", "last": "Nwosu" },
      "dob": { "date": "1995-03-08" },
      "phoneNo": "+2348051234567",
      "eMail": "adaeze.nwosu@email.com"
    }
  }
}

Response: Returns id — store as consumer_id.

Step 3 — Request Policy¶

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": "entt_{CONSUMER_ID}: insure",
      "seed": {
        "ctgry": "hlth",
        "type": "axam",
        "pckg": "1111",
        "id": "YOUR_UUID_V4_TX_REF",
        "insrncDrtn": "1m",
        "addtnlFact": {
          "RsdncState": "Lagos",
          "RsdncLga": "Lagos Island",
          "hospital": "Lagos Island General Hospital"
        }
      }
    }
  }'

Required Fields¶

Field	Type	Description
`ctgry`	string	`"hlth"`
`type`	string	`"axam"`
`pckg`	string	`"1111"`
`id`	string	Your transaction UUID
`insrncDrtn`	string	Cover period: `"1m"`, `"3m"`, `"6m"`, `"1y"`
`addtnlFact.RsdncState`	string	Consumer's state of residence — max 250 chars (e.g., `"Lagos"`, `"FCT"`)
`addtnlFact.RsdncLga`	string	Consumer's Local Government Area — max 250 chars
`addtnlFact.hospital`	string	Preferred approved hospital — max 300 chars

Response:

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

Step 4 — Check Policy Status¶

dump entt_{CONSUMER_ID}|insr_hlth-axam-1111-{TX_ID}*STATUS

Status values¶

`status`	Meaning	Next step
`"p"`	Pending — AXA 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. In live mode, poll every 5–10 seconds; health policies typically approve within 60 seconds.

Approved response (live mode):

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

AXA issues no certificate of its own (HMO cover is member-number + hospital access, not a certificate). On approval, Octamile generates the member's AXA Pass policy document — a personalized Policy Schedule page merged with the official AXA Pass Terms & Conditions — and returns it as a base64 PDF (crtfctType: "pdf"), the same way marine products return a document. The member/policy number is printed inside the document. In test mode, the response instead includes a demo certUrl for integration testing.

After Issuance — Your Policy Document & Accessing Care¶

Communicate the following to the customer (the Octamile customer portal email does this automatically; partners issuing via API should relay the same):

Download the policy document. The approval response carries the PDF (schedule + full Terms & Conditions). It shows the member/policy number, plan, cover start & expiry, assigned hospital, premium, and benefit limits.
5 working-day waiting period. Cover is active once premium is paid, but care is only accessible after a 5 working-day waiting period (AXA registration/underwriting). The document states the care-accessible-from date.
Accessing care: when the member needs care, they visit their assigned hospital (shown in the document) and present their name + member number. Covered consultations, tests and drugs are provided at no extra cost, subject to benefit limits. Telemedicine (speak to a doctor remotely) is also available.
One hospital per quarter — the member may change their chosen hospital each quarter.
Benefit limits: overall ₦25,000 per quarter; accidents & emergencies up to ₦50,000/year; funeral benefit ₦100,000 (after 6 months). Surgery and ante-natal care have a 12-month moratorium. A full exclusions list is in the Terms & Conditions pages.
Renewal: cover terminates at the end of the term; a 7-day grace period applies before accrued benefits are forfeited.

Member helpline / telemedicine number: pending confirmation from AXA — to be added to the policy document and customer email once provided.

Approved Hospitals¶

Use dump hlth_*HSPTLS to fetch the current list of approved hospitals:

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 hlth_*HSPTLS", "seed": {} }
  }'

The response returns a hospitals array. Each entry has these fields:

{
  "hospitals": [
    {
      "name": "Chukwuebuka Hospital",
      "address": "50 School Road Umuahia",
      "city": "Umuahia",
      "lga": "Umuahia South",
      "state": "Abia"
    }
  ]
}

Field	Type	Description
`name`	string	Hospital / facility name
`address`	string	Street address
`city`	string	City
`lga`	string	Local Government Area
`state`	string	State

Present this list to the consumer during checkout so they can select their preferred hospital.

Residence Details¶

Use the consumer's current state of residence, not state of origin. Spell the state in full (e.g., "Rivers" not "Rivers State", "FCT" for Abuja). All 36 states and FCT are accepted.

Group Health Enrolment (Employer Plans)¶

In addition to individual health policies issued via the API, the platform supports group health enrolment for employer clients managing staff cover through an HMO.

Features available in the dashboard for employer groups:

Roster management — add, remove, and bulk-import employees; sub-group filtering (e.g. by department or role)
Monthly roster confirmation with audit log
Billing preview and invoice history with payment status tracking
Digital member card — each enrolled employee receives a tokenised card link by email when their HMO member ID is confirmed; the card is mobile-first and can be bookmarked or added to the home screen

Communications sent automatically:

Welcome email on enrolment (plan, HMO name, what to expect)
Member activation email when the HMO ID is assigned (includes the digital card link)
Invoice issued and payment confirmed emails to the employer admin
Renewal reminders at 60, 30, and 14 days before policy expiry

Group enrolment is managed through the dashboard and is not exposed via the REST API. Contact your account manager to set up an employer group policy.