For Developers

A versioned interface over governed Mental Healthcare infrastructure.

Build against the same objects and authority boundaries Heyrafiki uses. Consent affects access, compatibility is explicit, and retries do not get to invent a second result.

Request API Access

Star on GitHub

eligibility · heyrafiki api

$ curl -X POST https://api.heyrafiki.space/v1/eligibility_checks \
    -H "Authorization: Bearer hey_sk_..." \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: elig_2026_08_09_a41" \
    --data '{
      "member_reference": "mem_7Qm4",
      "service_code": "psychotherapy_50",
      "scheduled_at": "2026-08-17T09:00:00Z",
      "amount": 250000,
      "currency": "KES"
    }'

{
  "object": "eligibility_check",
  "status": "eligible",
  "reason_codes": ["eligible"],
  "amount": { "requested":  250000, "currency":  "KES" },
  "authorization_required": false,
  "remaining_sessions": 6
}

An example request against the published API definition. Values are illustrative.

Build the part of the Care pathway your product needs.

Start with documented resources for Practitioners, eligibility, bookings and Claims, then add the next boundary without replacing the first.

/practitioners

Search a license-verified network by language, focus and availability.

/bookings

Availability, Bookings and Session Rooms, across time zones.

/eligibility and claims

Cover checks, pre-authorizations, Claims and remittances with explicit authority at each state.

/webhooks

Released events, signed and retried according to the documented behavior.

Public interfaces at the institutional boundary.

Request API Access

Public interfaces at the institutional boundary.

OpenAPI defines the resources, OAuth scopes access, signed Webhooks carry released events, and versioned adapters keep every external mapping explicit.

OpenAPI 3.1ICD-10OAuth 2.0REST + WebhooksOWASP ASVS

Open where it actually matters.

The API definition, SDKs and command-line tools are public under Apache 2.0. MCP adapts approved capabilities for authorized Sandbox projects and never widens Consent, role or purpose.

Why we build in the Open

Follow the released API.

The Developer Docs identify the released Webhook events, signature method and retry behavior supported by the canonical API.

Practitioner profiles and availability are separate typed resources
Bookings return the Session identifier that carries the Care lifecycle
Claims bind Cover, the delivered Session and coded service lines
Every example follows the canonical OpenAPI definition

curl https://api.heyrafiki.space/v1/eligibility_checks \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: elig_2026_08_11_a41" \
  -d '{
    "member_reference": "mem_7Qm4",
    "service_code": "psychotherapy_50",
    "scheduled_at": "2026-08-17T09:00:00Z",
    "amount": 350000,
    "currency": "KES"
  }'

# 200 OK
{
  "id": "elig_3f8",
  "object": "eligibility_check",
  "status": "eligible",
  "reason_codes": ["eligible"],
  "service": {
    "code": "psychotherapy_50",
    "scheduled_at": "2026-08-17T09:00:00Z"
  },
  "amount": {
    "requested": 350000,
    "currency": "KES",
    "maximum_per_session": 500000
  },
  "authorization_required": false,
  "remaining_sessions": 6,
  "coverage_valid_until": "2026-12-31T23:59:59Z",
  "checked_at": "2026-08-11T12:30:00Z"
}

Open the API reference

What teams can build.

This carries far more than our own product.

A University Counselling Portal

Students book verified Counsellors from a campus portal, with wellbeing trends reported to student services in aggregate only.

MatchingSchedulingRooms

An NGO Field Program

Connect approved Screening to a licensed referral path.

VerificationRecordsWebhooks

An Insurer Integration

Map structured Claims into an adjudication adapter with traceable state changes.

ClaimsPaymentsWebhooks

Start Building.

Request API Access

$ curl -X POST https://api.heyrafiki.space/v1/eligibility_checks \ -H "Authorization: Bearer hey_sk_..." \ -H "Content-Type: application/json" \ -H "Idempotency-Key: elig_2026_08_09_a41" \ --data '{ "member_reference": "mem_7Qm4", "service_code": "psychotherapy_50", "scheduled_at": "2026-08-17T09:00:00Z", "amount": 250000, "currency": "KES" }' { "object": "eligibility_check", "status": "eligible", "reason_codes": ["eligible"], "amount": { "requested": 250000, "currency": "KES" }, "authorization_required": false, "remaining_sessions": 6 }

Follow the released API.

The Developer Docs identify the released Webhook events, signature method and retry behavior supported by the canonical API.

Practitioner profiles and availability are separate typed resources

Bookings return the Session identifier that carries the Care lifecycle

Claims bind Cover, the delivered Session and coded service lines

Every example follows the canonical OpenAPI definition