> ## Documentation Index
> Fetch the complete documentation index at: https://docs.byblend.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How do I create a patient in Blend?

> POST /api/v1/patients with first_name, last_name, email, phone, date_of_birth, and address. Send your own external_id too — it makes prescription matching definitive. Duplicates return a 400 with the existing patient's ID.

`POST /api/v1/patients` creates a patient. Six fields are required: `first_name`, `last_name`, `email`, `phone`, `date_of_birth`, and an `address` object with `address_1`, `city`, `state`, and `zip_code`. Everything else is optional, but `external_id` is worth sending on every patient — it's what makes prescription matching definitive rather than a name lookup.

A patient must exist before an order can be placed for them, though a prescription can arrive first and wait.

## Create one

```bash theme={null}
curl -X POST https://api.byblend.com/api/v1/patients \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Willard",
    "last_name": "Donnelly",
    "email": "wdonnelly@example.com",
    "phone": "6417383445",
    "date_of_birth": "1990-01-01",
    "external_id": "clinic-pt-4471",
    "gender": "male",
    "height_inches": 72,
    "weight_pounds": 180,
    "address": {
      "address_1": "140 Lindgren Street",
      "address_2": "Apt 227",
      "city": "Boston",
      "state": "MA",
      "zip_code": "02108"
    },
    "risk_factors": {
      "allergies": "peanuts, tree nuts, shellfish",
      "conditions": "asthma, hypertension"
    }
  }'
```

Formatting rules worth knowing up front:

* **`phone`** — 10 digits, no formatting: `6417383445`, not `(641) 738-3445`.
* **`state`** — two-letter abbreviation. **`country`** defaults to `US`.
* **`zip_code`** — 5-digit or ZIP+4.
* **`date_of_birth`** — `YYYY-MM-DD`.
* **`ssn`** — accepted with or without hyphens.

## Handling a duplicate

<Warning>
  If the patient already exists, Blend returns **400** with a body that names the existing record: `error`, `existing_patient_id`, and `existing_patient_external_id` when that record has one. Treat this as a successful lookup, not a failure — read `existing_patient_id` and continue with it rather than retrying.
</Warning>

Duplicate detection runs **within your own customer account**, matching on name plus date of birth, or on `external_id`.

```python theme={null}
r = requests.post(url, json=payload, headers=headers)
if r.status_code == 400 and "existing_patient_id" in r.json():
    patient_id = r.json()["existing_patient_id"]
else:
    patient_id = r.json()["id"]
```

## Minors and guardians

If the patient is a minor, `guardian_name` is required. `guardian_phone`, `guardian_email`, and `guardian_relationship` complete the record — pull valid relationship values from `GET /patients/guardian_relationship_types`; `parent` and `legal_guardian` are the common ones, and `other` is accepted.

## Patient notifications

`receive_sms` and `receive_email` control whether the patient gets shipment notifications directly from Blend.

<Note>
  These flags only take effect if you have authorized Blend to send patient communications on your behalf. If you haven't, setting them has no effect — patient contact stays entirely with your business.
</Note>

## Creating a patient inline

You don't have to call this endpoint separately. Both `POST /orders` and the [composite endpoint](/guides/composite-creation) accept a full `patient` object and will create the patient as part of the same request — or accept `{ "external_id": "..." }` to reference an existing one.

<Tip>
  Patients can also be created and edited in the Blend Dashboard, and Blend can bulk-import your existing patient roster during onboarding — useful when you're bringing over refill prescriptions for established patients.
</Tip>

<CardGroup cols={2}>
  <Card title="Create a patient" icon="user-plus" href="/api-reference/patients/create-a-patient">
    POST /patients
  </Card>

  <Card title="Update a patient's details" icon="user-pen" href="/api-reference/patients/update-a-patients-details">
    PATCH /patients/{'{'}patient\_id{'}'}
  </Card>

  <Card title="Guardian relationship types" icon="people-roof" href="/api-reference/patients/get-guardian-relationship-types">
    Valid `guardian_relationship` values
  </Card>

  <Card title="Get a patient's details" icon="user" href="/api-reference/patients/get-a-patients-details">
    By UUID or your `external_id`
  </Card>
</CardGroup>