Patient API quickstart

Text your own phone as a test patient, check that the message was delivered, read your reply through the API, and clean up.

Get an API key

BloomText turns on API access for organizations with a signed BAA. Request API access if you don’t have it yet. An account Owner or IT person then creates a key in BloomText under Settings → Account → API keys. For this guide, give it the scopes patients.read, patients.write, messages.read, and messages.write. If your account has several organizations, limit the key to one, so the calls below need no org_id; see Organizations a key reaches. If your organization has more than one phone number, add "from" with one of them to the send below; see Which number it comes from.

Store the key in an environment variable. Never commit it or ship it to a browser.

Terminal


export BLOOMTEXT_API_KEY="bt_key_4f7c2a9e1b..."

Check the key

Retrieve your organization to confirm the key works.

cURL

Request


curl https://api.bloomtext.com/v1/organization \
  -H "Authorization: Bearer $BLOOMTEXT_API_KEY"

JavaScript

check.mjs


const response = await fetch('https://api.bloomtext.com/v1/organization', {
  headers: { Authorization: `Bearer ${process.env.BLOOMTEXT_API_KEY}` },
})
console.log(response.status, await response.json())

Python

check.py


import os
 
import requests
 
response = requests.get(
    "https://api.bloomtext.com/v1/organization",
    headers={"Authorization": f"Bearer {os.environ['BLOOMTEXT_API_KEY']}"},
)
print(response.status_code, response.json())

Response · 200 OK


{ "id": "6db1e3f5-9b7f-4f2b-8be1-0f1e1d7d7d8c", "name": "Northside Clinic" }

Text your own phone

Send a message to your own mobile number. BloomText doesn’t know the number yet, so it creates a patient. Name the patient “API Test” so staff know what it is.

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": { "phone": "YOUR_MOBILE_NUMBER", "patient": { "first_name": "API", "last_name": "Test" } },
    "body": "Hello from the BloomText API. Reply to this message to test replies.",
    "channel": "secure"
  }'

JavaScript

send.mjs


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: { phone: 'YOUR_MOBILE_NUMBER', patient: { first_name: 'API', last_name: 'Test' } },
    body: 'Hello from the BloomText API. Reply to this message to test replies.',
    channel: 'secure',
  }),
})
console.log(await response.json())

Python

send.py


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": {"phone": "YOUR_MOBILE_NUMBER", "patient": {"first_name": "API", "last_name": "Test"}},
        "body": "Hello from the BloomText API. Reply to this message to test replies.",
        "channel": "secure",
    },
)
response.raise_for_status()
print(response.json())

The examples explicitly choose the secure channel, so your phone gets a text with a link to read it. Save message.id and message.patient.id from the response.

Response · 201 Created


{
  "message": {
    "id": "4cbfdb50-6b7d-45d4-94b3-05a52ce3f4d1",
    "conversation": { "id": "e5c3b7b8-8f08-4d5a-9af1-0d11b0f4b7a0", "title": "API Test" },
    "sender": { "id": "b7e1c3a9-4d2f-4a8b-9c6e-0f1d2e3a4b5c", "name": "Reminder service", "kind": "api_key" },
    "patient": { "id": "5a1c9e2b-7d44-4f1a-9c3e-2b8d6f0a1e77", "name": "API Test" },
    "channel": "secure",
    "delivery": { "status": "queued", "error": null, "updated_at": "2026-09-27T15:04:05Z" },
    "body": "Hello from the BloomText API. Reply to this message to test replies.",
    "...": "..."
  },
  "patient_created": true,
  "conversation_created": true
}

Check delivery

After a few seconds, retrieve the message to see its delivery status.

Request


curl https://api.bloomtext.com/v1/patient-messages/4cbfdb50-6b7d-45d4-94b3-05a52ce3f4d1 \
  -H "Authorization: Bearer $BLOOMTEXT_API_KEY"

delivery.status moves from queued to sent to delivered as the carrier reports, within minutes. See Delivery status.

Read your reply

Open the link on your phone and reply. Then list the messages the test patient (you) sent, newest first:

Request


curl -G https://api.bloomtext.com/v1/patient-messages \
  -H "Authorization: Bearer $BLOOMTEXT_API_KEY" \
  --data-urlencode 'patient_id=5a1c9e2b-7d44-4f1a-9c3e-2b8d6f0a1e77' \
  --data-urlencode 'q=from:patient'

Clean up

Delete the test patient so it doesn’t stay in your organization’s records.

Request


curl -X DELETE https://api.bloomtext.com/v1/patients/5a1c9e2b-7d44-4f1a-9c3e-2b8d6f0a1e77 \
  -H "Authorization: Bearer $BLOOMTEXT_API_KEY"

Next steps

Send messages to patients Patients Manage members Read messages

Building for an org admin’s own conversations, like staff team chats? See the OAuth quickstart.