Send a message to a patient

POST/patient-messages

Sends a message to a patient by patient_id or phone number, from one of the organization’s numbers: from, else the key’s default number, else the organization’s only number. An organization with several numbers and no default answers 422 from_required. The message goes in that number’s team’s conversation with the patient, and comes from the API identity the key belongs to (an automated sender on the account, never a staff member); until identities are on for the account, it shows the key’s name with an API marker. BloomText finds the patient (or creates one for a new phone number), finds or starts the conversation, and sends. Messages go by secure link unless channel is sms.

Credentials: API key, or an OAuth access token
Scope: messages.write
Idempotent: With Idempotency-Key

Run in Postman: import the collection, set api_key, and find this request in its folder.

Query parameters

org_idUUID

The organization the call acts on, from List organizations. Required when an account API key reaches more than one organization; an organization key or a key limited to one organization can leave it out.

Headers

Idempotency-KeyUUIDRequired

A UUID you generate for each write. Retrying with the same key returns the original result for 24 hours. Reusing a key with a different method, path, or body returns 409.

Body parameters

A message to a patient.

toRecipientRequired

Who to message. Provide exactly one of patient_id or phone.

Show child attributes

patient_idUUID

The patient to message.

phonestring

A mobile number. BloomText finds the patient with this number, or creates one.

patientPatientDetails

Details for a patient BloomText creates while sending. Ignored when the phone number matches an existing patient.

Show child attributes

first_namestring

First name.

last_namestring

Last name.

date_of_birthdate

Date of birth.

emailstring

Email address.

mrnstring

The patient’s ID in your system.

bodystringRequired

Message text: up to 1,600 characters for sms, or 40,000 for secure. A longer one returns 422 too_long.

channelsecure, smsRequired

Required; there’s no default. sms sends the text itself as a regular SMS from the clinic’s number. secure sends a text or email with a secure link, and the message stays in BloomText.

fromstring

The clinic phone number to send from, in E.164 format, like +15125550100. Defaults to the API key’s default number, else the organization’s only number; an organization with several numbers and no default answers 422 from_required. See List phone numbers.

Any other field returns 422 unknown_field. See Unknown fields are rejected.

Returns

Returns 201 Created with the sent Message object in message, plus patient_created and conversation_created to say whether BloomText created either one. Returns 202 Accepted with the same body when the message waits for the patient’s consent to texting, with delivery.status consent_requested.

Errors

Failed requests return application/problem+json problem details. The errors specific to this endpoint:

Status	Code	Meaning
400	`invalid_request`	The request is malformed, such as invalid JSON.
400	`org_id_required`	The key reaches more than one organization: pass `org_id`.
401	`invalid_token`	The API key is missing or malformed, or isn’t a BloomText key.
401	`key_revoked`	The API key was revoked.
401	`key_expired`	The API key’s expiry has passed.
403	`insufficient_scope`	The key doesn’t have the scope this endpoint needs.
403	`org_not_reachable`	The key can’t reach the organization in `org_id`.
403	`plan_required`	The organization’s plan doesn’t include patient messaging.
404	`not_found`	The `patient_id` doesn’t exist in the organization, or `from` isn’t one of its phone numbers.
409	`idempotency_key_reused`	The Idempotency-Key was already used with a different request.
409	`idempotency_request_in_progress`	A request with this Idempotency-Key is still running. Retry shortly.
409	`ambiguous_recipient`	The phone number belongs to more than one patient. `candidates` lists them; send again with a `patient_id`, or add `patient.mrn`.
409	`recipient_mismatch`	`patient.mrn` belongs to a patient with a different phone number, or the number’s only patient has a different MRN. Nothing is sent. `candidates` lists that patient; update their phone, or send with their `patient_id`.
422	`validation_failed`	A field failed validation. See `field_errors`.
422	`from_required`	The organization has several phone numbers and no default. `detail` and `numbers` list them; set `from` to one.
422	`channel_required`	`channel` is missing. Set it to `sms` or `secure`; there’s no default.
422	`too_long`	The body is over `max` characters (1,600 for `sms`, 40,000 for `secure`). `length` and `max` say by how much.
422	`patient_has_no_phone`	An `sms` send to a patient with no phone number.
422	`no_contact_method`	A `secure` send to a patient with neither phone nor email.
422	`patient_opted_out`	The patient opted out: they replied STOP to one of the organization’s numbers, or staff recorded their opt-out. No number can text them until they reply START. `number` and `since` say which number the text would have come from and since when.
422	`carrier_blocked`	The carrier refused an earlier text to the patient because they replied STOP to that number, so the organization’s numbers don’t text them until they text START to one of them. `number` and `since` as above.
422	`number_blocked`	An admin in your organization blocked the patient’s number. Only an admin can unblock it, in the app. `number` and `since` as above.
422	`number_unreachable`	An earlier text failed because the patient’s number can’t receive texts: it’s a landline, or its carrier couldn’t be reached. It clears when the patient texts one of the organization’s numbers, when their phone number is changed, or when an admin clears it in the app. `number` and `since` as above.
429	`rate_limited`	Too many requests. Retry after `Retry-After` seconds.

cURL

Request


curl -X POST "https://api.bloomtext.com/v1/patient-messages" \
  -H "Authorization: Bearer $BLOOMTEXT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"to":{"patient_id":"5a1c9e2b-7d44-4f1a-9c3e-2b8d6f0a1e77"},"body":"Hi Jane, Dr. Example moved your appointment to Friday at 9:00. Reply here with any questions.","channel":"secure"}'

JavaScript

Request


const response = await fetch('https://api.bloomtext.com/v1/patient-messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BLOOMTEXT_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"to":{"patient_id":"5a1c9e2b-7d44-4f1a-9c3e-2b8d6f0a1e77"},"body":"Hi Jane, Dr. Example moved your appointment to Friday at 9:00. Reply here with any questions.","channel":"secure"}),
})
 
if (!response.ok) throw new Error(`BloomText API error: ${response.status}`)
const data = await response.json()

Python

Request


import os
import uuid
 
import requests
 
response = requests.post(
    "https://api.bloomtext.com/v1/patient-messages",
    headers={
        "Authorization": f"Bearer {os.environ['BLOOMTEXT_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"to":{"patient_id":"5a1c9e2b-7d44-4f1a-9c3e-2b8d6f0a1e77"},"body":"Hi Jane, Dr. Example moved your appointment to Friday at 9:00. Reply here with any questions.","channel":"secure"},
)
response.raise_for_status()
data = response.json()

Go

Request


package main
 
import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
 
	"github.com/google/uuid"
)
 
func main() {
	body := bytes.NewBufferString(`{"to":{"patient_id":"5a1c9e2b-7d44-4f1a-9c3e-2b8d6f0a1e77"},"body":"Hi Jane, Dr. Example moved your appointment to Friday at 9:00. Reply here with any questions.","channel":"secure"}`)
	req, err := http.NewRequest("POST", "https://api.bloomtext.com/v1/patient-messages", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("BLOOMTEXT_API_KEY"))
	req.Header.Set("Idempotency-Key", uuid.NewString())
	req.Header.Set("Content-Type", "application/json")
 
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
 
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(out))
}

Ruby

Request


require "net/http"
require "json"
require "securerandom"
 
uri = URI("https://api.bloomtext.com/v1/patient-messages")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("BLOOMTEXT_API_KEY")}"
request["Idempotency-Key"] = SecureRandom.uuid
request["Content-Type"] = "application/json"
request.body = { to: {"patient_id":"5a1c9e2b-7d44-4f1a-9c3e-2b8d6f0a1e77"}, body: "Hi Jane, Dr. Example moved your appointment to Friday at 9:00. Reply here with any questions.", channel: "secure" }.to_json
 
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end
data = JSON.parse(response.body)

Response · 201 Created


{
  "message": {
    "id": "4cbfdb50-6b7d-45d4-94b3-05a52ce3f4d1",
    "conversation": {
      "id": "e5c3b7b8-8f08-4d5a-9af1-0d11b0f4b7a0",
      "title": "Jane Doe"
    },
    "sender": {
      "id": "b7e1c3a9-4d2f-4a8b-9c6e-0f1d2e3a4b5c",
      "name": "Reminder service",
      "kind": "api_key"
    },
    "patient": {
      "id": "5a1c9e2b-7d44-4f1a-9c3e-2b8d6f0a1e77",
      "name": "Jane Doe"
    },
    "channel": "secure",
    "phone_number": null,
    "delivery": {
      "status": "queued",
      "error": null,
      "updated_at": "2026-09-21T15:04:05Z"
    },
    "campaign_id": null,
    "created_at": "2026-09-21T15:04:05Z",
    "edited_at": null,
    "type": "text",
    "body": "Hi Jane, Dr. Example moved your appointment to Friday at 9:00. Reply here with any questions.",
    "file": null,
    "reply_to_message_id": null,
    "unread": false,
    "sent_via": null
  },
  "patient_created": false,
  "conversation_created": false
}