Using Accelerator Web Service API

80 min

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.

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 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 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 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 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 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 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

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 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 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 Response Status – “Denied” Response Field Description Response Status – “Open” Response Field Description 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.