API Details

this section details the four download api endpoints note on sourceversions behavior the sourceversions value indicates the formulary data publication version originally supplied by the pbm possible values include 30 – pbm publishes formulary data using the version 3 0 format 60 – pbm publishes formulary data using the version 60 format surescripts will always publish the corresponding version of the formulary data, in addition to the following ​​if a pbm publishes formulary data in version 3 0 format, surescripts will up‑translate and publish the data in version 60 format if a pbm publishes formulary data in version 60 format, surescripts will down‑translate and publish the data in version 3 0 format get pbms /formulary/pbms the pbms endpoint returns an array of all pbms that supply formulary data through surescripts all pbms are returned note that the response returns all pbms, which could contain one or more pbms the client does not have access to a subsequent get lists request for a pbm the client cannot access will return an empty result request details headers x participant id (required) participant id for the requester parameters the request contains no parameters response details the response consists of three properties for each returned pbm pbmname string pbmid string containing the pbm’s participant id sourceversions array of enumerated versions (30, 60) indicating the versions supported by the pbm (integer) lastpublisheddate string (format iso date time) specifies the last date a file was published by the pbm the http response codes accompanying a response are 200 the request was processed successfully 400 the request contained an error 401 access denied 403 the requester does not have access to the endpoint 500 a system error occurred response example \[ { "pbmname" "southwest medicaid", "pbmid" "d00000049124989", "sourceversions" \[ "60" ] }, { "pbmname" "us med management", "pbmid" "d00000020106965", "sourceversions" \[ "30" ] }, { "pbmname" “commercial benefits", "pbmid" "d00000055125361", "sourceversions" \[ "30", "60" ] }, get list types /formulary/listtypes the listtypes endpoint returns the full set of list types (in v3 0 and +v60) and sub types (in v3 0) the set of list types returned, however, are restricted to the formulary version(s) that the client has access to request details headers x participant id (required) participant id for the requester parameters the request contains no parameters response details the response consists of three properties for each returned type name enumerated string representing the list type (see below) subtypes enumerated string representing the list sub type (v3 0 only see below ) version enumerated list version (30, 60) (integer) below are the list types and sub types returned in the response’s name and subtype properties version 30 (ncpdp f\&b version 3 0) name alt cop subtype ds, sl cov subtype al, de, gl, pa, ql, rd, rs, sm, st, tm fsl version +60 (ncpdp f\&b version 60) name fs, dt, at, ag, cs, ps, pe, al, gl, pa, ql, sp, st, sm, pc, pn, gm, me the http response codes accompanying a response are 200 the request was processed successfully 400 the request contained an error 401 access denied 403 the requester does not have access to the endpoint 500 a system error occurred response example \[ { "name" "at", "version" 60 }, { "name" "gl", "version" 60 }, { "name" "cov", "version" 30, "subtypes" \[ "al", "de", "gl", "pa", "ql", "rd", "rs", "sm", "st", "tm" ] }, { "name" "st", "version" 60 },… get lists /formulary/lists?pbmid=\<pbm>\&type=\<type>\&subtype=\<subtype> \&version=\<version>\&publishedafter=\<publishedafter> \&detailchangeafter=\<detailchangeafter>\&page=\<page>\&pagesize=\<pagesize> the lists endpoint enables clients to find formulary files for download it returns an array of objects representing available formulary lists matching the parameters submitted in the request this endpoint will be used for two types of processing full formulary download and delta file download interacting with the api is the same in both modes but in the delta file download process, the additional publishedafter parameter is included in the request to return changes since the last time the formulary file load was processed the api returns a lastdetailchangedate date and a lastpublisheddate value the lastdetailchangedate value indicates the last time the list detail records changed the lastpublisheddate is the last time the file was received from the pbm pbm file submissions may or may not include updated detail records from a previous file submission if a new list file is received, but the detail records have not been updated the lastpublisheddate will be updated to reflect the new date the file was received but the lastdetailchangedate will remain unchanged using the lastdetailchangedate, list lastpublisheddate, and pbm lastpublisheddate response values, you can reduce the number of file downloads that are needed for processing pbm list searches can be skipped when the pbm lastpublisheddate is older than the last formulary load execution if the lastdetailchangedate value is newer than the lastdetailchangedate in your system, then download and process the updated file if the lastdetailchangedate is the same as the lastdetailchangedate in your system, but the lastpublisheddate is newer than the lastpublisheddate in your system, then the effective date and expiration date for the list might have changed you can use the effective date and expiration date returned by the lists api to update your system if the lastdetailchangedate and lastpublisheddate match the values in your system for the list then the file does not need to be downloaded and processed timing best practices timing full formulary downloads should be performed weekly or when drug database changes occur delta file download should be performed nightly for clients using the non rolled up version of the formulary files, then all files should be downloaded and processed after each drug database update in the client system request details headers x participant id (required) participant id for the requester parameters the request consists of multiple search parameters that can be used in combination to locate lists available for download only the page parameter is required; all other parameters are optional all parameters are case sensitive they can be submitted in any order pbmid string type enumerated string, all v3 0 and +v60 list types "alt", "cls", "crs", "cop", "cov", "fsl", "ag", "al", "at", "cs", "fs", "gl", "gm", "me", "pa", "pc", "pe", "pn", "ps", "ql", "sm", "sp", "st" subtype enumerated string, only applies to v3 0 list sub types "ds", "sl", "al", "de", "gl", "pa", "ql", "rd", "rs", "sm", "st", "tm" publishedafter string (format iso date time) the last time the file was received from a pbm expected format yyyy mm ddthh\ mm\ ss sssz (including time) detailchangeafter string (format iso date time) when the last change to detail records occurred expected format yyyy mm ddthh\ mm\ ss sssz (including time) version string (30 or 60) if not included, the response defaults to the client’s preferred version if set to a version not available to the client will return an empty result set page required numeric 1 should be used for the first page of data pagesize numeric value with default of 10000 notes a query may include a combination of type and subtype; however, invalid combinations of types and subtypes will return an empty result set by default, files of the client's preferred version will be returned based on the surescripts configuration the version parameter is available for clients with access to both v30 and +v60 response details the response includes a lists array which consists of nine properties for each returned formulary list, current page, total pages, and page size lists name string pbmid string listtype enumerated string, all v3 0 and +v60 list types "alt", "cls", "crs", "cop", "cov", "fsl", "ag", "al", "at", "cs", "fs", "gl", "gm", "me", "pa", "pc", "pe", "pn", "ps", "ql", "sm", "sp", "st" subtype enumerated string, all v3 0 list sub types "ds", "sl", "al", "de", "gl", "pa", "ql", "rd", "rs", "sm", "st", "tm" o only populated for v3 0 coverage and copay list types size integer lastpublisheddate string (format iso date time) lastdetailchangedate string (format iso date time) effectivedate string (format date without dashes, from original file) expirationdate string (format date without dashes, from original file) not always present in the response, as it is an optional list element filelink string, contains the url to download the file totalpages total number of pages based on the current page size pagesize page size for the request currentpage the current page number for the request note get lists requests for pbms the client doesn’t have access to will return an empty result the http response codes accompanying a response are 200 the request was processed successfully 400 the request contained an error 401 access denied 403 the requester does not have access to the endpoint 404 no files matching the request were found 500 a system error occurred response example (version 60 list) { "lists" \[ { "name" "file fs 1001", "pbmid" "t00000000021633", "listtype" "fs", "size" 281, "lastpublisheddate" "2024 07 05t21 24 36 708z", "lastdetailchangedate" "2024 07 05t21 24 36 708z", "effectivedate" "20230410", "expirationdate" "20991231", "filelink" "https //formulary surescripts net/formulary download/formulary/pbms/t00000000021633/types/fs/lists/file fs 1001/file" }, … ] , "totalpages" 1, "currentpage" 1, “pagesize" 10000 } response example (version 30 list including the subtype property) { "lists" \[ { "name" "al73046", "pbmid" "t0000000003444", "listtype" "cov", "subtype" "al", "size" 277, "lastpublisheddate" "2024 07 05t21 24 36 259z", "lastdetailchangedate" "2024 07 05t21 24 36 259z", "effectivedate" "20230413", "expirationdate" null, "filelink" "https //formulary surescripts net/formulary download/formulary/pbms/t00000000003444/types/cov/subtypes/al/lists/al73046/file" }, … ] , "totalpages" 1, "currentpage" 1, “pagesize" 10000 } get file this endpoint returns the actual formulary file request details headers x participant id (required) participant id for the requester parameters the request uri is structured as follows for version 3 0 formulary files and version +60 files all path parameters are case sensitive for +v60 & v3 0 fsl & alt files /formulary/pbms/\<pbmid>/types/\<type>/lists/\<list>/file e g , /formulary/pbms/t00000000021633/types/fs/lists/file fs 1001/file for v3 0 cov & cop files /formulary/pbms/\<pbmid>/types/\<type>/subtypes/\<subtype>/lists/\<list>/file e g , /formulary/pbms/t0000000003444/types/cop/subtypes/al/lists/al73046/file response details the endpoint’s response is the requested file note that, in the event that multiple files match the request (e g , a current file and one whose effective date is in the future) the endpoint will return the file with the most recent effective date that is either today or in the past the http response codes accompanying a response are 200 the request was processed successfully 400 the request contained an error 401 access denied 403 the requester does not have access to the requested file 404 the requested file was not found 500 a system error occurred response \[streamed text file] hdr|30|d00000000119037| |s00000000000001|testload1|2207190021|20220719|08273100|frm|u|20220714|t ghd|t3apa00940|pa|d|20220715 gtr|0 trl|2 error responses and handling error responses from all formulary download apis are returned in the same manner, with a json structured body accompanying the http response status code for example, if a request is submitted to the get lists with the invalid version parameter value of 99, the response will be http response status code 400 (bad request) response body { "code" "400 01", "message" "invalid version" } the code value in the response body consists of the http response status code followed by a dash and an additional 2 digit code providing a more specific indication of the issue encountered, when possible the table below details the error responses produced by each of the apis and the appropriate client actions to be taken in each scenario api http status response body code/message client action get pbms 401 401 01 missing certificate details 403 403 01 permission denied for the selected version 403 403 02 could not find participant 500 500 01 internal error get list types 401 401 01 missing certificate details correct the version parameter and resubmit 403 403 01 permission denied for the selected version 403 403 02 could not find participant 500 500 01 internal error get lists 400 400 01 invalid version only version 30 or 60 is allowed correct the version parameter and resubmit 400 400 02 participant configuration was not found contact surescripts support to confirm your configuration 400 400 03 invalid pbm name parameter valid pbm values are returned from the pbms endpoint in the pbmid field 400 400 04 invalid type parameter valid list type values are returned from the list type endpoint in the name fields confirm you are using the correct list types for the configured formulary version 400 400 05 invalid subtype parameter valid list type values are returned from the list type endpoint in the subtypes fields confirm you are using the correct list types for the configured formulary version 401 401 01 missing certificate details contact surescripts support to confirm your configuration 403 403 01 permission denied for the selected version contact surescripts support to confirm your configuration 403 403 02 could not find participant contact surescripts support to confirm your configuration 500 500 01 internal error get file 400 400 01 invalid version only version 30 or 60 is allowed correct the version parameter and resubmit 400 400 02 participant configuration was not found contact surescripts support to confirm your configuration 401 401 01 missing certificate details contact surescripts support to confirm your configuration 403 403 01 permission denied for the selected version contact surescripts support to confirm your configuration 403 403 02 could not find participant contact surescripts support to confirm your configuration 403 403 03 permission denied for selected file participant configuration does not allow access to this file 404 404 01 file not found could not find the selected file this file may have been removed from the formulary list 500 500 01 internal error