Skip to content
KiweelyKiweelyKiweely

Approving, Denying, and Sending Back Workday Business Process Steps via REST and SOAP APIs

Advance pending Workday workflow steps via businessProcess v1 REST endpoints (/eventSteps/{ID}/approve, /deny, /sendBack, /toDo, /reassign) using the Event Record WID, or via Integrations SOAP operations (Approve_Business_Process, Deny_Business_Process, Send_Back_Business_Process).

  • Checked against Workday on
  • Applies to Workday Business Processes & APIs
  • 7 min read
  • Published
  • By Kiweely
On this page

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:

http
GET /ccx/api/businessProcess/v1/{tenant}/eventSteps/7ad3143787b64ee8937b33fbc1198356 HTTP/1.1
Accept: application/json

Check three properties in the response before choosing an action endpoint:

  1. status.descriptor: Confirm it equals "Awaiting Action".
  2. 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 /approve fails with A190).
    • "Complete Questionnaire" -> must use POST /eventSteps/{ID}/questionnaire with stepAction and questionnaireResponse.
    • Domain-specific "Action" steps (for example, Enter PayGroup during Hire or Accept Shift Swap) require completing the functional domain payload rather than a bare /approve call.
  3. event.id: Save the parent Event WID if you also need to read GET /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)

http
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):

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

http
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"
json
{
  "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

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

xml
<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 when Disable Comments is 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, if Disable Comments is active (globally synced or locally overridden on the Business Process Security Policy), sending a comment string returns error A1573 (You can't comment on this business process type) in REST or a Validation_Fault in SOAP (This Business Process has been configured to disable comment). Conversely, when comments are enabled, omitting comment on REST /approve or /deny returns A181.
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.

Sources checked

Related guides

All guides

Let Workday check the work.

Kiweely writes WQL and builds orchestrations in your own tenant, and Workday, not Kiweely, says whether they passed.

Get the next guide in your inbox.

One email a month with new guides and one Extend tip. Nothing else.

We’ll email you once to confirm. Unsubscribe in one click from any issue.