Create an external communication

API reference

Create an external communication

Request

Capture an external communication which has occurred with a patient, outside of the Dentally eco-system.
This is used to capture messages sent via channels that Dentally does not support.
Please note, the Dentally portal has not yet been updated to display this information.
Logging an SMS requires the communication:external:sms:write scope instead of communication:external:write.
Please note, access to the communication:external:sms:write scope is provisioned by a Dentally admin.

Security

oauth2(Required scopes: communication:external:write) or oauth2(Required scopes: communication:external:sms:write)

X-Practice-Idstring, (uuid)required

UUID of the practice in whose context the request is executed. The API uses this to resolve data the caller is permitted to access for that practice.

Bodyapplication/jsonrequired

Details of the communication that was sent to a patient.

patient_idstring, (uuid)required

ID of the patient who is the intended recipient of the communication.

communication_channelstringrequired

Value:"sms"

Discriminator

directionstringrequired

The direction of the communication.
Inbound indicates that the communication was received from the patient, while outbound indicates that the communication was sent to the patient.

Enum:"inbound""outbound"

message_typestring(communication-message-type)required

The different types of communications that can be sent to patients.

Enum Value	Description
appointment_reminder	Communication sent to remind a patient of an upcoming appointment.
appointment_confirmation	Communication sent to confirm a patient's appointment booking.
appointment_cancellation	Communication sent to notify a patient of an appointment cancellation.
task_reminder	Communication sent to remind a patient of a task they need to complete (e.g., fill out a form).
feedback_request	Communication sent to request feedback from a patient after an appointment or interaction.
marketing	Communication sent for marketing purposes, such as promotions or newsletters.
estimate	Communication sent to provide a patient with an estimate for a treatment or procedure.
invoice	Communication sent to provide a patient with an invoice for services rendered.
fta	Communication sent to notify a patient of a missed appointment (FTA = "Failure To Attend").
recall	Communication sent to recall a patient for follow-up care or routine check-ups.
patient_reply	Communication that is a reply from a patient, which may be received via certain channels and logged in the system.
payment_request	Communication sent to request payment from a patient for a deposit or outstanding balance.
medical_history	Communication sent to request or provide information about a patient's medical history.
unclassified	Communication that does not fit into any of the other predefined categories.

site_idstring, (uuid)

The ID of the site associated with the communication.

Example:"123e4567-e89b-12d3-a456-426614174089"

bodystring, <= 1600 charactersrequired

The main plain text content of the SMS message.

Example:"Your appointment is scheduled for tomorrow at 3 PM."

curl -i -X POST \
  https://docs.api.dentally.com/_mock/docs/versions/2026-01-01/nexgen/external_communications \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Practice-Id: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -d '{
    "direction": "outbound",
    "patient_id": "123e4567-e89b-12d3-a456-426614174000",
    "communication_channel": "sms",
    "body": "Your appointment is scheduled for tomorrow at 3 PM.",
    "message_type": "appointment_reminder",
    "site_id": "123e4567-e89b-12d3-a456-426614174001"
  }'

Responses

Response after creating an external communication.

Bodyapplication/json

dataobject(resource_timestamps)required

Object containing the ID of the external communication that was created.

Response

{
  "data": {
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-06-20T14:05:22Z",
    "id": "123e4567-e89b-12d3-a456-426614174005"
  }
}