Therapy Provider Guide

This document defines all requirements, flows, events, and integration rules for Therapy Providers on the AwaDoc Platform. It covers physiotherapy and all therapy-related services.

Important: The therapy flow is self-contained end-to-end under the therapy.* namespace. It covers availability discovery, booking, payment confirmation, assignment, scheduling, and the full session lifecycle.

1. Overview

Therapy services operate as scheduled consultations. A user books a session; the provider must accept, decline, or propose a new time. Sessions may be single or multi-session therapy plans.

2. Prerequisites (Platform-Side Setup)

Before you can receive or send any therapy events, the following must be set:

Requirement	Details
Business Record	Must exist and be ACTIVE
Service Offering	At least one APPROVED offering under category consultation
Callback URLs	`testCallbackUrl` and `productionCallbackUrl` must be configured by platform team
API Keys	Test and/or Production keys provided by platform admin
Bank Verification	Mandatory for production keys
Note	Callback URLs cannot be changed via API

3. Environments

Environment	Triggered When	Used For
Test	Test keys generated	`testCallbackUrl` + Test API key
Production	Business is live	`productionCallbackUrl` + Production API key

4. Base URLs

Sandbox: https://partners-staging.awadoc.com/api-doc
Production: https://partners-prod-001.awadoc.com/api-doc

5. Security — HMAC SHA256 Signatures

All communication must be signed.

Inbound (Platform → Provider)

Header	Value
`X-Event-Id`	Unique event UUID
`X-Timestamp`	Unix seconds
`X-Signature`	`HMAC_SHA256( sha256(body) + "\n" + timestamp, secret )` → hex
`Content-Type`	`application/json`

Outbound (Provider → Platform)

Endpoint:

POST /api/partners/:partnerId/callback

Header	Value
`x-timestamp`	Unix seconds
`x-signature`	`HMAC_SHA256( sha256(body) + "\n" + timestamp, secret )` → hex
`Content-Type`	`application/json`

Clock Skew Allowed: ±5 minutes

Signature Example (Node.js)

const crypto = require("crypto");
function signPayload(body, timestamp, secret) {
  const hash = crypto.createHash("sha256").update(body).digest("hex");
  const message = `${hash}\n${timestamp}`;
  return crypto.createHmac("sha256", secret).update(message).digest("hex");
}

6. Full Therapy Flow (End-to-End)

The therapy lifecycle consists of two phases:

Phase 1 — Booking Flow (Events 1–5): Availability discovery, booking, payment confirmation, therapist assignment, and scheduling.
Phase 2 — Session Lifecycle (Events 6–10): Session management, follow-ups, and plan completion.

Phase 1: Booking Flow

Event 1 — `therapy.availability.query` (Platform → Provider)

Sent when a user searches for available therapy/physiotherapy specialists.

Provider should respond within 10 seconds.

Example Payload

{
  "event_id": "evt-abc123",
  "event_type": "therapy.availability.query",
  "timestamp": "2025-12-09T10:00:00Z",
  "user": { "id": "usr-5521", "name": "Chinwe Okoye" },
  "context": {
    "service_area": "Lagos",
    "schedule": {
      "preferred_mode": "home_visit", // home_visit, office_visit, both
      "preferred_lang": "en"
    }
  },
  "meta": {
    "query_id": "qry-789",
    "trace_id": "trace-456"
  }
}

Your Response

{
  "status": "available",
  "query_id": "qry-789",
  "queried_at": "2025-12-09T10:00:05Z",
  "specialists": [
    {
      "type": "physiotherapist",
      "name": "Physiotherapist",
      "availability_mode": "home_visit",
      "scheduling_mode": "patient_choice",
      "pricing": { "amount": 15000.0, "currency": "NGN" },
      "doctor_time": [
        {
          "timezone": "Africa/Lagos",
          "days": ["MON", "WED", "FRI"],
          "hours": { "start": "08:00", "end": "18:00" }
        }
      ]
    }
  ]
}

doctor_time is required if scheduling_mode === "doctor_choice"

Event 2 — `therapy.request` (Platform → Provider)

Sent when a user selects your therapy offering to book.

Provider must respond within 10 minutes.

Example Payload

{
  "event_id": "evt-def456",
  "event_type": "therapy.request",
  "timestamp": "2025-12-09T10:20:12Z",
  "user": {
    "id": "usr-5521",
    "name": "Chinwe Okoye",
    "phone": "+2348091112223"
  },
  "context": {
    "specialist_type": "physiotherapist",
    "service_type": "physiotherapy",
    "session_type": "single",
    "schedule": {
      "preferred_mode": "home_visit",
      "preferred_time": "2025-12-09T14:00:00Z",
      "preferred_lang": "en"
    },
    "notes": "Lower back pain for 2 weeks",
    "location": {
      "address": "Lekki Phase 1, Lagos"
    }
  },
  "meta": {
    "request_id": "req-321",
    "trace_id": "trace-789"
  }
}

Response Options

1. Confirm

{
  "status": "confirmed",
  "request_id": "req-321",
  "confirmed_at": "2025-12-09T10:20:22Z",
  "therapy": {
    "id": "thp-901",
    "schedule": {
      "preferred_mode": "home_visit",
      "preferred_time": "2025-12-09T14:00:00Z",
      "preferred_lang": "en"
    },
    "pricing": { "amount": 15000.0, "currency": "NGN" }
  }
}

Pricing is required for order creation.

2. Decline

{
  "status": "declined",
  "request_id": "req-321",
  "reason": "no_available_therapist"
}

3. Propose Reschedule

{
  "status": "reschedule_proposed",
  "request_id": "req-321",
  "proposed_time": "2025-12-09T16:00:00Z",
  "reason": "therapist_unavailable_at_requested_time"
}

Event 3 — `therapy.confirmed` (Platform → Provider)

Sent after payment succeeds. This is the platform confirming the booking is paid and locked in.

Example Payload

{
  "event_id": "evt-ghi789",
  "event_type": "therapy.confirmed",
  "timestamp": "2025-12-09T11:30:00Z",
  "user": { "id": "usr-5521", "name": "Chinwe Okoye" },
  "context": {
    "therapy": {
      "id": "thp-901",
      "schedule": {
        "preferred_mode": "home_visit",
        "preferred_time": "2025-12-09T14:00:00Z"
      },
      "pricing": { "amount": 15000.0, "currency": "NGN" }
    }
  },
  "meta": { "request_id": "req-321", "trace_id": "trace-789" }
}

Your Response

{
  "status": "acknowledged",
  "acknowledged_at": "2025-12-09T11:30:05Z"
}

Event 4 — `therapy.doctor_assigned` (Provider → Platform)

Send this when you assign a therapist to the session.

{
  "event_id": "evt-your-uuid",
  "event_type": "therapy.doctor_assigned",
  "timestamp": "2025-12-09T12:00:00Z",
  "context": {
    "therapy": {
      "id": "thp-901",
      "schedule": {
        "preferred_mode": "home_visit",
        "preferred_time": "2025-12-09T14:00:00Z"
      },
      "pricing": { "amount": 15000.0, "currency": "NGN" }
    },
    "doctor": {
      "id": "thp-stf-220",
      "name": "Dr. Kemi Balogun",
      "email": "kemi@clinic.com",
      "contact": "+2347012345678",
      "avatar_url": "https://..."
    }
  }
}

Event 5 — `therapy.scheduled` (Provider → Platform) or (Platform → Provider)

Send this when you confirm the final schedule (especially if you picked the time or mode).

{
  "event_id": "evt-your-uuid-2",
  "event_type": "therapy.scheduled",
  "timestamp": "2025-12-09T12:05:00Z",
  "context": {
    "therapy": {
      "id": "thp-901",
      "schedule": {
        "preferred_mode": "home_visit",
        "preferred_time": "2025-12-09T14:00:00Z"
      },
      "pricing": { "amount": 15000.0, "currency": "NGN" }
    },
    "meeting": {
      "mode": "home_visit",
      "start_time": "2025-12-09T14:00:00Z",
      "end_time": "2025-12-09T15:00:00Z",
      "duration": "01:00:00",
      "address": "Lekki Phase 1, Lagos"
    }
  }
}

Platform responds with { "status": "acknowledged", ... }

Phase 2: Session Lifecycle

Once the booking phase is complete (therapist assigned, session scheduled), the session events begin.

Event 6 — `therapy.session.started` (Provider → Platform)

Send when the therapist physically begins the session.

{
  "request_id": "req-321",
  "therapy_id": "thp-901",
  "event": "therapy.session.started",
  "started_at": "2025-12-09T14:05:00Z"
}

Event 7 — `therapy.session.completed` (Provider → Platform)

Send after the therapy session ends.

{
  "request_id": "req-321",
  "therapy_id": "thp-901",
  "event": "therapy.session.completed",
  "completed_at": "2025-12-09T15:00:00Z",
  "summary": "User responded well to initial mobility exercises."
}

Payout is triggered after this event.

Event 8 — `therapy.followup.required` (Provider → Platform) (Optional)

For physiotherapy or multi-session plans, send this to indicate additional sessions are needed.

{
  "request_id": "req-321",
  "therapy_id": "thp-901",
  "event": "therapy.followup.required",
  "sessions_remaining": 5,
  "notes": "Requires 2x weekly sessions for 3 weeks."
}

Event 9 — `therapy.session.assigned` (Platform → Provider)

Sent by the platform when it confirms therapist assignment for a follow-up session.

{
  "event_type": "therapy.session.assigned",
  "request_id": "req-321",
  "therapy_id": "thp-901",
  "therapist": {
    "name": "Dr. Kemi Balogun",
    "id": "thp-stf-220"
  }
}

Event 10 — `therapy.plan.completed` (Provider → Platform)

Send when all sessions in a multi-session therapy plan have been completed.

{
  "request_id": "req-321",
  "therapy_id": "thp-901",
  "event": "therapy.plan.completed",
  "completed_at": "2025-12-30T12:00:00Z"
}

7. Complete Flow Diagram

[User Searches]
      |
      v
Event 1: therapy.availability.query       (Platform → Provider)
      |
      v
[Provider returns available therapists]
      |
      v
Event 2: therapy.request                  (Platform → Provider)
      |
      ├── confirmed → continue
      ├── declined → flow ends
      └── reschedule_proposed → user decides
      |
      v
[Payment processed by platform]
      |
      v
Event 3: therapy.confirmed                (Platform → Provider)
      |
      v
[Provider acknowledges]
      |
      v
Event 4: therapy.doctor_assigned          (Provider → Platform)
      |
      v
Event 5: therapy.scheduled                (Provider → Platform)
      |
      v
─────────── SESSION LIFECYCLE ───────────
      |
      v
Event 6: therapy.session.started          (Provider → Platform)
      |
      v
Event 7: therapy.session.completed        (Provider → Platform)
      |
      ├── Single session → DONE, payout triggered
      └── Multi-session plan
            |
            v
      Event 8: therapy.followup.required  (Provider → Platform)
            |
            v
      Event 9: therapy.session.assigned   (Platform → Provider)
            |
            v
      [Repeat Events 6–8 per session]
            |
            v
      Event 10: therapy.plan.completed    (Provider → Platform)

8. Timeouts & Platform Rules

Scenario	Time Allowed	Platform Action
No response to `therapy.request`	10 mins	Auto-decline
Therapist does not start session	20 mins grace	User prompted to reschedule
Missed follow-up session	24 hrs	Request reopens
Availability query response	10 secs	Provider skipped in results

9. Payment & Payout Rules

Providers are paid after therapy.session.completed.
Multi-session plans pay per session, not upfront.
Home visits include an additional field for distance-based compensation.

10. Therapy Specialist Types

Use these exact specialist_type slugs when registering therapy service offerings:

specialist_type	Specialty
`physiotherapist`	Physiotherapist
`occupational-therapist`	Occupational Therapist
`speech-therapist`	Speech Therapist

11. Error Handling

Standard Provider Error Response

{
  "error": "invalid_payload",
  "message": "scheduled_for field missing"
}

12. Key Notes

Topic	Detail
Event namespace	All events are prefixed `therapy.*`
Currency field	Use `"currency"` — exact match required
Timestamp units	Inbound: seconds, Outbound: seconds
No Callback URL	Provider is skipped entirely in availability and booking
Specialist types	Use exact slug strings (e.g. `physiotherapist`)
Idempotency	All callbacks must be idempotent — the platform may retry events

Contact & Support

Integration help: integration@awadoc.com (include partner_id and trace_id in subject)
Production disbursal issues: settlements@awadoc.com

You are now equipped to offer therapy through the AwaDoc network. Fast, clear decisions save users time and money ensure your callbacks are real-time and idempotent.

Respond fast. Users rely on you. 💸✅

Therapy Provider Guide