Handle claims

File claims for your customers, attach evidence, and follow the insurer's decision. Claim statuses are the insurer's own.

1. Collect the claimlink

If the insurer uses a claim form, fetch it with GET /products/{providerId}/{productId}/form?context=claim and collect the answers, exactly as for a quote.

2. Upload evidencelink

Each file takes two steps:

Reserve a slot with the file's exact size:

curl -X POST https://insure-api.netapps.ng/api/v1/uploads \
  -H "x-api-key: $INSURETECH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "providerId": "66f1c2a9e4b0d3a1c8e7f512",
    "purpose": "CLAIM_EVIDENCE",
    "filename": "rear-bumper.jpg",
    "mediaType": "image/jpeg",
    "bytes": 345120
  }'

PUT the raw bytes to the returned uploadUrl before expiresAt:

curl -X PUT "$UPLOAD_URL" -H "Content-Type: image/jpeg" --data-binary @rear-bumper.jpg

Keep the fileId.

3. File the claimlink

curl -X POST https://insure-api.netapps.ng/api/v1/claims \
  -H "x-api-key: $INSURETECH_API_KEY" \
  -H "Idempotency-Key: 2e4a6c8e-0b2d-4f6a-8c0e-1a3c5e7a9b1d" \
  -H "Content-Type: application/json" \
  -d '{
    "providerId": "66f1c2a9e4b0d3a1c8e7f512",
    "policyId": "pol_5e5447c7b9c6",
    "type": "MOTOR_ACCIDENT",
    "incidentAt": "2026-11-02T09:30:00.000Z",
    "formId": "form_motor_claim",
    "formVersion": 1,
    "formData": { "incident": { "description": "Rear-ended at a junction.", "occurredOn": "2026-11-02", "policeReport": true } },
    "claimedAmount": { "amountMinor": 12000000, "currency": "NGN" },
    "attachments": [{ "fileId": "file_e0d9523d054b", "purpose": "CLAIM_EVIDENCE" }],
    "payout": { "preference": "BANK_TRANSFER", "reference": "0123456789" }
  }'

Keep claimId and show your customer the claimNumber.

4. Follow the decisionlink

Listen for claim.updated, claim.settled and claim.rejected.
Read the claim with GET /claims/{providerId}/{claimId}, and its full timeline with GET /claims/{providerId}/{claimId}/history.
Add evidence the insurer asks for with POST /claims/{providerId}/{claimId}/documents.

5. Appeal or withdrawlink

Your customer wants to	Call	Note
Dispute a decision	`POST /claims/{providerId}/{claimId}/appeal`	A claim gets one appeal. Attach new evidence if you have it.
Drop an open claim	`POST /claims/{providerId}/{claimId}/withdraw`	A withdrawn claim cannot be reopened.

Nextlink

Settle your statement for the premiums you collected.