MPT data dictionary - deprecated - NHS England Digital

Overview

This page describes the data structure and fields required to find patients using the Master Patient Trace (MPT) service. This service is not available to new users.

For details of the PDS MESH service that replaces it, see Using the PDS MESH service with the MESH user interface.

MPT allows you to submit a file of partial patient information and get back the full information. MPT uses the Personal Demographics Service (PDS) to find patient details.

The key files are the 'request file' and the 'response file', both described here.

Request file format

Your trace request must be in the form of a comma separate value (CSV) file.

A file request is made up of a header record and one or more data records.

Request file name

File name is of the format: MPTREQ_CCYYMMDDHHMISS.csv

Where:

MPTREQ_ is fixed text
CCYYMMDDHHMISS is the file creation time stamp

Header record

This is the first row of the request file and contains the following fields. The header record is mandatory in each submitted file request.

Column name	Field length	Description
RequestrReference	21	File name in format of fixed text ‘MPTREQ_’ and request timestamp, for example MPTREQ_CCYYMMDDHHMISS
WorkFlowId	21	Use the value SPINE_MPTPHASE4_TRACE
Request timestamp	14	Timestamp of request file creation in format: CCYYMMDDHHMISS
Number of data records	numeric	The number of data records included in the file.

Data record

Each request file must contain at least one data record under the header record. There is only one mandatory field (UNIQUE REFERENCE), but providing data in as many fields as possible gives the best opportunity to match with the correct patient record on PDS.

The following table shows the data record column names along with the maximum length and description. Each column must be separated by a comma.

Column name

Maximum length

Description

UNIQUE REFERENCE

Any

Mandatory field. Client generated unique reference used as a record identifier to enable the sender to identify and correlate responses.

The following characters are not allowed:
'!', '$', '%', '&', '(', ')', '[', ']', '{','}', '=', ':', ';', '#', '~', '@', '|', '<', '>', '.', '?', '_', '\\', '£'.

NHS_NO

10

NHS number used to identify a person uniquely within the NHS in England and Wales.

FAMILY_NAME

40

Surname, or family name.

GIVEN_NAME

40

Forename, or given name.

OTHER_GIVEN_NAME

100

Other given, or middle, name.

GENDER

1

Gender (sex) of the person, values:
0 = Not Known
1 = Male
2 = Female
9 = Not Specified

DATE_OF_BIRTH

12

In one of the following formats:

full date and time (YYYYMMDDHHMM)
full date (YYYYMMDD)
year & month (YYYYMM)
year only (YYYY)

POSTCODE

8

Postcode of the person’s address.

For most effective matching, enter postcodes with the correct format including a space.

DATE_OF_DEATH

12

In one of the following formats:

full date and time (YYYYMMDDHHMM)
full date (YYYYMMDD)
year & month (YYYYMM)
year only (YYYY)

ADDRESS_LINE1

n/a

Unused, leave blank.

ADDRESS_LINE2

n/a

Unused, leave blank.

ADDRESS_LINE3

n/a

Unused, leave blank.

ADDRESS_LINE4

n/a

Unused, leave blank.

ADDRESS_LINE5

n/a

Unused, leave blank.

ADDRESS_DATE

8

Unused, leave blank.

GP_PRACTICE_CODE

8

GP practice code.

NHAIS_POSTING_ID

3

Unused, leave blank.

AS_AT_DATE

8

Unused, leave blank.

LOCAL_PATIENT_ID

n/a

Unused, leave blank.

INTERNAL_ID

n/a

Unused, leave blank.

TELEPHONE_NUMBER

n/a

Unused, leave blank.

MOBILE_NUMBER

n/a

Unused, leave blank.

EMAIL_ADDRESS

n/a

Unused, leave blank.

Sending the trace request to PDS

Create a new message and fill in the fields as follows:

for ‘Select Message Type’, choose ‘Master Patient Tracing Service (SPINE_MPTPHASE4_TRACE)'
for ‘To’, choose ‘INTERNAL SPINE - INTERNAL SPINE’
for ‘Attach a document’, select the CSV file for your trace request

Click the Submit button to send your trace request.

Response file

Response file name

The file name is of the format: RESP_MPTREQ_CCYYMMDDHHMISS_CCYYMMDDHHMISS.dat where:

RESP_ is fixed text
MPTREQ_CCYYMMDDHHMISS is the original request reference provided in the request file
CCYYMMDDHHMISS is the response file creation time stamp

Download the trace request response

To do this:

once you receive a reply in your MESH inbox, click on the download button next to the message to save the file to your local machine.
the response file is named RESP_ followed by the name of your original CSV trace request file.
you can rename the DAT file to a CSV file and import it into a spreadsheet for easy viewing.

For example, a single patient DAT response file looks like this:

Header record

The header record in the response contains fields described in the following table 3 including the maximum length.

Column name	Max length	Description
Response reference	21	The request reference provided in the request file – for example: MPTREQ_CCYYMMDDHHMISS
WorkFlowId	n/a	Fixed response value of SPINE_MPTPHASE4_TRACE.
Number of data records	Any	Number of data records included in the file. This is the number submitted in the request file or ‘0’ in the case of error.
File response code	2	A numeric code representing the outcome of processing the request. See the response code table for details.

Data record

The response file contains a data record for each record supplied in the request file.

Fields left blank in the request file are populated with demographic data in the response file, where it's available for that patient.

The following table shows the columns and their maximum length.

Column name	Maximum length	Description
UNIQUE REFERENCE	Any	Unique reference supplied in the request file. This is used as a record identifier to enable the sender to identify and correlate responses.
REQ_NHS_NUMBER	10	Requested NHS number. Populated with the value provided in the request file. The matched NHS number is provided in the column MATCHED _NHS_NO.
FAMILY_NAME	40	Surname, or family name.
GIVEN_NAME	40	Forename, or given name.
OTHER_GIVEN_NAME	100	Other given, or middle, name.
GENDER	1	Gender (sex) of the person, values: 0 = Not Known 1 = Male 2 = Female 9 = Not Specified
DATE_OF_BIRTH	12	In one of the following formats: full date and time (YYYYMMDDHHMM) full date (YYYYMMDD) year & month (YYYYMM) year only (YYYY)
DATE_OF_DEATH	12	In one of the following formats: full date and time (YYYYMMDDHHMM) full date (YYYYMMDD) year & month (YYYYMM) year only (YYYY)
ADDRESS_LINE1	Any	First line of a person’s usual address.
ADDRESS_LINE2	Any	Second line of a person’s usual address.
ADDRESS_LINE3	Any	Third line of a person’s usual address.
ADDRESS_LINE4	Any	Fourth line of a person’s usual address.
ADDRESS_LINE5	Any	Fifth line of a person’s usual address.
POSTCODE	8	Postcode of the person’s usual address.
GP_PRACTICE_CODE	8	Primary Care Provider GP practice code.
NHAIS_POSTING_ID	3	Unique code that represents the NHAIS box
AS_AT_DATE	8	Ignore this field.
LOCAL_PATIENT_ID	Any	Ignore this field.
INTERNAL_ID	n/a	Ignore this field.
TELEPHONE_NUMBER	Any	Person's telephone number.
MOBILE_NUMBER	Any	Person's mobile number.
EMAIL_ADDRESS	Any	Person's email address.
SENSITIVITY FLAG	1	The list below contains the potential response values: S: Sensitive Y: Legacy Sensitive I: Invalid N: Legacy Not Sensitive B: Legacy Under Business Investigation If the record has the value S or Y, all the location information for the patient is redacted. If the record has the value I or B, there are issues with the record, and it should not be used. If the record has the value N, the record is OK to be used.
MPS_ID	10	Ignore this field.
ERROR/SUCCESS_CODE	2	The code corresponding to this record. See the person level response code table for details.
MATCHED _NHS_NO	10	This field needs to be checked for one of the values below. If there is a match with the values below, the record has not been successfully matched. Any other number indicates a match. 0000000000: No match was found 9999999999: Multiple matches were found. <blank>: Not enough fields provided for the trace.
MATCHED_ALGORITHM_INDICATOR	1	This will be one of the following values: 0: No Match 1: Cross Check 3: Alphanumeric 4: Algorithmic
MATCHED_CONFIDENCE_PERCENTAGE	3	Total % score (0 or 100% for cross check, simple and alphanumeric, weighted, and aggregated average for algorithmic). Note: for most purposes, if the percentage is less than 100 the record needs to be checked manually using local processes. Individual use cases may differ and can use confidence percentages at less than 100. The 100% score is dependent on the number of input fields. If only 3 fields (such as Family, DoB and GENDER) are provided as an input, then it is suggested that the percentages below are used.
Algorithmic_Trace columns	n/a	The following column names are all prefixed with “Algorithmic_Trace”
FAMILY_NAME_score_%	3	Calculated % score % / 0 if no matches or not performed
GIVEN_NAME_score_%	3	Calculated % score % / 0 if no matches or not performed
DoB_score_%	3	Calculated % score % / 0 if no matches or not performed
GENDER_score_%	3	Calculated % score % / 0 if no matches or not performed
POSTCODE_score_%	3	Calculated % score % / 0 if no matches or not performed

Response codes

Header response codes

These are the response codes that can be generated at a file level in the header record of the response file in the “File Response Code” field.

Error constant	Error code	Description
SUCCESS	0	Successfully processed, but the record may or may not have been found.
PARSE_ERROR	1	Input could not be parsed or is invalid, for example: The header line has empty fields a trace request line is blank a trace request line cannot be decoded (example: unsupported character set)
INVALID_REQUEST_REFERENCE	2	The request reference in the header line does not match the format: MPTREQ_<14 DIGITS>
INVALID_WORKFLOW_ID	3	The workflow ID in the header line does not exactly match one of: SPINE_MPT_TRACE SPINE_MPTPHASE3_TRACE SPINE_MPTPHASE4_TRACE
DATA_RECORD_COUNT_MISMATCH	4	The number of trace request lines does not match the count in the header line.
UNEXPECTED_ERROR	5	Internal error - contact the National Service Desk, with details (date, time, filename) for investigation.
MAXIMUM_RECORDS_EXCEEDED	6	Number of trace request lines exceeds current maximum allowed (500,000 lines).
FILENAME_REFERENCE_MISMATCH	7	The file name in the header line does not match the input file name.
UNIQUE_REFERENCE_ERROR	8	Deprecated
INVALID_TIMESTAMP	9	The header line timestamp must be in the format YYYYMMDDHHMMSS.
REQUIRED_FIELD	10	A required trace request line field is empty – currently the only required field is UNIQUE_REFERENCE.
FIELD_LENGTH_EXCEEDED	11	A field length has been exceeded.
INVALID_GENDER_VALUES	12	Invalid value in request file.
INVALID_FIELD_FORMAT	13	Invalid field value format in a trace request line: dates must match the format: YYYYMMDD or YYYYMMDDHHMMSS (not DDMMYYYY and not MMDDYYYY) gender code must be a digit. NHS number must be 10 digits only (no spaces)
DATASTORE_ERROR	14	Internal error - contact the National Service Desk, with details (date, time, filename) for investigation.
NO_TRACE_PERFORMED	15	The minimum criteria for a trace were not met.
NOT_ENOUGH_FIELDS_PROVIDED	16	Not enough fields provided for either a header line or trace request line -enough comma delimiters must be provided, even if the fields are empty.
NUMBER_OF_FIELDS_GRE-ATER_THAN_ALLOWED	17	Too many fields provided for a header line or trace request line - comma delimiters must not exceed the required number of fields.

Person level response codes

This table shows the response codes that can be generated at a person level in the response file in the “ERROR/SUCCESS_CODE” field.

Response constant	Error or success code	Description
SUCCESS	00	A match is found
SUCCESS_SUPERCEDED	90	When a record is matched by cross check trace but has a superseding record, the details for the superseding record are returned. (A superseding record is a new PDS record, with a new NHS number which replaces an old PDS record.)
INVALID	91	Record tracing completed successfully, and a match was found, but the record has confidentiality status set to 'I' (invalid). For invalid records all details of the patient are suppressed, including the NHS number, so the response looks like the following: 02403456-031f-11e7-a926-080027a2de00,9991112758,,,,,,,,,,,,,,,,91,0000000000,1,0,0,0,0,0, where 02403456-031f-11e7-a926-080027a2de00 is the unique reference.
SENSITIVE	92	When a record is marked as sensitive, location sensitive information is not returned in queries. This includes address, GP practice identifier, contact details (phone, email) and related person details. Can be used by any NHS patient who feels that their location details should not be accessible by the NHS, or in other situations where vulnerable NHS patients request restricted access. Access restrictions can be requested by the patient or agencies such as social services, parole boards, probation services, or the police.
NOT_ENOUGH_DATA	96	There are multiple exact matches. Too little data has been provided to provide a meaningful match, so it's not possible to distinguish between the possible matches. For example, John Smith, male where multiple people have the same date of birth, but no address or NHS number was provided. MPT generates response code 96 when top two records have the same score of 100 percent and either date of birth or postcode is unavailable in the request message.
MULTIPLE_CLOSE_MATCHES	97	There are multiple matches with very close match scores and no meaningful way to distinguish them apart.
NOT_FOUND	98	There is no match for the combination of data in the input
LEGACY_UNDER_BUSINESS_INVESTIGATION	95	n/a