API Reference

Called once, after your organization has been approved and a one-time activation token has been issued to your contact email. Sets the account's password and marks it active. The token is single-use.

HTTP 204 No Content on success.

Standard OAuth2 password flow. Sends credentials as application/x-www-form-urlencoded form data, not JSON.

• •Login is blocked while your organization (insurance company or broker) is pending, rejected, or suspended.

Changes the password of the currently authenticated account.

Registers a new insurance company. It starts in pending status and must be approved by an Insureflow operator before the contact email receives an activation token.

Returns the current state of the insurance company record.

Every broker with an active assignment to this insurer — the many-to-many relationship, not a fixed 1:1 broker.

Array of broker objects (same shape as the Brokers section's GET response).

Registers the account Insureflow transfers premium proceeds into (net of commission) after each successful payment. Performs a live NIBSS name-enquiry lookup before saving — the response's settlement_account_name is whatever that lookup confirmed, never a value you supply directly.

Returns the updated company object.

• •Required before settlement payouts fire. Payments can still be collected without it, but proceeds won't transfer until an account is on file.
• •The NIBSS lookup is real even in sandbox — a dummy account number returns HTTP 424.

Registers a new broker. Starts in pending status.

Broker roles can only retrieve their own broker record.

Every insurer with an active assignment to this broker.

Array of insurance company objects (same shape as the Insurance Companies section's GET response).

Creates an additional login under the same broker organization with the Broker Staff role — full transacting access, but cannot manage other staff accounts.

full_name is the only required field; the rest improve reminder delivery and identity verification.

Same shape as the create response above.

An Insurance Company Admin sees every policyholder across their assigned brokers by default; a broker sees only their own.

Array of policyholder objects.

Same shape as the create response above.

user_id narrows to one policyholder's policies; omitted returns every policy you can see.

Array of policy objects.

The full installment schedule for one policy, in due-date order.

Array of installment objects — see the Installments section for the full field list.

Scoped to everything you can see: your whole tenant for an insurer, your own broker's book across every insurer you work with for a broker (narrow with insurer_id).

Attaches your own debit-note or reconciliation reference to a specific installment — useful for matching an Excel bulk-pay upload against your own records.

Returns the updated installment object.

Requires an Idempotency-Key header (see Overview). Rate-limited per broker and per IP.

• •mismatch means the wrong amount was transferred — the sender is refunded; initiate a new payment (new Idempotency-Key) for the correct amount.
• •expired means the transfer window elapsed with no transfer — initiate a new payment.
• •failed means a gateway-side error — check failure_reason; a 502 from this API is transient and safe to retry with a new Idempotency-Key.

Poll this until status leaves initiated.

Same shape as the create response above.

Array of payment objects, newest first.

Every installment must belong to your broker, be due or overdue, and belong to the same insurer — a batch cannot mix insurers. Requires an Idempotency-Key header.

Same shape as the create response above.

Array of batch objects, newest first.

A minimal .xlsx with the one column header POST /payments/bulk/resolve-file's matcher accepts, so the expected format is unambiguous.

Binary .xlsx (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet).

Upload a filled-in reference-number spreadsheet (multipart/form-data); matches each row's reference number against your due/overdue installments and returns which installment_ids matched, so you can pass them straight to POST /payments/bulk.

Submits BVN and phone number to provision (or re-provision) the broker's permanent virtual account with Squad.

Returns the updated virtual account object.

One endpoint handles every scope, but who can call it depends on the request body's scope: global and insurance_company rates are an Insureflow platform operation; an Insurance Company Admin may only set broker-scoped overrides for brokers actively assigned to their own company.

• •Example: a ₦10,000 premium under GTBank 50 bps / Insureflow 50 bps / broker 100 bps splits as ₦50 + ₦50 + ₦100 commission, insurer receives the ₦9,800 remainder.

An Insurance Company Admin sees every config touching their company: global, company-level, and per-broker rates for their assigned brokers. A broker sees global rates and their own broker-scoped rates only.

Array of commission config objects, newest first.

Fans out to one reminder per installment_id, never blocking on an individual failure.

Array of reminder objects.

Sums successful payments (single and bulk) in the given range. An insurer's rows are grouped by broker; a broker's rows are grouped by insurer.

Same params and data as above, returned as a downloadable spreadsheet instead of JSON.

Binary .xlsx (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet).

Same shape as the list response above.