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

# Patients

> Search and view patient profiles via the Management API

# Patients

Search for patients by email address, view patient profiles, and check patient intent status.

## Create or Resolve Patient

Create a patient profile for a shop customer, or return the existing profile if the `shop_uid` and `shop_customer_id` pair already exists. This is the supported patient creation flow for API-key integrations that later use Scheduling.

```bash theme={null}
POST /v1/management/patients
```

**Required permission:** `patient:write`

```bash theme={null}
curl -X POST "https://api.rxscale.com/v1/management/patients" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "shop_uid": "shop_123",
    "shop_customer_id": "customer_456",
    "email": "max@example.com",
    "fields": [
      {
        "field": "first_name",
        "value": "Max",
        "source": "shop"
      }
    ]
  }'
```

<ParamField body="shop_uid" type="string" required>
  UID of the shop the customer belongs to
</ParamField>

<ParamField body="shop_customer_id" type="string" required>
  The shop's identifier for the customer
</ParamField>

<ParamField body="email" type="string">
  Optional patient email stored on the shop-patient mapping and used for patient lookup/search.
</ParamField>

<ParamField body="fields" type="array">
  Optional patient profile fields to set for the shop customer.
</ParamField>

```json theme={null}
{
  "patient_profile_uid": "pp-abc123"
}
```

## Search Patient by Email

Find a patient by their email address. Returns the most recently created patient whose shop-patient email or order email matches the given email.

```bash theme={null}
GET /v1/management/patients?email={email}
```

<ParamField query="email" type="string" required>
  The email address to search for
</ParamField>

**Required permission:** `patient:read`

### Example Request

```bash theme={null}
curl -X GET "https://api.rxscale.com/v1/management/patients?email=max@example.com" \
  -H "X-API-Key: your-api-key-here"
```

### Response

```json theme={null}
{
  "uid": "pp-abc123",
  "data": {
    "display_name": "Max Mustermann",
    "email": "max@example.com",
    "date_of_birth": "1990-01-15"
  }
}
```

### Error Responses

| Status Code | Description                           |
| ----------- | ------------------------------------- |
| `400`       | Missing or invalid email parameter    |
| `404`       | No patient found with the given email |

## Get Patient Profile

Retrieve a patient profile by UID.

```bash theme={null}
GET /v1/management/patients/{patient_uid}
```

<ParamField path="patient_uid" type="string" required>
  The patient UID
</ParamField>

**Required permission:** `patient:read`

### Example Request

```bash theme={null}
curl -X GET "https://api.rxscale.com/v1/management/patients/pp-abc123" \
  -H "X-API-Key: your-api-key-here"
```

### Response

```json theme={null}
{
  "uid": "pp-abc123",
  "data": {
    "display_name": "Max Mustermann",
    "email": "max@example.com",
    "date_of_birth": "1990-01-15"
  }
}
```

## Check Patient Intent

Check the intent return code for a patient. Returns a code indicating when the last signed submission for this intent was made.

```bash theme={null}
GET /v1/management/patients/{patient_uid}/intent/{intent}
```

<ParamField path="patient_uid" type="string" required>
  The patient UID
</ParamField>

<ParamField path="intent" type="string" required>
  The intent identifier
</ParamField>

**Required permission:** `patient:read`

### Example Request

```bash theme={null}
curl -X GET "https://api.rxscale.com/v1/management/patients/pp-abc123/intent/consultation" \
  -H "X-API-Key: your-api-key-here"
```

### Response

```json theme={null}
{
  "return_code": "VALID"
}
```

### Return Code Values

| Code        | Description                                                |
| ----------- | ---------------------------------------------------------- |
| `VALID`     | The patient has a valid, recent submission for this intent |
| `EXPIRED`   | The patient's last submission has expired                  |
| `NOT_FOUND` | No submission found for this intent                        |