# Patient API endpoints

> Every endpoint an organization API key can call in the BloomText Patient API, grouped by resource, with the scope each one needs.

Source: https://www.bloomtext.com/developers/api/reference/patient-api-endpoints/

All 25 endpoints an organization [API key](https://www.bloomtext.com/developers/api/api-keys/) can call, grouped by resource. An [org admin's OAuth token](https://www.bloomtext.com/developers/api/reference/oauth-endpoints/) can call every one of them too, and they behave the same. Each links to its full reference page, with parameters, errors, and code samples.

```text filename="Base URL"
https://api.bloomtext.com/v1
```

Send the key as `Authorization: Bearer $BLOOMTEXT_API_KEY`. The scope column is what the key needs; see [Scopes](https://www.bloomtext.com/developers/api/authentication/#scopes). An API key can't reach anything under `/me` or `/users`, which return `403` with `code: oauth_required`. See [OAuth endpoints](https://www.bloomtext.com/developers/api/reference/oauth-endpoints/) for those.

## Organization

The organization a credential belongs to.

| Method | Path | Endpoint | Scope |
| --- | --- | --- | --- |
| GET | `/organization` | [Retrieve the organization](https://www.bloomtext.com/developers/api/reference/get-organization/) | Any |

## Patients

Patient records, always found by patient ID, phone number, or MRN.

| Method | Path | Endpoint | Scope |
| --- | --- | --- | --- |
| GET | `/patients` | [Find patients](https://www.bloomtext.com/developers/api/reference/list-patients/) | `patients.read` |
| POST | `/patients` | [Create a patient](https://www.bloomtext.com/developers/api/reference/create-patient/) | `patients.write` |
| GET | `/patients/{patientId}` | [Retrieve a patient](https://www.bloomtext.com/developers/api/reference/get-patient/) | `patients.read` |
| PATCH | `/patients/{patientId}` | [Update a patient](https://www.bloomtext.com/developers/api/reference/update-patient/) | `patients.write` |
| DELETE | `/patients/{patientId}` | [Delete a patient](https://www.bloomtext.com/developers/api/reference/delete-patient/) | `patients.write` |

## Patient imports

Bulk imports of patient records.

| Method | Path | Endpoint | Scope |
| --- | --- | --- | --- |
| POST | `/patient-imports` | [Import patients](https://www.bloomtext.com/developers/api/reference/create-patient-import/) | `patients.write` |
| GET | `/patient-imports/{importId}` | [Retrieve an import](https://www.bloomtext.com/developers/api/reference/get-patient-import/) | `patients.write` |

## Patient messages

Messages with patients: send to a patient by ID or phone number, read patient messages by time range, and check delivery.

| Method | Path | Endpoint | Scope |
| --- | --- | --- | --- |
| GET | `/patient-messages` | [List patient messages](https://www.bloomtext.com/developers/api/reference/list-patient-messages/) | `messages.read` |
| POST | `/patient-messages` | [Send a message to a patient](https://www.bloomtext.com/developers/api/reference/send-message/) | `messages.write` |
| GET | `/patient-messages/{messageId}` | [Retrieve a patient message](https://www.bloomtext.com/developers/api/reference/get-patient-message/) | `messages.read` |

## Patient conversations

Conversations with patients, one per patient and clinic phone number.

| Method | Path | Endpoint | Scope |
| --- | --- | --- | --- |
| GET | `/patient-conversations` | [List patient conversations](https://www.bloomtext.com/developers/api/reference/list-patient-conversations/) | `messages.read` |
| GET | `/patient-conversations/{conversationId}` | [Retrieve a patient conversation](https://www.bloomtext.com/developers/api/reference/get-patient-conversation/) | `messages.read` |

## Phone numbers

The clinic phone numbers messages to patients come from, and the team each belongs to.

| Method | Path | Endpoint | Scope |
| --- | --- | --- | --- |
| GET | `/phone-numbers` | [List phone numbers](https://www.bloomtext.com/developers/api/reference/list-phone-numbers/) | `messages.read` |

## Campaigns

One message sent to many patients from a clinic phone number, with per-patient delivery.

| Method | Path | Endpoint | Scope |
| --- | --- | --- | --- |
| GET | `/campaigns` | [List campaigns](https://www.bloomtext.com/developers/api/reference/list-campaigns/) | `messages.read` |
| POST | `/campaigns` | [Create a campaign](https://www.bloomtext.com/developers/api/reference/create-campaign/) | `messages.write` |
| GET | `/campaigns/{campaignId}` | [Retrieve a campaign](https://www.bloomtext.com/developers/api/reference/get-campaign/) | `messages.read` |
| PATCH | `/campaigns/{campaignId}` | [Update a campaign](https://www.bloomtext.com/developers/api/reference/update-campaign/) | `messages.write` |
| DELETE | `/campaigns/{campaignId}` | [Delete a campaign](https://www.bloomtext.com/developers/api/reference/delete-campaign/) | `messages.write` |
| GET | `/campaigns/{campaignId}/recipients` | [List campaign recipients](https://www.bloomtext.com/developers/api/reference/list-campaign-recipients/) | `messages.read` |
| POST | `/campaigns/{campaignId}/recipients` | [Add campaign recipients](https://www.bloomtext.com/developers/api/reference/add-campaign-recipients/) | `messages.write` |
| POST | `/campaigns/{campaignId}/recipients/remove` | [Remove campaign recipients](https://www.bloomtext.com/developers/api/reference/remove-campaign-recipients/) | `messages.write` |
| POST | `/campaigns/{campaignId}/start` | [Start a campaign](https://www.bloomtext.com/developers/api/reference/start-campaign/) | `messages.write` |
| POST | `/campaigns/{campaignId}/pause` | [Pause a campaign](https://www.bloomtext.com/developers/api/reference/pause-campaign/) | `messages.write` |
| POST | `/campaigns/{campaignId}/stop` | [Stop a campaign](https://www.bloomtext.com/developers/api/reference/stop-campaign/) | `messages.write` |