# Changelog

> Dated changes to the BloomText API and these docs, including new endpoints, fields, authentication, and behavior changes.

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

This page lists changes to the BloomText API and these docs. The API is versioned in the URL (`/v1`). Additive changes, such as new endpoints, fields, or search operators, ship within `v1`, so build clients that ignore fields they don't recognize. Breaking changes ship as a new version, announced here first.

## November 1, 2026

### Request access, API identities, and the docs for IT

- Features BloomText turns on per account now have a **Request access** button that books a call: OAuth (client credentials and authorization code, everything under `/me` and `/users`), [webhooks](https://www.bloomtext.com/developers/api/webhooks/), [API identities](https://www.bloomtext.com/developers/api/api-identity/), [phone-number limits on keys](https://www.bloomtext.com/developers/api/api-keys/#limit-a-key-to-phone-numbers), [campaigns](https://www.bloomtext.com/developers/api/campaigns/), [patient imports](https://www.bloomtext.com/developers/api/patients/#import-patients), and the [audit events API](https://www.bloomtext.com/developers/api/reporting-and-audit/#audit-events-api). They replace the earlier banners. The [OpenAPI spec](https://www.bloomtext.com/developers/api/openapi/bloomtext-api.yaml) still marks them `x-status: planned`.
- [API identities](https://www.bloomtext.com/developers/api/api-identity/): sending keys belong to an automated sender with its own name, avatar, teams and numbers.
- New pages: [SSO and Directory Sync](https://www.bloomtext.com/developers/api/identity-and-sso/), on Okta single sign-on and provisioning alongside the members API, and [Reporting and audit data](https://www.bloomtext.com/developers/api/reporting-and-audit/).
- Members managed by the account's Okta rules show `managed_by: okta`, and changing them through the API returns `409 managed_by_identity_provider`. See [Manage members](https://www.bloomtext.com/developers/api/members-api/).
- The OpenAPI spec is also published as [JSON](https://www.bloomtext.com/developers/api/openapi/bloomtext-api.json), alongside the 3.0 and 2.0 copies, with a Postman collection generated from it. See the [API reference](https://www.bloomtext.com/developers/api/reference/).
- The API keys tab is **Settings → Account → API keys**.

## October 31, 2026

### Account keys and the members API

- API keys belong to your account. An Owner or IT person creates them under **Settings → Account → API keys**, for every organization on the account or only some. Organizations no longer have an API keys tab. See [API keys](https://www.bloomtext.com/developers/api/api-keys/).
- A key that reaches several organizations passes `org_id` on every call, or gets `400 org_id_required`; an `org_id` it can't reach returns `403 org_not_reachable`. Keys made before keep working with no `org_id`. See [Organizations a key reaches](https://www.bloomtext.com/developers/api/api-keys/#organizations-a-key-reaches).
- New endpoints: [`GET /orgs`](https://www.bloomtext.com/developers/api/reference/list-orgs/), [`/members`](https://www.bloomtext.com/developers/api/reference/list-members/), [`/teams`](https://www.bloomtext.com/developers/api/reference/list-teams/), [`/teams/{teamId}/members`](https://www.bloomtext.com/developers/api/reference/add-team-member/), and [`/member-events`](https://www.bloomtext.com/developers/api/reference/list-member-events/), with the new scopes `members.read`, `members.write`, and `teams.write`. They return `403 accounts_not_enabled` until BloomText turns on accounts for your account. See [Manage members](https://www.bloomtext.com/developers/api/members-api/).

### Sends that wait for consent to text

- When your organization requires consent before texting and the patient's phone hasn't agreed yet, [Send a message to a patient](https://www.bloomtext.com/developers/api/reference/send-message/) returns `202 Accepted` instead of `201`. The message is in the conversation with `delivery.status` `consent_requested`, and BloomText texts the patient a consent request. The text goes out when they reply YES or staff record their consent. See [Delivery status](https://www.bloomtext.com/developers/api/send-messages/#delivery-status).
- [Send messages in a batch](https://www.bloomtext.com/developers/api/reference/send-message-batch/) reports these messages with `status: consent_requested`.
- A retry with the same `Idempotency-Key` returns the stored result and sends nothing new.
- A message BloomText didn't send for lack of consent becomes `rejected` with `delivery.error_code` `consent_required` (the patient hasn't given consent) or `consent_not_sent` (the text waited for consent and wasn't sent). See [Delivery status](https://www.bloomtext.com/developers/api/send-messages/#delivery-status).

## October 20, 2026

### Org admins create API keys

- Once BloomText turns on API access for your organization, an org admin creates keys under **Settings → API keys → Create API key**, choosing the name, scopes, and expiry. See [API keys](https://www.bloomtext.com/developers/api/api-keys/).

## October 15, 2026

### Sends to a phone number never switch patients

- A send to `to.phone` with a `patient.mrn` that belongs to a patient with a different number now returns `409 recipient_mismatch` instead of texting the number on file. So does a number whose only patient has a different MRN. Nothing is sent; update the patient, or send with `patient_id`. See [Who gets it](https://www.bloomtext.com/developers/api/send-messages/#who-gets-it).
- A phone number check that fails on BloomText's side now returns `500 internal_error`, which you can retry with the same `Idempotency-Key`, instead of `422 validation_failed`.
- An API key's default number that's no longer one of the organization's numbers is ignored, so a one-number organization still sends without `from`.

## October 14, 2026

### Numbers that can't receive texts

- When a text fails with carrier error 30006 (a landline, or a carrier that couldn't be reached), BloomText stops texting that number from all of your organization's numbers. Later sends return `422 number_unreachable`, with `number` and `since`, and a text already queued becomes `rejected` with `delivery.error_code` `number_unreachable`. See [Opt-outs and blocked numbers](https://www.bloomtext.com/developers/api/send-messages/#opt-outs-and-blocked-numbers).
- [Patients](https://www.bloomtext.com/developers/api/reference/patient-object/) list it in `sms_undeliverable_reasons` as `unreachable`, after the other reasons.
- It clears when the patient texts one of your numbers, when their phone number is changed, or when an admin clears it in the app.

## October 13, 2026

### Rate limits per organization

- API key rate limits now apply to the organization, shared by all its keys, instead of to each key. A second key no longer adds to them.
- The limits are now 300 requests per minute, with bursts of 10 per second, and 60 messages per minute. A text number can only send so fast; a faster API backs texts up at the carrier, which delays every text from that number, including staff replies.
- [Send messages in a batch](https://www.bloomtext.com/developers/api/reference/send-message-batch/) takes up to 60 messages (was 500). A larger batch returns `422 validation_failed`.
- BloomText can raise the limits for an organization on request. See [Rate limits](https://www.bloomtext.com/developers/api/rate-limits/).

## October 12, 2026

### Batch sends and higher limits

- [Send messages in a batch](https://www.bloomtext.com/developers/api/reference/send-message-batch/): `POST /v1/messages:batch` sends up to 500 messages in one request and returns `207 Multi-Status` with a result per message.
- API keys get 600 requests per minute (was 300), with bursts of 20 per second, and a new limit of 5,000 messages per minute. See [Rate limits](https://www.bloomtext.com/developers/api/rate-limits/).
- [Idempotency](https://www.bloomtext.com/developers/api/idempotency/) now says it plainly: every retry must reuse its `Idempotency-Key`. A new key is a new message.

### Clearer send errors

- `channel` is now required on every send: `422 channel_required` without it.
- A text that can't be sent fails before it's queued, with `422 patient_opted_out`, `carrier_blocked`, `number_blocked` (an admin blocked the patient's number), or `patient_has_no_phone`. See [Opt-outs and blocked numbers](https://www.bloomtext.com/developers/api/send-messages/#opt-outs-and-blocked-numbers).
- A text over 1,600 characters returns `422 too_long` with `length` and `max`. See [Long texts](https://www.bloomtext.com/developers/api/send-messages/#long-texts).
- A send without `from`, when the organization has several numbers and no default, returns `422 from_required` with the numbers to choose from.

### Sends need the patient messaging plan

- Sending to patients (`POST /v1/patient-messages` and `POST /v1/messages:batch`) now needs the organization's plan to include patient messaging, as in the app. Without it, the request returns `403 plan_required`, a batch as a whole, and nothing is sent.

### Unknown fields are rejected

- A `POST` or `PATCH` body with a field the endpoint doesn't take now returns `422 unknown_field`, instead of the field being ignored. `field_errors` names each one and, for a field in the wrong place, where it goes, like `'patient' isn't a top-level field; put it under 'to'.` Nothing runs, and the `Idempotency-Key` can be reused with the fixed body. See [Unknown fields are rejected](https://www.bloomtext.com/developers/api/errors/#unknown-fields-are-rejected).

### API keys expire and can be revoked

- Every [API key](https://www.bloomtext.com/developers/api/api-keys/) has an expiry: 1 day, 7 days, 30 days, 90 days (the default for new keys), 1 year, or never. Keys created before today never expire. Requests with an expired key return `401` with the new code `key_expired`.
- Org admins can see, extend, and revoke their organization's keys under **Settings → API keys**. Requests with a revoked key return `401` with the new code `key_revoked`.
- `invalid_token` now only means the key is missing, malformed, or not a BloomText key.

### Opt-out state on patients, and what isn't served

- [Patients](https://www.bloomtext.com/developers/api/reference/patient-object/) now report whether your organization can text them. `sms_opted_out` was always `false` before; it's now `true` when the patient can't be texted for any reason. The new `sms_undeliverable_reasons` says why: `opted_out`, `carrier_blocked`, or `admin_blocked`. Each one blocks all of your organization's numbers.
- [Retrieve a patient message](https://www.bloomtext.com/developers/api/reference/get-patient-message/) is served: `GET /v1/patient-messages/{messageId}` returns one message, with its delivery status, under the same rules as the list.
- Endpoints that are documented but not served are marked in the docs: campaigns, patient imports, and OAuth (everything under `/me` and `/users`). The [OpenAPI spec](https://www.bloomtext.com/developers/api/openapi/bloomtext-api.yaml) marks them `x-status: planned`. Since November 1, 2026 their pages have a **Request access** button.

## September 26, 2026

### BloomText API v1

The first version of the BloomText API, with two ways in: the Patient API for servers, and OAuth for an org admin's own conversations.

> **Note:** Correction, November 1, 2026: OAuth (everything under `/me` and `/users`), campaigns and patient imports were documented in this release but not served. BloomText now turns them on for an account that asks; see [OAuth](https://www.bloomtext.com/developers/api/authentication/#oauth). The API key, patients, patient messages, phone numbers, search on `/patient-messages`, and the conventions below shipped as described.

**Authentication**

- [API keys](https://www.bloomtext.com/developers/api/api-keys/) belong to the organization and reach patient operations.
- [OAuth 2.0](https://www.bloomtext.com/developers/api/oauth/), using the authorization code flow with PKCE, for an org admin's own conversations.
- [Scopes](https://www.bloomtext.com/developers/api/authentication/#scopes): `messages.read`, `messages.write`, `patients.read`, and `patients.write`, shared by keys and OAuth, plus `offline_access` for OAuth.

**Patient API**

- [Send messages to patients](https://www.bloomtext.com/developers/api/send-messages/) by patient ID or phone number. Messages go by secure link unless you ask for SMS, and report delivery status.
- [Patients](https://www.bloomtext.com/developers/api/patients/): find by phone or MRN; create, update, and delete. BloomText turns imports on for an account that asks.
- [Campaigns](https://www.bloomtext.com/developers/api/campaigns/): one message to many patients from a clinic phone number.
- [Phone numbers](https://www.bloomtext.com/developers/api/reference/list-phone-numbers/): the clinic numbers messages come from.

**Reading and search**

- [Read messages](https://www.bloomtext.com/developers/api/read-messages/) in a time range with `GET /patient-messages`, or `GET /me/messages` with OAuth, one by one or grouped by conversation.
- [Search](https://www.bloomtext.com/developers/api/search/) with `q`, including operators like `from:patient`, `mrn:`, and `is:unread`.

**Conventions**

- [Idempotency keys](https://www.bloomtext.com/developers/api/idempotency/) on every `POST`, [cursor pagination](https://www.bloomtext.com/developers/api/pagination/), and [problem details errors](https://www.bloomtext.com/developers/api/errors/).
- The [OpenAPI 3.1 spec](https://www.bloomtext.com/developers/api/openapi/bloomtext-api.yaml) and [docs for AI agents](https://www.bloomtext.com/developers/api/llms/).
