Emergency Provider Guide

For Businesses Integrating as Emergency/Ambulance Partners on AwaDoc

This guide reflects the exact live platform behaviour as of December 2025.

Your Role as an Emergency Provider

You receive life-critical emergency requests (ambulance, rapid response team, etc.), must respond instantly with dispatch confirmation and live ETA, and keep the platform and patient updated until the case is resolved.

This is the highest-priority integration on AwaDoc — response times are strictly monitored.

Prerequisites (same for all partners)

Business Record status: ACTIVE
One or more APPROVED offerings in category emergency
testCallbackUrl & productionCallbackUrl configured by AwaDoc team
Test and/or Production API keys issued
Bank account verified (required for production)

Base URLs

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

Security

HMAC SHA256 signatures on every inbound and outbound payload. Clock skew tolerance: ±5 minutes.

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");
}

Complete Emergency Flow & Events

Step	Event Type	When It Is Sent	Mandatory Response Time	Required Response Fields
1	emergency.requested	User or family presses “Emergency” button	≤ 60 seconds (monitored)	Must reply dispatched or unavailable
–	(No availability query — emergencies are push-only)

1. emergency.requested (only event you receive)

Example payload (platform → you)

JSON

{
  "event_id": "evt-5001",
  "event_type": "emergency.requested",
  "timestamp": "2025-12-09T14:22:17Z",
  "user": {
    "id": "usr-8921",
    "name": "Aisha Ibrahim",
    "phone": "+2348123456789"
  },
  "context": {
    "request_id": "emg-3301",
    "type": "ambulance",                     // ambulance | medical_team | fire_support
    "emergency_type": "cardiac_arrest",
    "location": {
      "address": "Plot 5, Banana Island, Ikoyi, Lagos",
      "coordinates": { "lat": 6.4592, "lng": 3.4268 }
    },
    "notes": "65-year-old male, unconscious, not breathing",
    "caller_name": "Fatima Ibrahim",
    "caller_phone": "+2348031112222"
  },
  "meta": {
    "trace_id": "trace-789012"
  }
}

Your Immediate Response (≤ 60 seconds — critical)

Success — unit dispatched

JSON

{
  "status": "dispatched",
  "request_id": "emg-3301",
  "unit_id": "AMB-07-LAG",
  "unit_type": "ALS",                          // ALS | BLS | rapid_response
  "eta": "2025-12-09T14:35:00Z",                // accurate real ETA
  "dispatched_at": "2025-12-09T14:23:05Z",
  "provider_name": "Lagos State Ambulance Service (LASAMBUS)",
  "team_contact": "+2349012345678",
  "tracking_url": "https://track.lasambus.ng/unit/AMB-07-LAG"
}

Failure — cannot serve

JSON

{
  "status": "unavailable",
  "request_id": "emg-3301",
  "reason": "all_units_busy",                  // or "out_of_service_area"
  "retry_after": "2025-12-09T14:40:00Z"        // optional but helpful
}

Events You Must Send Back (Callbacks)

POST https://partners-{env}.awadoc.com/api/partners/:partnerId/callback You must send these in real time — patients and family see them live.

Event Type	When to Send	Critical Fields
emergency.en_route	Unit has left base	request_id, unit_id, updated_eta
emergency.arrived	Unit is on scene	request_id, arrived_at
emergency.patient_loaded	Patient is in ambulance	request_id, hospital_destination
emergency.at_facility	Arrived at receiving hospital	request_id, facility_name, handed_over_at
emergency.resolved	Case closed (patient handed over or cancelled)	request_id, outcome ("transported"
emergency.cancelled	False alarm or duplicate	request_id, reason

Example arrived callback

JSON

{
  "event_id": "evt-5005",
  "event_type": "emergency.arrived",
  "timestamp": "2025-12-09T14:34:22Z",
  "context": {
    "request_id": "emg-3301",
    "unit_id": "AMB-07-LAG",
    "arrived_at": "2025-12-09T14:34:20Z",
    "notes": "CPR in progress, preparing for transport"
  }
}

Key Notes & Requirements

60-second response SLA is enforced — repeated failures will suspend your emergency listing
Always include accurate coordinates when possible
Use exact status values above (platform validates them)
tracking_url is highly recommended (shown to family in app)
Never reject silently — always reply "unavailable" with reason
All timestamps must be ISO8601 UTC
No callback URL set → you will never receive emergency requests

You are now fully equipped to save lives through the AwaDoc Emergency network. Respond fast. Every second counts. 🚑❤️