POST/transactional-api/create-patient-record

Create Patient Record

Looks up the given NHS number in the NHS Personal Demographics Service and creates a Medicus patient record from the returned demographics. If a patient with this NHS number already exists, their existing Medicus ID is returned. Does not create a GP registration.

Authorization: Bearer token (JWT). See Authentication.

Request

curl -L -X POST 'https://{tenantId}.api.england.medicus.health/transactional-api/create-patient-record' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -d '{
    "nhsNumber": "9000000009"
  }'

Body parameters

Field	Type	Required	Description
nhsNumber	string	Yes	The 10-digit NHS number of the patient.

Responses

201 Patient created (or found) successfully.

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

400 Validation error.

3 possible code values

Code	Description	When
missing-nhs-number	The nhsNumber is required.	nhsNumber is missing or blank
invalid-nhs-number	nhsNumber must be a 10-digit number.	nhsNumber is not numeric and 10 characters long
invalid-nhs-number-check-digit	nhsNumber's check digit is invalid.	nhsNumber is the right shape but fails the NHS number check digit

{
  "errors": [
    {
      "code": "missing-nhs-number",
      "description": "The nhsNumber is required."
    }
  ]
}

422 The NHS number could not be resolved to a single patient.

2 possible code values

Code	Description	When
pds-record-not-found	No PDS record was found for this NHS number.	no PDS record exists for the supplied NHS number
multiple-patients-found	Multiple existing patients were found for this NHS number; this cannot be resolved automatically.	more than one existing Medicus patient is already linked to this NHS number

{
  "errors": [
    {
      "code": "pds-record-not-found",
      "description": "No PDS record was found for this NHS number."
    }
  ]
}