API Reference
Messages
Send SMS messages and check delivery status via the API
Messages
Send SMS messages to patients and track their delivery status.
Send a message
POST /messages/send
You can send a message in two ways:
- Inline content - provide the message text directly
- Practice template - reference a saved template by ID
The patient is identified by providerId. If the patient doesn't exist yet, include firstName, lastName, and mobileNumber and they'll be created automatically.
Request body (inline content)
{
"providerId": "EHR-123",
"firstName": "Ana",
"lastName": "Horvat",
"mobileNumber": "+385991234567",
"content": "Your appointment is tomorrow at 10:00."
}
Request body (practice template)
{
"providerId": "EHR-123",
"practiceTemplateId": "template-uuid-here"
}
Fields
| Field | Type | Required | Description |
|---|---|---|---|
providerId | string | Yes | Your external patient ID |
content | string | Conditional | Message text (required if no practiceTemplateId) |
practiceTemplateId | string | Conditional | Template ID (required if no content) |
provider | string | No | System name (defaults to API key name) |
firstName | string | No | Required if patient doesn't exist yet |
lastName | string | No | Required if patient doesn't exist yet |
mobileNumber | string | No | E.164 format. Required if patient doesn't exist yet |
email | string | No | Patient email |
dateOfBirth | string | No | ISO 8601 date |
You must provide exactly one of
content or practiceTemplateId, not both.To send rich content (form links, document attachments, dynamic variables), use a practice template. Create templates in the Voxares dashboard, then send them via the API with
practiceTemplateId. See Content API to browse available templates.Response
{
"messageId": "msg-uuid-here",
"patientId": "patient-uuid-here",
"status": "Pending",
"smsCount": 1,
"content": "Your appointment is tomorrow at 10:00.",
"sentOn": null,
"createdAt": "2025-05-25T10:00:00.000Z",
"updatedAt": "2025-05-25T10:00:00.000Z"
}
| Field | Type | Description |
|---|---|---|
messageId | string | Unique message ID. Use it to check status later |
patientId | string | Voxares patient ID (created or existing) |
status | string | Initial status, always Pending |
smsCount | integer | Number of SMS segments |
content | string | Resolved message text |
sentOn | string | null | ISO 8601 timestamp when the message was sent, or null if not yet sent |
createdAt | string | ISO 8601 timestamp |
updatedAt | string | ISO 8601 timestamp of last status change |
Get a message
GET /messages/:id
Returns the full message object including current delivery status.
Example
curl "https://api.voxares.com/api/v1/integration/messages/msg-uuid-here" \
-H "Authorization: Bearer vox-YOUR-API-KEY"
List messages
GET /messages
Supports standard pagination parameters.
Response
{
"data": [
{
"id": "msg-uuid-here",
"content": "Your appointment is tomorrow at 10:00.",
"status": "Delivered",
"smsCount": 1,
"patientId": "patient-uuid-here",
"sentOn": "2025-05-25T10:01:00.000Z",
"createdAt": "2025-05-25T10:00:00.000Z",
"updatedAt": "2025-05-25T10:01:30.000Z"
}
],
"count": 1
}
Message statuses
| Status | Description |
|---|---|
Pending | Message is queued for sending |
Sent | Message has been sent to the SMS provider |
Delivered | Message was delivered to the recipient |
Failed | Message could not be delivered |