Skip to content

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",
  "policyNo": "AXA-HLTH-2024-XXXXXXXX"
}

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

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": {} }
  }'

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.

See also