Developer documentation‎ > ‎HL7 API‎ > ‎

Identifiers & Matching

Overview

PKB supports 2 types of identifier in the HL7 API: national and local. A national identifier is an identifier that identifies a patient within a given country, such as an NHS number. A local identifier is an identifier which identifies a patient uniquely for a sender, but not outside that sender. An example would be a hospital number. A local identifier can be associated with either a PKB Organisation or a PKB Team.

See also the Identifiers section of our Data Model for more information.

Identifier Type Assignment

An HL7 identifier consists of several components. PKB is only interested in the following components:
  • [1] ID
  • [4] Assigning Authority
  • [5] Identifier Type Code
An identifier can appear in either PID-2 or PID-3. The field that the identifier appears in (or its position within the list of identifiers if PID-3), is not important to PKB.

We determine which type of identifier has been provided by matching the Assigning Authority (AA) and the Identifier Type Code (TC) to known types. To provide a national ID you must provide the AA and TC corresponding to the relevant identifier. These are given in the following section. To provide a local ID, you need to first agree with us what AA and TC values you use for each of your identifier types. We need to configure these for you before the IDs will be processed by our HL7 API.

Any supplied identifier that does not match a known type will be silently ignored.

National Identifiers

In order to send through a national ID, you need to supply the Assigning Authority and Identifier Type Code as detailed in the table below.

Identifier Name Country Assigning Authority Identifier Type Code Status Code
NHS Number * GB-ENG, GB-WLS NHS NH

In addition, note that the NHS number can optionally include a status code, as defined in the NHS Data Dictionary. If present, the status code is supplied with the identifier type code, in the format NH{status:XX} where XX is the status code. There must be no space between “NH” and the status code. Since the status code is optional, “NH” remains a valid identifier type code. For example: NH{status:01}

CHI Number *GB-SCTNHS ScotlandNH 
Health and Care Number *GB-NIRDHSSPSNH 
PPS NumberIEDSPNI 
SSNUSUSANI 
SINCACANI 
HKIDHKHKNI 
BSNNLNLNI 
KrankenversichertennummerDEDENH 
Civil IDKWKWNI 

* A note about NHS-Type Numbers. The following 3 National ID Types are drawn from the same numbering scheme, but with non-overlapping ranges. PKB considers them to be separate types. It is the responsibility of the sender to ensure the correct AA/TC values are sent.

  • CHI Number (Scotland): 010 101 0000 to 311 299 9999
  • Health and Care Number (Northern Ireland): 320 000 0010 to 399 999 9999
  • NHS Number (England and Wales): 400 000 0000 to 999 999 9999

Local Identifiers

You will need to agree with PKB what local identifiers you would like to send through.

Each PKB Organisation or PKB Team can be associated with multiple local identifier types, and each patient can be associated with multiple ID values for each local identifier type.

AA Wildcarding

A local ID type can have a wildcard for the Assigning Authority (but not the Type Code). If this is configured, then an HL7 identifier will be assigned to this type if the TC matches, regardless of the provided AA value.

Restrictions & Scope

The scope of AA/TC pairs for local IDs is the whole PKB Organisation. All AA/TC pairs for a PKB Organisation (and for all PKB Teams within that PKB Organisation) must be unique across the PKB Organisation.

In addition, a Type Code can only be used with a wildcarded Assigning Authority if that Type Code is not used by any other local ID within the PKB Organisation (or any PKB Teams within that PKB Organisation).

A local ID AA/TC pair must not match the AA/TC pair for any national ID.

The scope of a local ID is always the entire PKB Organisation which contains it. As such, a team-level HL7 connection can read and write local IDs of a type associated with another PKB Team (providing it is within the same PKB Organisation).

Matching

Once all the provided identifiers have been assigned to their corresponding types, PKB will attempt to match them to an existing medical record.

Hard Matching

Hard Matching refers to the process of identifying a medical record based on the values of the identifiers provided.

National and Local Identifiers are case sensitive.

Soft Matching

Soft Matching is an optional process allowing for stricter upstream system (LAB/PAS/etc.) data validation based on the following demographic fields. The more soft matched fields enabled the more stringent the upstream validation. If a message does not pass based on any of the enabled soft match criteria but does pass the hard match based on patient identifier the message will be placed in the HL7 review queue to be managed by the organization administrator.
  • Surname
  • Forename
    • Forename (full): The provided and known forename values are matched in their entirety, e.g. jo does not match joanne
    • Forename (short): The provided and known forename values are matched up to the length of the shorter of the two, e.g. jo does match joanne
    • Forename (initial): The provided and known forename values are matched just on the initial letter, e.g. jo does match janet
  • DOB
  • Gender
  • Postal Code

NHS Number Status Checking

Some messages cannot be soft-matched based on demographics.


  • When creating a new medical record there is no prior demographic information to match against.

  • When updating the demographic information on an existing medical record we must allow the message to change the existing demographic data, rather than match what is already stored.


Instead, PKB can optionally configure an interface to soft-match these messages based on the NHS number status. If this option is enabled, and an NHS number is provided, then PKB will check that the status is present and equal to “01” before creating or updating the medical record. If the check fails, then:


  • If the target medical record does not exist, PKB will ignore the NHS number and behave as if it had not been provided.

  • If the target medical record does exist, PKB will queue the message as needing manual review. A human must then manually confirm that the unverified demographic changes are correct.


In addition, if this option is enabled then an NHS number must be provided to update the demographics information of a medical record that already has an NHS number associated with it.

Auto Create

By default, medical records for new patients are created upon receipt of an A28 or A31 message only. PID segments for other message types that do not match a medical record will return an error. If you would like to disable this strict record checking, such that a new medical record is created whenever an unmatched PID is received (in any message) then we can configure this for you. However, you will still need to send an A28 or A31 to update the demographic details about each patient.

Workflow


The diagram below demonstrates our matching workflow.

Comments