# Patient registration

Canonical page: https://docs.ovok.com/authentication/patient-registration

Creates a patient account in a tenant and signs the patient in straight away: the response carries tokens, so there is no separate sign-in step.

| Method | Path |
| --- | --- |
| `POST` | `/v1/auth/tenant/Patient/register` |

No bearer token is needed. The tenant is named by `tenantCode`.

## What the project needs [#what-the-project-needs]

Registration is refused unless the project is set up for it. Check both before you build the screen.

| Requirement | Detail |
| --- | --- |
| A default patient AccessPolicy | `defaultPatientAccessPolicy` on the project. Every new patient receives it, and registration is refused with `403` until it exists. Set it with [`DEFAULT_PATIENT_ACCESS_POLICY`](/settings-and-features/settings/default-patient-access-policy). |
| Registration switched on | [`PATIENT_REGISTRATION_ENABLED`](/settings-and-features/settings/patient-registration-enabled) must not be `false`. It is on when unset, but `GET /v1/project/settings` reports `false` for a project that has never set it. Set it explicitly. |

## Request [#request]

```bash
curl --request POST \
  --url 'https://api.sandbox.ovok.com/v1/auth/tenant/Patient/register' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "patient@example.com",
    "password": "your-password",
    "name": "Ada",
    "surname": "Lovelace",
    "tenantCode": "big-health-company"
  }'
```

| Body field | Required | Description |
| --- | --- | --- |
| `email` | Yes | The patient's email. Ovok lowercases it. |
| `password` | Yes | The patient's password: 12 to 128 characters, and not a common password. See the [password policy](/authentication#password-policy). |
| `name` | Yes | Given name. |
| `surname` | Yes | Family name. |
| `tenantCode` | Yes | The tenant to register in. |
| `continueAsPatientToken` | No | From a "continue as a patient" link; see [business-email sign-up](#business-email-sign-up). |

## Response [#response]

On success the answer is the same as a finished [sign-in](/authentication/patient-login#step-3-exchange-the-session-code-for-tokens):

| Response field | Example | Meaning |
| --- | --- | --- |
| `accessToken` | Token string | Bearer token for API calls. |
| `refreshToken` | Token string | Token used to renew the session. |
| `expiresIn` | `3600` | Access-token lifetime in seconds. |
| `project.reference`, `project.display` | `Project/<id>`, `Big Health Company` | Project the tokens are for. |
| `profile.reference`, `profile.display` | `Patient/<id>`, `Ada Lovelace` | Patient profile that was registered. |

A welcome email (`PATIENT_WELCOME`) is sent in the background, and only if that template is [mapped](/email-templates/template-catalogue). The response does not wait for it.

The one other success answer is `{ "nextStep": "clinician-invite" }`, with no tokens; see [business-email sign-up](#business-email-sign-up).

## What can go wrong [#what-can-go-wrong]

Checks run in this order, so the first one that fails is the one you see.

| Order | Status | Message | Cause |
| --- | --- | --- | --- |
| 1 | `429` | | More than 5 requests in a minute from the same IP address. |
| 2 | `404` | `Tenant not found.` | The tenant code is wrong. |
| 3 | `403` | `Registration is not enabled for this project.` | The project has no default patient AccessPolicy. |
| 4 | `403` | `Registration is not enabled for this project.` | [`PATIENT_REGISTRATION_ENABLED`](/settings-and-features/settings/patient-registration-enabled) is `false`. |
| 5 | `400` | `Registration failed.` | A patient with this email already exists in this project. |
| 6 | `400` | `The continue-as-patient link is invalid or has expired.` | A `continueAsPatientToken` was sent and is wrong, expired, or for another email or project. |

Steps 3 and 4 give the **same** message. If you did not turn the switch off, check the default patient AccessPolicy first. A body field that is missing or invalid answers `422` with a list of `path` and `message`.

## Business-email sign-up [#business-email-sign-up]

Some projects want colleagues from a company to become practitioners, not patients. With [`CLINICIAN_INVITE_ON_BUSINESS_EMAIL`](/settings-and-features/settings/clinician-invite-on-business-email) on, a registration with a business address creates a **practitioner invitation** instead of a patient. A business address is one that is neither free mail nor a throwaway domain.

The call then answers `{ "nextStep": "clinician-invite" }` with no tokens, and Ovok emails an invitation with a link to set a password as a practitioner. The email also carries a "continue as a patient" link; send its `continueAsPatientToken` back in this request to register as a patient anyway. The token is valid for 7 days and only for the same email in the same project. An invalid or expired token answers `400` `The continue-as-patient link is invalid or has expired.`

The invitation goes out only when **all** of these hold:

- patient registration would otherwise succeed (the two requirements above);
- the setting is `true` ([how to set it](/settings-and-features/settings/clinician-invite-on-business-email#turn-it-on));
- [`DEFAULT_PRACTITIONER_ACCESS_POLICY`](/settings-and-features/settings/default-practitioner-access-policy) resolves to a valid policy;
- a [`PRACTITIONER_APP_URL`](/settings-and-features/settings/practitioner-app-url) resolves, for the set-password link;
- a [`PATIENT_APP_URL`](/settings-and-features/settings/patient-app-url) resolves, for the "continue as a patient" link;
- the invitation email can be sent: `CLINICIAN_SIGNUP_INVITE` is [mapped](/email-templates/map-templates) and its provider is `ready`.

If any condition fails, the person is registered as a patient and **you are not told**; the reason is only logged. An email that already has an account in any project answers `400 Registration failed.`

## Gotchas [#gotchas]

- **Registration returns tokens even when [`PATIENT_LOGIN_ENABLED`](/settings-and-features/settings/patient-login-enabled) is `false`.** To stop patients signing up, use the registration switch.
- **Turning registration off does not stop every way to create a patient.** Invitations create patients too, while [`PATIENT_INVITATION_ENABLED`](/settings-and-features/settings/patient-invitation-enabled) is on, and first-time Google or Apple sign-in does as well. Turn the invitation switch off for an invitation-free project.
- **Off and "not configured" look the same.** Steps 3 and 4 return one message.
- **Handle `nextStep`.** A client that always expects `accessToken` breaks on `clinician-invite`.
- **Projects created with `POST /v1/slim/project/child` start with registration off and no default patient AccessPolicy.**
- **Every error takes at least a second**, so a spinner is the right UI.

## Related [#related]

- [Email templates](/email-templates), for the welcome and invitation emails
- [Patient sign-in](/authentication/patient-login)
- [PATIENT_REGISTRATION_ENABLED](/settings-and-features/settings/patient-registration-enabled)
- [Set up your project](/authentication/project-setup)
