Patients

Find, create, update, delete, and import the patients your organization messages, and read each patient’s conversations. A patient has a name, mobile number, email address, date of birth, and mrn, the patient’s ID in your own system. Patients belong to the organization, not to a team or a staff member.

Access

Patient operations work the same with an API key or an org admin’s OAuth token. You always name the patient, by ID, phone number, or MRN; there’s no directory listing or name search. See What the API can reach.

See Scopes.

Find a patient

Find patients by phone, mrn, or both:

curl -G https://api.bloomtext.com/v1/patients \
  -H "Authorization: Bearer $BLOOMTEXT_API_KEY" \
  --data-urlencode 'mrn=MRN-20931'

A phone number can be in any common format, like (512) 555-0143 or +15125550143. It can match more than one patient, like a family sharing a phone, so the response is a list. A request with neither phone nor mrn returns 400 patient_filter_required.

Keeping each patient’s mrn in BloomText is the most reliable way to link the two systems. Names change and phones get shared; your own ID doesn’t. With a patient’s BloomText id, retrieve them directly.

Create a patient

Create a patient needs a phone number, an email address, or both. BloomText first checks whether the patient already exists, using the same rules as its CSV import, so the API and the app never disagree about who someone is:

1. The same MRN in the organization.
2. Otherwise the same phone number, after normalizing the format. If several patients match, the most recently created one.
3. Otherwise the same email address.
4. Otherwise it’s a new patient.

A new patient returns 201. A match returns 200 with matched_by set to mrn, phone, or email, and leaves the existing record as it was. Update the patient to change it.

You don’t need to create a patient before messaging them: sending to a new phone number creates one. See Send messages to patients.

Update or delete a patient

Update a patient with only the fields that changed; send null to clear one.

Delete a patient removes the record, as deleting a patient in BloomText does. Their conversations stay in BloomText for your records and for the staff in them, and any campaign messages still waiting to go to them are cancelled.

Import patients

To load many patients at once, like a nightly sync from your EHR, import them. An import runs in the background and takes up to 10,000 patients as JSON or CSV.

curl -X POST https://api.bloomtext.com/v1/patient-imports \
  -H "Authorization: Bearer $BLOOMTEXT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: text/csv" \
  --data-binary @patients.csv

first_name,last_name,dob,mrn,phone,email
Jane,Doe,1986-04-12,MRN-20931,512-555-0143,jane.doe@example.com
John,Doe,1979-11-02,MRN-20932,(512) 555-0188,

Each row is matched with the rules above. Poll Retrieve an import until status is completed, then read each row’s outcome:

{
  "id": "imp_71c2",
  "status": "completed",
  "rows": 2,
  "created": 1,
  "matched": 1,
  "failed": 0,
  "results": [
    { "row": 1, "outcome": "matched", "matched_by": "mrn", "patient_id": "5a1c9e2b-7d44-4f1a-9c3e-2b8d6f0a1e77", "error": null },
    { "row": 2, "outcome": "created", "matched_by": null, "patient_id": "9e0d3f7a-2c1b-4e8d-a5f6-7b3c2d1e0f98", "error": null }
  ],
  "created_at": "2026-09-26T06:00:00Z"
}

Matched rows don’t change existing patients; if your system has newer details, update those patients afterwards. Use each row’s patient_id to add the patients to a campaign.

A patient’s conversations and messages

Pass patient_id to limit the conversation and message lists to one patient:

• List patient conversations with patient_id returns every conversation with that patient in the organization, one per clinic phone number they’ve texted with.
• List patient messages with patient_id returns their messages across all those conversations, from everyone in them, and takes a time range and q like any read. See Read messages.

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 'after=2026-09-01' \
  --data-urlencode 'group_by=conversation'

To pick up every patient’s replies at once, read messages with after set to your last check and q=from:patient. See Keep up with new messages.