Claims Management

The claims API lets your integration submit a First Notice of Loss (FNOL) against any policy you have issued, then track the claim through to settlement.

---

Overview

A claim is linked to an InsuranceRequest — the record created when a policy is issued via SR15. Use the id returned by SR25 (list insure) as the irId when submitting a claim.

Claim status states:

Status	Meaning
submitted	FNOL received; awaiting review
review	Claim under active review by Octamile
approved	Claim approved; awaiting settlement
declined	Claim declined; see declineReason
paid	Settlement disbursed; see settledAmountKobo

Valid transitions: submitted → review → approved → paid, or any non-paid state → declined.

---

Submit a Claim

Command: claim submit

{
  "userInfo": { "id": "YOUR_PARTNER_UUID", "athrzt": { "id": "AUTH_ID", "key": "AUTH_KEY" } },
  "cmmnd": {
    "cmmnd": "claim submit",
    "seed": {
      "irId": "INSURANCE_REQUEST_UUID",
      "claimantName": "James Okafor",
      "claimantPhone": "+2348011112222",
      "incidentDate": "2026-06-15",
      "description": "Goods damaged in transit due to road accident.",
      "estimatedLossKobo": 250000,
      "documents": [
        {
          "fileName": "police_report.pdf",
          "contentType": "application/pdf",
          "dataBase64": "BASE64_ENCODED_FILE"
        }
      ]
    }
  }
}

Seed fields:

Field	Type	Required	Notes
irId	string (UUID)	Yes	id from list insure response
claimantName	string	Yes	Full name of the person making the claim
claimantPhone	string	Yes	International format: +2348XXXXXXXXX
incidentDate	string	Yes	Date of incident — YYYY-MM-DD format
description	string	Yes	Narrative description of the incident
estimatedLossKobo	integer	No	Estimated loss amount in kobo
agentEmail	string	No	Agent email if claim was submitted via agent portal
documents	array	No	Supporting documents — maximum 10 files

Document object fields:

Field	Type	Notes
fileName	string	Original filename including extension
contentType	string	MIME type: image/jpeg, image/png, application/pdf, etc.
dataBase64	string	Base64-encoded file contents

Response:

{ "claimId": "a875ad7e-...", "status": "submitted" }

Error responses:

Code	Reason
406	Missing required field or incidentDate not in YYYY-MM-DD format
404	irId not found or does not belong to your account

---

Check Claim Status

Command: claim status

{
  "cmmnd": {
    "cmmnd": "claim status",
    "seed": { "claimId": "a875ad7e-..." }
  }
}

Response fields:

Field	Type	Notes
claimId	string	Claim UUID
insuranceRequestId	string	The policy this claim is against
claimantName	string
claimantPhone	string
incidentDate	string	YYYY-MM-DD
description	string
estimatedLossKobo	integer	0 if not provided
status	string	See status table above
settledAmountKobo	integer	Set when status is paid
declineReason	string	Set when status is declined
createdAt	string	ISO 8601 timestamp
updatedAt	string	ISO 8601 timestamp
documents	array	Files attached at submission
notes	array	Internal review notes added by Octamile

Document entry:

Field	Type
id	string (UUID)
fileName	string
contentType	string
url	string
uploadedAt	string (ISO 8601)

Note entry:

Field	Type	Notes
id	string (UUID)
author	string	Author name
authorType	string	partner, broker, agent, or superadmin
note	string
createdAt	string (ISO 8601)

---

List Claims

Command: claim list

{
  "cmmnd": {
    "cmmnd": "claim list",
    "seed": {
      "limit": 50,
      "offset": 0,
      "status": "submitted"
    }
  }
}

Only claims belonging to your account are returned.

Seed fields (all optional):

Field	Type	Default	Notes
limit	integer	50	Maximum results to return; maximum 200
offset	integer	0	Number of records to skip for pagination
status	string	—	Filter by status: submitted, review, approved, declined, or paid

Response:

{
  "count": 12,
  "claims": [
    {
      "id": "a875ad7e-...",
      "insuranceRequestId": "e3e711c5-...",
      "claimantName": "James Okafor",
      "claimantPhone": "+2348011112222",
      "incidentDate": "2026-06-15",
      "estimatedLossKobo": 250000,
      "status": "submitted",
      "agentEmail": "",
      "createdAt": "2026-06-18T15:30:00Z"
    }
  ]
}

count reflects the total matching records; claims contains the current page.

---

Getting the irId

The irId required for claim submit is the id field from your transaction list:

{
  "cmmnd": "list insure",
  "seed": { "limit": 10 }
}

Each transaction in the response has an id field — this is the InsuranceRequestID to use as irId.

---

Returning Customer

If the policyholder previously registered as a consumer, their consumer UUID is stored with the policy. See Consumer Management for the full consumer lifecycle.

---

Notes

• Claims submitted via the API trigger a review notification to the Octamile operations team.
• Status transitions (approved, declined, paid) are performed by Octamile staff — these commands are not available to partner integrations.
• For time-sensitive claims, you can also contact Octamile directly via business@octamile.com.