API overview - Heyrafiki

The released OpenAPI 1.0.0 definition contains 31 operations across eight resource areas. Every operation in this map is implemented in the Sandbox and generated into an endpoint page under API reference.

Released surface

Area	Operations	What you can do
API discovery	1	Inspect the authenticated project, environment and API version
Practitioners	3	List and retrieve synthetic Practitioners and recurring availability
Bookings	3	List, create and retrieve Bookings
Sessions	2	List and retrieve minimum-necessary Session records
Benefits	7	Record Coverage, check eligibility and manage pre-authorization decisions
Claims	7	Submit, retrieve, query, evidence, adjudicate and reconstruct Claim valuation
Remittances	3	List, create and retrieve remittance advice and reconciliation state
Webhooks	5	List, register, retrieve, disable and test endpoints

The reference is generated from the same versioned API definition used by the public conformance suite. A new endpoint appears here only after implementation, authorization and error behavior, examples, compatibility ownership and sensitive-data review pass the publication gate.

Start with one workflow

Discover a synthetic Practitioner, create a Booking, check Benefits and move covered Care from Claim to remittance.

List Practitioners

curl "https://api.heyrafiki.space/v1/practitioners?limit=2" \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxx"

{
  "object": "list",
  "data": [
    {
      "id": "prc_2481",
      "object": "practitioner",
      "name": "Emily Makena",
      "profession": "Clinical Psychologist",
      "location": {
        "city": "Nairobi",
        "country": "Kenya"
      },
      "session_fee": {
        "amount": 350000,
        "currency": "KES"
      }
    }
  ],
  "has_more": false
}

limit accepts an integer from 1 to 100 and defaults to 20.

Retrieve a Practitioner

curl "https://api.heyrafiki.space/v1/practitioners/prc_2481" \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxx"

The response uses the same Practitioner object returned by the list operation.

Retrieve recurring availability

curl "https://api.heyrafiki.space/v1/practitioners/prc_2481/availability" \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxx"

{
  "object": "availability",
  "practitioner_id": "prc_2481",
  "timezone": "Africa/Nairobi",
  "weekly_hours": [
    {
      "weekday": 1,
      "start": "09:00",
      "end": "17:00",
      "formats": ["online", "in_person"]
    }
  ]
}

weekday uses 0 for Sunday through 6 for Saturday. Hours are local to the returned IANA timezone. These are recurring weekly hours, not a promise that a particular Session slot remains bookable.

Create a Booking

curl https://api.heyrafiki.space/v1/bookings \
  -X POST \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: booking-demo-001" \
  -d '{
    "practitioner_id": "prc_2481",
    "starts_at": "2026-08-03T06:00:00.000Z",
    "ends_at": "2026-08-03T07:00:00.000Z",
    "format": "online",
    "payment_source": "self_pay"
  }'

The same idempotency key and body return the original Booking. Reusing the key with a different body returns 409 idempotency_conflict.

Check Benefits

Use an eligibility check before committing a covered Booking. If the response sets authorization_required to true, create a pre-authorization against the matching bkg_ identifier. See Benefits for the request sequence and decision fields.

List Sessions

curl "https://api.heyrafiki.space/v1/sessions?limit=10" \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxx"

{
  "object": "list",
  "data": [
    {
      "id": "ses_demo_jubilee_001",
      "object": "session",
      "practitioner_id": "prc_2481",
      "starts_at": "2026-08-02T07:00:00.000Z",
      "ends_at": "2026-08-02T08:00:00.000Z",
      "timezone": "Africa/Nairobi",
      "format": "online",
      "status": "confirmed",
      "payment_source": "covered"
    }
  ],
  "has_more": false
}

Session responses intentionally omit Person, clinical, coverage and payment-provider identifiers.

List Claims

curl "https://api.heyrafiki.space/v1/claims?limit=10" \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxx"

{
  "object": "list",
  "data": [
    {
      "id": "clm_demo_jubilee_001",
      "object": "claim",
      "status": "submitted",
      "provider_claim_reference": null,
      "submission_version": 1,
      "amount": {
        "currency": "KES",
        "billed": 380000,
        "approved": null,
        "settled": null
      },
      "service_period": {
        "starts_at": "2026-07-20T05:00:00.000Z",
        "ends_at": "2026-07-20T05:50:00.000Z"
      },
      "lines": [],
      "information_requests": [],
      "adjudication": null,
      "submitted_at": "2026-07-20T05:50:00.000Z",
      "updated_at": "2026-07-20T05:50:00.000Z"
    }
  ],
  "has_more": false
}

Claim responses are project-scoped and omit Person, payer and clinical-record identifiers. See Claims and remittance for submission, evidence, adjudication and reconciliation.

Conventions

IDs are opaque strings. Never parse them.
Amounts are integers in the currency’s minor unit. 350000 is KES 3,500.00.
Currency codes use ISO 4217.
Unknown fields may be added. Ignore fields your integration does not use.

The generated endpoint reference is built from the versioned OpenAPI definition in this repository.

​Released surface

​Start with one workflow

​List Practitioners

​Retrieve a Practitioner

​Retrieve recurring availability

​Create a Booking

​Check Benefits

​List Sessions

​List Claims

​Conventions