Credit Life Insurance Integration Guide¶

Credit Life Insurance covers outstanding loan balances in the event of death, disability, or other defined trigger events. Octamile offers four variants underwritten by SanlamAllianz, covering everything from personal and SME loans to keyman risk and mortgage protection.

All four products share the same integration flow. The main differences are in the rate and the events covered.

Products¶

Product	Code	API Rate	Covers
SME Loan Credit Life	`crlt-sme1-1111`	1%	Death (natural or accidental), Total Permanent Disability, Fire & Special Peril
Personal Loan Credit Life	`crlt-psnl-1111`	1%	Death (natural or accidental), Loss of Employment
Keyman Insurance	`crlt-kymn-1111`	0.5%	Death of key person
Mortgage Protection	`crlt-mrtg-1111`	0.85%	Death (natural or accidental), Fire & Special Peril

Indicative rates. Always call SR10 to retrieve the current rate before charging the consumer. Rates may change.

Cover period: The loan tenure — set via addtnlFact.loanTenure — is the cover period. There is no insrncDrtn field for these products.

Issuance: All four products are manually issued by the Octamile team. After submission, status will be "p" (pending) until the certificate is issued, typically within one business day.

Integration Flow¶

SR10 — Get premium quote (requires loanAmount in kobo)
SR05 — Register consumer once; store the returned id
SR15 — Submit policy request with loan details
SR20 — Poll until status: "a" and retrieve the certificate

Step 1 — Get Premium Quote¶

Send the loan amount in kobo (minor currency units: ₦1 = 100 kobo).

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_crlt-sme1-1111*PRMM",
      "seed": {
        "loanAmount": 10000000000
      }
    }
  }'

loanAmount is the full loan principal in kobo. The example above is ₦10,000,000 (ten million naira).

Response:

{
  "exctnFdbck": { "id": 75 },
  "currency": "NGN",
  "prmm": 100000000
}

prmm is the premium in kobo. In this example: 100,000,000 kobo = ₦1,000,000 (1% of ₦10M).

Type note: loanAmount must be a number (float), not a string.

Step 2 — Register Consumer¶

Standard SR05 call. Date of birth, gender, and address are required for credit life products.

{
  "cmmnd": {
    "cmmnd": "prfl entity",
    "seed": {
      "type": "s",
      "class": "h",
      "name": { "first": "Adaeze", "last": "Nwosu" },
      "gender": "f",
      "dob": { "date": "1985-03-22" },
      "addrss": { "addrss": "14 Broad Street, Lagos Island, Lagos" },
      "phoneNo": "+2348031234567",
      "eMail": "adaeze.nwosu@email.com"
    }
  }
}

Response: Returns id — store as consumer_id.

For a complete guide including returning-customer handling, see the Consumer Management Guide.

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": "crlt",
        "type": "sme1",
        "pckg": "1111",
        "id": "YOUR_32_CHAR_TX_REF",
        "addtnlFact": {
          "loanAmount": 10000000000,
          "loanTenure": 12,
          "disbursementDate": "2024-06-01",
          "loanStartDate": "2024-06-01",
          "loanEndDate": "2025-06-01"
        }
      }
    }
  }'

Required Fields (all four products)¶

Field	Type	Description
`ctgry`	string	`"crlt"`
`type`	string	`"sme1"`, `"psnl"`, `"kymn"`, or `"mrtg"`
`pckg`	string	`"1111"`
`id`	string	Your transaction reference (UUID or 32-char hex)
`addtnlFact.loanAmount`	number (float)	Loan principal in kobo — e.g., `10000000000` for ₦10M
`addtnlFact.loanTenure`	number (float)	Loan term in months — e.g., `12`
`addtnlFact.disbursementDate`	string	Date funds were disbursed — `YYYY-MM-DD`
`addtnlFact.loanStartDate`	string	Cover start date — `YYYY-MM-DD`
`addtnlFact.loanEndDate`	string	Cover end date — `YYYY-MM-DD`

SME Loan — Optional Fields¶

For SME loans where the borrower is an organisation, you may include director details:

Field	Type	Description
`addtnlFact.directorName`	string	Director's full name
`addtnlFact.directorDob`	string	Director's date of birth — `YYYY-MM-DD`

Lender Name¶

Do not include lenderName in your request. It is automatically populated from your partner account name on file with Octamile.

Medical Test Requirement¶

For loans of ₦100,000,000 or above (1,000,000,000 kobo), a medical test clearance is required before issuance. Include the following field in addtnlFact:

"medicalTestClearance": "true"

If the loan amount meets the threshold and this field is absent, SR15 returns a 406 error:

Medical test clearance required for loans of ₦100M and above

Response:

{
  "exctnFdbck": { "id": 75 }
}

Step 4 — Check Policy Status¶

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 entt_{CONSUMER_ID}|insr_crlt-sme1-1111-{TX_ID}*STATUS",
      "seed": {}
    }
  }'

Status values¶

`status`	Meaning	Next step
`"p"`	Pending — Octamile is reviewing and issuing the certificate	Poll again; see timing note below
`"a"`	Approved — certificate included in response	Done
`"d"`	Declined — see `statusNote` for the reason	Contact Octamile

Credit life issuance is a manual process. After submission, status will remain "p" until the Octamile team issues the certificate, typically within one business day. Poll every few minutes and notify the disbursement workflow asynchronously when status becomes "a".

Approved response:

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

Integration Timing¶

Purchase the credit life cover at or before loan disbursement:

Call SR10 at loan approval to display the premium to the borrower.
Collect the premium as part of loan processing.
Disburse the loan.
Immediately call SR15 with the actual disbursement date.

Do not submit the policy request days after disbursement — loanStartDate should match the actual disbursement date.

Common Errors¶

Error	Cause	Fix
`406 loanAmount not provided`	Missing or null `addtnlFact.loanAmount`	Include `loanAmount` (kobo, float) in `addtnlFact`
`406 loanTenure not provided`	Missing `addtnlFact.loanTenure`	Include loan term in whole months
`406 Medical test clearance required`	`loanAmount >= 1,000,000,000 kobo` but `medicalTestClearance` absent	Add `"medicalTestClearance": "true"` to `addtnlFact`
`406 disbursementDate / loanStartDate / loanEndDate not provided`	One of the date fields is missing	All three date fields are required in `YYYY-MM-DD` format
`400 Product specified not supported`	Incorrect product code	Use `crlt-sme1-1111`, `crlt-psnl-1111`, `crlt-kymn-1111`, or `crlt-mrtg-1111`