Response File Elements

6 min

Validation Response Header (SDH) Elements

Field	Field Name	Code	Comments	Field Values/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. Value: 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 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)
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 GUID 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	Field Values/Examples
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.	Examples: • 1 • 2 • 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.	Examples: • 1 • 2 • 3
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

Panel Management Response Header (HDR) Elements

Field	Field Name	Data Type	Code	Comments	Field Values/Examples
0	Record Type	an3	mandatory	Value signifying that the following string is a part of the header.	Value: HDR
1	Version	an1...5	mandatory	Indicates the version of Medication History for Populations.	Value: 3.0
2	Receiver ID	an15	mandatory	A unique identification number assigned by Surescripts indicating the receiver of the file.	Example: P00000000023456
3	Sender ID	an15	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)
4	Patient Population ID	an1..35	mandatory	A value assigned to a population by the customer provided in the patient file load.	Example: HighRisk
5	Transmission 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 can contain numerical or alphabetical characters and must be unique to each file transmission.	1234567891
6	Sent Time	Format: CCYYMMDD THHMMSS	mandatory	Identifies the time the response is sent to the sFTP.	For example, if the sent time is October 22, 2024, at 14:35:45, it would be written as: 20241022T143545.

Panel Management Response Details (DTL) Elements

Field	Field Name	Data Type	Code	Comments	Field Values/Examples
0	Record Type	an3	mandatory	Signifies that the following string of data is a detail record.	Value: DTL
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	MessageID	an1..35	mandatory	Unique Message ID for the RxHistoryResponse. Used as a reference for troubleshooting the medication history transaction.	Example: 12345678:12345543:1234567603128
3	Sent Time	Format CCYYMMDD THHMMSSNNZ	mandatory	Time that the file was generated by Surescripts	Examples: 2024-02-06T05:08:05 2024-07-14T13:13:09.679Z
4	Status	an1..35	mandatory	Approval response from data suppliers.	Value: Approved
5	Note	an..210	optional	Details added to the record to relay specific information.	Values: Although a patient was found, no medications were returned from partners. Not all medication history sources were accessible at this time. A processing error occurred. No medication history was returned. Although a patient record was found, no medications were available. Patient not found.
Requesting Prescriber Details
6	Prescriber NPI	an10	mandatory	The organizational or individual National Provider Identification (NPI) number of the prescriber/provider associated to the patient included in the file load from Panel user that is validated against the NPPES registry and mapped to the outgoing medication history request to data suppliers.	Example: 1234567891
7	Prescriber Name	an1..35	mandatory	The organization name or prescriber last name of NPI included in the file load.	Example: HEALTH AND HOSPITALS CORP
Patient Details
8	Patient ID	an1..35	mandatory	The patient specific unique identifier provided by the panel user.	Example: 593431
9	Patient Last Name	an2..35	mandatory	The last name of the patient. This field must contain more than 2 characters.	Example: WAYNE
10	Patient First Name	an2..35	mandatory	The first name of the patient. This field must contain more than 2 characters.	Example: TOM
11	Patient Date of Birth	Format: CCYYMMDD	mandatory	The date of birth for the patient.	Example: 19841024
12	Patient Administrative Gender	an1	mandatory	The gender as reported by the patient.	Values: M - Male F – Female N – non-binary U – Unknown
13	Patient Zip Code	an1..15	mandatory	The patients 5- or 9-digit zip code without punctuation	Examples: 60459 604591258
Request Details
14	Start Date	Format: CCYYMMDD	mandatory	The beginning date for the desired history defined in the Patient File Load header.	20240817
15	End Date	Format: CCYYMMDD	mandatory	The end date for the desired history defined in the Patient File Load header (e.g., today’s date).	20240818
16	Consent	an1	mandatory	When marked 'Y' consent has been given by the patient for the customer to receive their medication history.	Value: Y - Yes
Medication Details
17	Drug Description	an1..105	optional	Standardized drug name including strength and form from a Surescripts approved drug compendium.	Example: ATORVASTATIN 10MG TABLETS
18	Product Code	an..35	optional	Value used in conjunction with Product Code Qualifier to identify the product dispensed.	Example: 55111012105
19	Product Code Qualifier	an..5	optional	Codified value used to indicate the type of data submitted in the product code.	Values: ND - Code designating the use of the National Drug Code (NDC), which identifies the labeler/manufacturer, product, and package size of the drug. DI - Code designating the use of a Unique Device Identifier (UDI) which identifies the specific version or model of a device and the labeler of that device. UP - Code designating the use of the universal product code (UPC) defining then manufacturer and specific description of the product.
20	Strength Value	an..70	optional	The strength and strength unit of measure associated with the prescribed product.	Example: 100 MG
21	Drug Database Code	an..35	optional	Value used in conjunction with Drug Database Code Qualifier relaying the drug concept.	Example: 58160034100320
22	Drug Database Code Qualifier	an..5	optional	Codified value used to indicate the code set used to provide the Drug DB Code.	Values: SCD – Code designating the use of RxNorm semantic clinical drug, representing the ingredient plus strength and dose form. BD - Code designating the use of semantic branded drug, representing the ingredient, strength, and dose form plus the branded name. BPCK - Code designating the use of RxNorm branded package, representing the branded drug delivery device. GPCK - Code designating the use of RxNorm generic package, representing the generic drug delivery device.
23	No longer in use, field present but will remain null.
24	No longer in use, field present but will remain null.
25	Strength Form Code	an..15	optional	Codified value that qualifies the form of the dispensed product. Codes can be found at: https://evs.nci.nih.gov/ftp1/NCPDP/About.html	Example: C42946
26	Strength Unit of Measure	an..15	optional	Codified value representing the measurable unit in which the strength is measured. Codes can be found at: https://evs.nci.nih.gov/ftp1/NCPDP/About.html	Example: C28253
27	DEA Schedule	an..15	optional	Codified value designating the substance schedule as defined by the Drug Enforcement Administration (DEA).	Values: C38046 – Unspecified C48672 – Schedule I C48675 – Schedule II C48676 – Schedule III C48677 – Schedule IV C48679 – Schedule V
28	Quantity Dispensed	an..15	optional	The total quantity of a single prescription filled e.g. the count of tablets or number of grams.	Example: 90
29	Code List Qualifier	an..15	optional	Codified value qualifying the quantity	Values: 38 = Original Qty 40 = Remaining Qty 87 = Quantity Received QS = Quantity Sufficient (Long-Term Care only)
30	Unit Source Code	an..15	optional	AC Code identifying the source organization.	Value: AC = Potency Unit Code
31	Quantity Unit of Measure	an..15	optional	Codified value that represents the measurable unit in which the quantity to dispense is counted (e.g. tablets, capsules, milliliters, etc.). Codes can be found at: https://evs.nci.nih.gov/ftp1/NCPDP/About.html	Example: C48480
32	Days Supply	an..35	optional	Estimated number of days the prescription will last	Example: 90
33	Directions	an..1000	optional	SigText contains completely free text directions with no corresponding codified content.	Example: TAKE 1 TABLET BY MOUTH DAILY
34	Refills Remaining	an..35	optional	The number of refills remaining in the prescription.	Example: 3
35	No longer in use, field present but will remain null.
36	Substitutions	an..15	optional	Code indicating the prescriber's instructions regarding generic or interchangeable biosimilar substitution:	Values: 0 = No product selection indicated 1 = Substitution not allowed by prescriber
37	Date Written	Format: CCYYMMDD	optional	Date or date and time the prescription was issued.
38	Last Filled Date	Format: CCYYMMDD	optional	Date or date and time of the most recent fill.
39	Sold Date	Format: CCYYMMDD	optional	Sold Date is also referred to as Date Picked Up. This is the date that the prescription was picked up at the pharmacy/delivered to the patient.
40	No longer in use, field present but will remain null.
41	Prior Authorization Number	an..35	optional	Prior Authorization number assigned by PBM/payer.	Example: 1469123
Dispensing Pharmacy Details
42	NCPDP ID	an..35	optional	The unique NCPDP-assigned national provider identification number that identifies the pharmacy where the prescription was dispensed.	Example: 1469123
43	Pharmacy NPI	an..35	optional	The organizational National Provider Identification (NPI) number of the pharmacy that has dispensed the prescription.	Example: 1265666666
44	Store Number	an..70	optional	The name of the pharmacy where the medication was dispensed to the patient.	Example: Walgreens
45	Pharmacy Address line 1	an..35	optional	Address line 1 of the dispensing pharmacy.	Example: 1525 N Main Pkwy
46	Pharmacy Address Line 2	an..35	optional	Address line 2 of the dispensing pharmacy.	Example: Unit A
47	Pharmacy City	an..40	optional	The city where the dispensing pharmacy is located.	Example: Bloomington
48	Pharmacy State	an..15	optional	The State where the dispensing pharmacy is located.	Example: IL
49	Pharmacy Zip Code	an..15	optional	The postal code where the dispensing pharmacy is located.	Example: 60459 604591258
50	Pharmacy Phone Number	an..80	optional	The phone number of the dispensing pharmacy.	Example: 5555555555
51	Pharmacy Fax Number	an..80	optional	The fax number of the dispensing pharmacy.	Example: 7777777777
Prescriber Details
52	Prescriber NPI	an..35	optional	Individual or Organizational National Provider Identification (NPI) of provider responsible for the prescription.	Example: 1234567891
53	Prescriber DEA Number	an..35	optional	The Drug Enforcement Administration (DEA) assigned number of the provider prescribing controlled pharmaceutical prescriptions.	Example: FG1211119
54	Prescriber State License Number	an..35	optional	The number assigned and required by a State Board or other State/Territory regulatory agency that uniquely identifies the licensed individual responsible for the prescription.	Example: 201106119
55	Prescriber Last Name	an..35	optional	The last name of the prescriber responsible for the prescription.	Example: BERGER
56	Prescriber Middle Name	an..35	optional	Middle name of the prescriber responsible for the prescription.	Example: JAMES
57	Prescriber First Name	an..35	optional	First name of the prescriber responsible for the prescription.	Example: ROBERT
58	Prescriber Prefix	an..10	optional	Name prefix of the prescriber responsible for the prescription.	Example: Dr.
59	Prescriber Suffix	an..10	optional	Name suffix of the prescriber responsible for the prescription.	Example: II
60	Prescriber Address line 1	an..40	optional	Address line 1 of the prescriber responsible for the prescription.	Example: 1234 WESTAVE
61	Prescriber Address line 2	an..40	optional	Address line 2 of the prescriber responsible for the prescription.	Example: STE E
62	Prescriber City	an..15	optional	The city where the prescriber responsible for the prescription is located.	Example: CHICAGO
63	Prescriber State	an..15	optional	The state where the prescriber responsible for the prescription is located.	Example: IL
64	Prescriber Zip Code	an..15	optional	The zip code where the prescriber responsible for the prescription is located.	Examples: 60459 604591258
65	No longer in use, field present but will remain null.
66	Prescriber Phone Number	an1..80	optional	Ten-digit phone number of the prescriber responsible for the prescription without punctuation.	Example: 5555555555
67	Prescriber Fax Number	an1..80	optional	Ten-digit fax number of the prescriber responsible for the prescription without punctuation.	Example: 7777777777
Data Source Details
68	History Source Qualifier	an..3	optional	Indicates the data source type of the medication record.	Values: Payer = PBM/Payer Claims data Pharmacy = Pharmacy dispensed fill
69	Fill Number	n..2	optional	The code indicating whether the prescription is an original or a refill.	Values: 00 = Initial fill 01= First refill 02 = Second refill, etc. Allowed values 00 thru 99
70	Prescription Number	an..35	optional	Prescription Number assigned to medication history record.	Example: 1515320
71	Source Description	an..35	optional	Name of dispensing Pharmacy or PBM/Payer providing the medication record.	Example: Walgreens
72	Reference ID Value	an..35	optional	For pharmacy dispensed fill records (P2) this field will contain the NCPDP ID. For claims records (PY) this field will contain the Payer Participant ID.	P2 Examples: 4222154 PY Example: P00000000012345
73	Reference ID Qualifier	an..2	optional	Codified value indicating that the Reference ID Value is representative of the NCPDP ID.	Value: D3
74	Electronic RX Reference Number	an1..35	conditional	Electronic Prescription Reference Number assigned by the pharmacy system. Used to provide an audit trail for electronic prescriptions.	Example: 3971342601962144678
75	Electronic Prescription Order Number	an1..35	conditional	This is the Prescription Order Number on the NewRx created by the prescribing system. When this field is populated, the Electronic Rx Ref Number must also be populated.	Example: 3558474261
76	Patient Primary Phone Number	n10	conditional	Phone number of the patient.	Example: 9995551212
77	PlanCode	n2	conditional	Codified value indicating the type of payment plan utilized by the patient.	Type of payment plan. Values: 01 = Private Pay 02 = Medicaid 03 = Medicare 04 = Commercial PBM Insurance 05 = Major Medical 06 = Workers' Compensation
78	PaymentCode	n2	conditional	Codified value indicating the type of payment received for the prescription fill as recorded by a state Prescription Drug Monitoring Program (PDMP).	Values: 01 = Private Pay (Cash, Charge, Credit Card) 02 = Medicaid 03 = Medicare 04 = Commercial Insurance 05 = Military Installations and VA 06 = Workers' Compensation 07 = Indian Nations 99 = Other
79	BIN	n1..6	conditional	Plan network ID used to identify how a prescription drug will be reimbursed (plan information).	Example: 020107
80	PCN	an1..10	conditional	Plan network ID used to route pharmacy reimbursements (plan information).	Example: 01410000
81	GroupID	an1..35	conditional	ID assigned to the cardholder group or employer group.	Example: RX1011
82	CardholderNumber	an1..35	conditional	Insurance ID assigned to the cardholder or identification number used by the plan.	Example: John H. Doe
83	SexAssignedAtBirth	an1	optional	The label assigned at birth based on medical factors, including hormones, chromosomes and physical characteristics.	Values: M – Male F – Female U – Unknown I – Intersex
84	DiagnosisDetails	an0..15	optional	Code identifying the diagnosis of the patient.	Example: E109
85	NDC	an40	optional	Unique 10-digit number that identifies the medication based on manufacturer, product, and package size.	Example: 6539285415
86	Expandable fields for future flat file updates.			Over time, Surescripts will continue to add new values to the end of the record. It is important that the software consuming this file is designed to ignore new values until they are ready to be imported. This will allow the additional fields to be included at your convenience. As fields are added, this implementation guide will be updated to provide all of the necessary details for consuming the newly available records.

Panel Management Response Trailer (TRL) Elements

Field	Field Name	Type	Code	Description	Example
0	Record Type	an3	mandatory	Signifies that the following string of data is part of the trailer (summary) record.	TRL
1	Processed Record Count	n1..10	mandatory	Count of detail records (rows) in the response file.	100
2	Medication Count	n1..10	conditional	Total count of medications returned.	1000
3	Meds From PBM Count	n1..10	conditional	Total count of medications from PBM (claims).	200
4	Meds From Pharmacy Count	n1..10	conditional	Total count of medications from Pharmacy.	800
5	Patient found	n1..10	conditional	Total count of patients found (hit rate).	90
6	Some Drugs Returned	n1..10	conditional	Total Count of Note = "Not all medication history sources were accessible at this time.	2
7	No Meds Available	n1..10	conditional	Total count of Note = "Although a patient record was found, no medications were available.”	2
8	Patient Not Found	n1..10	conditional	Total Count of Note = "Patient Not Found."	5
9	Processing Error	n1..10	conditional	Total count of Note = "A processing error occurred. No medication history was returned."	2
10	More than 300 Meds Returned	n1..10	conditional	Count of patients with more than 300 medications returned.	2