Communication API

Base URL: https://api.welkinhealth.com/{tenantName}/{instanceName}/communications

The Communication API provides programmatic access to send messages to patients across supported channels (SMS, email, chat) without going through individual channel endpoints.

---

Send Communication

POST /communications

Sends a message to a patient via a specified channel using a template.

Request Body

Field	Type	Required	Description
patientId	string	Yes	ID of the patient
channel	string	Yes	SMS, EMAIL, or CHAT
templateName	string	Yes	Programmatic name of the message template
templateVariables	object	No	Key-value pairs for template variable substitution
senderId	string	Yes	User ID of the sender

Example Request

curl -X POST "https://api.welkinhealth.com/acme/live/communications" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "patientId": "pt_7f3a9b2c-1d4e-4f8a-b5c6-d7e8f9a0b1c2",
    "channel": "SMS",
    "templateName": "appointment_reminder",
    "templateVariables": {
      "appointmentDate": "March 25, 2026",
      "appointmentTime": "2:00 PM PST",
      "providerName": "Dr. Smith"
    },
    "senderId": "usr_1a2b3c4d-5e6f-7890-abcd-ef1234567890"
  }'

Example Response

{
  "communicationId": "comm_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "QUEUED",
  "channel": "SMS",
  "patientId": "pt_7f3a9b2c-1d4e-4f8a-b5c6-d7e8f9a0b1c2",
  "scheduledAt": "2026-03-19T10:05:00Z"
}

---

Get Communication Status

GET /communications/{communicationId}

Returns the current delivery status of a communication.

Path Parameters

Parameter	Type	Required	Description
communicationId	string	Yes	ID of the communication

Example Request

curl -X GET "https://api.welkinhealth.com/acme/live/communications/comm_a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer {access_token}"

Example Response

{
  "communicationId": "comm_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "DELIVERED",
  "channel": "SMS",
  "patientId": "pt_7f3a9b2c-1d4e-4f8a-b5c6-d7e8f9a0b1c2",
  "deliveredAt": "2026-03-19T10:05:12Z",
  "errorMessage": null
}

Status values: QUEUED, SENDING, DELIVERED, FAILED, BOUNCED

---

Get Communications for Patient

GET /communications

Returns a paginated list of communications for a patient.

Query Parameters

Parameter	Type	Required	Description
patientId	string	Yes	ID of the patient
channel	string	No	Filter by channel: SMS, EMAIL, CHAT
status	string	No	Filter by delivery status
startDate	string (ISO 8601)	No	Filter from date
endDate	string (ISO 8601)	No	Filter to date
page	integer	No	Page number (default: 0)
size	integer	No	Page size (default: 20)

Example Request

curl -X GET "https://api.welkinhealth.com/acme/live/communications?patientId=pt_7f3a9b2c-1d4e-4f8a-b5c6-d7e8f9a0b1c2&channel=SMS" \
  -H "Authorization: Bearer {access_token}"

Example Response

{
  "content": [
    {
      "communicationId": "comm_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "patientId": "pt_7f3a9b2c-1d4e-4f8a-b5c6-d7e8f9a0b1c2",
      "channel": "SMS",
      "templateName": "appointment_reminder",
      "status": "DELIVERED",
      "senderId": "usr_1a2b3c4d-5e6f-7890-abcd-ef1234567890",
      "scheduledAt": "2026-03-19T10:05:00Z",
      "deliveredAt": "2026-03-19T10:05:12Z",
      "errorMessage": null
    }
  ],
  "totalElements": 1,
  "totalPages": 1,
  "page": 0,
  "size": 20
}