Using Accelerator Web Service API

the web service api allows access to selected accelerator functionality via restful web services for customers who prefer to develop their own user interface the web service api does not enable all accelerator functionality provider vendors must implement the web application api to allow users to act on a task note to reduce unnecessary strain on the surescripts network, it is recommended that provider vendors implement controls on how often epa tasks or processes are polled for status and/or details possible controls include (but are not limited to) only querying apis upon user access to worklists that contain epa references querying apis for info only when a user requests a specific epa task please consult your surescripts resource for questions regarding appropriate api usage conventions general conventions the web service api follows representational state transfer (rest) architecture principles using http requests with appropriate http verbs and status codes the message body for requests and responses are of type application/json versioning and urls urls are of the form https //\[host]/uiservice/api/\[version]/\[path], where the host depends on the environment, and is provided as part of the surescripts integration processes the version is the requested version of the endpoint, and is provided as part of the surescripts integration processes the path points to the specific service the api version number ("v0" in the above example) is incremented when a breaking change is introduced a breaking change prevents an existing implementation from communicating with a particular version adding additional fields is not considered a breaking change an api client application needs to support additional fields being added to an existing version for example https //uiservice api staging surescripts net/uiservice/api/v0/processes examples of breaking changes includes, but are not limited to changing type or attributes of an existing field changing an endpoint path changing the semantic meaning of an existing field summary of web service api endpoints the following provides a summary of the web service api endpoints and the data that they provide api endpoint description \[get] /processes?patientid={{patientid}}\&facility={{facility}}\&createdfromdate={{createdfromdate}}\&createdthrudate ={{createdthrudate}}\&pageindex={{pageindex}}\&pagesize={{pagesize}} retrieves a paged list of processes for a given patient the process details include the relevant data from the epa messages for the current state in the workflow \[post] /processes retrieves a paged list of processes for specified initiator(s) \[post] /initiators/processes retrieves a paged list of processes for the given list of initiatorsprocessid(s) note the initiatorsprocessid is the pareferenceid as defined by the provider vendor system \[get] /processes/{{processid}} retrieve the process details for a specified processid \[get] /initiators/processes/{{initiatorsprocessid}} retrieve the process details for a specified initiatorsprocessid \[get] /worklist?patientid={{patientid}} \&facility={{facility}}\&user={{user}} \&pageindex={{pageindex}}\&pagesize={{pagesize}} retrieves a paged list of the active tasks for a given patient \[get] uiservice/api/v0/worklist/summary?patientid= {patientid]\&facility={{facility}} retrieves the count of worklist tasks for the patient \[put] /cancel/processes/{{processid}} initiates cancel for a process based on the processesid \[put] /cancel/initiators/processes/{{initiatorsprocessid}} initiates cancel for a process based on the initiatorsprocessid \[post] /uiservice/api/v0/complete/tasks completes a list of tasks for the given task ids returns list of task ids and any errors \[post] /uiservice/api/v0/complete/recipients/tasks completes all possible tasks for the given task recipient note only tasks that have been configured for this option will complete returns a list of task ids that have been completed api auth token request and api end point call process flow notes for the cancelled painitiationrequest process flow, see cancelled painitiationrequest process flow https //docs surescripts com/epa accelerator/guide/accelerator integration approach#cancelled painitiationrequest process flow api calls, with the exception of the cancel api call, are read only queries for processes and tasks the cancel api call sends a pacancelrequest message to pbm/payer(s) user security web service api messages are sent using https and routed through an allowed vendor aggregation server api note calls require the server ip addresses to be on the allowed list a call to a web service api requires the following headers a standard basic authentication header using the credentials assigned during the integration process for example authorization basic qwxhzgrpbjpvcgvuihnlc2ftzq== a custom x sender uid header that contains a surescripts identifier assigned during the integration process the format for the header value is qualifier id for example x sender uid dp epa123 request headers header code description authorization mandatory a standard basic authentication header using the credentials assigned during the integration process example authorization basic qwxhzgrpbjpvcgvuihnlc2ftzq== x sender uid mandatory a custom x sender uid header that contains a surescripts identifier assigned during the integration process the format for the header value is qualifier id format for a system user id is dp \[systemuserid] example dp epa123 security headers in an api call example security headers for a sample api call are shown in blue below post //uiservice/api/v0/worklist http/1 1 host localhost authorization basic dxnlcje6cgfzc3dvcmqx x sender uid dp epa123dp abc123np abc123dp spo123 content type application/json cache control no cache postman token f920dfc3 bc53 db39 fc4d b365f8cfb44c { user "rob", "recipients" \[ { "id" "6689026196001", "qualifier" "dzz", "name" "mouse, micky" } ] } list processes the following endpoints are available to retrieve a list of processes based on parameters and search criteria each item in the list is a summary of a process the responses are the same for all list processes endpoints created from date and created thru date details if createdfromdate and createdthrudate range is within 18 months, all dates are returned if createdfromdate and createdthrudate range exceeds 18 months, thru date less 18 months are returned if createdfromdate and createdthrudate = null, current date less 18 months are returned if createdfromdate is populated and createdthrudate = null, current date less 18 months are returned if createdfromdate = null and createdthrudate date is populated, current date less 18 months are returned list processes for patientid list processes for patientid retrieves a paged list of process summaries for a given patient id if the optional parameter of facility is not provided in the request, then only the processes that are not affiliated with a facility will be included in the results request template \[get] {{host}}/api/v0/processes?patientid={{patientid}}\&facility={{facility}} \&fromdate={{fromdate}}\&createdthrudate={{createdthrudate}}\&pageindex={{pageindex}}\&pagesize={{pagesize}} request parameters parameter data type code description patientid an 35 mandatory matches the patient id specified in the painitiationrequest/body/patient/identification/medicalrecordidentificationnumberehr facility an 35 conditional qualifier the vendor may use to make their patient id unique across their installations facility is only used in conjunction with patientid if facility is not specified, only records that have no facility associated with them will be returned this field matches the facility specified in the painitiationrequest/body/patient/identification/mutuallydefined in the ncpdp xml schema createdfromdate datetime conditional processes created on or after this date will be returned see created from date and created thru date details https //docs surescripts com/epa accelerator/guide/accelerator integration approach#cancelled painitiationrequest process flow for additional information on which dates will be returned note datetime format is ccyy mm ddthh\ mm\ ssz createdthrudate datetime conditional processes created on or prior to this date will be returned see created from date and created thru date details https //docs surescripts com/epa accelerator/guide/accelerator integration approach#cancelled painitiationrequest process flow for additional information on which dates will be returned note datetime format is ccyy mm ddthh\ mm\ ssz pagesize positive int conditional integer representing the number of records returned in each request if a pagesize is not specified, the default value of 25 is applied this value is truncated to 100 if larger pageindex positive int conditional integer representing the page index of data to be returned if a pageindex is not specified, the default value of 0 is applied request example \[get] {{host}}/uiservice/api/v0/processes?patientid=george123 list processes for initiator(s) list processes for initiator(s) retrieves a paged list of process summaries for the specified initiator(s) an initiator is an individual or physician that requested the epa request template \[post] {{host}}/processes request parameters parameter data type code description initiators complex type mandatory a collection of initiators an initiator is a list containing the initiators identifying data id an13 mandatory spi of the initiator (limit of 85 spis per request ) qualifier an1 mandatory spi's corresponding qualifier value = d createdfromdate datetime conditional processes created on or after this date will be returned see created from date and created thru date details https //docs surescripts com/epa accelerator/guide/accelerator integration approach#cancelled painitiationrequest process flow for additional information on which dates will be returned note datetime format is ccyy mm ddthh\ mm\ ssz createdthrudate datetime conditional processes created on or prior to this date will be returned see created from date and created thru date details https //docs surescripts com/epa accelerator/guide/accelerator integration approach#cancelled painitiationrequest process flow for additional information on which dates will be returned note datetime format is ccyy mm ddthh\ mm\ ssz pagesize positive int conditional integer representing the number of records returned in each request if a pagesize is not specified, the default value of 25 is applied this value is truncated to 100 if larger pageindex positive int conditional integer representing the page index of data to be returned if a pageindex is not specified, the default value of 0 is applied request example \[post] http //\[host]/uiservice/api/v0/processes { "initiators" \[ { "id" "6223033492001", "qualifier" "d" } ], "createdfromdate" "2014 12 05t15🕚42 578706 06 00", "createdthrudate" "2014 12 05t15🕚42 578706 06 00", "pageindex" 2, "pagesize" 3 } list processes for initiatorsprocessid(s) list processes for initiatorsprocessid(s) retrieves a paged list of processes for the specified initiatorsprocessid(s) initiatorsprocessid is the pareferenceid as defined by the provider vendor system request template \[post] {{host}}/processes request parameters parameter data type code description initiatorprocessids complex type mandatory a collection of initiators process ids createdfromdate datetime conditional processes created on or after this date will be returned see created from date and created thru date details https //docs surescripts com/epa accelerator/guide/accelerator integration approach#cancelled painitiationrequest process flow for additional information on which dates will be returned note datetime format is ccyy mm ddthh\ mm\ ssz createdthrudate datetime conditional processes created on or thru this date will be returned see created from date and created thru date details https //docs surescripts com/epa accelerator/guide/accelerator integration approach#cancelled painitiationrequest process flow for additional information on which dates will be returned note datetime format is ccyy mm ddthh\ mm\ ssz pagesize positive int conditional integer representing the number of records returned in each request if a pagesize is not specified, the default value of 25 is applied this value is truncated to 100 if larger pageindex positive int conditional integer representing the page index of data to be returned if a pageindex is not specified, the default value of 0 is applied request example \[post] http //\[host]/uiservice/api/v0/intiators/processes { "initiatorprocessids" \[ "f050fc8601444af1be3c5ffeb4c1d703", "3fb345ccf3814adc835f756e752c851a" ] } list processes response response httpstatus codes httpstatus description 200 successful response along with the processlist and the corresponding process response fields 400 bad request response field description – list processes field description pageindex integer representing the returned page index pagesize integer representing the page size totalrows integer representing the total number of rows matching the search criteria items collection of process summary objects see response field description – process summary https //docs surescripts com/epa accelerator/guide/using accelerator web service api#response field description process summary response field description – process summary field description processid unique surescripts id which represents the process instance processname name of the process initiatorsprocessid the initiatorsprocessid is the pareferenceid as defined by the provider vendor system initiator list containing the recipient's identifying data field(s) include id qualifier name note supported qualifiers are d and py if the qualifier is d, then the id will be the spi if the qualifier is py, the id will be the pbm/payer id patientid vendor supplied patient id facility optional vendor supplied value to create uniqueness across vendor installations patientfirstname patient’s first name patientlastname patient’s last name patientdob patient’s date of birth createddate date/time process was created completeddate date/time process was completed status integer representing the status of the process, possible values are 1 draft 2 in progress 3 complete 4 cancelled 5 errored note values with a strikethrough are not used for epa statusname textual name representing the status of the process description description of the process instance response example { "pageindex" 0, "pagesize" 25, "totalrows" 1, "items" \[ { "processid" 122908, "processname" "epa case", "initiatorsprocessid" "06056ea227e144cd820cfc0f6e860d1f", "initiator" { "id" "6590604289001", "qualifier" "d", "name" "mouse, mickey" }, "patientid" "george", "facility" "clinic1", "patientfirstname" "george", "patientlastname" "jetson", "patientdob" "1962 11 23t00 00 00", "createddate" "2014 12 05t17 36 38 476", "completeddate" "2014 12 05t17 37 45 757", "status" 4, "statusname" "cancelled", "description" "botox (onabotuilinumatoxina) 20mg vial" } ] } retrieve process detail to retrieve process detail, use the surescripts processid or the initiatorsprocessid per the information below retrieve process detail using the surescripts processid request template \[get] {{host}}/api/v0/processes/{{processid}} request parameters parameter data type code description processid long mandatory unique surescripts id which represents the process instance request example \[get] {{host}}/uiservice/api/v0/processes/123 retrieve process by initiatorsprocessid request template \[get] {{host}}/api/v0/initiators/processes/{{initiatorsprocessid}} request parameters parameter data type code description initiatorsprocessid string max 35 mandatory the initiatorsprocessid is the pareferenceid as defined by the provider vendor system request example \[get] {{host}}/uiservice/api/v0/processes/123p retrieve process response all process detail endpoints return the same response response httpstatus codes httpstatus description 200 successful response along with the process response fields 400 bad request response field description – process detail process summary fields are included in the process detail response see response field description – process summary https //docs surescripts com/epa accelerator/guide/using accelerator web service api#response field description process summary table for more information field description tasks collection that contains details of each task in the requested process see response field description – task detail for process https //docs surescripts com/epa accelerator/guide/using accelerator web service api#response field description task detail for process table for more information metadata list containing the response data corresponding to the state of the process field(s) include pacaseid response referencenumber approved denied open closed see the ncpdp script standard implementation guide version 2023011 for field definitions see tables below for possible status response details response status – “approved” response field description https //docs surescripts com/epa accelerator/guide/using accelerator web service api#response status approved response field descriptio response status – “denied” response field description https //docs surescripts com/epa accelerator/guide/using accelerator web service api#response status denied response field description response status – “open” response field description https //docs surescripts com/epa accelerator/guide/using accelerator web service api#response status open response field description response status – “closed” response field description https //docs surescripts com/epa accelerator/guide/using accelerator web service api#response status closed response field description response field description – task detail for process field description taskid unique surescripts id which represents the task instance taskname name of the task recipient list containing the recipient's identifying data field(s) include id qualifier name note supported qualifiers are d and py if the qualifier is d, then the id will be the spi if the qualifier is py, the id will be the pbm/payer id acceptedby dataset containing the identifying data for the user who acted upon the task field(s) include id qualifier name note supported qualifiers are d, py, and userid if the qualifier is d, then the id will be the spi if the qualifier is py, the id will be the pbm/payer id if the qualifier is userid, the id will be the end user id assigned by the provider vendor system duedate date/time task is required to be completed by accepteddate date/time task was accepted to be worked on responsedate date/time task was responded to status integer representing the status of the task task values are 1 draft 2 pending 3 assigned 4 distributed 5 accepted 6 released 7 complete 8 cancelled 9 errored note values with a strikethrough are not used for epa statusname textual name representing the status of the task response status – “approved” response field description field description pacaseid the unique case id assigned by the pbm/payer in the painitiationresponse authorizationnumber this optional element contains a payer assigned authorization number authorizationperiod this optional list provides the authorization start and end dates field(s) include effectivedate expirationdate see the ncpdp script standard implementation guide version 2023011 for field definitions appeal this mandatory list indicates whether this determination can be further appealed field(s) include iseappealsupported expirationdate panote see the ncpdp script standard implementation guide version 2023011 for field definitions panote free text note provides additional information regarding the response status response status – “denied” response field description field description pacaseid the unique case id assigned by the pbm/payer in the painitiationresponse appeal the appeal list details corresponding to the corresponding process field(s) include iseappealsupported expirationdate datetime panote note datetime format is ccyy mm ddthh\ mm\ ssz see the ncpdp script standard implementation guide version 2023011 for field definitions panote free text note provides additional information regarding the response status response status – “open” response field description field description pacaseid the unique case id assigned by the pbm/payer in the painitationresponse deadlineforreply list containing the deadline for reply criteria field(s) include datetime note datetime format is ccyy mm ddthh\ mm\ ssz see the ncpdp script standard implementation guide version 2023011 for field definitions panote free text note provides additional information regarding the response status appealcaseid only applies to an appeal unique appeal case id attached to the open response of which the appeal it is associated response status – “closed” response field description field description pacaseid the unique case id assigned by the pbm/payer in the painitiationresponse reasons list of reasons the epa has been closed field(s) include code description see the ncpdp script standard implementation guide version 2023011 for field definitions authorizationnumber this optional element contains a payer assigned authorization number authorizationdetail this optional list contains authorization details of the approval granted either authorizationdetail or authorizationperiod will be sent all elements in the composite are optional and used if they apply to the case field(s) include pharmacytype quantity value codelistqualifier quantityunitofmeasure code dayssupply numberofcycles numberofrefills panote see the ncpdp script standard implementation guide version 2023011 for field definitions authorizationperiod this optional list provides the authorization start and end dates either authorizationdetail or authorizationperiod will be sent field(s) include effectivedate expirationdate see the ncpdp script standard implementation guide version 2023011 for field definitions appealcaseid only applies to an appeal if a unique appeal case id was provided in the initial open paappealresponse, it will be provided in every subsequent appeal message – including the closed response panote free text note provides additional information regarding the response status response examples example response – last task is associated to a pending pbm/payer response { "tasks" \[ { "taskid" 673672, "taskname" "initiate pa", "status" 4, "statusname" "distributed", "recipient" { "id" "t00000090999022", "qualifier" "py", "name" "accl epa dev payer shawn" } } ], "processid" 123188, "processname" "epa case", "initiatorsprocessid" "f63c307e139b49f3b7d7b4c2cd22b14f", "initiator" { "id" "6223033492001", "qualifier" "d", "name" "mouse, mickey" }, "patientid" "george", "facility" "clinic1", "patientfirstname" "george", "patientlastname" "jetson", "patientdob" "1962 11 23t00 00 00", "createddate" "2014 12 09t20 28 12 417", "completeddate" "0001 01 01t00 00 00", "status" 2, "statusname" "in progress", "description" "botox (onabotuilinumatoxina) 20mg vial" } example open response { "metadata" { "pacaseid" "665616", "response" { "referencenumber" "an35xxxxx", "open" { "pacaseid" "665616", "deadlineforreply" { "datetime" "2013 08 13t09 30 47z" }, "panote" "panote the generic medicine must be tried before the name brand is approved " } } }, "tasks" \[ { "taskid" 673714, "taskname" "initiate pa", "status" 4, "statusname" "distributed", "recipient" { "id" "t00000090999022", "qualifier" "py", "name" "accl epa dev payer shawn" } }, { "taskid" 673716, "taskname" "initiate pa", "accepteddate" "2014 12 09t20 30 28 6", "responsedate" "2014 12 09t20 30 28", "status" 7, "statusname" "complete", "acceptedby" { "id" "t00000090999022" "qualifier" "py" }, "recipient" { "id" "t00000090999022", "qualifier" "py", "name" "accl epa dev payer shawn" } }, { "taskid" 673718, "taskname" "complete pa form", "duedate" "2013 08 13t09 30 47", "status" 4, "statusname" "distributed", "recipient" { "id" "6223033492001", "qualifier" "d", "name" "mouse, mickey" } } ], "processid" 123190, "processname" "epa case", "initiatorsprocessid" "66561645fcaa4dd88c40cc1c3df9d3e3", "initiator" { "id" "6223033492001", "qualifier" "d", "name" "mouse, mickey" }, "patientid" "george", "facility" "clinic1", "patientfirstname" "george", "patientlastname" "jetson", "patientdob" "1962 11 23t00 00 00", "createddate" "2014 12 09t20 30 25 58", "completeddate" "0001 01 01t00 00 00", "status" 2, "statusname" "in progress", "description" "botox (onabotuilinumatoxina) 20mg vial" } example closed response { "metadata" { "pacaseid" "ed717e", "response" { "referencenumber" "an35xxxxx", "closed" { "pacaseid" "ed717e", "reasons" \[ { "code" "cc", "description" "prior authorization not required for patient/medication" } ], "authorizationdetail" \[ { "pharmacytype" "retail", "dayssupply" "12", "numberofrefills" "3" } ], "authorizationperiod" { "effectivedate" { "datetime" "2013 10 02t00 00 00" }, "expirationdate" { "datetime" "2013 10 22t00 00 00" } }, "panote" "this medication does not require a pa" } } }, "tasks" \[ { "taskid" 673720, "taskname" "initiate pa", "status" 4, "statusname" "distributed", "recipient" { "id" "t00000090999022", "qualifier" "py", "name" "accl epa dev payer shawn" } }, { "taskid" 673722, "taskname" "initiate pa", "accepteddate" "2014 12 09t20 32 46 841", "responsedate" "2014 12 09t20 32 46", "status" 7, "statusname" "complete", "acceptedby" { "id" "t00000090999022" "qualifier" "py" }, "recipient" { "id" "t00000090999022", "qualifier" "py", "name" "accl epa dev payer shawn" } }, { "taskid" 673724, "taskname" "acknowledge pa not needed", "status" 4, "statusname" "distributed", "recipient" { "id" "6223033492001", "qualifier" "d", "name" "mouse, mickey" } } ], "processid" 123192, "processname" "epa case", "initiatorsprocessid" "ed717eea2cdc4ec483f6af8811864265", "initiator" { "id" "6223033492001", "qualifier" "d", "name" "mouse, mickey" }, "patientid" "george", "facility" "clinic1", "patientfirstname" "george", "patientlastname" "jetson", "patientdob" "1962 11 23t00 00 00", "createddate" "2014 12 09t20 32 45 496", "completeddate" "0001 01 01t00 00 00", "status" 2, "statusname" "in progress", "description" "botox (onabotuilinumatoxina) 20mg vial" } example approved response { "metadata" { "pacaseid" "0f038d", "response" { "approved" { "pacaseid" "0f038d", "authorizationnumber" "111222333", "authorizationperiod" \[ { "effectivedate" { "datetime" "2014 12 09t00 00 00" }, "expirationdate" { "datetime" "2015 12 09t00 00 00" } } ], "appeal" { "iseappealsupported" "y", "expirationdate" { "datetime" "2014 12 14t00 00 00" } }, "panote" "this is an approved pa note " } } }, "tasks" \[ { "taskid" 673778, "taskname" "initiate pa", "status" 4, "statusname" "distributed", "recipient" { "id" "t00000090999022", "qualifier" "py", "name" "accl epa dev payer shawn" } }, { "taskid" 673780, "taskname" "initiate pa", "accepteddate" "2014 12 09t21 14 26 985", "responsedate" "2014 12 09t21 14 26", "status" 7, "statusname" "complete", "acceptedby" { "id" "t00000090999022", "qualifier" "py" }, "recipient" { "id" "t00000090999022", "qualifier" "py", "name" "accl epa dev payer shawn" } }, { "taskid" 673782, "taskname" "complete pa form", "duedate" "2013 08 13t09 30 47", "status" 4, "statusname" "distributed", "recipient" { "id" "6223033492001", "qualifier" "d", "name" "mouse, mickey" } }, { "taskid" 673784, "taskname" "complete pa form", "duedate" "2013 08 13t09 30 47", "accepteddate" "2014 12 09t21 14 35 563", "status" 5, "statusname" "accepted", "acceptedby" { "id" "shawn", "qualifier" "userid" }, "recipient" { "id" "6223033492001", "qualifier" "d", "name" "mouse, mickey" } }, { "taskid" 673786, "taskname" "complete pa form", "duedate" "2013 08 13t09 30 47", "accepteddate" "2014 12 09t21 14 35 563", "responsedate" "2014 12 09t21 14 43", "status" 7, "statusname" "complete", "acceptedby" { "qualifier" "userid", "id" "shawn" }, "recipient" { "id" "6223033492001", "qualifier" "d", "name" "mouse, mickey" } }, { "taskid" 673788, "taskname" "send pa request", "status" 4, "statusname" "distributed", "recipient" { "id" "system generated", "qualifier" "userid", "name" "system generated" } }, { "taskid" 673790, "taskname" "send pa request", "accepteddate" "2014 12 09t21 14 43 629", "responsedate" "2014 12 09t21 14 43", "status" 7, "statusname" "complete", "acceptedby" { "id" "6223033492001", "qualifier" "d" }, "recipient" { "id" "system generated", "qualifier" "userid", "name" "system generated" } }, { "taskid" 673792, "taskname" "pbm response", "status" 4, "statusname" "distributed", "recipient" { "id" "t00000090999022", "qualifier" "py", "name" "accl epa dev payer shawn" } }, { "taskid" 673794, "taskname" "pbm response", "accepteddate" "2014 12 09t21 14 46 626", "responsedate" "2014 12 09t21 14 46", "status" 7, "statusname" "complete", "acceptedby" { "id" "t00000090999022", "qualifier" "py" }, "recipient" { "id" "t00000090999022", "qualifier" "py", "name" "accl epa dev payer shawn" } }, { "taskid" 673796, "taskname" "acknowledge approval", "status" 4, "statusname" "distributed", "recipient" { "id" "6223033492001", "qualifier" "d", "name" "mouse, mickey" } } ], "processid" 123200, "processname" "epa case", "initiatorsprocessid" "0f038d30ca2b404d873c180543041da1", "initiator" { "id" "6223033492001", "qualifier" "d", "name" "mouse, mickey" }, "patientid" "george", "facility" "clinic1", "patientfirstname" "george", "patientlastname" "jetson", "patientdob" "1962 11 23t00 00 00", "createddate" "2014 12 09t21 14 26 144", "completeddate" "0001 01 01t00 00 00", "status" 2, "statusname" "in progress", "description" "botox (onabotuilinumatoxina) 20mg vial" } example denied response { "metadata" { "pacaseid" "2b2d9b", "response" { "denied" { "pacaseid" "2b2d9b", "appeal" { "iseappealsupported" "y", "expirationdate" { "datetime" "2014 12 14t00 00 00" }, "panote" "appeal note" }, "panote" "this is an denied pa note " } } }, "tasks" \[ { "taskid" 673798, "taskname" "initiate pa", "status" 4, "statusname" "distributed", "recipient" { "id" "t00000090999022", "qualifier" "py", "name" "accl epa dev payer shawn" } }, { "taskid" 673800, "taskname" "initiate pa", "accepteddate" "2014 12 09t21 15 35 956", "responsedate" "2014 12 09t21 15 35", "status" 7, "statusname" "complete", "acceptedby" { "id" "t00000090999022" "qualifier" "py", }, "recipient" { "id" "t00000090999022", "qualifier" "py", "name" "accl epa dev payer shawn" } }, { "taskid" 673802, "taskname" "complete pa form", "duedate" "2013 08 13t09 30 47", "status" 4, "statusname" "distributed", "recipient" { "id" "6223033492001", "qualifier" "d", "name" "mouse, mickey" } }, { "taskid" 673804, "taskname" "complete pa form", "duedate" "2013 08 13t09 30 47", "accepteddate" "2014 12 09t21 15 45 707", "status" 5, "statusname" "accepted", "acceptedby" { "id" "shawn" "qualifier" "userid" }, "recipient" { "id" "6223033492001", "qualifier" "d", "name" "mouse, mickey" } }, { "taskid" 673806, "taskname" "complete pa form", "duedate" "2013 08 13t09 30 47", "accepteddate" "2014 12 09t21 15 45 707", "responsedate" "2014 12 09t21 15 52", "status" 7, "statusname" "complete", "acceptedby" { "id" "shawn" "qualifier" "userid", }, "recipient" { "id" "6223033492001", "qualifier" "d", "name" "mouse, mickey" } }, { "taskid" 673808, "taskname" "send pa request", "status" 4, "statusname" "distributed", "recipient" { "id" "system generated", "qualifier" "userid", "name" "system generated" } }, { "taskid" 673810, "taskname" "send pa request", "accepteddate" "2014 12 09t21 15 54 07", "responsedate" "2014 12 09t21 15 54", "status" 7, "statusname" "complete", "acceptedby" { "id" "6223033492001" "qualifier" "d" }, "recipient" { "id" "system generated", "qualifier" "userid", "name" "system generated" } }, { "taskid" 673812, "taskname" "pbm response", "status" 4, "statusname" "distributed", "recipient" { "id" "t00000090999022", "qualifier" "py", "name" "accl epa dev payer shawn" } }, { "taskid" 673814, "taskname" "pbm response", "accepteddate" "2014 12 09t21 15 56 298", "responsedate" "2014 12 09t21 15 56", "status" 7, "statusname" "complete", "acceptedby" { "id" "t00000090999022" "qualifier" "py" }, "recipient" { "id" "t00000090999022", "qualifier" "py", "name" "accl epa dev payer shawn" } }, { "taskid" 673816, "taskname" "acknowledge denied pa", "status" 4, "statusname" "distributed", "recipient" { "id" "6223033492001", "qualifier" "d", "name" "mouse, mickey" } } ], "processid" 123202, "processname" "epa case", "initiatorsprocessid" "2b2d9ba639874df08474b38af8fdc9e9", "initiator" { "id" "6223033492001", "qualifier" "d", "name" "mouse, mickey" }, "patientid" "george", "facility" "clinic1", "patientfirstname" "george", "patientlastname" "jetson", "patientdob" "1962 11 23t00 00 00", "createddate" "2014 12 09t21 15 33 966", "completeddate" "0001 01 01t00 00 00", "status" 2, "statusname" "in progress", "description" "botox (onabotuilinumatoxina) 20mg vial" } retrieve worklist retrieve worklist returns the list of active tasks awaiting action based on the given filter criteria the items returned by a worklist request either have the acceptedby as the user in the worklist request or the acceptedby is null retrieve worklist by patient retrieving a worklist by patient retrieves a paged list of the active tasks for a given patient request template example \[get] {{host}}/worklist?patientid={{patientid}}\&facility={{facility}}\&user={{user}}& pageindex={{pageindex}}\&pagesize={{pagesize}} request parameters parameter data type code description patientid an 35 mandatory matches the patientid specified in the painitiationrequest/body/patient/identification/ medicalrecordidentificationnumberehr user an 250 mandatory unique provider vendor end user id representing the user working the task list this is the end user id and does not have to be the user id of the prescriber associated with the tasks facility an 35 conditional qualifier the vendor may use to make their patient id unique across their installations facility is only used in conjunction with patientid if facility is not specified, only records that have no facility associated with them will be returned this field matches the facility specified in the painitiationrequest/body/patient/identification/ mutuallydefined in the ncpdp xml schema pagesize positive int conditional integer representing the number of records returned in each request if a pagesize is not specified, the default value of 25 is applied pageindex positive int conditional integer representing the page index of data to be returned if a pageindex is not specified, the default value of 0 is applied \[get] {{host}}/uiservice/api/v0/worklist?patientid=george\&facility=clinic1\&user=jake \[get] {{host}}/uiservice/api/v0/worklist?patientid=george\&user=jake get worklist by recipients retrieves a paged list of the active tasks for a given collection of recipients (providers) request template example \[post] {{host}}/worklist request json fields json field data type code description user an 250 mandatory unique provider vendor end user id representing the user working the task list this is the end user id and does not have to be the user id of the prescriber associated with the tasks recipients list mandatory collection of recipients for which accelerator based tasks will be retrieved id an13 mandatory spi of the initiator qualifier an1 mandatory spi's corresponding qualifier qualifier = d pagesize positive int conditional integer representing the number of records returned in each request if a pagesize is not specified, the default value of 25 is applied this value is truncated to 100 if larger pageindex positive int conditional integer representing the page index of data to be returned if a pageindex is not specified, the default value of 0 is applied request example \[post] https //\[host]/uiservice/api/v0/worklist { "user" "jake", "recipients" \[ { "id" "6417473720001" "qualifier" "dzz", } ] } retrieve worklist response response codes and fields httpstatus code description 200 successful response along with the processlist and the corresponding process response fields 400 invalid request description message body json fields field description items collection of task details matching the corresponding process see description message body items json fields table below pageindex integer representing the returned page index pagesize integer representing the page size totalrows integer representing the total number of rows matching the search criteria description message body items json fields field description processid unique surescripts id which represents the process instance processname name of the process initiatorsprocessid the initiatorsprocessid is the pareferenceid as defined by the provider vendor system taskid unique surescripts id which represents the task instance taskname name of the task patientid vendor supplied patient id facility vendor supplied value to create uniqueness across vendor installations patientfirstname patient’s first name patientlastname patient’s last name patientdob patient’s date of birth initiator list containing the recipients identifying data field(s) include id qualifier name see the ncpdp script standard implementation guide version 2023011 for field definitions recipient list containing the recipient's identifying data field(s) include id qualifier name note supported qualifiers are d and py if the qualifier is d, then the id will be the spi if the qualifier is py, the id will be the pbm/payer id see the ncpdp script standard implementation guide version 2023011 for field definitions acceptedby dataset containing the accepted by identifying data field(s) include id qualifier name note supported qualifiers are d, py, and userid if the qualifier is d, then the id will be the spi if the qualifier is py, the id will be the pbm/payer id userid is the end user id assigned by the provider vendor system see the ncpdp script standard implementation guide version 2023011 for field definitions createddate date/time task was created duedate date/time task is required to be completed by accepteddate date/time task was accepted to be worked on responsedate date/time task was responded to status integer representing the status of the task task values are draft pending assigned distributed accepted released complete cancelled errored note values with a strikethrough are not used for epa statusname textual name representing the status of the task worklist response example { "pageindex" 0, "pagesize" 25, "totalrows" 2, "items" \[ { "processid" 123268, "processname" "epa case", "initiatorsprocessid" "a27332aae4a04340a512be900bf09ca0", "patientid" "elizabeth", "facility" "clinic2", "patientfirstname" "elizabeth", "patientlastname" "johanson anderson", "patientdob" "1967 08 13t00 00 00", "initiator" { "id" "6223033492001", "qualifier" "d", "name" "mouse, mickey" }, "createddate" "2014 12 10t21 47 59 582", "taskid" 674376, "taskname" "complete pa form", "duedate" "2013 08 13t09 30 47", "status" 4, "statusname" "distributed", "recipient" { "id" "6223033492001", "qualifier" "d", "name" "mouse, mickey" } }, { "processid" 123266, "processname" "epa case", "initiatorsprocessid" "abd2dc86d5ab4ad09fe7ffa203411ee2", "patientid" "george", "facility" "clinic1", "patientfirstname" "george", "patientlastname" "jetson", "patientdob" "1962 11 23t00 00 00", "initiator" { "id" "6223033492001", "qualifier" "d", "name" "mouse, mickey" }, "createddate" "2014 12 10t21 47 50 798", "taskid" 674370, "taskname" "complete pa form", "duedate" "2013 08 13t09 30 47", "status" 4, "statusname" "distributed", "recipient" { "id" "6223033492001", "qualifier" "d", "name" "mouse, mickey" } } ] } cancel process cancelling a process sends a pacancelrequest to the pbm/payer, which begins the process of cancelling an epa case cancel process using the processid request template \[put] {{host}}/cancel/processes/{{processid}} request parameters parameter data type description processid long mandatory unique surescripts id which represents the process instance request json fields json field data type code description user an 250 mandatory id of the end user logged into the provider vendor system cancelcode an2 conditional ncpdp code for the reason epa is being cancelled values ac = prescriber is no longer responsible for patient’s care bw = change to a different medication by = other ispatientnotified an1 conditional boolean value signifying if the patient was notified values y n note an 2000 conditional free text note to pbm/payer regard the cancellation of an epa request example \[put] https //\[host]/uiservice/api/v0/cancel/processes/1234 { user “jake”, cancelcode "bw", ispatientnotified “n”, note “sample note” } cancel process using initiatorsprocessid use the initiatorsprocessid to cancel a process request template \[put] {{host}}/cancel/initiators/processes/{{initiatorsprocessid}} request parameters parameter data type code description initiatorsprocessid an 255 mandatory the initiatorsprocessid is the pareferenceid as defined by the provider vendor description of json fields json field data type code description user an 250 mandatory id of the end user logged into the provider vendor system cancelcode an2 conditional ncpdp code for the reason epa is being cancelled values ac = prescriber is no longer responsible for patient’s care bw = change to a different medication by = other ispatientnotified an1 conditional boolean value signifying if the patient was notified values y n note an 2000 conditional free text note to pbm/payer regard the cancellation of an epa request example \[put] https //\[host]/uiservice/api/v0/cancel/initiators/processes/123p { user "jake", cancelcode "bw", ispatientnotified “n”, note “sample note” } cancel a process response response codes and fields httpstatus code description 200 successful response 400 invalid request worklist summary the api/v0/worklist/summary provides summary information of task counts for a provider or a patient the api takes a list of recipients or a patient and a products object, which can include all or just one product if product is not sent, the customer will get back the task counts for all products implemented patient request template example \[get] {{host}}/uiservice/api/v0/worklist/summary?patientid={patientid] \&facility={{facility}} patient request parameters parameter data type code description patientid an 35 mandatory matches the patientid specified in the painitiationrequest/body/patient/identification/medicalrecordidentificationnumberehr facility an 35 conditional qualifier the vendor may use to make their patient id unique across their installations facility is only used in conjunction with patientid if facility is not specified, only records that have no facility associated with them will be returned this field matches the facility specified in the painitiationrequest/body/patient/identification/mutuallydefined in the ncpdp xml schema product an 5 conditional value epa optional qualifier the vendor may use to filter the active tasks to only epa when using the patientid patient request example \[get] {{host}}/uiservice/api/v0/worklist/summary?patientid=george\&facility=clinic1 provider worklist summary \[post] {{host}}/uiservice/api/v0/worklist/summary provider request json fields json field data type code description recipients list mandatory collection of recipients for which accelerator based tasks will be retrieved qualifier an 1 mandatory spi's corresponding qualifier value d id an 13 mandatory spi of the provider products list conditional required if customer needs a specific product if not sent, all products will be returned example epa id an 5 conditional product id at least one product id is required if ‘products’ is used value epa processtypes an 12 conditional required if process types filter is needed note process types are not currently used for electronic prior authorization value null request example { "recipients" \[ { "qualifier" "d", "id" "6598607334001" } ], "products" \[ { "id" "epa", "processtypes" null } ] } worklist summary response http status codes http status code description 200 successful response 400 invalid request description message body json fields field description product name of the product value epa low integer representing the count of active tasks with a low priority note currently epa does not use priority types for messages medium integer representing the count of active tasks with a medium priority note currently epa does not use priority types for messages high integer representing the count of active tasks with a high priority note currently epa does not use priority types for messages urgent integer representing the count of active tasks with an urgent priority note currently epa does not use priority types for messages alert integer representing the count of active tasks with an alert priority note currently epa does not use priority types for messages total integer representing the total count of active tasks json response example \[ { "product" "epa", "low" 0, "medium" 0, "high" 0, "urgent" 0, "alert" 0, "total" 6 } ] complete tasks completing a task sets the status of the task to complete and moves the process on to the next task, if there is one in many cases this could mean also completing the process not all task types are allowed to be completed via this api because user interaction may be required to complete the task the results of the complete api call will indicate which tasks were allowed to be completed via api complete tasks by taskids request template \[post] {{host}}/uiservice/api/v0/complete/tasks request json fields json field data type code description taskids list\<long> mandatory list the ids of the tasks for completion request example \[post] https //\[host]/uiservice/api/v0/complete/tasks \[83756, 83757, 83759, 83786] complete tasks by taskids response response codes and fields httpstatus code description 200 successful response 400 invalid request description message body json fields collection of the following json items field description taskid the taskid requested to be completed error null if successful reason for non completion if not successful complete response example { "taskid" 83756, "error" "task 83756 has already been completed" } { "taskid" 83757, "error" "task 83757 is not configured to be completed via an external api call " } { "taskid" 83759 } { "taskid" 83786 } complete tasks by recipientid attempts to complete the tasks associated with the given user request template \[post] {{host}}/uiservice/api/v0/complete/recipients/tasks description of json fields json field data type code description recipients list mandatory collection of recipients for which accelerator based tasks will attempt to be complete qualifier an 1 mandatory spi's corresponding qualifier value d id an 13 mandatory spi of the provider products list conditional required if request should be restricted to specific products if not sent, surescripts will attempt to complete tasks for all eligible products example epa id an 5 conditional product id at least one product id is required if ‘products’ is used value epa processtypes an 12 conditional required if process types filter is needed note process types are not currently used for electronic prior authorization value null request example \[post] https //\[host]/uiservice/api/v0/complete/recipients/tasks { "recipients" \[ { "qualifier" "d", "id" "6223034442001" } { "qualifier" "d", "id" "6223044592002" } ], "products" \[ {"id" "epa"} ] } complete tasks by recipient response response codes and fields httpstatus code description 200 successful response 400 invalid request description message body json fields field description list\<long> the list of task ids that were successfully completed by this call