Skip to main content

Business flow

The InsureLink platform sits between four actors and supports two acquisition channels that share the same downstream pipeline:

Channel A (agent-mediated):  CLIENT ⇄ AGENT ⇄ ZFA (InsureLink) ⇄ INSURER
Channel B (ZFA-direct):      CLIENT         ⇄ ZFA (InsureLink) ⇄ INSURER

Money and information move along the chain. Three rules that everything else derives from:

  1. Clients pay insurers directly. InsureLink never touches the client's premium. Proof-of-Payment (POP) evidence is what proves the payment happened. This holds on both channels.
  2. Insurers pay commissions to ZFA. ZFA remits to registered agents (agent-mediated), net of ZFA fees, URA WHT, and IIU membership. On ZFA-direct referrals there is no agent leg — commission settles to a dedicated ZFA house wallet (URA WHT still applies; ZFA-fee and IIU levy are skipped because you can't charge yourself).
  3. One pipeline, one state machine. The referral / POP / policy / claim / commission stack does not fork between channels. What differs is the front (who creates the referral) and the commission payee (agent vs house wallet). Every referral carries a channelSource ∈ { agent_referral, zfa_direct, client_self_service } so reporting and authorisation can branch cleanly.

Actors at a glance​

ActorWhat they doWhat they access
ClientBuys the insurance. Pays the insurer directly. Shares POP with the agent (Channel A) or directly with ZFA via the portal (Channel B). Views their own policies + claims via the client portal.Public inquiry form (anonymous) or client portal (magic-link + OTP session — no password)
AgentIntroduces clients, submits referrals, uploads the client's POP to InsureLink. Licensed agents can sponsor introducers. Only present on Channel A.Platform JWT with agent-scoped permissions
ZFA (InsureLink)On Channel A: reviews referrals, verifies POPs, forwards to the insurer, receives commissions, remits to agents net of deductions. On Channel B: additionally owns the client relationship, runs the direct-inquiry desk, converts inquiries to referrals, and reconciles the house wallet.Platform JWT with ZFA-staff / super-admin / finance / compliance permissions
InsurerUnderwrites, quotes, issues policies, confirms POPs on their side, pays commissions to ZFA. Contract-neutral to channel — sees the referral either way.Insurer inbound webhooks (HMAC-signed), or ZFA staff acting on their behalf via POST /proof-of-payment/:id/insurer-confirm

Choosing the channel​

SignalChannel
Client walked in / called ZFA, no agent involvedZFA-direct — ZFA staff creates the inquiry via POST /admin/zfa-direct/inquiries
Client submitted the public web formZFA-direct (self-service) — via POST /public/client-inquiries; magic-link creates the portal session
Returning client with an active portal sessionZFA-direct (portal) — via POST /client-portal/inquiries
Licensed agent introduced the clientAgent-mediated — via POST /referrals from the agent's session
Introducer (non-licensed) brought the clientAgent-mediated — the introducer's sponsor-agent is credited (see sponsor tree)

Channel A — agent-mediated lifecycle​

Channel B — ZFA-direct lifecycle​

Client contacts ZFA without an agent. Three entry points feed the same inquiry queue, which converts to a referral that then flows through the identical downstream pipeline as Channel A.

Referral state machine (shared)​

Both channels share the same 20-state referral machine. The initial creator differs (agent vs client-inquiry conversion), but from draft onward the transitions are identical:

POP verification detail (two stages)​

Because the client pays the insurer directly, both ZFA and the insurer must independently confirm the payment before commission is recognised. The POP record has its own status track that runs alongside the referral:

Only insurer_confirmed transitions the referral to premium_paid. zfa_verified alone is not enough — ZFA's verification is a first-line sanity check (does the POP look real, does the amount match), but only the insurer can confirm the money actually landed in their account.

Endpoints in the API Reference:

Commission flow (Insurer → ZFA → payee wallet)​

Commission is the reverse leg. It originates at the insurer and lands in a wallet selected by Referral.channelSource:

Every deduction row carries beneficiaryTypes so the engine knows which wallet types it applies to (agent, zfa_house, or both). The schedule seeded today is the default, not immutable — ZFA can add / retire / version rules over time. See /deduction-types/preview to see the net effect on a specific gross amount and beneficiary type.

House-wallet endpoints:

ZFA-direct desk & client entities​

Direct-channel introduces a first-class Client entity and a triaging desk. Endpoints:

Design deep-dive: ZFA-direct channel design doc.

Licensed agents can sponsor introducers — non-licensed people who bring in business but cannot transact with insurers directly. Every introducer must attach to a licensed sponsor at self-registration time:

The sponsor sees every downstream introducer's referrals via GET /agents/:id/internal-referrals — "book-of-business" view.

Where to go next​