POST/transactional-api/match-patient

Match Patient

Resolves a single patient from supplied demographics. Provide one of: NHS number; NHS number plus demographics (date of birth, family name, postcode) to verify; or date of birth plus given name and family name. Returns the matched patientId only when exactly one record matches.

Authorization: Bearer token (JWT). See Authentication.

Request

curl -L -X POST 'https://{tenantId}.api.england.medicus.health/transactional-api/match-patient' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -d '{
    "nhsNumber": "9990000018",
    "dateOfBirth": "1990-05-12",
    "givenName": "Jane",
    "familyName": "Smith",
    "postcode": "LS1 4AB"
  }'

Body parameters

Field	Type	Required	Description
nhsNumber	string (nullable)	No	NHS number. When supplied alone, matches on NHS number; combine with demographics to verify.
dateOfBirth	string<date> (nullable)	No	Date of birth (YYYY-MM-DD).
givenName	string (nullable)	No	Given (first) name. Required for a demographics-only match.
familyName	string (nullable)	No	Family (last) name.
postcode	string (nullable)	No	Postcode, used to verify an NHS-number match.

Responses

200 Matched patient.

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

400 Unable to match.

4 possible code values

Code	Description	When
invalid-parameters	Must specify either NHS Number, NHS Number + demographics, or DOB + Given Name + Family Name	none of the supported parameter combinations were supplied
no-records-found	No records found for the NHS Number.	no patient matches the supplied NHS number, or DOB + given name + family name
multiple-records-found	Multiple patients exist for the NHS Number.	more than one patient matches the supplied NHS number, or DOB + given name + family name
unable-to-match-demographics	Unable to match demographics specified.	NHS number matched, but supplied dateOfBirth/familyName/postcode don't match that patient

{
  "errors": [
    {
      "code": "invalid-parameters",
      "description": "Must specify either NHS Number, NHS Number + demographics, or DOB + Given Name + Family Name"
    }
  ]
}