Service the policy

After the sale, your customer will want their documents, changes to their cover, a renewal, or a cancellation. Every call here takes the providerId and policyId you kept from the purchase.

Show the policylink

curl https://insure-api.netapps.ng/api/v1/policies/66f1c2a9e4b0d3a1c8e7f512/pol_5e5447c7b9c6 \
  -H "x-api-key: $INSURETECH_API_KEY"

The policy is read live from the insurer, so its status is current. GET /policies lists every policy your business sold.

Give your customer their documentslink

1. List them with GET /policies/{providerId}/{policyId}/documents.
2. Download one with GET /policies/{providerId}/{policyId}/documents/{documentId}. The answer is the file itself, such as a PDF certificate, not JSON.

Listen for document.ready to learn when a new document appears.

Change the cover mid-termlink

An endorsement is a change such as a higher sum assured or an added driver. It takes two calls, so your customer sees the cost before anything changes.

1. Fetch the endorsement form: GET /products/{providerId}/{productId}/form?context=endorsement.
2. Price the change with POST /policies/{providerId}/{policyId}/endorsements, sending formId, formVersion and the answers.
3. Show endorsement.premiumDelta. Positive means your customer pays more, negative means a refund.
4. Confirm before endorsement.expiresAt with POST /policies/{providerId}/{policyId}/endorsements/{endorsementId}/confirm. When the change costs more, charge your customer exactly the delta first and send it as payment.

A price increase is billed on your next statement. A decrease is credited on it, and you return it to your customer.

Renewlink

When policy.renewal_due arrives:

1. Ask for a renewal quote with POST /policies/{providerId}/{policyId}/renewal-quote. There is no request body.
2. The answer is an ordinary quote with renewalOf set. A 202 means the insurer is still pricing it: wait for quote.completed.
3. Charge your customer and buy it with POST /purchases, exactly like a first sale.

Cancellink

curl -X POST https://insure-api.netapps.ng/api/v1/policies/66f1c2a9e4b0d3a1c8e7f512/pol_5e5447c7b9c6/cancel \
  -H "x-api-key: $INSURETECH_API_KEY" \
  -H "Idempotency-Key: 9d1f3b5a-7c9e-4b1d-a3f5-8e0c2a4b6d8f" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "CUSTOMER_REQUEST", "note": "The customer sold the vehicle." }'

cancellation.refund.payTo says who refunds your customer:

When an insurer does not offer somethinglink

Not every insurer supports every change. A 422 FEATURE_NOT_SUPPORTED names the missing feature in details.feature. Retrying will not help: tell your customer to contact the insurer.

Nextlink

Handle claims on the policies you sold.