WhatsApp Messaging

Send approved WhatsApp templates and inspect conversations for numbers connected to your organisation. Phone numbers are represented as digits only, without spaces or a leading plus sign.Authenticate with either X-Scrubs-Clinic-Api-Key or X-Scrubs-Clinic-Code , together with X-Scrubs-Clinic-Provider .

POST /api/v1/whatsapp/onboarding-links

Creates a hosted WhatsApp onboarding link that your organisation can pass to a customer. The returned URL is a public Scrubs redirect link that sends the customer to the hosted setup page. This does not claim or persist a sender number; call POST /api/v1/whatsapp/numbers/claim after the customer completes onboarding.HEADER PARAMETERS

REQUIREDX-Scrubs-Clinic-Providerstring

Provider ID associated with your EHR application.

OPTIONALX-Scrubs-Clinic-Api-Keystring

API key for authentication. Provide either this header or X-Scrubs-Clinic-Code.

OPTIONALX-Scrubs-Clinic-Codestring

Legacy HCI code for authentication. Provide either this header or X-Scrubs-Clinic-Api-Key.

BODY PARAMETERS

OPTIONALcustomer_namestring

Optional. Friendly customer name for the hosted onboarding flow.

OPTIONALsuccess_redirect_urlstring

Optional. URL the customer is sent to after successful onboarding.

OPTIONALfailure_redirect_urlstring

Optional. URL the customer is sent to if onboarding fails.

OPTIONALallowed_connection_typesstring[]

Optional. Array containing "coexistence", "dedicated", or both. A single value auto-selects that mode.

OPTIONALlanguagestring

Optional. Setup flow language. Supported values: en, es, pt, hi, id, ar.

Error Codes4 cases

Authentication

400	Provider or HCI code is invalid.	Check X-Scrubs-Clinic-Provider and, when using HCI auth, X-Scrubs-Clinic-Code.
401	Authentication failed.	Provide a valid API key for the provider, or a valid HCI code for the provider.

Onboarding validation

400	Request body is invalid.	Check redirect URL format, language, and connection type values.
502	Onboarding link could not be created.	The WhatsApp provider could not create the customer or onboarding link.

Domain

BASE URL

1https://usescrubs.com

Sample Request

CURL

Node.JS

Python

CURL

1curl --location --request POST 'https://usescrubs.com/api/v1/whatsapp/onboarding-links' \
2--header 'X-Scrubs-Clinic-Api-Key: your_api_key_here' \
3--header 'X-Scrubs-Clinic-Provider: your_provider_id' \
4--header 'Content-Type: application/json' \
5--data '{
6  "customer_name": "Example Customer",
7  "success_redirect_url": "https://example.com/whatsapp/success",
8  "failure_redirect_url": "https://example.com/whatsapp/failed",
9  "allowed_connection_types": ["coexistence", "dedicated"],
10  "language": "en"
11}'

Sample Response

JSON

1{
2  "data": {
3    "onboarding_link_id": "setup_link_id",
4    "url": "https://usescrubs.com/api/v1/whatsapp/onboarding-links/encrypted_redirect_token",
5    "status": "active",
6    "expires_at": "2026-07-07T10:00:00.000Z",
7    "whatsapp_setup_status": "pending",
8    "whatsapp_setup_error": null
9  }
10}

POST /api/v1/whatsapp/numbers/claim

Claims an already-onboarded WhatsApp number for the authenticated organisation. The number must be supplied as digits only.HEADER PARAMETERS

REQUIREDX-Scrubs-Clinic-Providerstring

Provider ID associated with your EHR application.

OPTIONALX-Scrubs-Clinic-Api-Keystring

API key for authentication. Provide either this header or X-Scrubs-Clinic-Code.

OPTIONALX-Scrubs-Clinic-Codestring

Legacy HCI code for authentication. Provide either this header or X-Scrubs-Clinic-Api-Key.

BODY PARAMETERS

REQUIREDphone_numberstring

The onboarded WhatsApp sender number, digits only.

REQUIREDhci_codestring

The clinic this number is being claimed for. The number is linked to the clinic immediately, so its messaging configuration exists from the moment it is claimed. This link is permanent: claiming is a one-time operation and a number cannot later be moved to another clinic through the API.

Error Codes4 cases

Authentication

400	Provider or HCI code is invalid.	Check X-Scrubs-Clinic-Provider and, when using HCI auth, X-Scrubs-Clinic-Code.
401	Authentication failed.	Provide a valid API key for the provider, or a valid HCI code for the provider.

Claim validation

404	Phone number was not found.	Complete WhatsApp onboarding before claiming the number through this endpoint.
409	Phone number cannot be claimed.	The number is not connected yet, has already been claimed (claiming is one-time — reassigning a number to a different clinic is a manual operation), or the clinic given in hci_code already has a WhatsApp number (each clinic supports one).

Domain

BASE URL

1https://usescrubs.com

Sample Request

CURL

Node.JS

Python

CURL

1curl --location --request POST 'https://usescrubs.com/api/v1/whatsapp/numbers/claim' \
2--header 'X-Scrubs-Clinic-Api-Key: your_api_key_here' \
3--header 'X-Scrubs-Clinic-Provider: your_provider_id' \
4--header 'Content-Type: application/json' \
5--data '{
6  "phone_number": "sender_phone_number",
7  "hci_code": "clinic_hci_code"
8}'

Sample Response

JSON

1{
2  "data": {
3    "phone_number": "sender_phone_number",
4    "display_name": "Example Clinic",
5    "status": "CONNECTED",
6    "quality_rating": "GREEN",
7    "claimed_at": "2026-06-06T07:20:00.000Z",
8    "last_synced_at": "2026-06-06T07:20:00.000Z"
9  }
10}

GET /api/v1/whatsapp/numbers

Lists WhatsApp sender numbers currently claimed by the authenticated organisation.HEADER PARAMETERS

REQUIREDX-Scrubs-Clinic-Providerstring

Provider ID associated with your EHR application.

OPTIONALX-Scrubs-Clinic-Api-Keystring

API key for authentication. Provide either this header or X-Scrubs-Clinic-Code.

OPTIONALX-Scrubs-Clinic-Codestring

Legacy HCI code for authentication. Provide either this header or X-Scrubs-Clinic-Api-Key.

Error Codes2 cases

Authentication

400	Provider or HCI code is invalid.	Check X-Scrubs-Clinic-Provider and, when using HCI auth, X-Scrubs-Clinic-Code.
401	Authentication failed.	Provide a valid API key for the provider, or a valid HCI code for the provider.

Domain

BASE URL

1https://usescrubs.com

Sample Request

CURL

Node.JS

Python

CURL

1curl --location --request GET 'https://usescrubs.com/api/v1/whatsapp/numbers' \
2--header 'X-Scrubs-Clinic-Api-Key: your_api_key_here' \
3--header 'X-Scrubs-Clinic-Provider: your_provider_id'

Sample Response

JSON

1{
2  "data": [
3    {
4      "phone_number": "sender_phone_number",
5      "display_name": "Example Clinic",
6      "status": "CONNECTED",
7      "quality_rating": "GREEN",
8      "claimed_at": "2026-06-06T07:20:00.000Z",
9      "last_synced_at": "2026-06-06T07:20:00.000Z"
10    }
11  ]
12}

GET /api/v1/whatsapp/numbers/{phone_number}/templates

Lists available templates for a claimed sender number. Rejected templates are hidden unless includeRejected=true is supplied.HEADER PARAMETERS

REQUIREDX-Scrubs-Clinic-Providerstring

Provider ID associated with your EHR application.

OPTIONALX-Scrubs-Clinic-Api-Keystring

API key for authentication. Provide either this header or X-Scrubs-Clinic-Code.

OPTIONALX-Scrubs-Clinic-Codestring

Legacy HCI code for authentication. Provide either this header or X-Scrubs-Clinic-Api-Key.

QUERY PARAMETERS

OPTIONALincludeRejectedstring

Optional. Set to "true" to include rejected templates in the response.

Error Codes3 cases

Authentication

400	Provider or HCI code is invalid.	Check X-Scrubs-Clinic-Provider and, when using HCI auth, X-Scrubs-Clinic-Code.
401	Authentication failed.	Provide a valid API key for the provider, or a valid HCI code for the provider.

Template lookup

404

Sender number was not found.

Claim the sender number before listing templates for it.

Domain

BASE URL

1https://usescrubs.com

Sample Request

CURL

Node.JS

Python

CURL

1curl --location --request GET 'https://usescrubs.com/api/v1/whatsapp/numbers/{sender_phone_number}/templates' \
2--header 'X-Scrubs-Clinic-Api-Key: your_api_key_here' \
3--header 'X-Scrubs-Clinic-Provider: your_provider_id'

Sample Response

JSON

1{
2  "data": [
3    {
4      "template_name": "appointment_reminder_en",
5      "language": "en_US",
6      "status": "APPROVED",
7      "category": "UTILITY",
8      "dynamic_fields": [
9        {
10          "component": "body",
11          "field": "1",
12          "format": "positional",
13          "parameter_type": "text",
14          "example": "Example Patient"
15        }
16      ]
17    }
18  ]
19}

POST /api/v1/whatsapp/numbers/{phone_number}/messages/template

Sends an approved WhatsApp template from a claimed sender number to one recipient.HEADER PARAMETERS

REQUIREDX-Scrubs-Clinic-Providerstring

Provider ID associated with your EHR application.

OPTIONALX-Scrubs-Clinic-Api-Keystring

API key for authentication. Provide either this header or X-Scrubs-Clinic-Code.

OPTIONALX-Scrubs-Clinic-Codestring

Legacy HCI code for authentication. Provide either this header or X-Scrubs-Clinic-Api-Key.

BODY PARAMETERS

REQUIREDrecipient_phone_numberstring

Recipient WhatsApp number, digits only.

REQUIREDtemplate_namestring

Template name returned by the templates endpoint.

REQUIREDlanguagestring

Template language code returned by the templates endpoint.

OPTIONALcomponentsarray

Array of template components (HEADER, BODY, BUTTON), each with its parameters in positional order. A HEADER {{1}} and a BODY {{1}} are separate values.

Error Codes4 cases

Authentication

400	Provider or HCI code is invalid.	Check X-Scrubs-Clinic-Provider and, when using HCI auth, X-Scrubs-Clinic-Code.
401	Authentication failed.	Provide a valid API key for the provider, or a valid HCI code for the provider.

Send validation

400	Template components are invalid or template is not approved.	Send one component per component returned by the templates endpoint, each with exactly as many parameters as it declares. Rejected templates cannot be sent.
404	Sender number or template was not found.	Claim the sender number and use a template name/language returned for that sender number.

Domain

BASE URL

1https://usescrubs.com

Sample Request

CURL

Node.JS

Python

CURL

1curl --location --request POST 'https://usescrubs.com/api/v1/whatsapp/numbers/{sender_phone_number}/messages/template' \
2--header 'X-Scrubs-Clinic-Api-Key: your_api_key_here' \
3--header 'X-Scrubs-Clinic-Provider: your_provider_id' \
4--header 'Content-Type: application/json' \
5--data '{
6  "recipient_phone_number": "recipient_phone_number",
7  "template_name": "appointment_reminder_en",
8  "language": "en_US",
9  "components": [
10    {
11      "type": "BODY",
12      "parameters": [
13        { "type": "text", "text": "Example Patient" },
14        { "type": "text", "text": "Wednesday, 10-Jun-2026" },
15        { "type": "text", "text": "09:30 AM" },
16        { "type": "text", "text": "Example Clinic" },
17        { "type": "text", "text": "clinic_contact_number" },
18        { "type": "text", "text": "Dr Example" },
19        { "type": "text", "text": "General consultation" },
20        { "type": "text", "text": "Please arrive 10 minutes early." }
21      ]
22    }
23  ]
24}'

Sample Response

JSON

1{
2  "messaging_product": "whatsapp",
3  "recipient_phone_number": "recipient_phone_number",
4  "contacts": [
5    {
6      "input": "recipient_phone_number",
7      "wa_id": "recipient_phone_number"
8    }
9  ],
10  "messages": [
11    {
12      "id": "wamid.HBg..."
13    }
14  ]
15}

GET /api/v1/whatsapp/numbers/{phone_number}/conversations

Lists conversations for a claimed sender number. If recipient_phone_number is omitted, all conversations for the sender number are returned.HEADER PARAMETERS

REQUIREDX-Scrubs-Clinic-Providerstring

Provider ID associated with your EHR application.

OPTIONALX-Scrubs-Clinic-Api-Keystring

API key for authentication. Provide either this header or X-Scrubs-Clinic-Code.

OPTIONALX-Scrubs-Clinic-Codestring

Legacy HCI code for authentication. Provide either this header or X-Scrubs-Clinic-Api-Key.

QUERY PARAMETERS

OPTIONALrecipient_phone_numberstring

Optional. Filters conversations to one recipient phone number, digits only.

OPTIONALstatusstring

Optional. Filter by conversation status.

OPTIONALlimitnumber

Optional. Page size from 1 to 100. Defaults to 20.

OPTIONALafterstring

Optional. Cursor for the next page. Use the value returned in paging.next.

OPTIONALbeforestring

Optional. Cursor for the previous page. Use the value returned in paging.previous.

Error Codes2 cases

Authentication

400	Provider or HCI code is invalid.	Check X-Scrubs-Clinic-Provider and, when using HCI auth, X-Scrubs-Clinic-Code.
401	Authentication failed.	Provide a valid API key for the provider, or a valid HCI code for the provider.

Domain

BASE URL

1https://usescrubs.com

Sample Request

CURL

Node.JS

Python

CURL

1curl --location --request GET 'https://usescrubs.com/api/v1/whatsapp/numbers/{sender_phone_number}/conversations?recipient_phone_number={recipient_phone_number}&limit=20' \
2--header 'X-Scrubs-Clinic-Api-Key: your_api_key_here' \
3--header 'X-Scrubs-Clinic-Provider: your_provider_id'

Sample Response

JSON

1{
2  "data": [
3    {
4      "conversation_id": "817ad873-0d2b-401c-8a75-e106583b79a5",
5      "recipient_phone_number": "recipient_phone_number",
6      "status": "ended",
7      "last_active_at": "2026-05-25T03:57:40-04:00",
8      "created_at": "2026-05-25T03:55:00-04:00",
9      "updated_at": "2026-05-25T03:57:40-04:00",
10      "contact_name": "Example Patient",
11      "messages_count": 7,
12      "last_message_type": "text",
13      "last_message_timestamp": "2026-05-25T03:57:40-04:00",
14      "last_inbound_at": "2026-05-25T03:57:36-04:00",
15      "last_outbound_at": "2026-05-25T03:57:40-04:00"
16    }
17  ],
18  "paging": {
19    "next": "next_cursor",
20    "previous": null
21  }
22}

GET /api/v1/whatsapp/numbers/{phone_number}/conversations/{conversation_id}/messages

Lists messages for a conversation returned by the conversations endpoint. Results are scoped to the authenticated organisation and claimed sender number.HEADER PARAMETERS

REQUIREDX-Scrubs-Clinic-Providerstring

Provider ID associated with your EHR application.

OPTIONALX-Scrubs-Clinic-Api-Keystring

API key for authentication. Provide either this header or X-Scrubs-Clinic-Code.

OPTIONALX-Scrubs-Clinic-Codestring

Legacy HCI code for authentication. Provide either this header or X-Scrubs-Clinic-Api-Key.

QUERY PARAMETERS

OPTIONALdirectionstring

Optional. Filter by message direction. Supported values: inbound, outbound.

OPTIONALstatusstring

Optional. Filter by message status, such as sent, delivered, read, or failed.

OPTIONALmessage_typestring

Optional. Filter by WhatsApp message type, such as text, image, or template.

OPTIONALhas_mediastring

Optional. Set to "true" or "false" to filter messages by media presence.

OPTIONALlimitnumber

Optional. Page size from 1 to 100. Defaults to 20.

OPTIONALafterstring

Optional. Cursor for the next page. Use the value returned in paging.next.

OPTIONALbeforestring

Optional. Cursor for the previous page. Use the value returned in paging.previous.

Error Codes4 cases

Authentication

400	Provider or HCI code is invalid.	Check X-Scrubs-Clinic-Provider and, when using HCI auth, X-Scrubs-Clinic-Code.
401	Authentication failed.	Provide a valid API key for the provider, or a valid HCI code for the provider.

Message lookup

400	Query parameters are invalid.	Use true or false for has_media and a valid conversation_id path value.
404	Sender number was not found.	Claim the sender number before listing messages for its conversations.

Domain

BASE URL

1https://usescrubs.com

Sample Request

CURL

Node.JS

Python

CURL

1curl --location --request GET 'https://usescrubs.com/api/v1/whatsapp/numbers/{sender_phone_number}/conversations/{conversation_id}/messages?limit=20' \
2--header 'X-Scrubs-Clinic-Api-Key: your_api_key_here' \
3--header 'X-Scrubs-Clinic-Provider: your_provider_id'

Sample Response

JSON

1{
2  "data": [
3    {
4      "message_id": "wamid.HBg...",
5      "timestamp": "1705395000",
6      "type": "text",
7      "direction": "inbound",
8      "status": "delivered",
9      "processing_status": "processed",
10      "origin": "cloud_api",
11      "from_phone_number": "recipient_phone_number",
12      "to_phone_number": "sender_phone_number",
13      "contact_name": "Example Patient",
14      "content": "Hello, I need help with my appointment.",
15      "has_media": false
16    }
17  ],
18  "paging": {
19    "next": "next_cursor",
20    "previous": null
21  }
22}