# Register a new patient

Operation ID: `patient.register`

Create a Cognito user and a FHIR Patient record for a new patient, then send an email OTP for verification. No authentication is required. The returned `access_token`/`id_token` are populated only when the tenant's registration flow auto-signs the user in; otherwise the patient must verify their email via `patient.verifyEmail` before calling `patient.login`.

## Public method

`register`

Signature: `auth.register(request)`

Return type: `Promise<RegisterPatientResponse>`

## Authentication

Classification: **PUBLIC**

## Prerequisites

None documented.

## HTTP

`POST /auth/register`

## Path parameters

None.

## Query parameters

None.

## Body parameters

| Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
|---|---|---:|---|---|---|---:|---|
| `body` | [`patient.RegisterRequest`](../models/patient.RegisterRequest.md) | Yes |  |  |  | No |  |

Request model: [`patient.RegisterRequest`](../models/patient.RegisterRequest.md)

## Request example

```json
{
  "address": {},
  "addresses": [
    {}
  ],
  "attributes": {},
  "created_by": "string",
  "date_of_birth": "2026-01-01",
  "drivers_license": {
    "expiration_date": "string",
    "image": "string",
    "number": "string",
    "state": "st"
  },
  "email": "string",
  "ethnicity": "hispanic_or_latino",
  "first_name": "string",
  "flags": {},
  "last_name": "string",
  "marital_status": "single",
  "password": "stringxx",
  "phone": "string",
  "preferred_language": "string",
  "race": "string",
  "sex_at_birth": "male",
  "tenant_id": "string"
}
```

## Success responses

| Status | Shape | Content type | Description |
|---|---|---|---|
| `201` | [`patient.RegisterResponse`](../models/patient.RegisterResponse.md) | application/json | Patient registered |

## Success response examples

### 201

```json
{
  "access_token": "string",
  "athena_drivers_license_status": "linked",
  "cognito_sub": "string",
  "email_otp_sent": true,
  "email_verified": true,
  "expires_in": 0,
  "fhir_document_reference_id": "string",
  "fhir_patient_id": "string",
  "id_token": "string",
  "openloop_drivers_license_status": "linked",
  "steadymd_drivers_license_status": "linked",
  "telehealth_id": 0
}
```

## Common errors

| Status | Shape | Content type | Description |
|---|---|---|---|
| `400` | [`patient.ErrorResponse`](../models/patient.ErrorResponse.md) | application/json | Registration failed — missing/invalid fields, or the email is already registered |

## Error examples

### 400 — Registration could not be completed

```json
{
  "error": "email already registered"
}
```

## NodeJS / TypeScript implementation

```ts
import { HCSDK } from "@healthcloudai/hc-sdk";
import type { RegisterPatientRequest } from "@healthcloudai/hc-sdk";
```

```ts
const request = {
  "address": {},
  "addresses": [
    {}
  ],
  "attributes": {},
  "created_by": "string",
  "date_of_birth": "2026-01-01",
  "drivers_license": {
    "expiration_date": "string",
    "image": "string",
    "number": "string",
    "state": "st"
  },
  "email": "string",
  "ethnicity": "hispanic_or_latino",
  "first_name": "string",
  "flags": {},
  "last_name": "string",
  "marital_status": "single",
  "password": "stringxx",
  "phone": "string",
  "preferred_language": "string",
  "race": "string",
  "sex_at_birth": "male",
  "tenant_id": "string"
};

const result = await auth.register(request);
```

## cURL

```bash
curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{"address":{},"addresses":[{}],"attributes":{},"created_by":"string","date_of_birth":"2026-01-01","drivers_license":{"expiration_date":"string","image":"string","number":"string","state":"st"},"email":"string","ethnicity":"hispanic_or_latino","first_name":"string","flags":{},"last_name":"string","marital_status":"single","password":"stringxx","phone":"string","preferred_language":"string","race":"string","sex_at_birth":"male","tenant_id":"string"}' \
  'https://dev-api-patient.health.cloud/auth/register'
```

## Notes

None.

## Prepared Test Console scenario

No canonical scenario is currently associated.

## Real response

No approved real integration response is currently published. Unapproved candidates are never rendered as examples.