# Search messages

> Search BloomText messages and conversations with words and operators like from:patient, mrn:, and is:unread, combined with an after and before time range.

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

Find messages by their words and by operators like `from:patient` and `is:unread`. Both message lists, [`GET /patient-messages`](https://www.bloomtext.com/developers/api/reference/list-patient-messages/) and [`GET /me/messages`](https://www.bloomtext.com/developers/api/reference/list-messages/), take these in a `q` parameter, as does the OAuth conversation list, [`GET /me/conversations`](https://www.bloomtext.com/developers/api/reference/list-conversations/). Combine `q` with the `after` and `before` [time range](https://www.bloomtext.com/developers/api/read-messages/#choose-the-range) to say when.

```bash filename="Request"
curl -G https://api.bloomtext.com/v1/patient-messages \
  -H "Authorization: Bearer $BLOOMTEXT_API_KEY" \
  --data-urlencode 'after=2026-09-21' \
  --data-urlencode 'q=refill from:patient' \
  --data-urlencode 'order=asc'
```

Search works the same on both. `/patient-messages` searches patient conversations (with an [API key](https://www.bloomtext.com/developers/api/api-keys/)). `/me/messages` searches the connected person's own conversations (with [OAuth](https://www.bloomtext.com/developers/api/oauth/)), including messages sent before they joined one. Results are complete [Message objects](https://www.bloomtext.com/developers/api/reference/message-object/), each with its sender and conversation, so you don't need a second request per message. They're paginated like every other list; see [Pagination](https://www.bloomtext.com/developers/api/pagination/).

## Operators

| Operator | Example | Matches messages |
| --- | --- | --- |
| free text | `referral` | Containing the word, in the text or an attachment's file name. Case doesn't matter. |
| `"…"` | `"prior auth"` | Containing the exact phrase. |
| `from:` | `from:me`, `from:patient`, `from:staff`, `from:8b9c2d2f-…` | From the connected admin (OAuth only), any patient, any staff member, or a specific user by ID. |
| `patient:` | `patient:5a1c9e2b-…` | In conversations with that patient. |
| `mrn:` | `mrn:MRN-20931` | Same, by the patient's ID in your system. |
| `phone:` | `phone:+15125550143` | Same, by the patient's phone number. Any common format works. |
| `is:unread` | `is:unread` | That the connected admin hasn't read yet. OAuth only; API keys have no read state. |
| `is:failed` | `is:failed` | Sent to a patient but not delivered. See [Delivery status](https://www.bloomtext.com/developers/api/send-messages/#delivery-status). |

Time isn't part of `q`; use `after` and `before`. To narrow to one conversation or patient, use `conversation_id` or `patient_id`. See [Read messages](https://www.bloomtext.com/developers/api/read-messages/#narrow-it-down).

### Combining terms

- Terms combine with AND by default: `from:patient is:unread` matches unread messages from patients.
- `-` negates: `-from:me` matches messages the connected admin didn't send.
- `OR` gives alternatives. Group with parentheses: `(referral OR "prior auth")`.

## Examples

| You want | Parameters |
| --- | --- |
| Everything since the start of yesterday | `after=2026-09-25` |
| What the admin hasn't read (OAuth) | `q=is:unread` |
| Patient messages this week | `after=2026-09-21&q=from:patient` |
| Everything with one patient this month | `after=2026-09-01&patient_id=5a1c9e2b-…` (or `q=mrn:MRN-20931`) |
| Texts that didn't reach patients today | `after=2026-09-26&q=is:failed` |
| Everything today except the admin's own messages | `after=2026-09-26&q=-from:me` |
| Referrals or prior authorizations this month | `after=2026-09-01&q=(referral OR "prior auth")` |
| One conversation's messages about a refill | `conversation_id=e5c3b7b8-…&q=refill` |

## Order and grouping

Messages come back newest first. Pass `order=asc` for oldest first, which reads more naturally when you summarize a period. Pass `group_by=conversation` to get every matching message from one conversation before the next. See [Read messages](https://www.bloomtext.com/developers/api/read-messages/#one-by-one-or-grouped-by-conversation).

## Search conversations too

With OAuth, [`GET /me/conversations`](https://www.bloomtext.com/developers/api/reference/list-conversations/) takes its own `q` to find the person's conversations rather than messages. With `after` and `before`, it returns conversations active in that range, each with its latest message and how many messages fell in the range.

The Patient API's [`GET /patient-conversations`](https://www.bloomtext.com/developers/api/reference/list-patient-conversations/) has no `q`, so patients can't be searched by name. Filter it by `after` or `patient_id` instead.

| Operator | Example | Matches conversations |
| --- | --- | --- |
| free text | `doe` | With the text in the title or a participant's name. |
| `is:unread` | `is:unread` | With unread messages. |
| `with:` | `with:8b9c2d2f-…` | That include this user or patient. |

```bash filename="Request"
curl -G https://api.bloomtext.com/v1/me/conversations \
  -H "Authorization: Bearer $BLOOMTEXT_ACCESS_TOKEN" \
  --data-urlencode 'after=2026-09-26' \
  --data-urlencode 'q=is:unread'
```

## Find a patient

To find a patient rather than messages, use [Find patients](https://www.bloomtext.com/developers/api/reference/list-patients/) with `phone` or `mrn`. See [Patients](https://www.bloomtext.com/developers/api/patients/#find-a-patient).

## Good to know

- Search covers only what the credential can see. See [Core concepts](https://www.bloomtext.com/developers/api/concepts/#what-the-api-can-reach).
- Matching is on whole words and phrases, with no fuzzy or meaning-based matching. To find messages about a topic, have your app or model search for a few likely words combined with `OR`.
- Queries are limited to 1,000 characters. A query BloomText can't parse returns `400` with `code: invalid_query` and a `detail` pointing at the problem.
- Searching never marks messages as read. See [Read state](https://www.bloomtext.com/developers/api/concepts/#read-state).
- To keep up with new messages, ask again with `after` set to the newest message you've seen. See [Read messages](https://www.bloomtext.com/developers/api/read-messages/#keep-up-with-new-messages).