Consultation Provider Guide

For Businesses Integrating as Consultation Partners

This guide explains exactly what you need to do as a consultation provider to receive bookings, respond to availability checks, and manage consultations — based on the current live platform behavior.

Your Role as a Consultation Provider

You provide medical consultations (virtual or physical). The platform:

Discovers your approved consultation offerings
Sends you real-time availability queries and booking requests
Expects signed, timely responses from your system
Aggregates your responses and completes the user flow

Prerequisites (Platform-Side Setup)

Before you can receive events:

Requirement	Details
Business Record	Must exist with `status: ACTIVE`
Service Offering	One or more `APPROVED` offerings in category `consultation`
Callback URLs	`testCallbackUrl` and `productionCallbackUrl` must be set on your Business record
API Keys	Test and/or Production keys issued via platform admin
Bank Verification	Required for production keys

Note: You cannot set callback URLs via API. These are configured by the platform team.

Environments

Environment	Triggered When	Uses
Test	`Test keys are generated`	`testCallbackUrl` + test API key
Production	`Account is live`	`productionCallbackUrl` + production API key

Base URLs

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

Security: HMAC SHA256 Signatures

All communication is secured with HMAC SHA256 using your environment-specific secret.

From Platform → You (Inbound)

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`

From You → Platform (Outbound)

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 Generation (Node.js Example)

import crypto from "crypto";

function signPayload(body: any, secret: string, timestamp: number): string {
  const bodyHash = crypto
    .createHash("sha256")
    .update(JSON.stringify(body))
    .digest("hex");
  const canonical = `${bodyHash}\n${timestamp}`;
  return crypto.createHmac("sha256", secret).update(canonical).digest("hex");
}

Events You Will Receive

1. `consultation.availability.query`

Sent when a user searches for available specialists.

Payload

{
  "event_id": "evt-abc123",
  "event_type": "consultation.availability.query",
  "timestamp": "2025-11-05T10:00:00Z",
  "user": { "id": "usr-123", "name": "Jane Doe" },
  "context": {
    "service_area": "Lagos", // or "ALL"
    "schedule": {
      "preferred_mode": "virtual", // virtual | physical | null
      "preferred_lang": "en"
    }
  },
  "meta": {
    "query_id": "qry-789",
    "trace_id": "trace-456"
  }
}

Your Response (within 10s recommended)

{
  "status": "available",
  "query_id": "qry-789",
  "queried_at": "2025-11-05T10:00:05Z",
  "specialists": [
    {
      "type": "general-practitioner",
      "name": "General Practitioner",
      "availability_mode": "both", // virtual | physical | both
      "scheduling_mode": "patient_choice", // or "doctor_choice"
      "pricing": { "amount": 5000.0, "currency": "NGN" },
      "doctor_time": [
        {
          "timezone": "Africa/Lagos",
          "days": ["MON", "TUE", "WED"],
          "hours": { "start": "09:00", "end": "17:00" }
        }
      ]
    }
  ]
}

doctor_time required only if scheduling_mode === "doctor_choice"
Use "currency" (yes, match exactly)

2. `consultation.request`

Sent when a user selects your offering to book.

Payload

{
  "event_id": "evt-def456",
  "event_type": "consultation.request",
  "timestamp": "2025-11-05T11:00:00Z",
  "user": { "id": "usr-123", "name": "Jane Doe" },
  "context": {
    "specialist_type": "general-practitioner",
    "schedule": {
      "preferred_mode": "virtual",
      "preferred_time": "2025-11-05T14:00:00Z",
      "preferred_lang": "en"
    }
  },
  "meta": { "request_id": "req-321", "trace_id": "trace-789" }
}

Your Response

{
  "status": "confirmed",
  "request_id": "req-321",
  "confirmed_at": "2025-11-05T11:00:10Z",
  "consultation": {
    "id": "cns-901",
    "schedule": {
      "preferred_mode": "virtual",
      "preferred_time": "2025-11-05T14:00:00Z",
      "preferred_lang": "en"
    },
    "pricing": { "amount": 5000.0, "currency": "NGN" }
  }
}

Pricing is required for order creation
Known bug: platform may reject if pricing present — report if blocked

3. `consultation.confirmed`

Sent after payment succeeds.

Payload

{
  "event_id": "evt-ghi789",
  "event_type": "consultation.confirmed",
  "timestamp": "2025-11-05T11:30:00Z",
  "user": { "id": "usr-123", "name": "Jane Doe" },
  "context": {
    "consultation": {
      "id": "cns-901",
      "schedule": { ... },
      "pricing": { "amount": 5000.00, "currency": "NGN" }
    },
    "meeting": { ... }
  },
  "meta": { "request_id": "req-321", "trace_id": "trace-789" }
}

Your Response

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

Events You Must Send (via Callback)

Use:
&#xNAN;POST /api/partners/:partnerId/callback

1. `consultation.doctor_assigned`

When you assign a doctor (especially if scheduling_mode: doctor_choice)

{
  "event_id": "evt-your-uuid",
  "event_type": "consultation.doctor_assigned",
  "timestamp": "2025-11-05T12:00:00Z",
  "context": {
    "consultation": { "id": "cns-901", "schedule": { ... }, "pricing": { ... } },
    "doctor": {
      "id": "doc-555",
      "name": "Dr. Aisha Bello",
      "email": "aisha@clinic.com",
      "avatar_url": "https://..."
    }
  }
}

2. `consultation.scheduled` (Provider → Platform) or (Platform → Provider)

When you pick time/mode (if user didn’t specify)

{
  "event_id": "evt-your-uuid-2",
  "event_type": "consultation.scheduled",
  "timestamp": "2025-11-05T12:05:00Z",
  "context": {
    "consultation": { "id": "cns-901", "schedule": { ... }, "pricing": { ... } },
    "meeting": {
        "mode": "virtual",
        "start_time": "2025-11-05T14:00:00Z",
        "end_time": "2025-11-05T14:30:00Z",
        "duration": "00:30:00",
        "link": "https://meet.awadoc.com/room/cns-901"
     }
  }
}

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

Testing Checklist

Confirm testCallbackUrl is set and reachable
Request test API keys
Implement callback endpoint with:
- Signature verification (inbound)
- Signature generation (outbound, ms)
- JSON parsing & validation
Respond to:
- consultation.availability.query → return specialists
- consultation.request → return confirmed with pricing + meeting
- consultation.confirmed → return acknowledged
Send:
- consultation.doctor_assigned
- consultation.scheduled (if needed)
Test end-to-end with platform team

Key Notes

Topic	Detail
Specialist Types	Use exact strings like `general-practitioner` (not `general-pratitional`)
Currency Field	Use `"currency"` — yes, exact match
Timestamp Units	Inbound: seconds, Outbound: seconds
Response Time	Aim for <10s for availability, <30s for booking
No Callback URL?	You are skipped entirely in availability and booking

This list defines the canonical set of medical specialties used across our platform integrations. Each specialist_type or speciality is a stable, slug-based identifier derived from the specialty name and is used by integration specialists to map external provider data, APIs, and workflows to AwaDoc’s internal taxonomy. During integrations, partners must reference these specialist_type or speciality values when registering services, routing consultations, configuring eligibility rules, reporting, or syncing provider catalogs. Using this standardized list ensures consistent discovery, reporting, and analytics across all partners and environments.

specialist_type	Specialty	Category
general-practitioner	General Practitioner	Primary care
family-medicine-physician	Family Medicine Physician	Primary care
internal-medicine-physician	Internal Medicine Physician	Primary care
pediatrician	Pediatrician	Child health
neonatologist	Neonatologist	Child health
cardiologist	Cardiologist	Heart and vascular care
interventional-cardiologist	Interventional Cardiologist	Heart and vascular care
dermatologist	Dermatologist	Skin care
plastic-surgeon	Plastic Surgeon	Skin and cosmetic care
gynecologist	Gynecologist	Women’s health
obstetrician	Obstetrician	Maternal care
reproductive-endocrinologist	Reproductive Endocrinologist	Fertility and reproduction
orthopedic-surgeon	Orthopedic Surgeon	Musculoskeletal
rheumatologist	Rheumatologist	Autoimmune and joint care
neurologist	Neurologist	Nervous system
neurosurgeon	Neurosurgeon	Nervous system
psychiatrist	Psychiatrist	Mental health
clinical-psychologist	Clinical Psychologist	Mental health
ophthalmologist	Ophthalmologist	Eye care
optometrist	Optometrist	Eye care
ent-specialist	ENT Specialist	Ear, nose and throat
audiologist	Audiologist	Hearing care
urologist	Urologist	Urology
nephrologist	Nephrologist	Kidney care
gastroenterologist	Gastroenterologist	Digestive system
hepatologist	Hepatologist	Liver care
pulmonologist	Pulmonologist	Respiratory system
sleep-medicine-specialist	Sleep Medicine Specialist	Sleep disorders
endocrinologist	Endocrinologist	Hormonal disorders
diabetologist	Diabetologist	Diabetes care
oncologist	Oncologist	Cancer care
hematologist	Hematologist	Blood disorders
infectious-disease-specialist	Infectious Disease Specialist	Infectious diseases
immunologist	Immunologist	Immune system
radiologist	Radiologist	Diagnostic imaging
anesthesiologist	Anesthesiologist	Surgical care
general-surgeon	General Surgeon	Surgical care
vascular-surgeon	Vascular Surgeon	Surgical care
emergency-physician	Emergency Physician	Acute and emergency care
critical-care-physician	Critical Care Physician	Intensive care
pain-management-specialist	Pain Management Specialist	Pain and palliative care
palliative-care-physician	Palliative Care Physician	Pain and end-of-life care

Need Help?

Contact the platform integrations team with:

Your partnerId
Environment (test/production)
Logs of failed signatures or missing events

You’re now ready to receive and fulfill consultation bookings.

Consultation Provider Guide

Your Role as a Consultation Provider

Prerequisites (Platform-Side Setup)

Environments

Base URLs

Security: HMAC SHA256 Signatures

From Platform → You (Inbound)

From You → Platform (Outbound)

Signature Generation (Node.js Example)

Events You Will Receive

1. consultation.availability.query

2. consultation.request

3. consultation.confirmed

Events You Must Send (via Callback)

1. consultation.doctor_assigned

2. consultation.scheduled (Provider → Platform) or (Platform → Provider)

Testing Checklist

Key Notes

Need Help?

1. `consultation.availability.query`

2. `consultation.request`

3. `consultation.confirmed`

1. `consultation.doctor_assigned`

2. `consultation.scheduled` (Provider → Platform) or (Platform → Provider)