Skip to main content

Create a new message

POST 
/v2/messages

Create a new message to be delivered to a patient. Messages can be associated with forms, packets, or documents. At least one of the following parameters must be provided: form, packet, or document. You can also schedule a message for future delivery.

Example request body:

{
    "patient": 123,
    "form": "abc123",
    "message_type": "form_response_request",
    "preferred_delivery_method": "email",
    "target_email": "patient@example.com",
    "scheduled_at": "2025-05-10T15:00:00Z"
}

Reminders​

message_type: "reminder" does not create a new message. It re-sends the original link for a response the patient has not completed yet, and the send is recorded in that message's reminders history.

Provide exactly one of response or packet_response, identifying the outstanding response. form, packet, and document are not used for reminders. The response body is the original message, so message_code is unchanged.

{
    "message_type": "reminder",
    "response": "0c7f2f1e-6b2a-4a1f-9f0a-2f4f1c9a7b31",
    "preferred_delivery_method": "email",
    "target_email": "patient@example.com"
}

If preferred_delivery_method is omitted, the channel follows the contact override you send: target_phone on its own means SMS, target_email on its own means email. When neither is sent the message keeps the channel it already used.

Returns 400 when neither or both parent references are given, when the response has no message, when that message has not been sent yet, or when the resolved channel has no destination to send to (for example sms with no phone number on the patient or the message).

Request​

Responses​