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.

Emails the account a link to choose a new password. The link works once, for 30 minutes. Also works when a one-time password has expired.

HTTP 204 No Content whether or not the address has an account, so it can't be used to find out who does. Limited to 5 requests an hour per address.

Sets the password using the token from the emailed link, then the token stops working.

HTTP 204 No Content on success; 422 if the link is invalid, used or expired.

Creates an Insurance Company Staff login. Staff can create policies and clients, send reminders, set premium references and see every report, but can't manage brokers, staff, the settlement account or webhooks, or mark a premium paid by hand. Their one-time password is emailed to them.

Every login of your company, the admin first.

Ends a staff member's access immediately. The admin login can't be deactivated.

Creates a broker that isn't on Insureflow yet, approves it for you at once and adds it to your brokers. Other insurers don't see it until Insureflow approves it for everyone. Its admin is emailed a welcome with a one-time password; once signed in, they add the broker's BVN and phone number (PATCH /virtual-accounts/me), which creates the account it pays premiums into, and its team.

Multipart upload (field: file) of an .xlsx or .csv with two columns, Broker Name and Email (GET /insurance-companies/me/brokers/import/template for a blank .xlsx). Reports which rows would be added and why the rest wouldn't: a missing name, an invalid or repeated email, an email that already has an account, or a broker already on Insureflow (add it with POST /insurance-companies/me/brokers instead). Writes nothing. Up to 200 rows.

Adds the rows a preview returned as ready (re-checked first). Each broker is approved for you only and added to your brokers, as with Add a new broker, and its admin is emailed a welcome with a one-time password. Rows that fail are reported without stopping the rest.

Brokers waiting for approval that named you when they signed up (requested_insurer_id).

Approves the broker for you only, creates its account number, and adds it to your brokers.

Not a broker you work with. It isn't rejected: it waits for Insureflow to review it instead.

Insureflow-approved brokers, searchable by name or email, each flagged with whether it's already one of yours.

Start working with an approved broker -- no Insureflow step needed. You can then create policies for them, and they can remit your premiums. Adding a broker you already have returns the existing assignment.

• •409 if the broker isn't approved; 404 if it doesn't exist.

Stop working with a broker: no new policies can be created for them. Their existing policies, open remittances and payment history are kept.

The ended assignment.

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 brokers can remit to you: Insureflow pays you the moment a broker's transfer arrives, so it won't accept a remittance it couldn't pay out.
• •The NIBSS lookup is real even in sandbox — a dummy account number returns HTTP 424.

Registers a new broker. In production it starts pending until Insureflow approves it; approval creates the broker's Insureflow account number (the account premiums are paid into). On the sandbox it's approved at once and gets its account straight away.

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).

Every login of your broker, admins first.

Creates a login under your broker, as staff (see and pay premiums) or another admin (also manages the team, webhooks and your account details). Their one-time password is emailed to them. POST /brokers/{broker_id}/staff does the same.

Makes them an admin or staff, from their next request. Not your own login, so your broker always keeps an admin.

Returns the team member, as in the list.

Ends their access at once. Not your own login.

Returns the team member, as in the list.

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.

An .xlsx with the expected columns and two example rows, plus a second sheet listing your assigned brokers (name and email) for the Broker column.

The .xlsx file itself (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet).

Upload a filled-in template as multipart form data (field name: file). Every row is validated — broker assignment, debit-note uniqueness, amounts, dates — and reported as ready or with a reason. Nothing is written.

Creates one policy (and its premium schedule) per row, reusing a client when their email matches an existing client of the same broker. Every row is re-validated, so pass the preview's ready rows back unchanged.

• •A row that fails never blocks the rest, and never leaves a client created without its policy.

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.

Every premium must be yours, due or overdue, not already in another open remittance, and for the same insurer, and that insurer must have confirmed its settlement account. You can't have two open remittances of the same total (409) — the amount is what identifies your transfer. Requires an Idempotency-Key header. Rate-limited per broker and per IP.

• •Send exactly total_net_kobo. A different amount doesn't pay the remittance — it waits as a receipt for you to say what it was for, or to ask for it back.
• •No part payments: a premium is either fully in a remittance or not in it.

Poll this until status leaves open.

Same shape as the create response above.

Scoped to what you can see: your own as a broker, those for your company as an insurer.

Array of remittance objects, newest first.

Sandbox only — 404 on production. Has the bank's sandbox simulator send this open remittance's exact total into your Insureflow account, then processes it immediately, exactly as a real transfer would be: the premiums are marked paid and each premium's payout to the insurer is sent from Insureflow's sandbox Squad balance. No real money moves. The simulator carries no narration, so the transfer is matched by amount alone.

The remittance — normally now paid, with each line's fees and insurer net filled in. If the simulator is slow to report the transfer it's returned still open and is paid within a few minutes; poll GET /remittances/{remittance_id}. 409 if the remittance isn't open.

• •Rate-limited like POST /remittances.

Only an open remittance; its premiums are released. Don't cancel one you've already paid for.

The cancelled remittance.

For a paid remittance: every debit note with its gross premium, broker commission, Squad fee, Insureflow fee, payout fee and the amount paid to the insurer, plus the receipt reference and, per premium, the reference and status of the transfer that carried it.

Binary .xlsx. 409 if the remittance isn't paid yet.

A minimal .xlsx with the column header POST /remittances/resolve-file accepts.

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

Upload a spreadsheet of debit notes or premium reference numbers (multipart/form-data); returns which of your unpaid premiums they match, so you can pass the installment_ids to POST /remittances. A reference no premium carries is matched against your policies' debit notes, resolving to that policy's earliest unpaid premium.

Brokers see their own. Insurers see only receipts tied to them — paid to their remittances, or that the broker said were meant for them.

The remittance must be yours, open, and for exactly the receipt's amount. If none is, create one that is, then apply. The insurer is paid straight away.

The updated receipt.

Squad verifies the destination account; whether its name matches the sender is shown to the approver. Nothing is sent until an Insureflow Admin approves.

The updated receipt.

Queues the transfer back to the broker. A failed refund hands the receipt back to the broker.

The updated receipt.

The receipt goes back to waiting for the broker, with the reason.

The updated receipt.

Array of payment objects, newest first. GET /payments/{payment_id} returns one.

Array of batch objects, newest first. GET /payments/bulk/{batch_id} returns one.

A broker an insurer added has no BVN or phone number yet, so its admin adds them here; the account number is created straight away. A broker that signed up itself gave them then, and only needs this to correct them. If the payment provider refuses them, nothing is saved and its reason is returned.

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.

Emails the premium's broker a reminder to pay it.

Creates a reminder for each of your premiums overdue past the 30-day grace period, and emails each broker once, listing all of its premiums with the total. No request body.

Array of reminder objects.

Sums paid premiums (remittances and past payments, at gross) 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.

Registers an endpoint and returns its signing secret — the only time the secret is returned. Up to 5 endpoints per organization.

Your organization's endpoints. Never includes secrets.

Array of WebhookEndpoint objects.

A WebhookEndpoint object.

Change any of the fields below; omitted fields are left unchanged. A disabled endpoint receives nothing; its pending deliveries resume when it's re-enabled.

The updated WebhookEndpoint.

Stops all deliveries to the endpoint and deletes its delivery history.

HTTP 204 No Content.

Issues a new secret. The old one stops signing immediately, including for retries already queued.

Queues a webhook.test event to this endpoint only, regardless of its subscriptions. It's sent within about 15 seconds, signed like any other event.

HTTP 202 with the queued WebhookDelivery.

The 50 most recent deliveries to this endpoint, newest first.

Sends the same event — same id, same body — again, with a fresh retry schedule.

HTTP 202 with the re-queued WebhookDelivery.