Skip to content
KiweelyKiweelyKiweely

Querying Pending Workday My Tasks and Inbox Approvals via API and WQL

Retrieve pending Workday My Tasks items for the signed-in worker via GET /common/v1/workers/{ID}/inboxTasks, or query awaiting approvals with WQL data sources such as businessProcessTransactionsAwaitingMyAction and businessProcessStepsAwaitingMe alongside businessProcess v1 REST calls.

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

To query pending Workday My Tasks (formerly Inbox) items for the signed-in user, call GET /common/v1/workers/{ID}/inboxTasks for a lightweight task list, or execute Workday Query Language (WQL) against businessProcessTransactionsAwaitingMyAction (event-level) and businessProcessStepsAwaitingMe (step-level Event Record rows). When acting on a step—approving, denying, sending back, reassigning, or submitting a To Do—pair those reads with /businessProcess/v1/eventSteps/{ID}.

Integrations, custom approval portals, and external AI connectors often stumble because Workday splits pending workflow state across two distinct business objects: the parent Event (or Action Event, representing the overall business process transaction such as Request Time Off or Expense Report Event) and the child Event Record (representing the individual routing step currently awaiting one or more workers). Picking the wrong endpoint or WQL data source either drops parallel steps, misses items excluded from My Tasks, or leaves you without the Event Record Workday ID needed to call /approve.

Comparing Workday REST Endpoints and WQL Data Sources for Pending Tasks

Choose your read path based on whether you are building a personal queue for the signed-in employee, a step-action client, or a cross-worker bottleneck audit:

Access Path Primary Object Security Domain & Scope Key Filter Parameters Best Use Case
Access PathGET /common/v1/workers/{ID}/inboxTasks Primary ObjectinboxTaskSummary (Event Record) Security Domain & ScopeCore Navigation (Tenant Non-Configurable scope) Key Filter ParametersID (or me), limit, offset Best Use CaseFast My Tasks badge counts and personal approval lists (overallProcess, stepType, subject, assigned, due).
Access PathGET /businessProcess/v1/eventSteps Primary ObjectEvent Record Security Domain & ScopeCore Navigation, Public Business Processes Key Filter ParametersbusinessProcess, createdOnOrAfter, createdOnOrBefore, dueDateOnOrAfter, dueDateOnOrBefore, stepType Best Use CaseRetrieving actionable event step IDs to pass into /eventSteps/{ID}/approve, /deny, or /toDo.
Access PathGET /businessProcess/v1/events Primary ObjectEvent Security Domain & ScopeCore Navigation, Public Business Processes Key Filter ParametersRequires worker; optional status, businessProcess, initiator, date ranges Best Use CaseInspecting in-progress events about a specific worker (/events/{ID}/inProgressSteps and /remainingSteps).
Access PathWQL: businessProcessTransactionsAwaitingMyAction Primary ObjectEvent Security Domain & ScopeWorkday Query Language + user’s BP view security Key Filter ParametersZero required built-in prompts (first50... variant also exists) Best Use CaseEvent-level summary of every transaction awaiting the signed-in caller, including daysPastDue and initiator.
Access PathWQL: businessProcessStepsAwaitingMe Primary ObjectEvent Record Security Domain & ScopeWorkday Query Language + user’s BP view security Key Filter ParametersPrompts for startDate & endDate; optional businessProcessesToInclude / Exclude Best Use CaseStep-level My Tasks filtering with step, stepType, completedByDelegate, and activeBusinessProcessDelegation.
Access PathWQL: businessProcessTransactionsAwaitingEmployeeID Primary ObjectEvent Security Domain & ScopeWorkday Query Language + constrained BP admin/manager view Key Filter ParametersBuilt-in worker ID prompt (see also allBusinessProcessTransactionsAwaitingPersons) Best Use CaseAuditing stuck approvals on a specific direct report, manager on leave, or departing worker.

For diagnosing why a workflow stalled on an unexpected approver in the tenant, see troubleshooting business processes awaiting action.

Reading Personal Queues via common/v1 and businessProcess/v1 REST APIs

When an external portal or assistant authenticates via a user-delegated OAuth client registered with Register API Client (Authorization Code Grant with PKCE), GET /common/v1/workers/me/inboxTasks is the fastest zero-configuration read because it is secured by Core Navigation under the Tenant Non-Configurable functional scope.

http
GET /ccx/api/common/v1/{tenant}/workers/me/inboxTasks?limit=25&offset=0 HTTP/1.1
Accept: application/json

Each item in data[] follows Workday’s inboxTaskSummary schema:

json
{
  "total": 2,
  "data": [
    {
      "id": "7ad3143787b64ee8937b33fbc1198356",
      "descriptor": "Approval by Manager",
      "stepType": {
        "id": "d9e41244446c11de98360015c5e6daf6",
        "descriptor": "Approval"
      },
      "status": {
        "id": "d9e41a8c446c11de98360015c5e6daf6",
        "descriptor": "Awaiting Action"
      },
      "overallProcess": {
        "id": "33e401f400214610bbfedddad82f7e65",
        "descriptor": "Request Time Off: Maya Lin"
      },
      "subject": {
        "id": "766f3df40606431e8229445f1fe283c3",
        "descriptor": "Maya Lin"
      },
      "initiator": {
        "id": "766f3df40606431e8229445f1fe283c3",
        "descriptor": "Maya Lin"
      },
      "assigned": "2026-11-14T16:20:00.000Z",
      "due": "2026-11-17T08:00:00.000Z"
    }
  ]
}

When you need deeper step context or want to inspect parallel steps on the parent event, pass overallProcess.id to GET /businessProcess/v1/events/{ID}/inProgressSteps and /events/{ID}/comments, or fetch the individual step via GET /businessProcess/v1/eventSteps/{ID}. Note Workday’s strict access check on /eventSteps/{ID}: if the signed-in caller lacks view access to the parent event, Workday returns HTTP 404 rather than leaking the step’s existence.

Watch out for the mandatory worker parameter trap on /businessProcess/v1/events:

http
# Returns a blank response because no worker parameter was supplied:
GET /ccx/api/businessProcess/v1/{tenant}/events?status=d9e41a8c446c11de98360015c5e6daf6

# Works: specifies exactly one worker ID to inspect events for that worker:
GET /ccx/api/businessProcess/v1/{tenant}/events?worker=766f3df40606431e8229445f1fe283c3

Step-Level vs. Event-Level WQL Queries (and Excluded My Tasks Steps)

REST /inboxTasks only accepts limit and offset, so sorting by daysPastDue, filtering out specific business process types, or finding tasks excluded from My Tasks requires WQL.

Why would an awaiting-action step be missing from My Tasks? On high-volume business process definitions (such as recruiting assessments or bulk expense checks), administrators use Business Process > Maintain My Tasks Display to exclude Action, Approval, or To Do steps from My Tasks. Once excluded after the effective date, those steps do not trigger My Tasks notifications, do not appear in My Tasks even if sent back or delegated, and cannot be moved with the standard Reassign Tasks task (requiring Mass Operation Management, the event’s Reassign This Task related action, or the Reassign Business Process Step web service instead; see reassigning awaiting-action steps).

Using WQL lets you query awaiting transactions cleanly with SQL predicates. Compare an event-level query against a step-level query:

Works
-- Event-level query: zero required built-in prompts, ideal for overdue triage
SELECT
  workdayID,
  businessProcessEvent,
  businessProcessStepAwaitingAction,
  subject,
  initiator,
  dateAndTimeInitiated,
  dueDate,
  daysSinceInitiated,
  daysPastDue,
  awaitingPersons
FROM businessProcessTransactionsAwaitingMyAction
WHERE inProgress = true
ORDER BY daysPastDue DESC, dateAndTimeInitiated ASC

If a parent business process has two parallel steps awaiting action at the same time, event-level data sources return one row per Event, whereas businessProcessStepsAwaitingMe returns one row per Event Record so you capture each individual step’s workdayID, stepType, and delegation metadata:

Works
-- Step-level query: returns 1 row per pending Event Record within date window
SELECT
  workdayID,
  overallProcess,
  businessProcessDefinition,
  step,
  stepType,
  subject,
  initiator,
  createdOn,
  dueDate,
  activeBusinessProcessDelegation
FROM businessProcessStepsAwaitingMe(
  startDate = '2026-09-01',
  endDate = '2026-11-15'
)
ORDER BY dueDate ASC

Completing Approvals and To Dos via `businessProcess/v1`

When submitting an action back to Workday, match the endpoint and required body fields to stepType:

  • Approval step: POST /businessProcess/v1/eventSteps/{ID}/approve with {"comment": "Approved after schedule check"} (comment is required by the OpenAPI schema).
  • Deny step: POST /businessProcess/v1/eventSteps/{ID}/deny with id, comment, and stepAction when multiple step actions exist.
  • To Do step: POST /businessProcess/v1/eventSteps/{ID}/toDo with {"stepAction": {"id": "133d5c88baa64136aab041c1d2e9ed53"}} for Submit (or d9e41d34446c11de98360015c5e6daf6 for Save for Later).

Verification Checklist Before Exposing Approvals Externally

  1. Authenticate per user, never via a shared ISU: Approving or reading My Tasks through an Integration System User (Register API Client for Integrations) attributes audit history to a service account instead of the human approver. Register a user-delegated client via Register API Client with Authorization Code Grant and PKCE so Workday’s Who Can Do Actions on Entire Business Process and step security policies evaluate the actual approver.
  2. Test delegated and terminated-worker edge cases: Verify how your query handles active delegations (activeBusinessProcessDelegation) and confirm your Termination and End Contingent Worker Contract definitions include Manage Business Processes for Worker or Auto-Manage Business Processes so steps do not strand on expired accounts.
  3. Require explicit human confirmation before POST .../approve or /deny: Never allow an automated script or conversational prompt to fire /approve without displaying the subject worker, business process details, and requested values to the approver first.

Teams connecting Workday My Tasks to external chat or custom approval views can use Kiweely Bridge (coming next) for user-delegated conversational reads with out-of-band browser write checks, or Kiweely Leaf (coming next) to embed stateless pass-through approval screens directly inside Microsoft Teams, Slack, DingTalk, Lark, or mobile browsers without storing HR data outside Workday.

Frequently asked questions

What is the difference between Workday Inbox and My Tasks in REST and WQL APIs?

Workday renamed the user-facing Inbox experience to My Tasks in the browser UI, while underlying REST paths such as GET /common/v1/workers/{ID}/inboxTasks keep the legacy inboxTasks resource name for backward compatibility. Both read the same underlying awaiting-action Event Record objects.

Why is an awaiting-action business process step missing from My Tasks?

Administrators can exclude high-volume Action, Approval, and To Do steps from My Tasks via Business Process > Maintain My Tasks Display. Excluded steps never appear in My Tasks—even if sent back, reassigned, or delegated—and must be queried via awaiting-action reports or WQL data sources.

Which REST API approves, denies, or completes a pending step?

The Workday businessProcess v1 REST API exposes POST /eventSteps/{ID}/approve (requires comment), POST /eventSteps/{ID}/deny (requires id, comment, and stepAction when applicable), POST /eventSteps/{ID}/sendBack, POST /eventSteps/{ID}/reassign, and POST /eventSteps/{ID}/toDo.

Why does GET /businessProcess/v1/events return a blank response?

Workday requires specifying exactly one worker query parameter on GET /businessProcess/v1/events. Omitting the worker parameter causes the endpoint to return a blank response rather than listing every business process event in the tenant.

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.