# Patients

> Find patients by phone number or MRN; create, update, delete, and import them; and read each patient's conversations and messages.

Source: https://www.bloomtext.com/developers/api/patients/

Find, create, update, delete, and import the patients your organization messages, and read each patient's conversations. A [patient](https://www.bloomtext.com/developers/api/reference/patient-object/) 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](https://www.bloomtext.com/developers/api/api-keys/) or an [org admin's OAuth token](https://www.bloomtext.com/developers/api/oauth/). 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](https://www.bloomtext.com/developers/api/concepts/#what-the-api-can-reach).

| To | You need |
| --- | --- |
| Find and read patients | `patients.read` |
| Create, update, delete, and import patients | `patients.write` |
| Read a patient's conversations and messages | `messages.read` |
| Message a patient, including a new phone number | `messages.write` |

See [Scopes](https://www.bloomtext.com/developers/api/authentication/#scopes).

## Find a patient

[Find patients](https://www.bloomtext.com/developers/api/reference/list-patients/) by `phone`, `mrn`, or both:

```bash filename="Request"
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](https://www.bloomtext.com/developers/api/reference/get-patient/) directly.

## Create a patient

[Create a patient](https://www.bloomtext.com/developers/api/reference/create-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](https://www.bloomtext.com/developers/api/reference/update-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](https://www.bloomtext.com/developers/api/send-messages/#who-gets-it).

## Update or delete a patient

[Update a patient](https://www.bloomtext.com/developers/api/reference/update-patient/) with only the fields that changed; send `null` to clear one.

[Delete a patient](https://www.bloomtext.com/developers/api/reference/delete-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](https://www.bloomtext.com/developers/api/reference/create-patient-import/). An import runs in the background and takes up to 10,000 patients as JSON or CSV.

```bash filename="Request"
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
```

```text filename="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](https://www.bloomtext.com/developers/api/reference/get-patient-import/) until `status` is `completed`, then read each row's outcome:

```json filename="Response · 200 OK"
{
  "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](https://www.bloomtext.com/developers/api/campaigns/#add-recipients).

## A patient's conversations and messages

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

- [List patient conversations](https://www.bloomtext.com/developers/api/reference/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](https://www.bloomtext.com/developers/api/reference/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](https://www.bloomtext.com/developers/api/read-messages/).

```bash filename="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 '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](https://www.bloomtext.com/developers/api/read-messages/#keep-up-with-new-messages).