# Search messages

> Search BloomText patient messages with words and operators like from:patient, mrn:, and is:failed, 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:failed`. [`GET /patient-messages`](https://www.bloomtext.com/developers/api/reference/list-patient-messages/) takes these in a `q` parameter. With [OAuth](https://www.bloomtext.com/developers/api/oauth/), so do [`GET /me/messages`](https://www.bloomtext.com/developers/api/reference/list-messages/) and [`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, and the carrier reported it failed. Also `is:undelivered`, `is:rejected` (BloomText didn't send it: the patient opted out, the carrier blocks texts to them, an admin blocked the number, the number can't receive texts, the patient hasn't given consent to text, or the text waited for consent and wasn't sent), `is:queued`, `is:sent`, and `is: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: `refill from:patient` matches patients' messages that mention a refill.
- `-` negates: `-from:staff` matches messages that staff 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 (OAuth) | `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](https://www.bloomtext.com/developers/api/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).
