Panel Patient File Record Element Details

data element requirements \<font color="#000000">requirement designation \</font> 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 guid docid\ grxcnasbfothahj l z7n surescripts recommends representing assigning authority as an oid docid\ grxcnasbfothahj l z7n 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 \<font color="#45494c">product\</font> an3 mandatory product type fixed value pma pma 3 \<font color="#45494c">end monitoring date\</font> 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 guid docid\ grxcnasbfothahj l z7n 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