Quickstart
How it works
A mental model of the platform — layered, canonical, and standards-aligned. The same architecture powers connectivity for distribution, claims, verification, and the Records API.
Five-layer model#
Inbound requests flow top-down; events and notifications flow bottom-up. Each layer hides the next from your code.
| Layer | Name | Responsibility |
|---|---|---|
| L1 | Partner channel | Accepts API requests from your application. |
| L2 | API gateway & security | Authentication, rate limiting, tenant resolution, validation. |
| L3 | Core orchestration | Business logic: enrollment, policy, pricing, claims, ledger. |
| L4 | HMO connectors | One adapter per HMO vendor — normalises every difference. |
| L5 | Intelligence | AI normalisation, fraud scoring, plan ranking, pricing. |
Request lifecycle#
A typical enrollment touches every layer. From your POST to the policy being live in the HMO's system, the journey is:
- Gateway validates auth, schema, idempotency key.
- Identity service verifies BVN/NIN.
- Duplicate detection checks for existing policies.
- Policy engine applies plan rules and waiting periods.
- Premium router initiates the first collection.
- HMO connector posts the enrollment to the HMO's system.
- Pierflow stores the canonical policy record.
- Commission engine posts the ledger entry.
- Webhooks fire to your endpoint.
You only need to think about steps 1 and 9 — the gateway and the events. Everything between is handled for you.