Automating mobile receipt capture and expense submission in Workday uses a four-step workflow in the expense/v1 REST API (scoped to the Expenses functional area under Self-Service: Expense Report): stage a Quick Expense (POST /entries), upload the receipt image or PDF up to 32 MB (POST /entries/{ID}/attachments), create the Expense Report header and line referencing that Quick Expense (POST /reports -> POST /reports/{ID}/lines), and route the report into the Expense Report Event approval workflow (POST /reports/{ID}/submit).
For complex hotel itemizations, per-diem rate tables, mileage calculations, or corporate credit card reconciliations that exceed expense/v1 REST fields, Workday pairs REST with Resource_Management SOAP (Submit_Expense_Report, Get_Expense_Reports, Get_Expense_Credit_Card_Transactions) and WQL (expenseReportsForWorker). Understanding how Expense Items, Spend Categories, multi-currency conversions, and receipt attachment rules fit together keeps external expense tools from failing accounting validations.
Comparing Workday Expense APIs Across REST, SOAP, and WQL
| Operation / Resource | Interface | Purpose | Governing Security (Expenses Scope) |
|---|---|---|---|
Operation / ResourceGET /expenseItems & /values/bespokePrompt/expenseItem |
InterfaceREST expense/v1 |
PurposeLists active Expense Items segmented for the signed-in worker (Meals, Hotel, Ground Transport). |
Governing Security ( Expenses Scope)Access Expense Item (Segmented), Self-Service: Expense Report |
Operation / ResourcePOST /entries & POST /entries/{ID}/attachments |
InterfaceREST expense/v1 |
PurposeCreates a Quick Expense (multipart/form-data) and attaches receipt files (32 MB max per file). |
Governing Security ( Expenses Scope)Self-Service: Expense Report |
Operation / ResourcePOST /reports & POST /reports/{ID}/lines |
InterfaceREST expense/v1 |
PurposeCreates a draft Expense Report header and attaches lines (direct, or linked from quickExpense, creditCardTransaction, or travelBookingRecord). |
Governing Security ( Expenses Scope)Self-Service: Expense Report |
Operation / ResourcePOST /reports/{ID}/submit |
InterfaceREST expense/v1 |
PurposeSubmits the draft report and initiates the Expense Report Event business process. |
Governing Security ( Expenses Scope)Business Process Type: Expense Report Event (Initiate) |
Operation / ResourceSubmit_Expense_Report & Get_Expense_Reports |
InterfaceSOAP Resource_Management |
PurposeFull-featured XML expense report creation (itemizations, tax declarations, guest lists, split worktags) and extraction. | Governing Security ( Expenses Scope)Resource_Management / Expense Report Event BP |
Operation / ResourceexpenseReportsForWorker & expenseReportLinesForWorker |
InterfaceWQL (wql/v1) |
PurposeQueries report status, reimbursementCurrency, multicurrencyExpenseEntry, approval dates, and payment dates. |
Governing Security ( Expenses Scope)Self-Service: Expense Report (expenseReportsForCurrentWorker filter) |
Expense Items vs. Spend Categories: How Accounting Mapping Works
Engineers coming from general accounting ERPs often search the expense/v1 OpenAPI specification for a spendCategory field on expense lines and come up empty. Workday intentionally separates the employee-facing prompt from the general ledger posting rule:
- Expense Item (
Create Expense Item): What the employee selects (Taxi / Rideshare,Client Dinner,Conference Registration). Each Expense Item defines required instructional attributes (such asMerchant,Attendees,Travel City, or per-mile rate tables) and can be restricted via Expense Item Security Segments (Access Expense Item (Segmented)) so retail workers do not see executive relocation items. - Spend Category (
Get_Spend_Category_Hierarchies): Mapped behind the scenes on the Expense Item setup (Setup Considerations: Expense Items). When the Expense Report reaches approval completion, Workday Accounting derives the Spend Category and ledger account from the selected Expense Item plus the header or lineworktag(Cost Center,Project,Region,Grant). - Prompting Rule: Always populate your UI dropdown using
GET /expense/v1/values/bespokePrompt/expenseItem(rather than unfilteredGET /expenseItems) so the signed-in worker only sees Expense Items active for their Expense Group and Country.
End-to-End Receipt Upload and Expense Report Flow (expense/v1)
Step 1: Create a Quick Expense and Upload the Receipt Binary
While you can post bare lines directly to POST /reports/{ID}/lines, expense/v1 attaches receipt binaries specifically on Quick Expenses (POST /entries/{ID}/attachments). Creating the Quick Expense first mirrors Workday Mobile’s own receipt wallet and carries the attachment cleanly onto the Expense Report line:
POST /ccx/api/expense/v1/{tenant}/entries HTTP/1.1
Authorization: Bearer <user_delegated_access_credential>
Content-Type: multipart/form-data; boundary=---ExpenseEntryBoundaryWith the JSON part specifying date (the required transaction date), expenseItem, merchant, memo, and amount (including transaction currency from GET /values/bespokePrompt/currency):
{
"date": "2026-11-12",
"merchant": "Sound Transit Rail",
"memo": "Airport rail transfer to Seattle client workshop",
"expenseItem": {
"id": "dce1c1d299a110000cf4000e5823003c"
},
"amount": {
"value": 3.50,
"currency": "USD"
}
}Take the returned Quick Expense id and upload the receipt JPEG, PNG, or PDF via POST /entries/{ID}/attachments (32 MB maximum file size, subject to tenant allowed file extensions and virus scanning in Edit Tenant Setup - System; see Workday attachment upload rules):
{
"fileName": "sound-transit-2026-11-12.pdf",
"contentType": {
"id": "83509a26446c11de98360015c5e6daf6"
},
"fileLength": 84210,
"attachmentContent": "<base64_encoded_receipt_bytes>"
}Step 2: Create the Expense Report Header and Line
Create the parent Expense Report via POST /expense/v1/reports, passing creationDate, company, payee (the signed-in worker), expenseReportMemo, and default costing worktag:
{
"creationDate": "2026-11-15",
"company": {
"id": "7debfd10616e100004ba993bbe7f0039"
},
"payee": {
"id": "3aa5550b7fe348b98d7b5741afc6f534"
},
"expenseReportMemo": "Seattle Q4 Client Workshop Travel",
"worktag": {
"id": "9dcae422ca6e100009fb17cb0b99004c"
}
}Then attach your Quick Expense (or an imported corporate card charge creditCardTransaction) to the report via POST /expense/v1/reports/{report_ID}/lines:
{
"date": "2026-11-12",
"expenseItem": {
"id": "dce1c1d299a110000cf4000e5823003c"
},
"quickExpense": {
"id": "bace579f29e310000ef5e3b010ac00c7"
},
"memo": "Airport rail transfer to Seattle client workshop",
"totalAmount": {
"value": 3.50,
"currency": "USD"
}
}Step 3: Multi-Currency Handling and Final Submission
When an employee based in a USD company incurs a hotel or rail receipt in EUR or GBP, capture the original receipt currency in amount / totalAmount (GET /values/bespokePrompt/currency). Workday converts the transaction amount into the worker’s reimbursementCurrency using the tenant’s active currency rate table (Maintain Currency Conversion Rates) as of the expense line’s date.
Once all lines and receipts pass policy checks (such as receipt-required thresholds configured on the Expense Item), call POST /expense/v1/reports/{report_ID}/submit to launch the Expense Report Event business process.
Common Validation Traps to Avoid
- Missing Receipt Thresholds: Many tenants configure a custom or delivered validation requiring an attachment whenever a line exceeds
$25or$75. SubmittingPOST /reports/{ID}/submitwithout attaching the receipt on the underlying entry triggers an HTTP400business process validation failure. - Closed Accounting Periods: If an employee submits an old receipt dated in a closed financial ledger period, Workday rejects submission unless accounting rules permit posting to the current open period.
- Add-Only SOAP Constraint: In
Resource_ManagementSOAP,Submit_Expense_Reportoperates in Add Only mode—attempting to re-post the same document ID to edit lines fails withThe Web Service is set to Add Only; documents cannot be resubmitted.Stage drafts via RESTPOST /reportsso users can review every line before triggeringsubmit.
Teams building streamlined expense capture or manager approval flows use Kiweely Leaf (coming next) to embed fast mobile receipt capture and inline Teams, Slack, DingTalk, or Lark expense approvals directly over standard Workday APIs without a Workday Extend license—or Kiweely Bridge (coming next) so travelers can check reimbursement status (expenseReportsForWorker) or stage expense entries in Claude, ChatGPT, and Gemini with an out-of-band browser confirmation card before submission.
Frequently asked questions
Do employees select a Spend Category or an Expense Item when creating an expense line via the Workday API?
Employees and REST callers specify an Expense Item (such as Airfare, Client Meals, or Mileage) retrieved from GET /expense/v1/expenseItems or GET /values/bespokePrompt/expenseItem. Workday automatically derives the underlying accounting Spend Category configured on that Expense Item.
How do you attach a receipt PDF or photo to an expense line in the Workday expense v1 REST API?
Create a Quick Expense via POST /entries, upload the receipt binary (up to 32 MB) to POST /entries/{ID}/attachments, and then reference that quickExpense ID when adding the line via POST /reports/{ID}/lines so the receipt carries onto the Expense Report.
Why does Resource_Management SOAP Submit_Expense_Report reject updates to an already submitted report?
In Resource_Management SOAP, Submit_Expense_Report is Add Only for web service submissions—documents cannot be resubmitted to overwrite lines once in progress or posted to a closed ledger period. Use draft staging in REST (POST /reports and POST /reports/{ID}/lines) before calling POST /reports/{ID}/submit.
Can contingent workers submit Expense Reports via the Workday Expenses API?
Only if your tenant configures contingent worker expense reimbursement or routes contractor spend separately; in Resource_Management SOAP Submit_Expense_Report, Workday enforces the validation that the Expense Payee must be an eligible employee payee unless configured otherwise.