--- category: [Administration & Integrations, Administration & Integrations/Workday API, Platform and Product Extensions, Platform and Product Extensions/Integration, Administration & Integrations/Custom Integrations & Apps, Platform and Product Extensions/Workday Extend] keyword: [Business Process, BP, Extend BP, Extend Pro, Subprocess, Orchestration, Model Component BP, BP Event] nav: wcp_docs parent_url: /wcp_docs/ title: Events REST APIs layout: subsection --- ## Overview The Events REST API in the Business Process REST service enables apps to: - Retrieve information about Workday-delivered and Extend business process events, specifically: - Initiator, effective date, due date, completion date. - Status of the business process event. - Parent business process or subprocess. - In-progress, completed, and remaining steps - Business object the business process is for. - Comments. - Attachments. - Cancel or rescind the event. For reference documentation about the Events REST APIs, see `businessProcess/events` in the [REST API Explorer on the Developer Site](https://developer.workday.com/rest-api-explorer) or [Workday REST Services Directory](https://community.workday.com/sites/default/files/file-hosting/restapi/index.html?lang=en-us). ## URL Base Path Tenant Base Path `https://{tenantHostname}/api/businessProcess/{version}/{tenantName}` . Example: `https://yourTenantHostName.com/api/businessProcess/v1/gms` . Workday Extend and Integration API Gateway Base Path For Workday Extend and Integration apps, use the API Gateway URL for the region of your company. See [Reference: Workday Extend API Gateways and Authorization Base URLs](https://developer.workday.com/documentation/dlh1653340161856) on the Developer Site. Example for US region: `https://api.workday.com/businessProcess/v1` ## Workday Tasks This table lists the Events REST API endpoints that are equivalent to these Workday tasks.
Workday TaskEndpoint
Cancel action (from a button on a business process step or as a related action)POST /events/{id}/cancel
Find Events > View Event > Process Tab (In-Progress Steps)GET /events/{ID}/inProgressSteps
Find Events > View Event > Process Tab (Completed Steps)GET /events/{ID}/completedSteps
Find Events > View Event > Process Tab (Remaining Steps)GET /events/{ID}/remainingSteps
Find Events > View Event > Process Tab > Comments columnGET /events/{ID}/comments

## Security Considerations The same security framework applies to both Workday-delivered and Extend business processes. The Events APIs use these primary security domains: - Core Navigation: Controls access to the user navigation in the Workday application. This security domain belongs to several functional areas, which are listed as Scopes in the Open API Specifications. - Public Business Processes in the Tenant Non-Configurable functional area: Controls access to business processes. This security domain is different from the business process security policies. The Events API endpoint descriptions list the security domains in the Open API Specifications. Consider these guidelines: - To view the security context of a business process event in Workday, select Business Process > View Security as a related action from the business process event. This task is secured by the Business Process Administration domain in the System functional area. - In an Extend app, define security domains for your Extend business processes and use the same security mechanisms to define a business process policy through App Manager. - If you need to trigger an orchestration from a Workday-delivered business process, you’ll need to set up orchestration credentials using either the Integration System User (ISU) or the initiating user authentication type. See [Trigger an Orchestration from a Business Process](https://developer.workday.com/documentation/kcz1625656998198). ## Prerequisites For Workday-delivered business processes: - Configure the business process definition in the tenant. See [Setup Considerations: Business Processes](https://doc.workday.com/admin-guide/en-us/manage-workday/business-processes/business-process-framework-concepts/khy1593557050505.html?toc=6.0.0) . - Configure the business process security policy in the tenant. See [Edit Business Process Security Policies](https://doc.workday.com/admin-guide/en-us/authentication-and-security/configurable-security/security-policies/dan1370796362110.html?toc=2.4.2) . For Extend business processes: - Configure an Extend business object for the business process. - Configure the business process in App Builder. See [Add Business Processes in Visual Mode](https://developer.workday.com/documentation/cvo1664795778240) . - Create the business process security domain in App Builder and configure it in App Manager. See [Add Security Domains in Visual Mode](https://developer.workday.com/documentation/cvo1664795778240) . - Create app pages for routing. See [Add Pages in Visual Mode](https://developer.workday.com/documentation/GUID-04c93222-0401-49c9-a223-a78f0a365501). - For the cancel and rescind endpoints, Extend processes must have Enable Cancellation and Enable Rescind fields set to true. Note: A Rescind action in Workday Extend only marks the business process event as rescinded. It doesn’t roll back any data. To force a rollback, create a custom orchestration that performs the required 'rollback' actions. ## Business Processes - A Workday-delivered business process event is initiated on a Workday-delivered business object from its corresponding Workday UI task or REST API in the corresponding Workday REST service. An Extend business process is initiated from an app using the Extend Business Process Event REST API. An Extend business process can also be initiated from a Workday-delivered business process in these ways: - You can add a Workday Business Process orchestration to the app and configure a Business Process Trigger step that specifies the input data from the business process. In the tenant, add the Orchestration Service step to the business process definition. For details, see [Trigger an Orchestration from a Business Process](https://developer.workday.com/documentation/kcz1625656998198). - You can configure the Extend business process to run as a subprocess of a selected Workday-delivered parent business process. This configuration enables you to embed custom business logic and processes created in Extend directly into standard, Workday-delivered workflows. For details, see [Add Parent Business Process to Extend Subprocess](https://developer.workday.com/documentation/GUID-bf7ef8cb-6300-46e2-a4a2-122dba844794-enHYPHENus). ## Integration Touchpoints Business Process REST APIs are critical for integrating Workday business processes with other systems and Workday components. - Orchestrations: Orchestrate can trigger Business Processes and invoke Workday APIs. To call an Extend business process from orchestration: - In the business process configuration, set the Enable for Orchestrate field (or `useForOrchestrate` attribute) to true. - In the orchestration, add the Send API Request component to call the POST endpoint that initiates the Extend business process event. Example: An orchestration can fetch CSV data, load it to an Extend business object, then trigger a business process. You can enable a business process for Async orchestrations by setting Enable for Orchestrate (or `useForOrchestrate` attribute) to true in the business process configuration in App Builder. Set this attribute to true when you want the orchestration to pause when the business process starts, and to resume when the Orchestration Service step configured on the business process definition resumes the orchestration. You can configure a Workday-delivered business process to automatically launch an orchestration when any of these actions are performed on an event step: Cancel, Rescind, Correct, Deny. These orchestrations must be based on the Workday Business Process template. For details, see [Launch Orchestrations on Business Process Status Changes](https://developer.workday.com/documentation/GUID-9b1d837c-fd73-4768-92d7-40b9ed06ac25). Extend business processes also support orchestrations on Cancel, Rescind and Deny actions. - Extend Subprocesses: Extend business processes can be configured to run as a subprocess of selected Workday-delivered business processes. The Extend subprocess event target changes from the parent business process event to an Extend business object instance after the initiation step. Workday saves the event history of an Extend subprocess within the parent Workday-delivered business process event history. An Extend subprocess creates a task in "My Tasks" which then triggers the Extend business process. - Third-Party Integrations: Interaction with external services or other third-party systems through the REST API can be part of processes triggered by or interacting with business processes. ## Getting a List of Events You can get a list of business process events that are either: - About a worker, which is the target business object. To get the events for a worker, call `GET /events` with the `worker` query parameter. - Initiated by a specific user. If the target business object is a worker, the initiator can be different from the target worker. To get the events initiated by a particular user, call `GET /events` with the `initiator` query parameter. The `GET /events` endpoint requires either the `worker` or `initiator` query parameter. To filter the list of events by the business process type, specify the `businessProcess` query parameter. To get the ID of the business process type: - Use the Find Events report to search by the business process name. - On the Business Process Name , click the Related Actions menu, and view its Integration ID. Example: Get events about a worker This example gets events for Beth Liu that were initiated on or after a certain date. The `worker` query parameter specifies the Workday ID of Beth Liu. Sample request: ``` GET /events?worker=3bcc416214054db6911612ef25d51e9f&initiatedOnOrAfter=2024-06-01 ``` Sample response: ``` { "data": [ { "for": { "descriptor": "Beth Liu", "id": "3bcc416214054db6911612ef25d51e9f" }, "descriptor": "Give Feedback: Beth Liu", "id": "98003ba86b421000bd918d4214200000", "status": { "descriptor": "Successfully Completed", "id": "b90bc51be01d4ae99b603b02b073714d" }, "overallBusinessProcess": { "descriptor": "Give Feedback: Beth Liu", "id": "98003ba86b421000bd918d4214200000" }, "initiator": { "descriptor": "Logan McNeil (On Leave)", "id": "3aa5550b7fe348b98d7b5741afc65534" }, "completedDate": "2024-12-09T16:55:35.020Z", "creationDate": "2024-12-09", "dueDate": "2024-12-10" }, { "for": { "descriptor": "P-00010 Director, Payroll Operations - Beth Liu", "id": "aa1562e740aa48739aded3c3cbe056a4" }, "descriptor": "Title Change: Beth Liu", "id": "33126fde95be1008704003147a720000", "status": { "descriptor": "Successfully Completed", "id": "b90bc51be01d4ae99b603b02b073714d" }, "overallBusinessProcess": { "descriptor": "Title Change: Beth Liu", "id": "33126fde95be1008704003147a720000" }, "initiator": { "descriptor": "Logan McNeil (On Leave)", "id": "3aa5550b7fe348b98d7b5741afc65534" }, "completedDate": "2024-12-06T17:30:58.528Z", "effectiveDate": "2024-12-06", "creationDate": "2024-12-06", "dueDate": "2024-12-08" }, . . . ], "total": 25 } ``` Example: Get events about a worker for a business process type This example gets the Title Change events for Lincoln Cook. The `businessProcess` query parameter specifies the Workday ID of the Title Change business process type. Sample request: ``` GET /events?worker=Employee_ID=21295&businessProcess=15c5d891b0af46fe8ea9857985449cae ``` Sample response: ``` { "data": [ { "for": { "descriptor": "P-00397 Customer Service Representative - Lincoln Cook", "id": "1f78293acefb4ccebb5213c9d6bb2a97" }, "descriptor": "Title Change: Lincoln Cook", "id": "e9a9f59f7bf01001d02d80dd2b970000", "status": { "descriptor": "Successfully Completed", "id": "b90bc51be01d4ae99b603b02b073714d" }, "overallBusinessProcess": { "descriptor": "Title Change: Lincoln Cook", "id": "e9a9f59f7bf01001d02d80dd2b970000" }, "initiator": { "descriptor": "Logan McNeil (On Leave)", "id": "3aa5550b7fe348b98d7b5741afc65534" }, "completedDate": "2026-04-24T02:37:56.093Z", "effectiveDate": "2026-04-23", "creationDate": "2026-04-23", "dueDate": "2026-04-25" } ], "total": 1 } ``` Example: Get events by initiator This example gets events that were initiated by Joy Banks on or after a certain date. The `initiator` query parameter specifies the Workday ID of Joy Banks. This example uses a sample Extend business process, Create Work Event. Sample request: ``` GET /events?initiator=1f8ff0a1f91410f6cb260e1be5fe0b91&initiatedOnOrAfter=2024-12-01 ``` Sample response: ``` { "data": [ { "for": { "descriptor": "Lunar New Year", "id": "9a6a199318249001b7b9c9667b510000" }, "descriptor": "Create Work Event: Lunar New Year", "id": "9a6a199318249001b7b9e76408c00000", "status": { "descriptor": "In Progress", "id": "e2d08afc53614c37b32b31270bb8bee3" }, "creationDate": "2025-01-23", "overallBusinessProcess": { "descriptor": "Create Work Event: Lunar New Year", "id": "9a6a199318249001b7b9e76408c00000" }, "initiator": { "descriptor": "Joy Banks", "id": "1f8ff0a1f91410f6cb260e1be5fe0b91" } } ], "total": 1 } ``` ## Getting the Steps of an Event by Status You can get the in-progress, completed, and remaining steps of a business process event by using these endpoints: - `GET /events/{ID}/inProgressSteps` - `GET /events/{ID}/completedSteps` - `GET /events/{ID}/remainingSteps` Example: Get the In-Progress Steps This example gets a list of the Create Work Event steps that are in-progress. The Create Work Event business process is a sample Extend business process. Sample request: ``` GET /events/a6f4dc4218b89000d7f4017a3bf80000/inProgressSteps ``` This sample response shows the approval step as the in-progress step, along with the status and awaiting person: ``` { "data": [ { "anonymous": false, "descriptor": "Approval by Manager", "businessProcessStep": { "descriptor": "Create Work Event (Default Definition) step b - Approval", "id": "6c65436bb5531003ed9fdbe144230000" }, "id": "a6f4dc4218b89000d7f4051360dd0001", "order": "b", "status": { "descriptor": "Awaiting Action", "id": "d9e4108c446c11de98360015c5e6daf6" }, "awaitingPersons": [ { "descriptor": "Joy Banks", "id": "1f8ff0a1f91410f6cb0bcc3076ee0b58" } ], "creationDate": "2025-01-28T00:51:04.459Z" } ], "total": 1 } ``` Example: Get the Completed Steps This example gets a list of the completed steps for the Create Work Event. Sample request: ``` GET /events/a6f4dc4218b89000d7f4017a3bf80000/completedSteps ``` This sample response shows the completed steps, the person who completed the step, and the completion date. ``` { "data": [ { "event": { "descriptor": "Create Work Event: Anniversary Party", "id": "a6f4dc4218b89000d7f4017a3bf80000" }, "descriptor": "Create Work Event", "id": "a6f4dc4218b89000d7f40213c22c0000", "completedByPerson": { "descriptor": "Logan McNeil", "id": "9feb1da3167840a9852698a2f228f795" }, "creationDate": "2025-01-28T00:51:04.459Z", "completedDate": "2025-01-28T00:51:04.459Z", "order": "a", "status": { "descriptor": "Step Completed", "id": "d9e41366446c11de98360015c5e6daf6" } } ], "total": 1 } ``` Example: Get the Remaining Steps This sample request gets a list of the Create Work Event steps that are remaining. Sample request: ``` GET /events/a6f4dc4218b89000d7f4017a3bf80000/remainingSteps ``` This sample response shows the remaining action step, along with the assigned group: ``` { "data": [ { "stepType": { "descriptor": "Action", "id": "d8c89128446c11de98360015c5e6daf6" }, "step": "Book Event Space", "descriptor": "Create Work Event (Default Definition) step c - Action", "groups": [ { "descriptor": "HR Administrator", "id": "7e1c5e73b2de4667a42041d1f9d3eef9" } ], "id": "6c65436bb5531003ed9fdaae185d0000", "order": "c", "completionStep": false } ], "total": 1 } ``` ## Canceling an Event To cancel or immediately end a business process event, call the `POST /events/{ID}/cancel` endpoint. This example cancels a home contact change business process event, whose Workday ID is specified as the event ID. Sample request: ``` POST /events/f4edd719789a10016c7addfdfa1b0000/cancel { "comment": "Cancel home contact info change" } ``` Sample response: ``` { "comment": "Cancel home contact info change", "descriptor": "Home Contact Change: Teresa Serrano", "id": "f4edd719789a10016c7addfdfa1b0000", "status": "Canceled" } ``` ## Rescinding an Event To rescind or reverse a completed business process, call the `POST /events/{ID}/rescind` endpoint. This example rescinds a change job business process event, whose Workday ID is specified as the event ID. Sample request: ``` POST /events/49367bfa904f10009759749ac9310000/rescind { "comment": "Rescind the change job location request" } ``` Sample response: ``` { "descriptor": "Data Change: Maria Cardoza (Rescinded)", "id": "49367bfa904f10009759749ac9310000", "status": "Rescinded" } ``` ## Limitations - The Business Process APIs don't support bulk operations. Data needs to be processed individually row by row. Submitting a large volume of events can impact tenant health due to the shared business process framework. ## Performance Considerations Avoid submitting a large volume of events simultaneously as it can impact tenant health due to the shared business process framework. ## Common Errors
ErrorCause and Solution
400 error when triggering Business Process.Possible causes include incorrect businessProcessTarget or security issues. Verify the businessProcessTarget ID and ensure the API client has the necessary permissions.
Orchestration service step stuck 'in progress'.Occurs when a Workday-delivered BP triggers an Extend business process, which then completes, but the parent step remains stuck. Check business process security and ensure the Extend business process is configured and invoked correctly.
Orchestration not completing / returning "Failed" status.Orchestrations triggered by a business process might not complete or return a "Failed" status to the underlying business process through an integration step.
Permission Denied Error for Studio Integration calling Business Process API.Occurs when Studio tries to call the API for business process events without adequate permissions. Ensure the Studio integration has the necessary security access.

## Reference Apps - [App Catalog: Charitable Donations](https://developer.workday.com/app-catalog/charitableDonations) - [App Catalog: Create a Work Event](https://developer.workday.com/app-catalog/createAWorkEvent) - [App Catalog: Project Forecasting](https://developer.workday.com/app-catalog/projectForecasting) - [App Catalog: Tuition Reimbursement](https://developer.workday.com/app-catalog/tuitionReimbursement) - [App Catalog: Vaccine Management](https://developer.workday.com/app-catalog/vaccineManagement)