Docs/API Reference

Referrals

Create, list and retrieve patient referrals. The referral object, its statuses, and every field and validation rule.

A referral is a patient you've sent to Rehabify. Once you create one, Rehabify's care team and Joy, our WhatsApp care assistant, contact the patient, match them with a physiotherapist and book their care. You follow progress through the referral's status, through webhooks, and through sessions and progress reports.

Method	Path
`POST`	`/partners/referrals`	Create a referral
`GET`	`/partners/referrals`	List referrals
`GET`	`/partners/referrals/{id}`	Retrieve a referral

The referral object

{
  "object": "referral",
  "id": "jd7f3k2m9x1q8w4e5r6t7y8u9i0o1p2a",
  "tracking_code": "RHB-4829173655",
  "partner_reference": "HMO-REF-2026-0091",
  "environment": "live",
  "status": "received",
  "patient": {
    "first_name": "Adeola",
    "last_name": "Balogun",
    "phone": "+2348012345678",
    "email": "adeola@example.com",
    "city": "Lagos",
    "state": "Lagos",
    "area": "Ikeja",
    "preferred_language": "en"
  },
  "clinical": {
    "condition": "Lower back pain",
    "priority": "standard",
    "recommended_sessions": 6,
    "referring_clinician": "Dr. Okafor"
  },
  "care": { "preferred_mode": "patient_choice", "preferred_contact_channel": "whatsapp" },
  "billing_mode": "hmo_direct_billing",
  "provider": null,
  "sessions": { "completed": 0, "total": 6, "last_session_at": null, "next_session_at": null },
  "links": {
    "tracking_url": "https://physioaroundme.com/track/RHB-4829173655",
    "whatsapp_intake_url": "https://wa.me/2348061525811?text=START%20RHB-4829173655"
  },
  "metadata": { "member_plan": "gold" },
  "created_at": "2026-10-13T09:30:00.000Z",
  "updated_at": "2026-10-13T09:30:00.000Z"
}

Field	Type	Description
`object`	string	Always `referral`.
`id`	string	Rehabify's unique ID for the referral.
`tracking_code`	string	`RHB-` followed by 10 digits. Older referrals may have `RHB-` followed by 5 digits. Case-insensitive, and safe to share with the patient.
`partner_reference`	string or null	Your own reference, if you sent one.
`environment`	string	`sandbox` or `live`.
`status`	string	The public status. See Statuses.
`patient`	object	Contact details as stored: `first_name`, `last_name`, `phone` (always E.164), `email`, `city`, `state`, `area`, `preferred_language`. Webhooks never include this block.
`clinical`	object	`condition`, `priority`, `recommended_sessions`, `referring_clinician`. `clinical.notes` is write-only and never returned.
`care`	object	`preferred_mode` and `preferred_contact_channel`.
`billing_mode`	string	`patient_self_pay`, `hmo_direct_billing` or `corporate_sponsored`.
`provider`	object or null	`null` until a physiotherapist is matched. Then `{ "name": "Chiamaka Obi", "license_number": "MRTBN/PT/12345" }`, where `license_number` may be `null`. In sandbox: `{ "name": "Sandbox Physiotherapist", "license_number": "SANDBOX-0001" }`.
`sessions`	object	`completed` (sessions attended), `total` (sessions prescribed), `last_session_at`, `next_session_at`.
`links.tracking_url`	string	The public status page for this referral. It shows only the status timeline, with no personal or clinical data.
`links.whatsapp_intake_url`	string	Opens WhatsApp with Joy, pre-filled with `START <tracking_code>`. Give it to the patient so they can start intake straight away.
`metadata`	object	The metadata you sent, echoed back.
`created_at`, `updated_at`	string	ISO-8601 UTC timestamps.

Statuses

A referral's status is always one of these eight values:

Status	Meaning
`received`	Rehabify accepted the referral.
`contacted`	The care team or Joy reached the patient, and intake has started.
`booked`	The first appointment is confirmed.
`in_treatment`	Rehabilitation sessions are under way.
`completed`	The care episode is complete and the patient has been discharged.
`not_suitable`	Rehabify's services aren't appropriate for this patient, who has been redirected to appropriate care. No clinical detail is disclosed.
`cancelled`	The referral or booking was cancelled or refunded.
`closed`	No further activity is expected.

Every status change fires a webhook named after the new status, such as referral.booked.

Create a referral

POST /partners/referrals

Creates a referral and returns it with status received. In live, Rehabify's care team and Joy then contact the patient.

Headers: Authorization, Content-Type: application/json, and Idempotency-Key. The idempotency key is optional but strongly recommended. See Idempotency.

Request body

Field	Type	Required	Rules
`partner_reference`	string	No	1–100 characters. Unique per partner per environment. Reusing one returns `409 duplicate_partner_reference`.
`patient.first_name`	string	Yes	1–100 characters.
`patient.last_name`	string	No	Up to 100 characters.
`patient.phone`	string	Yes	E.164 (`+2348012345678`) or Nigerian local format (`08012345678`, `2348012345678`). Stored and returned as E.164.
`patient.email`	string	No	A valid email address.
`patient.city`, `patient.state`, `patient.area`	string	No	Up to 100 characters each.
`patient.preferred_language`	string	No	`en`, `yo`, `ig` or `ha`.
`clinical.condition`	string	No	Up to 200 characters, for example `Lower back pain`.
`clinical.notes`	string	No	Up to 5,000 characters. Write-only: stored for Rehabify clinicians, and never returned by the API or webhooks.
`clinical.priority`	string	No	`standard` (default) or `urgent`.
`clinical.recommended_sessions`	integer	No	1–52. Default `4`.
`clinical.referring_clinician`	string	No	Up to 200 characters.
`care.preferred_mode`	string	No	`remote`, `in_person` or `patient_choice` (default).
`care.preferred_contact_channel`	string	No	`whatsapp` (default), `phone`, `email` or `sms`.
`billing_mode`	string	No	`patient_self_pay` (default), `hmo_direct_billing` or `corporate_sponsored`.
`consent.granted`	boolean	Yes	Must be `true`. By setting it, you confirm the patient agreed to be contacted by Rehabify. Anything else returns `422 consent_required`.
`consent.method`	string	No	Up to 50 characters, for example `electronic`.
`consent.captured_at`	string	No	ISO-8601 timestamp of when consent was captured.
`consent.privacy_notice_version`	string	No	Up to 50 characters.
`metadata`	object	No	Up to 20 keys (each up to 40 characters) with string values (each up to 500 characters). Echoed back on the referral and in webhooks.

Unknown fields are ignored. Use partner_reference for your own ID. There is no external_ref field.

Example

curl https://api.physioaroundme.com/v1/partners/referrals \
  -X POST \
  -H "Authorization: Bearer $REHABIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f8a2c71-5e4b-4d9a-b6c2-7e1f0a9d8c3b" \
  -d '{
    "partner_reference": "HMO-REF-2026-0091",
    "patient": {
      "first_name": "Adeola",
      "last_name": "Balogun",
      "phone": "+2348012345678",
      "email": "adeola@example.com",
      "city": "Lagos",
      "state": "Lagos",
      "area": "Ikeja",
      "preferred_language": "en"
    },
    "clinical": {
      "condition": "Lower back pain",
      "notes": "L4-L5 disc bulge on MRI. No red flags.",
      "priority": "standard",
      "recommended_sessions": 6,
      "referring_clinician": "Dr. Okafor"
    },
    "care": { "preferred_mode": "patient_choice", "preferred_contact_channel": "whatsapp" },
    "billing_mode": "hmo_direct_billing",
    "consent": {
      "granted": true,
      "method": "electronic",
      "captured_at": "2026-10-13T09:00:00.000Z",
      "privacy_notice_version": "2026-09-01"
    },
    "metadata": { "member_plan": "gold" }
  }'

Response

201 Created returns the referral object shown above, with status set to received and provider set to null. A replayed request (same Idempotency-Key, same body) returns the original response with the header Idempotent-Replayed: true.

Errors

HTTP	Code	When
400	`invalid_json`	The body isn't valid JSON.
401	`missing_api_key`, `invalid_api_key`	The key is missing, unknown or revoked.
403	`partner_inactive`, `production_access_required`	Your organisation or production access isn't approved.
409	`duplicate_partner_reference`	The `partner_reference` already exists in this environment. `error.existing` holds `id` and `tracking_code`.
409	`idempotency_request_in_progress`	A request with the same `Idempotency-Key` is still processing.
422	`validation_error`	A field failed validation. `param` names it.
422	`consent_required`	`consent.granted` isn't `true`.
422	`patient_ineligible`	Sandbox only: `patient.phone` is `+2348000000004`. No referral is created.
422	`idempotency_key_reused`	The same `Idempotency-Key` was used with a different body.
429	`rate_limit_exceeded`	Too many requests. Respect `Retry-After`.

What happens next

In live, Rehabify's care team and Joy contact the patient on their preferred channel. Give the patient links.whatsapp_intake_url, by SMS, email or in your app, so they can start straight away. Every status change is pushed to your webhook endpoint: referral.created fires immediately, then referral.contacted, referral.provider_matched, referral.booked, and so on.

In sandbox, nobody is contacted. Use magic phone numbers or the advance endpoint to simulate progress.

List referrals

GET /partners/referrals

Returns your referrals in the key's environment, newest first, as a paginated list.

Query parameters

Parameter	Type	Description
`limit`	integer	1–100. Default `25`.
`cursor`	string	The `next_cursor` from the previous page.
`status`	string	Only referrals in this public status.
`partner_reference`	string	Only the referral with this `partner_reference`.
`created_after`	string	ISO-8601 timestamp. Only referrals created after this time.
`created_before`	string	ISO-8601 timestamp. Only referrals created before this time.

An invalid value returns 400 invalid_parameter with param set.

curl "https://api.physioaroundme.com/v1/partners/referrals?status=in_treatment&created_after=2026-10-01T00:00:00.000Z&limit=50" \
  -H "Authorization: Bearer $REHABIFY_API_KEY"

200 OK

{
  "object": "list",
  "data": [
    {
      "object": "referral",
      "id": "jd7f3k2m9x1q8w4e5r6t7y8u9i0o1p2a",
      "tracking_code": "RHB-4829173655",
      "partner_reference": "HMO-REF-2026-0091",
      "environment": "live",
      "status": "in_treatment",
      "patient": {
        "first_name": "Adeola",
        "last_name": "Balogun",
        "phone": "+2348012345678",
        "email": "adeola@example.com",
        "city": "Lagos",
        "state": "Lagos",
        "area": "Ikeja",
        "preferred_language": "en"
      },
      "clinical": {
        "condition": "Lower back pain",
        "priority": "standard",
        "recommended_sessions": 6,
        "referring_clinician": "Dr. Okafor"
      },
      "care": { "preferred_mode": "patient_choice", "preferred_contact_channel": "whatsapp" },
      "billing_mode": "hmo_direct_billing",
      "provider": { "name": "Chiamaka Obi", "license_number": "MRTBN/PT/12345" },
      "sessions": {
        "completed": 2,
        "total": 6,
        "last_session_at": "2026-10-18T10:00:00.000Z",
        "next_session_at": "2026-10-22T10:00:00.000Z"
      },
      "links": {
        "tracking_url": "https://physioaroundme.com/track/RHB-4829173655",
        "whatsapp_intake_url": "https://wa.me/2348061525811?text=START%20RHB-4829173655"
      },
      "metadata": { "member_plan": "gold" },
      "created_at": "2026-10-13T09:30:00.000Z",
      "updated_at": "2026-10-18T10:47:00.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0xMC0xM1QwOTozMDowMC4wMDBaIn0"
}

Retrieve a referral

GET /partners/referrals/{id}

{id} can be the referral's id, its tracking_code (case-insensitive), or your partner_reference. URL-encode a partner_reference that contains special characters.

# By tracking code; the id or your partner_reference work the same way
curl https://api.physioaroundme.com/v1/partners/referrals/RHB-4829173655 \
  -H "Authorization: Bearer $REHABIFY_API_KEY"

Response: 200 OK with the referral object.

Errors: 404 referral_not_found when nothing matches in this environment. This includes referrals that belong to another partner or to the other environment.

← PreviousOverview Next →Sessions