POST/transactional-api/update-patient-official-name

Update Patient Official Name

Sets the patient's official (legal) name. Changing this while the patient has an active NHS permanent registration sends an NHS GP Amendment message via NHAIS. User-restricted only.

Authorization: Bearer token (JWT). See Authentication.

Request

curl -L -X POST 'https://{tenantId}.api.england.medicus.health/transactional-api/update-patient-official-name' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -d '{
    "patientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "officialName": {
      "prefix": "Mrs",
      "givenName": "Jane",
      "middleNames": "Elizabeth",
      "familyName": "Doe",
      "suffix": ""
    }
  }'

Body parameters

Field	Type	Required	Description
patientId	string<uuid>	Yes	Medicus patient identifier.
officialName	object	Yes	Object with: prefix, givenName, middleNames, familyName, suffix.

Responses

200 Official name updated.

Response fields

Field	Type	Description
status	string

{
  "status": "ok"
}

400 Validation error.

5 possible code values

Code	Description	When
missing-patient-id	The patientId is required	patientId missing
invalid-patient-id	The patientId is not valid	patientId not a valid UUID
missing-given-name	The officialName is required, with at least givenName and familyName.	officialName is missing, or its givenName is missing
missing-family-name	The officialName is required, with at least givenName and familyName.	officialName.familyName is missing
patient-not-found	Patient not found for this patientId	patientId doesn't exist

Response fields

Field	Type	Description
errors[].code	string
errors[].description	string

{
  "errors": [
    {
      "code": "missing-patient-id",
      "description": "The patientId is required"
    }
  ]
}

403 The call is application-restricted rather than user-restricted.

Response fields

Field	Type	Description
errors[].code	string
errors[].description	string

{
  "errors": [
    {
      "code": "application-restricted-not-supported",
      "description": "This endpoint is only available to user-restricted callers."
    }
  ]
}