Rehabify Partner API Documentation

Version 1.0 Partner Integration Reference

Purpose

This document defines the version 1 contract for partners sending patient referrals to Rehabify and receiving non-clinical progress updates. It is intended for partner engineering and product teams.

Recommended Integration

• Use the hosted referral link when no engineering work is required.
• Use the API when the partner wants to create referrals inside its own product, reconcile status, or receive automated webhook updates.

Integration Options

Environment and Format

• The environment-specific base URL and credentials are issued during onboarding.
• Examples use https://{environment-host}/v1 (e.g. https://api.physioaroundme.com/v1). Replace {environment-host} with the supplied host.
• Requests and responses use UTF-8 JSON over HTTPS. Timestamps use ISO 8601 UTC.
• Currency values are integer minor units. For example, NGN 20,000 is sent as 2000000 kobo.

Data Boundary (NDPR Compliance)

The partner API carries referral, contact, appointment and commercial status only. Clinical notes, Joy conversations, assessment findings, and treatment plans are never returned to partners.

Authentication

Send the partner API key as a bearer token. Keys are environment-specific and must be stored server-side. Never place an API key in a browser, mobile application, or referral URL.

Authorization: Bearer <partner_api_key>
Content-Type: application/json
Idempotency-Key: <unique_value>
X-Request-ID: <optional_trace_id>

Create Referral

POST /api/v1/partners/referrals (or POST /v1/partner/referrals)

Request Fields

Create Referral Example

curl -X POST https://api.physioaroundme.com/api/v1/partners/referrals \
  -H "Authorization: Bearer sk_test_rehabify_sandbox" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7b83f5e1-88f2-4917-8a4b-220011bb91ab" \
  -d '{
    "external_ref": "WELLS-10482",
    "patient": {
      "first_name": "Tolu",
      "phone": "+2348012345678",
      "email": "tolu@example.com",
      "city": "Lagos"
    },
    "reason": "Ongoing lower back pain and difficulty walking",
    "care_mode": "either",
    "preferred_contact": "whatsapp",
    "route": "joy",
    "consent": {
      "accepted": true,
      "accepted_at": "2026-09-10T14:20:00Z",
      "version": "partner-referral-v1",
      "source": "wells_health_app"
    },
    "metadata": {"campaign": "launch_2026"}
  }'

Successful Response (HTTP 201 Created)

{
  "referral_id": "ref_01K4R7G9T4",
  "external_ref": "WELLS-10482",
  "status": "received",
  "care_mode": "either",
  "next_action": "start_joy",
  "joy_session_url": "https://physioaroundme.com/joy/session-token",
  "created_at": "2026-09-10T14:20:02Z"
}

[!IMPORTANT] The joy_session_url is short-lived and intended for the patient. Do not log it or use it as the permanent referral identifier. Store referral_id and external_ref instead.

Retrieve Referrals

GET /api/v1/partners/referrals/{referral_id}
GET /api/v1/partners/referrals?external_ref=WELLS-10482
GET /api/v1/partners/referrals?status=booked&created_from=2026-09-01T00:00:00Z

List responses are paginated using limit and cursor. The response may include appointment status, paid amount, and partner commission where the commercial agreement permits it. It never includes clinical records.

Referral Statuses

Hosted Referral Links

Rehabify issues a unique trackable link for each partner or campaign:

https://physioaroundme.com/r/{public_code}

• The public code is non-guessable and contains no patient information.
• Inactive or expired links show a safe error page and do not accept submissions.
• A link click is not commission-eligible by itself. Eligibility follows the signed commercial agreement.

Webhook Delivery

Rehabify sends signed POST requests to the partner webhook URL. Return any 2xx response after successful validation and processing. Delivery may be repeated, so event handling must be idempotent using event_id.

Webhook Headers & Verification

X-Rehabify-Event-ID: evt_01K4R9
X-Rehabify-Timestamp: 1789050120
X-Rehabify-Signature: v1=<hex_hmac_sha256>

Calculate HMAC SHA-256 over timestamp + '.' + exact_raw_request_body using the webhook secret. Reject invalid signatures and timestamps older than five minutes. Compare signatures using a constant-time function.

Webhook Example Payload

{
  "event_id": "evt_01K4R9",
  "type": "payment.completed",
  "occurred_at": "2026-09-12T10:42:11Z",
  "data": {
    "referral_id": "ref_01K4R7G9T4",
    "external_ref": "WELLS-10482",
    "status": "paid",
    "care_mode": "remote",
    "payment": {
      "currency": "NGN",
      "amount_minor": 2000000,
      "partner_commission_minor": 200000,
      "commission_status": "pending_settlement"
    }
  }
}

Retry policy: Non-2xx responses are retried with exponential backoff for up to 24 hours. Partners must tolerate duplicate and out-of-order delivery.

Error Handling

{
  "error": {
    "code": "validation_error",
    "message": "One or more fields are invalid",
    "fields": {
      "patient.phone": "Use E.164 format"
    },
    "request_id": "req_01K4RA"
  }
}

Sandbox Acceptance Checklist

Before production credentials are issued, partners should verify each item:

1. Create valid contact referral: 201 Created response and stable referral_id
2. Create valid Joy referral: 201 Created response and short-lived joy_session_url
3. Retry same POST: No duplicate referral; original referral returned
4. Send invalid phone number: 422 Unprocessable Entity with field-level error
5. Retrieve by referral_id and external_ref: Both resolve to identical referral record
6. Receive and verify webhooks: Valid HMAC SHA-256 signature and idempotent processing
7. Complete paid referral: Payment and commission match the commercial agreement
8. Review logs: No API keys, patient health notes, or session URLs in logs