Search messages

Find messages by their words and by operators like from:patient and is:unread. Both message lists, GET /patient-messages and GET /me/messages, take these in a q parameter, as does the OAuth conversation list, GET /me/conversations. Combine q with the after and before time range to say when.

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). /me/messages searches the connected person’s own conversations (with OAuth), including messages sent before they joined one. Results are complete Message objects, 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.

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.

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.

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.

Search conversations too

With OAuth, GET /me/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 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.

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 with phone or mrn. See Patients.

Good to know

Search covers only what the credential can see. See Core concepts.
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.
To keep up with new messages, ask again with after set to the newest message you’ve seen. See Read messages.