# Patient API quickstart

> Make your first Patient API requests with an organization API key. Text your phone, check delivery, read the reply, and clean up.

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

Text your own phone as a test patient, check that the message was delivered, read your reply through the API, and clean up.

### Get an API key

API access is turned on for organizations with a signed BAA. [Request API access](https://calendly.com/tyler-bloom/bloomtext-homepage-demo-request?utm_campaign=api-access) if you don't have it yet. An org admin then creates a key in BloomText under **Settings → API keys**. For this guide, give it the scopes `patients.read`, `patients.write`, `messages.read`, and `messages.write`, and a default phone number.

Store the key in an environment variable. Never commit it or ship it to a browser.

```bash filename="Terminal"
export BLOOMTEXT_API_KEY="bt_key_4f7c2a9e1b..."
```

### Check the key

Retrieve your organization to confirm the key works.

```bash filename="Request"
curl https://api.bloomtext.com/v1/organization \
  -H "Authorization: Bearer $BLOOMTEXT_API_KEY"
```

```js filename="check.mjs"
const response = await fetch('https://api.bloomtext.com/v1/organization', {
  headers: { Authorization: `Bearer ${process.env.BLOOMTEXT_API_KEY}` },
})
console.log(response.status, await response.json())
```

```python filename="check.py"
import os

import requests

response = requests.get(
    "https://api.bloomtext.com/v1/organization",
    headers={"Authorization": f"Bearer {os.environ['BLOOMTEXT_API_KEY']}"},
)
print(response.status_code, response.json())
```

```json filename="Response · 200 OK"
{ "id": "6db1e3f5-9b7f-4f2b-8be1-0f1e1d7d7d8c", "name": "Example Clinic" }
```

### Text your own phone

Send a message to your own mobile number. BloomText doesn't know the number yet, so it creates a patient. Name the patient "API Test" so staff know what it is.

```bash filename="Request"
curl -X POST https://api.bloomtext.com/v1/patient-messages \
  -H "Authorization: Bearer $BLOOMTEXT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "to": { "phone": "YOUR_MOBILE_NUMBER", "patient": { "first_name": "API", "last_name": "Test" } },
    "body": "Hello from the BloomText API. Reply to this message to test replies."
  }'
```

```js filename="send.mjs"
const response = await fetch('https://api.bloomtext.com/v1/patient-messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BLOOMTEXT_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: { phone: 'YOUR_MOBILE_NUMBER', patient: { first_name: 'API', last_name: 'Test' } },
    body: 'Hello from the BloomText API. Reply to this message to test replies.',
  }),
})
console.log(await response.json())
```

```python filename="send.py"
import os
import uuid

import requests

response = requests.post(
    "https://api.bloomtext.com/v1/patient-messages",
    headers={
        "Authorization": f"Bearer {os.environ['BLOOMTEXT_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "to": {"phone": "YOUR_MOBILE_NUMBER", "patient": {"first_name": "API", "last_name": "Test"}},
        "body": "Hello from the BloomText API. Reply to this message to test replies.",
    },
)
response.raise_for_status()
print(response.json())
```

The message goes by secure link (the default), so your phone gets a text with a link to read it. Save `message.id` and `message.patient.id` from the response.

```json filename="Response · 201 Created"
{
  "message": {
    "id": "4cbfdb50-6b7d-45d4-94b3-05a52ce3f4d1",
    "conversation": { "id": "e5c3b7b8-8f08-4d5a-9af1-0d11b0f4b7a0", "title": "API Test" },
    "sender": { "id": "b7e1c3a9-4d2f-4a8b-9c6e-0f1d2e3a4b5c", "name": "Reminder service", "kind": "api_key" },
    "patient": { "id": "5a1c9e2b-7d44-4f1a-9c3e-2b8d6f0a1e77", "name": "API Test" },
    "channel": "secure",
    "delivery": { "status": "queued", "error": null, "updated_at": "2026-09-27T15:04:05Z" },
    "body": "Hello from the BloomText API. Reply to this message to test replies.",
    "...": "..."
  },
  "patient_created": true,
  "conversation_created": true
}
```

### Check delivery

After a few seconds, [retrieve the message](https://www.bloomtext.com/developers/api/reference/get-patient-message/) to see its delivery status.

```bash filename="Request"
curl https://api.bloomtext.com/v1/patient-messages/4cbfdb50-6b7d-45d4-94b3-05a52ce3f4d1 \
  -H "Authorization: Bearer $BLOOMTEXT_API_KEY"
```

`delivery.status` moves from `queued` to `sent` to `delivered`, then `opened` once you open the link.

### Read your reply

Open the link on your phone and reply. Then list the messages the test patient (you) sent, newest first:

```bash filename="Request"
curl -G https://api.bloomtext.com/v1/patient-messages \
  -H "Authorization: Bearer $BLOOMTEXT_API_KEY" \
  --data-urlencode 'patient_id=5a1c9e2b-7d44-4f1a-9c3e-2b8d6f0a1e77' \
  --data-urlencode 'q=from:patient'
```

### Clean up

Delete the test patient so it doesn't stay in your organization's records.

```bash filename="Request"
curl -X DELETE https://api.bloomtext.com/v1/patients/5a1c9e2b-7d44-4f1a-9c3e-2b8d6f0a1e77 \
  -H "Authorization: Bearer $BLOOMTEXT_API_KEY"
```

## Next steps

  - [Send messages to patients](https://www.bloomtext.com/developers/api/send-messages/)
  - [Patients and imports](https://www.bloomtext.com/developers/api/patients/)
  - [Campaigns](https://www.bloomtext.com/developers/api/campaigns/)
  - [Read messages](https://www.bloomtext.com/developers/api/read-messages/)

Building for an org admin's own conversations, like staff team chats? See the [OAuth quickstart](https://www.bloomtext.com/developers/api/oauth-quickstart/).