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

API access is turned on for organizations with a signed BAA. Request API access if you don’t have it yet. An org admin then creates a key in BloomText under Settings → API keys. For this guide, give it the scopes patients.read, patients.write, messages.read, and messages.write, and a default phone number.

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": "Example 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."
  }'

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.',
  }),
})
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.",
    },
)
response.raise_for_status()
print(response.json())

The message goes by secure link (the default), 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, then opened once you open the link.

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 and imports Campaigns Read messages

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