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.

See also