How Heyrafiki works

The system the API sits on: what each surface does and how a Session moves through it.

Heyrafiki is one Rail beneath Mental Healthcare. Finding Care, delivering it, recording it, covering it and paying for it are one system rather than five that email each other.

Surfaces

Surface	Who uses it	What it does
App	People	Find and fund Care, join Sessions, control sharing
Practice	Practitioners	Run a Practice: Calendar, Inbox, Notes, Claims, Payouts
Organization	Employers, Universities, NGOs	Fund Care Budgets, read aggregate reporting
Insurer	Payers	Adjudicate Claims, manage the Practitioner Network
API	Builders	Everything above, as endpoints

A Session, end to end

1. Match

   A Person states language, focus, budget, schedule and Cover. Iris filters to verified Practitioners, ranks by fit and shows the reasons. The Person chooses.

2. Book

   The booking creates the Session and its Room. Self-pay is captured now and held.

3. Meet

   The Session runs online or in person. If the Practitioner brings Iris in as Scribe, the Client is told in the Room.

4. Approve

   Iris drafts a SOAP Note. Nothing enters the record until the Practitioner approves it.

5. Settle

   Self-pay releases the moment the Session ends. Covered Sessions generate a coded Claim from the approved Note.

Money

The double-entry Ledger is the source of truth, not the payment provider. Booking captures into an escrow account, delivery releases to the Practitioner, and covered Sessions post a receivable against the Payer instead. Every movement is a Ledger entry with a matching pair.

Standards

Clinical records follow FHIR resource shapes and ICD-10 coding, so Claims, referrals and records exchange with systems that already exist. Aggregate exports align with national health reporting, DHIS2 included.