To advance an awaiting-action workflow step in Workday, call the businessProcess/v1 REST resource on the specific Event Record Workday ID (POST /eventSteps/{ID}/approve, /deny, /sendBack, /toDo, or /reassign), or invoke the Integrations SOAP web service (Approve_Business_Process, Deny_Business_Process, Send_Back_Business_Process, Reassign_Business_Process_Step). Use the REST eventSteps endpoints whenever a user-delegated OAuth client acts on a specific My Tasks item, especially on business processes with parallel approval branches.
Most 400 Bad Request and SOAP Validation_Fault failures when advancing workflows come from three mismatches: passing the parent Event WID where Workday expects the step’s Event Record WID, calling /approve on a To Do or Action step type, or violating tenant comment rules (Disable Comments vs. required comment / reason fields).
REST businessProcess/v1 vs. SOAP Integrations Step Operations
Before writing client code, verify which ID type, security domain, and payload contract each operation expects:
| Workflow Action | REST businessProcess/v1 Endpoint |
Target Path ID | SOAP Integrations Operation |
SOAP Target Element | Required Body Fields (REST) |
|---|---|---|---|---|---|
| Workflow ActionApprove Step | REST businessProcess/v1 EndpointPOST /eventSteps/{ID}/approve |
Target Path IDEvent Record WID |
SOAP Integrations OperationApprove_Business_Process |
SOAP Target ElementEvent_Reference (WID or Ref ID) |
Required Body Fields (REST)comment (unless comments disabled) |
| Workflow ActionDeny Step | REST businessProcess/v1 EndpointPOST /eventSteps/{ID}/deny |
Target Path IDEvent Record WID |
SOAP Integrations OperationDeny_Business_Process |
SOAP Target ElementEvent_Reference (WID or Ref ID) |
Required Body Fields (REST)id, comment, and stepAction.id (when multiple actions exist) |
| Workflow ActionSend Back Step | REST businessProcess/v1 EndpointPOST /eventSteps/{ID}/sendBack |
Target Path IDEvent Record WID |
SOAP Integrations OperationSend_Back_Business_Process |
SOAP Target ElementEvent_Reference (Action_Event WID) |
Required Body Fields (REST)id, to.id (target prior step), reason |
| Workflow ActionComplete To Do | REST businessProcess/v1 EndpointPOST /eventSteps/{ID}/toDo |
Target Path IDEvent Record WID |
SOAP Integrations Operation(Event-specific / service step) | SOAP Target Element— | Required Body Fields (REST)stepAction.id (Submit or Save for Later); optional comment |
| Workflow ActionReassign Step | REST businessProcess/v1 EndpointPOST /eventSteps/{ID}/reassign |
Target Path IDEvent Record WID |
SOAP Integrations OperationReassign_Business_Process_Step |
SOAP Target ElementEvent_Record_Reference (WID) |
Required Body Fields (REST)addAssignees and/or removeAssignees; optional comment |
| Workflow ActionCancel / Rescind Event | REST businessProcess/v1 EndpointPOST /events/{ID}/cancel or /rescind |
Target Path IDParent Event WID |
SOAP Integrations OperationCancel_Business_Process / Rescind_Business_Process |
SOAP Target ElementEvent_Reference (Action_Event WID) |
Required Body Fields (REST)comment |
All businessProcess/v1 step-action endpoints are secured by the Core Navigation and Public Business Processes domains (available under Functional Areas including Tenant Non-Configurable, Benefits, and Adaptive Planning), intersected with the authenticated caller’s view and action permissions on the underlying business process security policy.
Step 1: Confirm Event Record WID and stepType Before Acting
Never hardcode /approve for every item in a worker’s queue. First, inspect the pending step via Workday’s inboxTasks or eventSteps read endpoints:
GET /ccx/api/businessProcess/v1/{tenant}/eventSteps/7ad3143787b64ee8937b33fbc1198356 HTTP/1.1
Accept: application/jsonCheck three properties in the response before choosing an action endpoint:
status.descriptor: Confirm it equals"Awaiting Action".stepType.descriptor:"Approval"or"Approval Chain"or"Consolidated Approval"-> eligible for/approve,/deny(if allowed by policy), or/sendBack."To Do"-> must use/toDo(calling/approvefails withA190)."Complete Questionnaire"-> must usePOST /eventSteps/{ID}/questionnairewithstepActionandquestionnaireResponse.- Domain-specific
"Action"steps (for example, Enter PayGroup during Hire or Accept Shift Swap) require completing the functional domain payload rather than a bare/approvecall.
event.id: Save the parentEventWID if you also need to readGET /events/{ID}/attachments,/comments, or/completedSteps.
Step 2: Executing REST approve, deny, sendBack, and toDo Calls
Every successful POST to a businessProcess/v1 step action returns HTTP 201 Created with the updated step payload and resulting eventStatus.
Approving an Approval Step (/approve)
POST /ccx/api/businessProcess/v1/{tenant}/eventSteps/7ad3143787b64ee8937b33fbc1198356/approve HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"comment": "Reviewed coverage and approved."
}Denying an Approval Step (/deny)
POST /eventSteps/{ID}/deny requires the step’s id in the JSON body alongside comment (and stepAction with { "id": "..." } when multiple step actions are available on that step):
POST /ccx/api/businessProcess/v1/{tenant}/eventSteps/7ad3143787b64ee8937b33fbc1198356/deny HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"id": "7ad3143787b64ee8937b33fbc1198356",
"comment": "Duplicate submission for the same dates; Nov 24-25 request is already approved."
}Sending Back a Step to a Prior Actor (/sendBack)
Before calling /sendBack, discover which prior steps the workflow allows sending back to via GET /ccx/api/businessProcess/v1/{tenant}/values/sendBack/to/ (passing the step context). Then submit id, to (the target step WID), and reason:
POST /ccx/api/businessProcess/v1/{tenant}/eventSteps/7ad3143787b64ee8937b33fbc1198356/sendBack HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"id": "7ad3143787b64ee8937b33fbc1198356",
"to": {
"id": "d9e4108c446c11de98360015c5e6daf6"
},
"reason": "Please attach itemized hotel folio showing daily room rate and tax breakdown."
}Completing a To Do Step (/toDo)
Workday defines fixed WIDs for stepAction on POST /eventSteps/{ID}/toDo:
- Submit:
"133d5c88baa64136aab041c1d2e9ed53" - Save for Later:
"d9e41d34446c11de98360015c5e6daf6"
{
"stepAction": {
"id": "133d5c88baa64136aab041c1d2e9ed53"
},
"comment": "Badge and safety orientation checklist completed."
}Step 3: Advancing Steps via SOAP (Integrations Service)
When working with legacy integrations or workflows where only the parent Event WID or Reference ID is on hand, Workday’s Integrations WSDL (https://{hostname}/ccx/service/{tenant}/Integrations/v43.0) provides Approve_Business_Process, Deny_Business_Process, and Send_Back_Business_Process. These SOAP operations accept an OAuth 2.0 Bearer access token header in place of WS-Security username headers when called on behalf of a signed-in worker.
SOAP Approve_Business_Process Example
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:bsvc="urn:com.workday/bsvc">
<soapenv:Header/>
<soapenv:Body>
<bsvc:Approve_Business_Process_Request bsvc:version="v43.0">
<bsvc:Event_Reference>
<bsvc:ID bsvc:type="WID">f1208b90446c11de98360015c5e6daf6</bsvc:ID>
</bsvc:Event_Reference>
<bsvc:Approve_Business_Process_Data>
<bsvc:Comment>Approved after verifying cost center budget.</bsvc:Comment>
</bsvc:Approve_Business_Process_Data>
</bsvc:Approve_Business_Process_Request>
</soapenv:Body>
</soapenv:Envelope>SOAP Send_Back_Business_Process Example
Note that SOAP Send_Back_Business_Process takes the Business_Process_Step_ID Reference ID (for example, from Workflow_Step_ID on the business process definition) rather than the runtime Event Record WID:
<bsvc:Send_Back_Business_Process_Request bsvc:version="v43.0">
<bsvc:Event_Reference>
<bsvc:ID bsvc:type="WID">f1208b90446c11de98360015c5e6daf6</bsvc:ID>
</bsvc:Event_Reference>
<bsvc:Send_Back_Business_Process_Data>
<bsvc:Business_Process_Step_ID>REQUEST_TIME_OFF_INITIATION</bsvc:Business_Process_Step_ID>
<bsvc:Comment>Adjust hours on Friday from 8 to 4 to match half-day holiday schedule.</bsvc:Comment>
</bsvc:Send_Back_Business_Process_Data>
</bsvc:Send_Back_Business_Process_Request>Also note embedded Business_Process_Parameters on domain-initiating SOAP operations (such as Enter_Time_Off in Absence_Management, Submit_Expense_Report or Submit_Requisition in Resource_Management, and Change_Job in Staffing): setting <bsvc:Auto_Complete>true</bsvc:Auto_Complete> bypasses downstream approvals only when called by an authorized integration security group during data loads or pre-approved system syncs. Never enable Auto_Complete on employee self-service submissions, or you will skip manager approval chains completely.
Comment Sync Rules and Common Validation Errors (400 / Validation_Fault)
Workday’s comment configuration trips up API callers because Disable Comments exists in two places—globally on Edit Tenant Setup - Business Processes and locally on each Business Process Security Policy:
- Actions Exempt from
Disable Comments: Even whenDisable Commentsis checked, Workday still accepts (and requires) reasons on Deny, Send Back, Cancel, Rescind, Correct, Manual Advance, and Add Approvers. - Approvals Under
Disable Comments: On Approve and To Do steps, ifDisable Commentsis active (globally synced or locally overridden on the Business Process Security Policy), sending acommentstring returns errorA1573(You can't comment on this business process type) in REST or aValidation_Faultin SOAP (This Business Process has been configured to disable comment). Conversely, when comments are enabled, omittingcommenton REST/approveor/denyreturnsA181.
| Error Code / SOAP Fault | Exact Meaning & Root Cause | Fix |
|---|---|---|
Error Code / SOAP FaultA181 (Specify a comment / A comment is required) |
Exact Meaning & Root CauseREST /approve or /deny body omitted comment on a BP where comments are enabled. |
FixPass a non-empty comment string in the JSON request body. |
Error Code / SOAP FaultA1573 (You can't comment on this business process type) |
Exact Meaning & Root CauseDisable Comments is enabled on Edit Tenant Setup - Business Processes or the BP Security Policy. |
FixOmit comment for that business process type or uncheck Disable Comments on the BP Security Policy. |
Error Code / SOAP FaultA190 (This event step type cannot be approved) |
Exact Meaning & Root CauseCaller sent /approve to a To Do, Questionnaire, or Action step. |
FixInspect stepType on GET /eventSteps/{ID} and route To Do steps to /toDo. |
Error Code / SOAP FaultA183 / A225 (Cannot be denied / Not authorized to deny) |
Exact Meaning & Root CauseStep type does not support denial, or caller’s security group is absent from Who Can Deny on the BP Security Policy. | FixVerify Deny permissions on Business Process Policy > Edit or offer Send Back instead. |
Error Code / SOAP FaultA212 (This event step is not awaiting your action) |
Exact Meaning & Root CauseWrong WID passed (such as parent Event WID), step already completed by another approver, or caller lacks assignment/delegation. |
FixPass the Event Record WID and refresh queue state gracefully on A212. |
Error Code / SOAP FaultA202 / A227 (Step sending back to/from isn't supported) |
Exact Meaning & Root CauseTarget step in to.id is not a valid prior step, or Send Back is disallowed on this step. |
FixPopulate valid destinations dynamically from GET /values/sendBack/to/. |
Error Code / SOAP FaultSOAP: This task has been delegated to another user and cannot be Denied |
Exact Meaning & Root CauseDelegator unchecked Retain Access to Delegated Tasks within My Tasks when delegating. |
FixHave the active delegate act on the step, or update delegation retention settings. |
When building external approval screens with Kiweely Leaf or connecting AI assistants through Kiweely Bridge (both coming next), each approval or send-back executes under the signed-in manager’s own Workday OAuth session—preserving every Business Process Security Policy check and recording the human approver in Workday’s process audit history.
Frequently asked questions
What ID does POST /businessProcess/v1/eventSteps/{ID}/approve expect in the URL path?
It expects the 32-character lowercase hexadecimal Workday ID (WID) of the awaiting Event Record (the individual business process step returned by GET /common/v1/workers/me/inboxTasks or GET /businessProcess/v1/eventSteps), not the WID of the parent Event.
Why does SOAP Approve_Business_Process take an Event_Reference while REST /eventSteps/{ID}/approve takes an Event Record WID?
The legacy Integrations SOAP operations (Approve_Business_Process, Deny_Business_Process, Send_Back_Business_Process) target the parent Event_Reference and advance the step awaiting the caller, whereas the modern businessProcess v1 REST API addresses the exact Event Record step resource directly—avoiding ambiguity when an event has parallel in-progress steps.
Is a comment required when approving or denying a step through the Workday REST API?
In businessProcess v1 REST, both /approve and /deny validate that a comment field is provided (returning HTTP 400 error A181 if omitted), unless comments are disabled on Edit Tenant Setup - Business Processes or the Business Process Security Policy (which returns A1573 if a comment is sent).
How do I complete a To Do step instead of an Approval step via REST?
Calling /approve on a To Do step fails with error A190 ('This event step type cannot be approved'). Instead, call POST /businessProcess/v1/eventSteps/{ID}/toDo with stepAction set to { id: '133d5c88baa64136aab041c1d2e9ed53' } for Submit.