Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/pull_request_template.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
## Change

Describe the reader task or contract surface changed.
Describe the reader task or API surface changed.

## Public boundary

Expand Down
2 changes: 1 addition & 1 deletion benefits.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -45,10 +45,10 @@
"currency": "KES",
"maximum_per_session": 600000
},
"authorization_required": true,

Check warning on line 48 in benefits.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

benefits.mdx#L48

Did you really mean 'authorization_required'?
"remaining_sessions": 6,

Check warning on line 49 in benefits.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

benefits.mdx#L49

Did you really mean 'remaining_sessions'?
"coverage_valid_until": "2027-01-01T00:00:00.000Z",

Check warning on line 50 in benefits.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

benefits.mdx#L50

Did you really mean 'coverage_valid_until'?
"checked_at": "2026-07-30T11:17:01.374Z"

Check warning on line 51 in benefits.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

benefits.mdx#L51

Did you really mean 'checked_at'?
}
```

Expand All @@ -74,6 +74,6 @@

## Data boundary

Responses omit the Member reference, payer identifier and internal coverage record. Clinical Notes, Diagnoses and Session content are never part of this contract.
Responses omit the Member reference, payer identifier and internal coverage record. Clinical Notes, Diagnoses and Session content are never part of this API response.

Use `benefits:write` for decisions and `benefits:read` for retrieval.
6 changes: 3 additions & 3 deletions changelog.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "API changelog"
description: "Released changes to the Heyrafiki API."

Check warning on line 3 in changelog.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

changelog.mdx#L3

Did you really mean 'Heyrafiki'?
keywords: ["Heyrafiki API changelog", "API releases", "OpenAPI changes"]
rss: true
---
Expand Down Expand Up @@ -29,9 +29,9 @@
</Update>

<Update label="9 August 2026" description="MCP 2026-07-28" tags={["Changed", "Sandbox"]}>
**Changed** the remote MCP server to the `2026-07-28` protocol contract, including stateless discovery, per-request capability metadata, transport header validation and structured completion results.
**Changed** the remote MCP server to the `2026-07-28` protocol version, including stateless discovery, per-request capability metadata, transport header validation and structured completion results.

**Added** private cache hints for `server/discover` and `tools/list`. See [MCP server](/mcp-server) for the connection contract.
**Added** private cache hints for `server/discover` and `tools/list`. See [MCP server](/mcp-server) for the connection requirements.
</Update>

<Update label="31 July 2026" description="Pre-authorization decisions" tags={["Added", "Changed"]}>
Expand Down Expand Up @@ -79,5 +79,5 @@

**Added** environment-scoped secret keys, stable error envelopes and per-key rate-limit headers.

**Published** the OpenAPI contract used by the generated endpoint reference.
**Published** the OpenAPI definition used by the generated endpoint reference.
</Update>
20 changes: 10 additions & 10 deletions concepts/institutions.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "Institutional integrations"
description: "Connect Care, Cover, Claims and audit through governed contracts."
description: "Connect Care, Cover, Claims and audit through governed interfaces."
keywords: ["institutional healthcare integration", "payer API", "health data governance", "research integration"]
---

Expand All @@ -17,7 +17,7 @@
Coordinate Care through purpose-bound Practitioner, Booking and Session capabilities.
</Card>
<Card title="Research and open ecosystems" icon="diagram-project" href="#research">
Use approved protocols, synthetic environments and versioned public contracts.
Use approved protocols, synthetic environments and versioned public API definitions.
</Card>
</Columns>

Expand All @@ -35,11 +35,11 @@
Evidence --> Oversight["Authorized oversight"]
```

Identity, clinical records, Benefit decisions and payment evidence keep separate authorities. Heyrafiki connects them through typed capabilities, explicit purpose, Organization boundaries, replay-safe writes and auditable state transitions.

Check warning on line 38 in concepts/institutions.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

concepts/institutions.mdx#L38

Did you really mean 'Heyrafiki'?

Check warning on line 38 in concepts/institutions.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

concepts/institutions.mdx#L38

Did you really mean 'auditable'?

## Integration boundaries

| Boundary | Contract |
| Boundary | Documented behavior |
| --- | --- |
| Access | Organization-scoped credentials, project isolation and least-privilege scopes |
| Cover and Claims | Idempotent eligibility, pre-authorization, Claim and remittance workflows |
Expand All @@ -52,25 +52,25 @@

<Tabs>
<Tab title="Engineering" icon="terminal">
Verify Coverage ingestion, eligibility, pre-authorization, Claim adjudication, remittance, Webhooks, retries and cross-tenant denial against the versioned contract.
Verify Coverage ingestion, eligibility, pre-authorization, Claim adjudication, remittance, Webhooks, retries and cross-tenant denial against the published API definition.
</Tab>
<Tab title="Finance" icon="chart-line">
Recompute line and Claim identities, reconcile advice to independent settlement evidence, and preserve service, submission, adjudication and payment dates for governed analysis.
</Tab>
<Tab title="Care" icon="clipboard-check">
Confirm that service evidence connects delivered Care to the covered workflow while Clinical Notes, Messages and private Session content remain outside the payer contract.
Confirm that service evidence connects delivered Care to the covered workflow while Clinical Notes, Messages and private Session content remain outside the payer interface.
</Tab>
<Tab title="Privacy" icon="fingerprint">
Exercise Organization isolation, least-privilege scopes, synthetic-only test data, signature validation, stale-event rejection and minimum-necessary response fields.
</Tab>
<Tab title="Governance" icon="file-shield">
Retain the contract commit, owner map, request identifiers, idempotency evidence, negative-test results, policy versions, reconciliation evidence and activation decision.
Retain the API definition commit, owner map, request identifiers, same-request retry evidence, negative-test results, policy versions, reconciliation evidence and activation decision.
</Tab>
</Tabs>

The [insurance acceptance plan](/insurance/acceptance-testing) turns these roles into one reproducible evidence pack. Sandbox access is issued to an approved Organization and stays isolated from production.

## Available contract
## Available interfaces

The sandbox provides:

Expand All @@ -88,7 +88,7 @@

Check eligibility before committing Cover. Where authorization is required, bind the eligibility decision to a covered Booking. Submit Claims from delivered Care, record line decisions, then allocate remittance against the approved amount.

Clinical Notes, message content and unrelated identity data are outside the payer contract.
Clinical Notes, message content and unrelated identity data are outside the payer interface.

Start with the [insurance integration guide](/insurance/integration-guide), then review the [financial controls](/insurance/financial-controls) and [acceptance test plan](/insurance/acceptance-testing).

Expand All @@ -104,16 +104,16 @@

| Review area | Evidence available now | Production decision owner |
| --- | --- | --- |
| Contract and interoperability | OpenAPI 3.1, stable identifiers, typed errors, versioning and public SDK source | Joint architecture review |
| API definition and interoperability | OpenAPI 3.1, stable identifiers, typed errors, versioning and public SDK source | Joint architecture review |
| Identity and authority | Organization, project, scope, role and purpose boundaries | Institution identity and security owners |
| Privacy | Opaque payer references, separated clinical content and minimum-necessary schemas | Institution privacy owner and Heyrafiki privacy owner |

Check warning on line 109 in concepts/institutions.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

concepts/institutions.mdx#L109

Did you really mean 'Heyrafiki'?
| Financial control | Integer minor units, balanced adjudication lines, idempotency and independent settlement matching | Payer finance and operations owners |

Check warning on line 110 in concepts/institutions.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

concepts/institutions.mdx#L110

Did you really mean 'idempotency'?
| Auditability | Request IDs, policy versions, append-only decisions, Webhook identifiers and evidence references | Authorized governance and audit owners |

Check warning on line 111 in concepts/institutions.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

concepts/institutions.mdx#L111

Did you really mean 'Auditability'?
| Resilience | Bounded retries, same-key replay, deterministic conflict behavior and rollback ownership | Joint operations owners |
| Pilot safety | Synthetic data, environment isolation, negative tests and activation gates | Named pilot steering group |

<Info>
A production integration activates only after the institution approves its authority mapping, data purpose, security controls and operating owners. The system contract and synthetic pilot remain available for technical due diligence before that decision.
A production integration activates only after the institution approves its authority mapping, data purpose, security controls and operating owners. The published API definition and synthetic pilot remain available for technical due diligence before that decision.
</Info>

## Research
Expand Down
2 changes: 1 addition & 1 deletion concepts/platform.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
keywords: ["healthcare platform workflow", "Care and Claims", "API workflow"]
---

Heyrafiki connects Care and payment operations through shared resource identifiers and versioned contracts.
Heyrafiki connects Care and payment operations through shared resource identifiers and versioned interfaces.

Check warning on line 7 in concepts/platform.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

concepts/platform.mdx#L7

Did you really mean 'Heyrafiki'?

## Resource model

Expand Down
8 changes: 4 additions & 4 deletions institutions/assurance-graph.mdx
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
---
title: "Assurance Graph"
description: "Trace every API capability to its contract, control owner, public source and executable evidence."
description: "Trace every API capability to its definition, control owner, public source and executable evidence."
keywords: ["regulatory assurance", "insurance API controls", "government integration", "digital health conformance"]
---

The Assurance Graph connects each public API operation to an accountable capability, control owner, governing source and executable evidence artifact. It gives insurer, government, regulator, security and engineering reviewers one path from a public statement to the contract and test that support it.
The Assurance Graph connects each public API operation to an accountable capability, control owner, governing source and executable evidence artifact. It gives insurer, government, regulator, security and engineering reviewers one path from a public statement to the API definition and test that support it.

The graph describes verified Heyrafiki behavior and keeps each institutional

Check warning on line 9 in institutions/assurance-graph.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

institutions/assurance-graph.mdx#L9

Did you really mean 'Heyrafiki'?
authority, operating decision and control owner explicit.

```mermaid
Expand All @@ -23,25 +23,25 @@
| Question | Evidence path |
| --- | --- |
| Who owns this capability? | Capability to named engineering, finance, clinical, privacy or reliability owner |
| Which public source informs the control? | Control to IRA, DHA, CPB, government integration boundary or Heyrafiki domain authority |

Check warning on line 26 in institutions/assurance-graph.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

institutions/assurance-graph.mdx#L26

Did you really mean 'Heyrafiki'?
| Which API operations implement it? | Capability to unique OpenAPI operation identifiers |
| How can a reviewer test it? | Control to fixture, schema and deterministic verification command |
| What happens when the contract grows? | CI fails when an operation has no accountable capability or references missing evidence |
| What happens when the API grows? | CI fails when an operation has no accountable capability or references missing evidence |

## Kenyan authority boundaries

<AccordionGroup>
<Accordion title="Insurance Regulatory Authority" icon="shield-check" defaultOpen>
IRA governs insurance supervision, market conduct and policyholder protection. Heyrafiki records the Claims, decision, communication, financial and audit evidence an accountable insurer can inspect. Heyrafiki does not become the insurer or supervisory authority.

Check warning on line 35 in institutions/assurance-graph.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

institutions/assurance-graph.mdx#L35

Did you really mean 'Heyrafiki'?

Check warning on line 35 in institutions/assurance-graph.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

institutions/assurance-graph.mdx#L35

Did you really mean 'Heyrafiki'?
</Accordion>
<Accordion title="Ministry of Health and Digital Health Agency" icon="hospital">
DHA defines digital health certification and national exchange requirements. Heyrafiki keeps registry identifiers, coded data, Consent, audit and adapter versions explicit at this boundary.

Check warning on line 38 in institutions/assurance-graph.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

institutions/assurance-graph.mdx#L38

Did you really mean 'Heyrafiki'?
</Accordion>
<Accordion title="Counsellors and Psychologists Board" icon="id-card">
CPB remains authoritative for counsellor and psychologist registration and licensing. Heyrafiki records the source observation, category, licence period and freshness separately from a Platform Care-eligibility decision.

Check warning on line 41 in institutions/assurance-graph.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

institutions/assurance-graph.mdx#L41

Did you really mean 'Heyrafiki'?
</Accordion>
<Accordion title="eCitizen and GavaConnect" icon="landmark">
These are approved government access and integration paths. They do not become the authority for clinical facts, insurance decisions or Heyrafiki ledger state.

Check warning on line 44 in institutions/assurance-graph.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

institutions/assurance-graph.mdx#L44

Did you really mean 'Heyrafiki'?
</Accordion>
</AccordionGroup>

Expand All @@ -68,7 +68,7 @@
npm test
```

The suite validates the OpenAPI contract, financial invariants, the bitemporal Claim valuation timeline and graph referential integrity.
The suite validates the OpenAPI definition, financial invariants, the Claim valuation timeline and graph referential integrity.

## Capability and access

Expand Down
10 changes: 5 additions & 5 deletions insurance/acceptance-testing.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
keywords: ["payer sandbox", "insurance API testing", "claims integration testing", "acceptance test plan"]
---

Use one isolated Sandbox project and synthetic records for the full payer pilot. Keep the API key in a secret manager and store the request ID, idempotency key and resulting resource identifier for every write.

Check warning on line 7 in insurance/acceptance-testing.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

insurance/acceptance-testing.mdx#L7

Did you really mean 'idempotency'?

<Tip>
Run the pilot as one shared evidence room. Payer engineering, actuarial and finance, Care operations, security and privacy, and governance each sign off on their own controls against the same synthetic workflow.
Expand All @@ -14,7 +14,7 @@

<Tabs>
<Tab title="Engineering" icon="terminal">
Own the contract commit, environment mapping, retry policy, idempotency keys, Webhook consumer and integration logs.
Own the API definition commit, environment mapping, retry policy, idempotency keys, Webhook consumer and integration logs.

Check warning on line 17 in insurance/acceptance-testing.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

insurance/acceptance-testing.mdx#L17

Did you really mean 'idempotency'?
</Tab>
<Tab title="Finance" icon="chart-line">
Own independent amount recomputation, Benefit interpretation, valuation assumptions, remittance allocation and settlement variance review.
Expand All @@ -32,13 +32,13 @@

```mermaid
flowchart LR
Contract["Freeze contract commit"] --> Positive["Run positive workflow"]
Definition["Freeze API definition commit"] --> Positive["Run positive workflow"]
Positive --> Negative["Run authorization and failure cases"]
Negative --> Reconcile["Recompute financial evidence"]
Reconcile --> Retrieve["Retrieve audit pack"]
Retrieve --> Decide{"Named owners approve"}
Decide -->|Approved| Gate["Open production activation gate"]
Decide -->|Changes required| Contract
Decide -->|Changes required| Definition
```

## Acceptance sequence
Expand Down Expand Up @@ -82,7 +82,7 @@
- missing requested evidence;
- duplicate Claim references;
- currency mismatch and remittance over-allocation;
- `429` handling with backoff;

Check warning on line 85 in insurance/acceptance-testing.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

insurance/acceptance-testing.mdx#L85

Did you really mean 'backoff'?
- a timeout followed by a same-key retry;
- Webhook signature failure, stale timestamp and duplicate event delivery.

Expand All @@ -104,12 +104,12 @@

The pilot evidence pack should contain:

- the OpenAPI contract commit used by both teams;
- the OpenAPI definition commit used by both teams;
- the payer-to-service-code mapping and its version;
- environment, Organization and scope mapping;
- synthetic request and response fixtures;
- authorization and negative-test results;
- idempotency and retry results;

Check warning on line 112 in insurance/acceptance-testing.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

insurance/acceptance-testing.mdx#L112

Did you really mean 'idempotency'?
- Webhook verification results;
- financial reconciliation results;
- named owners for payer operations, security, privacy and incident response;
Expand All @@ -120,7 +120,7 @@
<AccordionGroup>
<Accordion title="Minimum evidence pack structure" icon="folder-tree" defaultOpen>
<Tree>
<Tree.Folder name="01-contract" defaultOpen>
<Tree.Folder name="01-api-definition" defaultOpen>
<Tree.File name="openapi-commit.txt" />
<Tree.File name="service-code-map.csv" />
<Tree.File name="scope-map.md" />
Expand Down
4 changes: 2 additions & 2 deletions insurance/claim-valuation-timeline.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,14 @@
keywords: ["actuarial claims data", "bitemporal claim history", "claims development", "insurance valuation"]
---

Heyrafiki records when each Claim fact became effective and when the system learned it. This bitemporal history separates service, report, adjudication, remittance and settlement lag, and makes an as-of financial view reproducible.

Check warning on line 7 in insurance/claim-valuation-timeline.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

insurance/claim-valuation-timeline.mdx#L7

Did you really mean 'Heyrafiki'?

Check warning on line 7 in insurance/claim-valuation-timeline.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

insurance/claim-valuation-timeline.mdx#L7

Did you really mean 'bitemporal'?

<Columns cols={3}>
<Card title="Business time" icon="calendar">
`effective_at` records when the underlying Care, decision or money fact took effect.
</Card>
<Card title="Knowledge time" icon="clock">
`recorded_at` records when Heyrafiki received and persisted the fact.

Check warning on line 14 in insurance/claim-valuation-timeline.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

insurance/claim-valuation-timeline.mdx#L14

Did you really mean 'Heyrafiki'?
</Card>
<Card title="Valuation time" icon="calculator">
`valuation_at` excludes every fact recorded after the stated cutoff.
Expand Down Expand Up @@ -64,7 +64,7 @@
Trace the Claim from effective policy version through coded decision, communication event, remittance and settlement observation. Each transition retains its source authority and recorded time.
</Tab>
<Tab title="Engineering" icon="terminal">
Validate gapless event sequence, unique event identifiers, nondecreasing knowledge time, integer amounts and balanced adjudication in CI.

Check warning on line 67 in insurance/claim-valuation-timeline.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

insurance/claim-valuation-timeline.mdx#L67

Did you really mean 'gapless'?

Check warning on line 67 in insurance/claim-valuation-timeline.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

insurance/claim-valuation-timeline.mdx#L67

Did you really mean 'nondecreasing'?
</Tab>
</Tabs>

Expand Down Expand Up @@ -200,7 +200,7 @@
</Accordion>
</AccordionGroup>

The response includes the ordered Claim events with `effective_at`, `recorded_at`, status transitions, reason codes and bounded evidence references. The `GET /claims/{claim_id}/valuation` API reference contains the complete schema and error contract.
The response includes the ordered Claim events with `effective_at`, `recorded_at`, status transitions, reason codes and bounded evidence references. The `GET /claims/{claim_id}/valuation` API reference contains the complete schema and error format.

## Inspect the public evidence

Expand All @@ -220,7 +220,7 @@
This timeline supports analysis of reported Claims and reproducible outstanding observations. Portfolio reserve selection, IBNR, premium liability, capital, solvency, reinsurance and actuarial opinions remain with the insurer and its appointed actuarial authority.

<Info>
The open fixture uses synthetic data. An approved Organization can test the same contract in the [Sandbox](/sandbox), then define its production data mapping, valuation policy and control owners through the institutional review.
The open fixture uses synthetic data. An approved Organization can test the same workflow in the [Sandbox](/sandbox), then define its production data mapping, valuation policy and control owners through the institutional review.
</Info>

Continue with [financial controls](/insurance/financial-controls), the [Assurance Graph](/institutions/assurance-graph) and the [acceptance test plan](/insurance/acceptance-testing).
6 changes: 3 additions & 3 deletions insurance/financial-controls.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,14 @@
keywords: ["insurance controls", "claim adjudication math", "remittance reconciliation", "actuarial data"]
---

Heyrafiki uses integer minor units, balanced Claim lines and distinct evidence for authorization, adjudication, remittance and settlement. Models may help a reviewer find work. Deterministic rules decide whether a financial state transition is valid and write its audit evidence.

Check warning on line 7 in insurance/financial-controls.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

insurance/financial-controls.mdx#L7

Did you really mean 'Heyrafiki'?

## Money representation

- Every amount is an integer in the currency's minor unit.
- Every resource carries its ISO 4217 currency.
- Arithmetic does not use binary floating point.
- Cross-currency allocation is rejected. Currency conversion remains outside the Claim contract.
- Cross-currency allocation is rejected. Currency conversion remains outside the Claim workflow.
- Limits are applied to the service and effective period carried by the payer observation.

## Claim line identities
Expand Down Expand Up @@ -77,7 +77,7 @@

## Actuarial use

The operational contract preserves the service date, Coverage version, Benefit decision, submitted amount, allowed amount, payer amount, status history and remittance timing needed for governed payer analysis.
The operating model preserves the service date, Coverage version, Benefit decision, submitted amount, allowed amount, payer amount, status history and remittance timing needed for governed payer analysis.

Actuarial measures require explicit exposure and valuation assumptions. A payer analysis should define at least:

Expand All @@ -90,17 +90,17 @@

Use one stated cohort basis and valuation date. Distinguish service date, submission date, adjudication date and payment date. Count Claims consistently, preserve zero-Claim exposure, and include an explicit treatment for reported-but-not-settled and incurred-but-not-reported cost.

The payer remains the authority for premium, exposure, reserving assumptions, IBNR, capital models, IFRS 17 measurement and regulatory returns. Heyrafiki supplies governed operational evidence and does not replace the payer's actuarial valuation system.

Check warning on line 93 in insurance/financial-controls.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

insurance/financial-controls.mdx#L93

Did you really mean 'Heyrafiki'?

## Evidence available to reviewers

| Control | Evidence |
| --- | --- |
| Amount balance | OpenAPI schemas, database constraints and automated behavior tests |
| Retry safety | Idempotency records and same-key replay tests |

Check warning on line 100 in insurance/financial-controls.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

insurance/financial-controls.mdx#L100

Did you really mean 'Idempotency'?
| Decision authority | Organization, project, scope and actor records |
| Change history | Append-only observations, submissions, decisions and Events |
| Payment separation | Distinct remittance advice, settlement observation and reconciliation records |
| Privacy boundary | Opaque references and schemas that exclude clinical content |

Review the [Claims guide](/claims), [Security boundary](/security/data-boundaries) and [acceptance test plan](/insurance/acceptance-testing) alongside the API contract.
Review the [Claims guide](/claims), [Security boundary](/security/data-boundaries) and [acceptance test plan](/insurance/acceptance-testing) alongside the API definition.
12 changes: 6 additions & 6 deletions insurance/integration-guide.mdx
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
---
title: "Insurance integration guide"
description: "Connect payer Coverage, Benefits, Claims and remittance through one governed contract."
description: "Connect payer Coverage, Benefits, Claims and remittance through one governed interface."
keywords: ["health insurance API", "payer integration", "claims API", "benefits API", "Kenya insurance"]
---

An insurer connects to Heyrafiki through versioned payer observations and explicit workflow decisions. The insurer remains authoritative for membership, Benefit design, adjudication policy and payment advice. Heyrafiki records the bounded operational evidence that connects those decisions to delivered Care.

Check warning on line 7 in insurance/integration-guide.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

insurance/integration-guide.mdx#L7

Did you really mean 'Heyrafiki'?

Check warning on line 7 in insurance/integration-guide.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

insurance/integration-guide.mdx#L7

Did you really mean 'Heyrafiki'?

<Columns cols={3}>
<Card title="Coverage" icon="shield-check" href="/benefits">
Expand Down Expand Up @@ -40,7 +40,7 @@
H-->>P: Reconciliation state and audit references
```

The payer controls membership, Benefit design and adjudication policy. Heyrafiki controls the workflow contract, authorization boundary, retry behavior and audit evidence. The Practitioner controls the clinical record. A payment source supplies settlement evidence independently from payer advice.
The payer controls membership, Benefit design and adjudication policy. Heyrafiki controls the workflow definition, authorization boundary, retry behavior and audit evidence. The Practitioner controls the clinical record. A payment source supplies settlement evidence independently from payer advice.

Check warning on line 43 in insurance/integration-guide.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

insurance/integration-guide.mdx#L43

Did you really mean 'Heyrafiki'?

## End-to-end flow

Expand All @@ -58,10 +58,10 @@

<Steps>
<Step title="Establish the authority mapping">
Map one payer tenant to one Heyrafiki Organization and issue a separate project for each environment. Grant only the scopes required by the integration.

Check warning on line 61 in insurance/integration-guide.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

insurance/integration-guide.mdx#L61

Did you really mean 'Heyrafiki'?
</Step>
<Step title="Load Coverage">
Send individual observations through `POST /coverages`, or batches of up to 500 records through `POST /coverage_batches`. Each observation carries its source contract, source version, effective period and evidence references.
Send individual observations through `POST /coverages`, or batches of up to 500 records through `POST /coverage_batches`. Each observation carries its source policy reference, source version, effective period and evidence references.
</Step>
<Step title="Check the Benefit">
Call `POST /eligibility_checks` for the service date and requested amount. Treat `ineligible` as a decision with reason codes, not as a transport failure.
Expand All @@ -70,13 +70,13 @@
Create a pre-authorization from the eligibility decision and covered Booking. The payer records the decision through `POST /preauthorizations/{preauthorization_id}/decisions`.
</Step>
<Step title="Submit delivered Care">
Create the Claim only after the covered Session is delivered. Send service codes, units, amounts and evidence references. Clinical Notes and private Conversation content do not enter this contract.
Create the Claim only after the covered Session is delivered. Send service codes, units, amounts and evidence references. Clinical Notes and private Conversation content do not enter this API request.
</Step>
<Step title="Adjudicate every line">
Request bounded evidence when necessary, then record a versioned policy reference, line amounts and coded reasons through `POST /claims/{claim_id}/adjudications`.
</Step>
<Step title="Reconcile payer advice">
Send remittance advice with allocations to Claims. Heyrafiki keeps advice separate from independent settlement evidence so an advice file cannot assert that money moved.

Check warning on line 79 in insurance/integration-guide.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

insurance/integration-guide.mdx#L79

Did you really mean 'Heyrafiki'?
</Step>
</Steps>

Expand All @@ -103,12 +103,12 @@
"status": "active",
"currency": "KES",
"amount_limit": 600000,
"remaining_sessions": 8,

Check warning on line 106 in insurance/integration-guide.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

insurance/integration-guide.mdx#L106

Did you really mean 'remaining_sessions'?
"authorization_required": true,

Check warning on line 107 in insurance/integration-guide.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

insurance/integration-guide.mdx#L107

Did you really mean 'authorization_required'?
"coordination_priority": 1,

Check warning on line 108 in insurance/integration-guide.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

insurance/integration-guide.mdx#L108

Did you really mean 'coordination_priority'?
"valid_from": "2026-01-01T00:00:00Z",

Check warning on line 109 in insurance/integration-guide.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

insurance/integration-guide.mdx#L109

Did you really mean 'valid_from'?
"valid_until": "2026-12-31T23:59:59Z",

Check warning on line 110 in insurance/integration-guide.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

insurance/integration-guide.mdx#L110

Did you really mean 'valid_until'?
"observed_at": "2026-08-10T07:00:00Z",

Check warning on line 111 in insurance/integration-guide.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

insurance/integration-guide.mdx#L111

Did you really mean 'observed_at'?
"evidence_references": ["payer:source:synthetic:0001"]
}'
```
Expand Down Expand Up @@ -208,17 +208,17 @@
```
</Accordion>
<Accordion title="Replay and conflict behavior" icon="rotate">
Repeating the same payload with the same idempotency key returns the original observation with `200`. Reusing that key with different content returns `409` and writes no second observation.

Check warning on line 211 in insurance/integration-guide.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

insurance/integration-guide.mdx#L211

Did you really mean 'idempotency'?
</Accordion>
</AccordionGroup>

## Source data contract
## Source data mapping

| Payer field | Heyrafiki field | Rule |

Check warning on line 217 in insurance/integration-guide.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

insurance/integration-guide.mdx#L217

Did you really mean 'Heyrafiki'?
| --- | --- | --- |
| Membership key | `member_reference` | Send an opaque stable reference. Do not send a name, contact detail or government identifier. |
| Product contract | `source_contract_reference` | Identify the policy or Benefit contract that produced the observation. |
| Source revision | `source_version` or `record_version` | Increase when the payer source changes. Reusing an idempotency key with different content is rejected. |

Check warning on line 221 in insurance/integration-guide.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

insurance/integration-guide.mdx#L221

Did you really mean 'idempotency'?
| Service Benefit | `service_code` | Use the agreed versioned payer-to-Heyrafiki code mapping. |
| Limit | `amount_limit` | Send the per-Session limit in the currency's minor unit. |
| Utilization balance | `remaining_sessions` | Send the balance observed by the payer source. |
Expand All @@ -227,7 +227,7 @@

## Control ownership

| Decision | Authority | Heyrafiki responsibility |

Check warning on line 230 in insurance/integration-guide.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

insurance/integration-guide.mdx#L230

Did you really mean 'Heyrafiki'?
| --- | --- | --- |
| Member eligibility | Payer source | Preserve source, version, effective time and the resulting observation. |
| Pre-authorization | Authorized payer reviewer | Bind the decision to the eligible Booking and reserve the Benefit once. |
Expand All @@ -239,11 +239,11 @@
## Retry and recovery rules

- Send an `Idempotency-Key` on every supported write.
- Retry `429` and retryable `503` responses only after the stated delay.

Check warning on line 242 in insurance/integration-guide.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

insurance/integration-guide.mdx#L242

Did you really mean 'retryable'?
- Treat a timeout after submission as unknown. Retry with the same idempotency key.

Check warning on line 243 in insurance/integration-guide.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

insurance/integration-guide.mdx#L243

Did you really mean 'idempotency'?
- Treat `409` as a state or idempotency conflict that requires review.

Check warning on line 244 in insurance/integration-guide.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

insurance/integration-guide.mdx#L244

Did you really mean 'idempotency'?
- Persist the `X-Request-Id` with the payer's integration log.
- Consume Webhooks idempotently using the stable event identifier.

Check warning on line 246 in insurance/integration-guide.mdx

View check run for this annotation

Mintlify / Mintlify Validation (heyrafiki) - vale-spellcheck

insurance/integration-guide.mdx#L246

Did you really mean 'idempotently'?

## Data boundary

Expand All @@ -251,4 +251,4 @@

## Integration entry point

Use the [OpenAPI 3.1 contract](https://github.com/heyrafiki/contract), [Proving Ground](https://github.com/heyrafiki/proving-ground), [Sandbox](/sandbox) and [acceptance test plan](/insurance/acceptance-testing) for technical due diligence. [Request Sandbox access](https://heyrafiki.space/waitlist) when your integration team is ready to test.
Use the [OpenAPI 3.1 definition](https://github.com/heyrafiki/contract), [Proving Ground](https://github.com/heyrafiki/proving-ground), [Sandbox](/sandbox) and [acceptance test plan](/insurance/acceptance-testing) for technical due diligence. [Request Sandbox access](https://heyrafiki.space/waitlist) when your integration team is ready to test.
8 changes: 8 additions & 0 deletions legacy-domain-redirect.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
(() => {
if (window.location.hostname !== "heyrafiki.mintlify.app") return;

const destination = new URL(window.location.pathname, "https://docs.heyrafiki.space");
destination.search = window.location.search;
destination.hash = window.location.hash;
window.location.replace(destination.href);
})();
Loading