API reference
Base URL, authentication, every Partner API endpoint, and the OpenAPI 3.1 specification for Postman and Insomnia.
Base URL
https://api.physioaroundme.com/v1All paths on these pages are relative to this base URL. The same API is also available at https://physioaroundme.com/api/v1. Sandbox and live share both hosts, and the API key decides the environment.
Authentication
Send your secret key as a bearer token, or in X-API-Key:
Authorization: Bearer sk_test_xxxKeys starting with sk_test_ hit the sandbox, and keys starting with sk_live_ hit live. Never call the API from a browser or mobile app. See Authentication.
OpenAPI specification
A complete OpenAPI 3.1 document describes every endpoint, schema, error and webhook:
https://physioaroundme.com/openapi.json
You can import it into your API client:
- Postman: choose Import, paste the URL, and Postman creates a collection. Set the collection's authorization to Bearer Token with your
sk_test_key. - Insomnia: choose Import, then From URL, and paste the URL.
- Code generators: any OpenAPI 3.1-compatible generator can build a typed client from the document.
Endpoints
| Method | Path | Description |
|---|---|---|
POST | /partners/referrals | Create a referral |
GET | /partners/referrals | List referrals |
GET | /partners/referrals/{id} | Retrieve a referral by id, tracking_code or partner_reference |
GET | /partners/sessions | List appointments for your referrals |
GET | /partners/reports/{id} | Progress report (JSON, no clinical notes) |
GET | /partners/reports/{id}/pdf | Progress report as a PDF |
GET | /partners/providers | Verified physiotherapist directory |
POST | /partners/referral-links | Create a no-code referral link |
GET | /partners/referral-links | List your referral links |
PATCH | /partners/referral-links/{id} | Activate or deactivate a link |
GET | /partners/commercial | Your commercial terms and earnings summary |
GET | /partners/commissions | Commission ledger |
POST | /partners/eligibility | Eligibility check. Coming soon (sandbox preview only) |
Sandbox-only endpoints
These work only with sk_test_ keys. With a live key, they return 403 sandbox_only.
| Method | Path | Description |
|---|---|---|
POST | /sandbox/referrals/{id}/advance | Move a sandbox referral to a new status, firing the matching webhooks |
POST | /sandbox/trigger-webhook | Send a test event to your sandbox webhook endpoint |
Public endpoint (no API key)
| Method | Path | Description |
|---|---|---|
POST | /public/referral-links/{public_code}/leads | Submit a patient lead through a referral link. CORS-enabled and rate limited per IP. |
Response headers
| Header | When | Meaning |
|---|---|---|
X-Request-Id | Every response | Unique request ID, such as req_5f2c9a1b7d3e4f60a1b2c3d4. Quote it to support. |
X-Rehabify-Environment | Every response | sandbox or live |
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset | Every authenticated response | See Rate limits. |
Retry-After | 429 responses | Seconds to wait before retrying |
Idempotent-Replayed | Replayed POST responses | true when the response was replayed for a repeated Idempotency-Key |
Conventions at a glance
- JSON bodies in UTF-8. Unknown request fields are ignored.
- Timestamps are ISO-8601 UTC strings, such as
2026-10-13T09:30:00.000Z. - Money is in integer kobo, in fields ending
_kobo, with"currency": "NGN". - Lists use
limit(1–100, default 25) andcursor, and return{ "object": "list", "data": [...], "has_more": ..., "next_cursor": ... }. POSTendpoints acceptIdempotency-Key.
Details are in Conventions, and every error code is in Errors.