# Update an existing patient

Updates an existing patient record for a practice.

Endpoint: PATCH /patients/{id}
Version: 2026-01-01
Security: oauth2

## Security:

  - `oauth2` (unknown)
    oauth2 scopes: patient:write

## Path parameters:

  - `id` (string, required)
    Resource identifier to filter/find.

## Header parameters:

  - `X-Practice-Id` (string, required)
    UUID of the **practice** in whose context the request is executed. The API
uses this to resolve data the caller is permitted to access for that practice.

## Request body:

  - `application/json` (unknown)
    Fields to update on the patient. Omitted members are left unchanged.

## Request fields (application/json):

  - `first_name` (string)
    New given (first) name when updating.
    Example: Jane

  - `last_name` (string)
    New family (last) name when updating.
    Example: Doe

  - `date_of_birth` (string)
    New date of birth in ISO 8601 format (`YYYY-MM-DD`).
    Example: 1990-04-12

  - `ethnicity` (string)
    NHS ethnicity code for the patient, expressed as a two-digit zero-padded string
(for example `"01"`). Ethnicity is collected for UK practices that support patient
ethnicity (England, Wales, Northern Ireland, Channel Islands, and Isle of Man).
**Post–April 2026 codes** (England and Wales practices with NHS contract reform)
- `01` — White: English or Welsh or Scottish or Northern Irish or British
- `02` — White: Irish
- `03` — White: Any other White background
- `04` — Mixed multiple ethnic groups: White and Black Caribbean
- `05` — Mixed multiple ethnic groups: White and Black African
- `06` — Mixed multiple ethnic groups: White and Asian
- `07` — Mixed multiple ethnic groups: Any other Mixed or Multiple ethnic background
- `08` — Asian or Asian British: Indian
- `09` — Asian or Asian British: Pakistani
- `10` — Asian or Asian British: Bangladeshi
- `11` — Asian or Asian British: Any other Asian background
- `12` — Black or African or Caribbean or Black British: Caribbean
- `13` — Black or African or Caribbean or Black British: African
- `14` — Black or African or Caribbean or Black British: Other Black or African or Caribbean background
- `15` — Asian or Asian British: Chinese
- `16` — Other Ethnic Group: Any other Ethnic Group
- `17` — White: Gypsy or Irish Traveller
- `18` — Other Ethnic Group: Arab
- `97` — Other: Ethnicity Not Stated
- `98` — Other: Patient Ethnicity Unknown
- `99` — Other: Patient declined
    Enum: "01", "02", "03", "04", "05", "06", "07", "08", "09", "10", "11", "12", "13", "14", "15", "16", "17", "18", "97", "98", "99"

  - `site_id` (string)
    New default site (location) for the patient when changing association.
    Example: 7c9e6679-7425-40de-944b-e07fc1f90ae7

  - `payment_plan_id` (string)
    New payment plan identifier when reassigning the patient's plan.
    Example: 6ba7b810-9dad-11d1-80b4-00c04fd430c8

  - `title` (string)
    The different patient titles supported by Dentally.
    Enum: "Mr", "Mrs", "Miss", "Ms", "Dr", "Master", "Prof", "Hon", "Rev", "Sir", "Lady", "Lord", "Earl", "Judge", "Dame"

  - `biological_sex` (string)
    Maps to the patient `gender` field when updating.
    Enum: "male", "female"

  - `email_address` (string)
    Primary email address for contact.
    Example: jane.doe@example.com

  - `address` (object)
    Physical mailing or street address for a location. Field meanings depend on the
country or region (for example, what appears in `administrative_area` in one
country may differ from another). Every field may be `null` if it has not been
supplied; the object is still returned so clients can rely on a stable shape.
When provided, **fully replaces** the patient's stored address: each field is set to the value sent.
For **update** operations, the address is replacing the
previous value for all fields. Omit `address` entirely to leave the stored address unchanged.

  - `address.address_line_1` (string)
    Primary street line (building number, street name, or equivalent).
    Example: 42 High Street

  - `address.address_line_2` (string)
    Secondary street line (flat, suite, district, or equivalent), if applicable.
    Example: Suite 2

  - `address.address_line_3` (string)
    Third address line. Meaning varies by country: in some regions (for example Australia and New Zealand) this line typically holds **suburb**; elsewhere it may be any extra line needed after `address_line_1` and `address_line_2`.
    Example: Suburbia

  - `address.locality` (string)
    City, town, or other local place name, as used in that country.
    Example: London

  - `address.administrative_area` (string)
    First-level subdivision when applicable for that country (for example state, province, county, or region—whichever is conventional for that address).
    Example: Greater London

  - `address.postal_code` (string)
    Postal or ZIP code for that country, in the format stored for the address (not normalised to a single global format).
    Example: EC1A 1BB

  - `phones` (array)
    Contact numbers (`phone_type`, `phone_number`, and `phone_country`). Each `phone_type` maps to home, work, or mobile on the patient record.

  - `phones.phone_type` (string, required)
    Which patient phone slot this row maps to in Dentally.
    Enum: "home", "mobile", "work"

  - `phones.phone_number` (string)
    Raw number as stored for the practice (not necessarily E.164).
    Example: 01234567890

  - `phones.phone_country` (string)
    ISO-style country code for interpreting `phone_number`, when set.
    Example: NZ

  - `phones.phone_number_normalized` (string)
    Normalised representation (for example E.164) when available.
    Example: +641234567890

## Response 200:

  - `200` (unknown)
    Response after updating a patient (`200 OK`). The body reflects the patient state after the applied changes.

## Response 200 fields (application/json):

  - `data` (any, required)
    The updated patient record.

## Response 400:

  - `400` (unknown)
    Malformed Request ([ProblemDetails](https://tools.ietf.org/html/rfc7807))

## Response 400 fields (application/problem+json):

  - `type` (string)
    A URI reference [[RFC3986](https://tools.ietf.org/html/rfc3986)] that
identifies the problem type. It should provide human-readable
documentation for the problem type. When this member is not present, its
value is assumed to be "about:blank".
    Example: https://httpstatuses.io/400

  - `title` (string)
    A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
    Example: Bad Request

  - `status` (integer)
    The HTTP status code.
    Example: 400

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem.
    Example: Missing required field 'address'

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if de-referenced.
    Example: /v2/sites

## Response 401:

  - `401` (unknown)
    Unauthorized - Provide proof of identity ([ProblemDetails](https://tools.ietf.org/html/rfc7807))

## Response 401 fields (application/problem+json):

  - `type` (string)
    A URI reference [[RFC3986](https://tools.ietf.org/html/rfc3986)] that
identifies the problem type. It should provide human-readable
documentation for the problem type. When this member is not present, its
value is assumed to be "about:blank".
    Example: https://httpstatuses.io/400

  - `title` (string)
    A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
    Example: Bad Request

  - `status` (integer)
    The HTTP status code.
    Example: 400

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem.
    Example: Missing required field 'address'

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if de-referenced.
    Example: /v2/sites

## Response 404:

  - `404` (unknown)
    Not Found - Could not find a matching entity ([ProblemDetails](https://tools.ietf.org/html/rfc7807))

## Response 404 fields (application/problem+json):

  - `type` (string)
    A URI reference [[RFC3986](https://tools.ietf.org/html/rfc3986)] that
identifies the problem type. It should provide human-readable
documentation for the problem type. When this member is not present, its
value is assumed to be "about:blank".
    Example: https://httpstatuses.io/400

  - `title` (string)
    A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
    Example: Bad Request

  - `status` (integer)
    The HTTP status code.
    Example: 400

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem.
    Example: Missing required field 'address'

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if de-referenced.
    Example: /v2/sites

## Response 4XX:

  - `4XX` (unknown)
    User Error ([ProblemDetails](https://tools.ietf.org/html/rfc7807))

## Response 4XX fields (application/problem+json):

  - `type` (string)
    A URI reference [[RFC3986](https://tools.ietf.org/html/rfc3986)] that
identifies the problem type. It should provide human-readable
documentation for the problem type. When this member is not present, its
value is assumed to be "about:blank".
    Example: https://httpstatuses.io/400

  - `title` (string)
    A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
    Example: Bad Request

  - `status` (integer)
    The HTTP status code.
    Example: 400

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem.
    Example: Missing required field 'address'

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if de-referenced.
    Example: /v2/sites

## Response 5XX:

  - `5XX` (unknown)
    Server Error ([ProblemDetails](https://tools.ietf.org/html/rfc7807))

## Response 5XX fields (application/problem+json):

  - `type` (string)
    A URI reference [[RFC3986](https://tools.ietf.org/html/rfc3986)] that
identifies the problem type. It should provide human-readable
documentation for the problem type. When this member is not present, its
value is assumed to be "about:blank".
    Example: https://httpstatuses.io/400

  - `title` (string)
    A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
    Example: Bad Request

  - `status` (integer)
    The HTTP status code.
    Example: 400

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem.
    Example: Missing required field 'address'

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if de-referenced.
    Example: /v2/sites

## Response 200 examples:

  - `Single patient` (unknown)
    Wrapper returned by get, create, or update patient.

## Response 400 examples:

  - `Malformed or invalid request` (unknown)
    RFC 7807 problem details when validation fails (e.g. missing required field).

## Response 401 examples:

  - `Missing or invalid credentials` (unknown)
    RFC 7807 problem details when the caller is not authenticated.

## Response 404 examples:

  - `Resource not found` (unknown)
    RFC 7807 problem details when no resource matches the given identifier.

## Response 4XX examples:

  - `Generic client error response` (unknown)
    RFC 7807 problem details for a generic client error (e.g. conflict, unsupported media type).

## Response 5XX examples:

  - `Unexpected server error` (unknown)
    RFC 7807 problem details for an internal failure.