HMO and insurer integration

This guide shows how a Health Maintenance Organisation (HMO) or insurer can send covered members to Rehabify for physiotherapy, and track their care without paper claims.

The workflow

1. A member needs physiotherapy. A doctor recommends it, or the member asks in your app or call centre.
2. You authorise the care in your own system, as you do today, and get your authorisation or case number.
3. Your system creates a referral with billing_mode: "hmo_direct_billing" and your case number as partner_reference.
4. You give the member links.whatsapp_intake_url by SMS or in your app, so they can start with Joy straight away. Rehabify's care team also contacts them.
5. Webhooks keep your case record in sync as the member is contacted, booked, treated and discharged.
6. You pull a progress report (JSON or PDF) for utilisation review and to close the case.

1. Create the referral

Use your authorisation or case number as partner_reference. It must be unique per environment, and you can fetch the referral with it later. Put plan details in metadata, never clinical details.

curl https://api.physioaroundme.com/v1/partners/referrals \
  -X POST \
  -H "Authorization: Bearer $REHABIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 1c9e7a52-3b8d-4f6e-a1c0-9d8e7f6a5b4c" \
  -d '{
    "partner_reference": "AUTH-2026-55120",
    "patient": {
      "first_name": "Kelechi",
      "last_name": "Iheanacho",
      "phone": "08031122334",
      "city": "Lagos",
      "state": "Lagos",
      "area": "Victoria Island"
    },
    "clinical": {
      "condition": "Post-operative knee rehabilitation (meniscus repair)",
      "notes": "Arthroscopic meniscus repair 3 weeks ago. Cleared for physiotherapy by the orthopaedic surgeon.",
      "priority": "urgent",
      "recommended_sessions": 8,
      "referring_clinician": "Dr. Adebayo (Orthopaedics)"
    },
    "care": { "preferred_mode": "in_person", "preferred_contact_channel": "whatsapp" },
    "billing_mode": "hmo_direct_billing",
    "consent": {
      "granted": true,
      "method": "call_centre_verbal",
      "captured_at": "2026-10-13T08:45:00.000Z",
      "privacy_notice_version": "2026-09-01"
    },
    "metadata": { "plan": "gold", "authorised_sessions": "8" }
  }'

Metadata values must be strings, which is why authorised_sessions is sent as "8".

2. Hand the member over to Joy

Send the member links.whatsapp_intake_url, for example in an SMS: "Your physiotherapy is approved. Tap to start with Rehabify on WhatsApp: https://wa.me/2348061525811?text=START%20RHB-4829173655". The link opens a chat with Joy that's already linked to the referral, and referral.contacted fires once the member messages Joy.

3. Keep your case record in sync

Map webhook events to your case statuses:

Webhooks don't include member details, so match events on data.referral.partner_reference, which is your authorisation number. See Webhooks and Signature verification.

4. Pull progress reports

For utilisation review, fetch the progress report by your authorisation number. It shows sessions prescribed, attended, upcoming and cancelled, plus milestone dates. It contains no clinical notes.

curl https://api.physioaroundme.com/v1/partners/reports/AUTH-2026-55120 \
  -H "Authorization: Bearer $REHABIFY_API_KEY"

# The same report as a PDF, for the case file
curl https://api.physioaroundme.com/v1/partners/reports/AUTH-2026-55120/pdf \
  -H "Authorization: Bearer $REHABIFY_API_KEY" \
  -o AUTH-2026-55120.pdf

See Progress reports for the full object, and Sessions for per-appointment attendance.

Data protection

• Send only the clinical information Rehabify's clinicians need, in clinical.notes. It's write-only and never returned.
• Webhooks and reports never contain clinical notes, and webhooks never contain member personal data.
• Keep API keys and webhook secrets on your servers only.