Institutional integrations

Institutional integrations use versioned resources for Practitioner discovery, Bookings, Benefits, Claims and remittance.

Insurers and payers

Connect Coverage, eligibility, pre-authorization, Claims, remittance and reconciliation.

Government and regulators

Review authority, data minimization, audit evidence and controlled exchange boundaries.

Health Organizations

Coordinate Care through purpose-bound Practitioner, Booking and Session capabilities.

Research and open ecosystems

Use approved protocols, synthetic environments and versioned public API definitions.

One operating model

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.

Integration boundaries

Boundary	Documented behavior
Access	Organization-scoped credentials, project isolation and least-privilege scopes
Cover and Claims	Idempotent eligibility, pre-authorization, Claim and remittance workflows
Events	Signed Webhooks, request IDs and bounded retries
Data	Synthetic sandbox records and purpose-bound production access

Credential issuers remain authoritative for professional status. Payers remain authoritative for Benefit and Claim decisions. API responses carry references to those decisions.

Five-role acceptance model

Engineering
Finance
Care
Privacy
Governance

Verify Coverage ingestion, eligibility, pre-authorization, Claim adjudication, remittance, Webhooks, retries and cross-tenant denial against the published API definition.

The insurance acceptance plan turns these roles into one reproducible evidence pack. Sandbox access is issued to an approved Organization and stays isolated from production.

Available interfaces

The sandbox provides:

Practitioner discovery and recurring availability;
tenant-scoped Bookings and Sessions;
Benefit eligibility and pre-authorization;
project-scoped Claim submission, review and adjudication;
remittance allocation and reconciliation;
signed Webhook endpoint management;
read-only MCP tools over the same resources.

Use separate projects and keys for each environment. Sandbox data is synthetic.

Insurers and payers

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 interface. Start with the insurance integration guide, then review the financial controls and acceptance test plan.

Health Organizations

Use Practitioner, availability, Booking and Session resources to coordinate Care. Organization access remains purpose-bound and does not expose an individual’s Diagnosis or private Care activity.

Regulators and public systems

Use the sandbox to test identity, Consent, terminology and exchange mappings with synthetic data. Production access follows the authority’s active requirements and approval process.

Government and regulatory integration

Review area	Evidence available now	Production decision owner
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
Financial control	Integer minor units, balanced adjudication lines, idempotency and independent settlement matching	Payer finance and operations owners
Auditability	Request IDs, policy versions, append-only decisions, Webhook identifiers and evidence references	Authorized governance and audit owners
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

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.

Research

Research access requires an approved protocol and the minimum permitted data. Approved exports retain their provenance and access controls. See Security, Data boundaries, Authentication and Webhooks.