Request File Elements

5 min

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	Field Values/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.	Value: 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	an15	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 Surescriptsindicating the receiver of the file. Note: S00000000000006 has been deprecated for Patient File Load.	The following IDs are used for Medication History for Populations (Panel and Prescription Notifications): S00000000000003 (Medication History for Populations) S00000000000005 (Medication History for Populations for Health Plans)
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 which can accept patient enrollment based on the RecordType value in the detail information.	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.	Example: 12
15	Data Source Type	an3	conditional	Field specifying the desired data sources (Claims and Dispensed Fills) to include in the response file. If left null, the default value is set to 0.	Values: FIL - Only Dispensed Fill data CLM - Only Claim data NULL - 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.	Example: 20240531
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.	Example: 20241201

Request Details (DTL) Elements

Field	Field Name	Data Type	Code	Comments	Field Values/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 – Prescription 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	ID for the organization/system that assigned the related patient ID	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 (Medication History for Populations - S00000000000003) conditional (Medication History for Populations 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	For PAT record types this field indicates the date in which the customer desires the patient be removed from monitoring in Prescription Notifications. If no end date is desired, leave this field empty. Note: The End Monitoring Date must be set beyond the current date. Prescription Notifications cannot be stopped retroactively.
18	Notifications Requested for this Patient	an1..1000	conditional	For the PAT file type, this field allows for the customization of which notifications the customer would like to receive for the specific patient. If this patient is to be monitored for a list of notifications that is shorter than the contracted list, include individual notifications requested in a comma separated list. Field is case insensitive. Recommendations: Leave this field empty to make it easy for contracting new notification types in the future without need for a Patient File Load reload. If enrolling for specific notification types using this field, you must also include PMAInfo in order to receive informational notifications (e.g., patient is not found).	Values: PMANewRx PMARefill PMANewPrescriber PMAControlledSubstance PMANoRefillsRemaining PMARefillNotPickedUp PMACashPayRx PMAMonitoredMedRx
19	Patient Primary Telephone	n10	conditional	Patient's primary telephone number.	Example: 5555551234

Request Trailer (TRL) Elements

Field	Field Name	Data Type	Code	Comments	Field Values/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.	Examples: • 1 • 2

Detailed Information for Unenrollment

This is an optional record and should only be used for mass unenrollment purposes.

Field	Field Name	Type	Code	Description	Example
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. Allowed value is 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. Please be aware that specific patients cannot be unenrolled using this process.	20231231