API keys
An API key lets your server handle patient communication with no one signed in: syncing patients from your EHR, sending reminders, running campaigns, and reading what patients write back.
Your organization gets API access
API access is turned on for organizations with a signed BAA. Request API access to get started.
An org admin creates a key
In BloomText, an org admin creates a key under Settings → API keys, choosing:
- a name, like “Reminder service”. Messages the key sends come from this name, so staff know where they came from; patients see the clinic.
- its scopes. A key that only sends reminders needs
messages.writeandpatients.read. - a default phone number, used when a send doesn’t pass
from. See Phone numbers.
BloomText shows the key once. Store it in your secrets manager right away.
Your server sends it
Send the key as a Bearer token:
curl https://api.bloomtext.com/v1/organization \
-H "Authorization: Bearer $BLOOMTEXT_API_KEY"{ "id": "6db1e3f5-9b7f-4f2b-8be1-0f1e1d7d7d8c", "name": "Example Clinic" }What a key can reach
- Patients: find them by phone number or MRN, and retrieve, create, update, delete, and import them.
- Patient communication: message a patient, and read patient messages in a time range, for one patient, or across all patient conversations.
- Campaigns: create, change, run, and delete them.
A key reads with GET /patient-messages and GET /patient-conversations, which cover patient conversations only. It never sees staff conversations; see What the API can reach. The /me endpoints, for an admin’s own conversations, need OAuth. Staff-side calls, like the staff directory, reactions, participants, or sending in a staff conversation, return 403 with code: oauth_required.
Keep keys on your server. Never put a key in a browser, a mobile app, a public repository, or an AI prompt.
Rotate or delete a key
To rotate a key, create a second one, deploy it, then delete the old one. Both work during the overlap.
Delete a key in BloomText at any time. It stops working on the next request.