Panel Patient File Record Element Details

10 min

Data Element Requirements

Requirement Designation:

Code	Description
mandatory	The element must be used per the specification (e.g., XML schema validation). Note: The term mandatory applies to mandatory and required fields in the different standards. For example, FHIR uses the term required.
conditional	The element is to be used per the conditions specified.
optional	Some fields do not have specific conditions. Data should be sent if available.

Note: This guide includes data elements only where Surescripts has specific requirements or further explains the field usage.

Patient File Load Request Elements

Request Header (HDR) Elements

Note: Certain errors pertaining the Record Type and Transmission File Type fields could result the file not being processed, which would cause the response file to not be generated, preventing the visibility of resulting errors.

Field	Field Name	Data Type	Code	Comments	Values or Examples
0	Record Type	an3	mandatory	Assigns the following string of data to its desired action.	Value: HDR
1	Version	an3..5	mandatory	Indicates the version of Medication History for Populations.	3.0
2	Sender ID	an15	mandatory	A unique identification number assigned by Surescripts indicating the sender of the file.	Example: P00000000023456
3	Sender Password	an10	mandatory	The password to be utilized by the customer to access the Surescripts system.	Example: M94WJ7CW6H
4	Receiver ID	an1...15	mandatory	A unique identification number assigned by Surescripts indicating the receiver of the file.	Values: S00000000000003 - Panel Used for Medication History for Populations (Panel and Prescription Notifications) use cases except Health Plans S00000000000005 - Health Plans Used for Medication History for Populations (Panel and Prescription Notifications) use cases for Health Plans Note: S00000000000006 Patient File Load has been deprecated.
5	Transmission Control Number	an1..10	mandatory	A unique identifier defined by the sender used to map the Patient File Load to the Patient Response file. This field can contain numerical or alphabetical characters and must be unique to each file transmission.	Example: 1234567891
6	Transmission Date	Format: CCYYMMDD	mandatory	The date the file was transmitted to Surescripts.
7	Transmission Time	Format: HHMMSSDD	mandatory	The time the file was transmitted to Surescripts.
8	Transmission File Type	an1..4	mandatory	Identifier indicating the type of Patient Load File for Medication History for Population. Fixed Value: PMA	Value: PMA
9	No longer in use, field present but will remain null
10	Extract Date	Format: YYYYMMDD	mandatory	The date the file was created (extracted) from the source.	Example: 20240603
11	Usage Indicator	an1	mandatory	Indicates the environment where the transaction will take place.	Values: T = Test P = Production
12	Patient Population ID	an1..64	mandatory	A value assigned to a population by the customer that is provided in the patient file load. This field can contain numerical or alphabetical characters.	Example: HighRisk
13	No longer in use, field present but will remain null
14	Look Back Period in Months	n1...3	conditional	Configurable field specifying the number of months to look back from the request date. If left blank, the field defaults to 12 months. Notes: Request Start and End Date override Look Back period when both are provided. Not used for Prescription Notifications	Example: 12
15	Data Source Type	an3	conditional	Specifies which medication history data sources to include in the response. This element allows the requester to limit the response to claim data, dispensed fill data, or both. Notes: If this element is not populated (empty), both Claim and Dispensed Fill data are returned. Do not send the literal value NULL. To request both data sources, leave the element empty. This element is not used for Prescription Notifications.	Values: FIL - Only Dispensed Fill data CLM - Only Claim data (empty) - Claim and Dispensed Fill data
16	Request Start Date	Format: CCYYMMDD	conditional	The beginning date (UTC) for the desired history. May be left empty or customized to pull data a maximum of 12 months. The default value is set to 12 months from submission if left null. Note: Not used for Prescription Notifications	Example: 20250204
17	Request End Date	Format: CCYYMMDD	conditional	The end date (UTC) for the desired history. The default value is set to submission date if left null. Cannot contain a future date. Note: Not used for Prescription Notifications	Example: 20260204

Request Details (DTL) Elements

Field	Field Name	Data Type	Code	Comments	Values or Examples
0	Record Type	an3	mandatory	Assigns the following string of data to its desired action. Note: Patient file loads with PAT or PNM record types cannot be combined with UNR record types.	Values: PAT – Prescription Notifications and Panel enrollment PNM – Panel Management enrollment PMA – Patient Notification enrollment
1	Record Sequence Number	n1...10	mandatory	Unique number for the detail record in the received file where the first record begins with "1" and each subsequent record is incrementally increased by 1 as the file is processed.	Examples: • 1 • 2 • 3
2	Assigning authority	an1..64	mandatory	Unique ID for the organization/system that assigned the related patient ID. Assigning authority should be a GUIDGUID. Surescripts recommends representing assigning authority as an OIDOID.	Example: 1.3.44444.666.3.2.1
3	Patient ID	an1..35	mandatory	The patient specific unique identifier provided by the panel user.	Example: 593431
4	Last Name	an2..35	mandatory	The last name of the patient. This field must contain more than 2 characters.	Example: WAYNE
5	First Name	an2..35	mandatory	The first name of the patient. This field must contain more than 2 characters.	Example: TOM
6	Middle Name	an2..35	conditional	The middle name of the patient. Sent to aid in patient matching.	Example: J
7	Prefix	an1...10	conditional	The prefix for the patient. Sent to aid in patient matching.	Example: Mr.
8	Suffix	an1...20	conditional	The suffix for the patient. Sent to aid in patient matching.	Example: II
9	Address Line 1	an1...55	conditional	First line of the patient address without any C/O type information. Sent to aid in patient matching.	Example: 123 Street Avenue
10	Address Line 2	an1...55	conditional	Second line of the patient address without any C/O type information. Sent to aid in patient matching.	Example: Unit #41
11	City Name	an2...30	conditional	Patient city name. Sent to aid in patient matching.	Example: Jacksonville
12	State	an2...55	conditional	State in which the patient resides. Only United States addresses are supported. Note: Both state abbreviations and full state names are supported.	Examples: • Colorado • CO
13	Zip Code	an5..10	mandatory	Patient Zip or zip code must consist of five digits, an optional hyphen (-), and up to four additional digits. The first five characters must only consist of numbers.	Examples: • 55123 • 97116-2245 • 200607011
14	Date of Birth	Format: CCYYMMDD	mandatory	The date of birth for the patient.
15	Administrative Gender	an8	mandatory	The gender as reported by the patient.	Values: M – Male F – Female N – Non-binary U – Unknown
16	NPI	n10	mandatory (For treatment use cases - S00000000000003) conditional (For health plans - S00000000000005)	Individual or Organizational National Provider Identification (NPI) of the requester of the Medication History that is validated by Surescripts against the National Provider Identification file to verify that it exists. Note: A test NPI can be used in staging, as no NPPES validation is used during the testing process.	Example: 1234567893
17	End Monitoring Date	Format: CCYYMMDD	conditional	Indicates the date the customer wants the patient removed from monitoring in Prescription Notifications. If no end date is desired, leave this field empty. Note: The End Monitoring Date must be set to a date after the current date. Prescription Notifications cannot be stopped retroactively. Note: Used for Prescription Notifications only.
18	Notifications Requested for this Patient	an1..1000	conditional	Defines the notifications the customer wishes to receive for the patient. If this patient is to be monitored for a list of notifications that is shorter than the contracted list, include the individual notifications requested as a comma‑separated list. This field is case‑insensitive. Recommendation: Leave this field empty to simplify the addition of new notification types in the future without requiring a Patient File Load reload. Note: Used for Prescription Notifications only.	Values: PMANewRx PMARefill PMANewPrescriber PMAControlledSubstance PMANoRefillsRemaining PMARefillNotPickedUp PMACashPayRx PMAMonitoredMedRx PMAFirstFillNotPickedUp
19	Patient Primary Telephone	n10	optional	Patient's primary telephone number.	Example: 5555551234

Request Trailer (TRL) Elements

Field	Field Name	Data Type	Code	Comments	Values or Examples
0	Record Type	an3	mandatory	Assigns the following string of data to its desired action.	Value: TRL
1	Total Records	n1..10	mandatory	Summary of the total detail records submitted in the file	Example: 2

Request Patient Unenrollment

Field	Field Name	Data Type	Code	Comments	Values or Examples
0	Record Type	an3	mandatory	Identifies record type. Value: UNR = Unenroll patients Note: Patient file loads with this record type cannot be combined with PAT, PNM, or PMA record types.	UNR
1	Record Sequence Number	n1..10	mandatory	Number for this detail row in the file.	1
2	Product	an3	mandatory	Product Type. Fixed value: PMA	PMA
3	End Monitoring Date	dt8	mandatory	This is the date when all patients who are currently being monitored will be unenrolled from Prescription Notifications (Panel does not apply). This date must be set in the future from current date.	20281231

Patient File Response Elements

Validation Response Header (SHD) Elements

Field	Field Name	Data Type	Code	Comments	Values or Examples
0	Record Type	an3	mandatory	A single response that signifies the header row of the file	Value: SHD
1	Version	n3...5	mandatory	Indicates the version of Medication History for Populations.	3.0
2	Receiver ID	an3..30	mandatory	A unique identification number assigned by Surescripts indicating the receiver of the file.	Example: P00000000012345
3	Sender ID	an3..30	mandatory	A unique identification number assigned by Surescripts indicating the sender of the file.	Values: S00000000000003 - Panel S00000000000005 - Health Plans
4	Transaction Control Number	an1..36	mandatory	A unique identifier defined by the sender used to map the Patient File Load to the Patient Response file. This field will be a GUIDGUID in the response from Surescripts.	Example: ec622dd2-dab7-4945-bc2f-a9c0a78c64dd
5	Transaction Date	Format: CCYYMMDD	mandatory	The date the file was transmitted to the customer.	Example: 20241022 would represent October 22, 2024
6	Transaction Time	Format: HHMMSSDD	mandatory	The time the file was transmitted to customer.	Example: 14354587 would represent 14:35:45 and 87 hundredths of a second
7	Transaction File Type	an3	mandatory	Identifier indicating the type of Patient Load File which can accept patient enrollment based on the RecordType value in the detail information.	Value: PMA
8	Transmission Control Number Originating	an1..10	mandatory	Value that echo’s the Transmission Control Number sent in the patient file transmitted to Surescripts.	Example: 1234567891
9	Transmission Date- Originating	Format: CCYYMMDD	mandatory	Date Original Incoming File was created.	Example: 20241022 would represent October 22, 2024
10	Transmission Time- Originating	Format: HHMMSSDD	mandatory	Time Original Incoming File was created.	Example: 14354587 would represent 14:35:45 and 87 hundredths of a second
11	File Type	an1	mandatory	Indicates the environment where the transaction was routed.	Values: T – Test P – Production
12	Load Status	an2	mandatory	Codified value within the header response explaining the status of the file load. Note: If there is more than one error at the file level, there will be additional errors in detail records with a sequence of 1, null patient ID, and the header response code in the error code field.	Values: 01 – File loaded correctly. 02 – File loaded with errors and/or warnings. 03 – Failed to load file. No data was processed.
13	Load Status Description	an1..250	mandatory	Description of the status of the file load	Values: File loaded correctly. File loaded with errors and/or warnings. Failed to load file. No data was processed.

Validation Response Details (SDT) Elements

Field	Field Name	Data Type	Code	Comments	Values or Exmaples
0	Record Type	an3	mandatory	A value that signifies a validation error in the details row of the file.	Value: SDT
1	Record Sequence Number	n1...10	mandatory	Unique number for the detail record in the validation response file where the first record begins with "1" and each subsequent record is incrementally increased by 1 as the file is processed.	Example: 3
2	Source Record Sequence Number	n1...10	conditional	Record Sequence Number from the detail row on the request file. This is the value assigned by the sender of the file.	Example: 4
3	Assigning Authority	n1...64	conditional	ID from the request file for the organization/system that assigned the related patient ID.	Example: 1.3.44444.666.3.2.1
4	Patient ID	an1..35	conditional	The patient specific unique identifier provided by the panel user in the request file.	Example: 593431
5	Error Type	an1	mandatory	A single letter categorizing the severity of an error. Categories include: Warning (W) – Does not fail file or row. Error (E) – Fails the associated row, row is not processed. Fatal (F) – Fails entire file, nothing is processed.	Values: • W • E • F
6	Error Code	an10	mandatory	Codified value indicating the error found on this record.
7	Error Description	an1..250	conditional	Text describing the error found in this record.

Validation Response Trailer (STR) Elements

Field	Field Name	Data Type	Code	Comments	Field Values/Examples
0	Record Type	an3	mandatory	A single response that signifies the trailer (summary) row of the file.	Value: STR
1	Processed Record Count	n1...10	mandatory	Count of detail patient records processed in file. Note: Error Record Count + Loaded Record Count = Processed Record Count	Example: 100
2	Error Record Count	n1...10	conditional	Count of detail patient records that contained an error and did not load.	Example: 3
3	Loaded Record Count	n1...10	conditional	Count of detail patient records that were loaded for enrollment.	Example: 97
4	Total Error Count	n1...10	conditional	Number of errors listed in the Patient Response File. Note: A single input record could have one or more errors listed in the response file. Total Error Count will be > or = Error Record Count	Example: 7