Workday REST and SOAP (WWS v45+) API Capabilities

TL;DR

• Bottom line: Workday exposes 55 SOAP web services (WWS v45.2) covering HCM, Financials, Payroll, and Student, plus REST API v1, RaaS for reporting, WQL for queries, and Graph API (2023R1+). SOAP remains the primary integration surface for complex operations.
• Key limit: ~10 API calls/second per tenant (observed, not officially published); RaaS reports capped at 2 GB output with 30-minute timeout.
• Watch out for: RaaS does NOT support native JSON pagination — only XML supports page/count parameters. Large JSON reports will timeout for datasets >50K rows.
• Best for: Enterprise HCM and financial integrations requiring full CRUD on workers, compensation, payroll, benefits, and financial management objects.
• Authentication: OAuth 2.0 (REST/Graph) or WS-Security with Integration System User (SOAP). Each integration needs a dedicated ISU with domain security grants.

System Profile

Workday is a cloud-only enterprise platform covering HCM, Financial Management, Payroll, Student, and Planning. Unlike traditional on-premise ERPs, Workday is multi-tenant SaaS with no self-hosted option. All integrations route through Workday's cloud APIs. Workday releases two major updates per year (R1 in March, R2 in September), each introducing new WWS versions. The current production version is WWS v45.2 (2025R2, January 2026). Capabilities depend on which modules are licensed — there are no traditional "editions."

API Surfaces & Capabilities

Workday provides five distinct API surfaces, each suited to different integration patterns.

SOAP (WWS) — 55 Services

The SOAP API is Workday's most comprehensive integration surface with 55 named services as of v45.2, covering: Core HCM (Human_Resources, Staffing, Compensation, Benefits_Administration, Absence_Management, Talent, Performance_Management, Recruiting, Time_Tracking, Learning, Workforce_Planning, Scheduling), Financial (Financial_Management, Cash_Management, Revenue_Management, Settlement_Services, Professional_Services_Automation, Resource_Management), Payroll (Payroll, Payroll_Interface, Payroll_AUS, Payroll_CAN, Payroll_FRA, Payroll_GBR), Student (Student_Core, Student_Finance, Student_Records, and more), and Platform (Integrations, Identity_Management, Prism_Analytics, Workday_Extensibility, and others).

Rate Limits & Quotas

Per-Request Limits

Rolling / Daily Limits

Rate Limit Behavior

Workday does not publicly document precise rate limits for most endpoints. The ~10 calls/second limit is widely observed by integration partners. When limits are exceeded, the API returns HTTP 429 with a Retry-After header. During high-load periods (payroll processing, open enrollment, year-end close), effective throughput may drop significantly.

Authentication

Authentication Gotchas

• Each integration needs its own ISU: Sharing ISUs across integrations creates audit confusion and cascading permission risks. [src4]
• Domain Security Policies must be explicitly granted: Forgetting a domain means silent "no data returned" errors, not permission-denied errors. [src5]
• Activate Pending Security Policy Changes: After modifying ISU permissions, you must run activation. Changes are NOT immediate. [src4]
• Sandbox ISU credentials differ from production: ISU accounts exist per tenant. Migration scripts must account for different credentials per environment. [src4]

Constraints

• Cloud-only: Workday has no on-premise deployment. All integrations must go through cloud API endpoints. No direct database access exists.
• No native bulk import API: Unlike Salesforce (Bulk API 2.0) or SAP (FBDI), Workday has no dedicated bulk ingestion API. Large inbound loads must use SOAP with pagination or EIB file-based imports.
• RaaS JSON has no pagination: JSON-formatted RaaS output does not support pagination. Only XML output supports Response_Filter with Count/Page parameters.
• Rate limits are per-tenant, not per-ISU: All integrations sharing a tenant compete for the same ~10 calls/sec limit.
• WWS version support is 18 months minimum: Deprecated versions are removed after notice period.
• Module licensing gates API access: SOAP services only available for licensed modules.
• OAuth 2.0 mandatory for REST API: No API key or basic auth alternative for REST/Graph.

Integration Pattern Decision Tree

START -- User needs to integrate with Workday
|-- What's the integration pattern?
|   |-- Real-time (individual records, <1s)
|   |   |-- Reading data?
|   |   |   |-- Simple worker/org lookup -> REST API v1 or Graph API
|   |   |   +-- Complex multi-object query -> SOAP (WWS) Get operations
|   |   +-- Writing data?
|   |       |-- Standard business process -> SOAP (WWS) Submit/Put
|   |       +-- Custom object data -> REST API or Workday Extend
|   |-- Batch/Bulk (scheduled, high volume)
|   |   |-- Outbound (extracting)?
|   |   |   |-- < 50K rows -> RaaS (XML format with pagination)
|   |   |   |-- > 50K rows -> WQL with pagination or RaaS XML chunking
|   |   |   +-- Need calculated fields? -> RaaS
|   |   +-- Inbound (loading)?
|   |       |-- File-based -> EIB with CSV/XML
|   |       |-- Record-by-record -> SOAP Put/Submit with retry
|   |       +-- Mass migration -> Workday migration tools
|   |-- Event-driven (notifications)
|   |   |-- Outbound notifications -> Integration Events
|   |   +-- Real-time change detection -> Poll via RaaS/WQL (no native CDC)
|   +-- Reporting / Analytics
|       |-- Ad-hoc queries -> WQL via REST
|       |-- Scheduled reports -> RaaS via EIB
|       +-- Advanced analytics -> Prism Analytics API
|-- Direction?
|   |-- Inbound -> SOAP WWS (Put/Submit) or EIB
|   |-- Outbound -> RaaS, WQL, REST, or Graph API
|   +-- Bidirectional -> separate inbound/outbound flows
+-- Error tolerance?
    |-- Zero-loss -> idempotency + error logging + retry queues
    +-- Best-effort -> exponential backoff on 429s

Quick Reference

Key SOAP Operations by Service

REST API Key Endpoints

Step-by-Step Integration Guide

1. Create an Integration System User (ISU)

Every Workday integration starts with a dedicated ISU for audit trail and security isolation. [src4]

1. Search "Create Integration System User" in Workday
2. Set username (e.g., ISU_MyIntegration) and password
3. Uncheck "Require New Password at Next Sign In"
4. Create an Integration System Security Group (ISSG) and add the ISU
5. Grant domain security policy permissions (Get/Put) for required data domains
6. Run "Activate Pending Security Policy Changes"

Verify: Log in as the ISU and confirm access to required data via Workday search.

2. Register an OAuth 2.0 API Client (for REST/Graph)

Required for REST, Graph API, and WQL access. [src5]

1. Search "Register API Client for Integrations" in Workday
2. Set Client Name, select Non-Expiring Refresh Tokens
3. Add required scopes (HCM, Financials, Staffing)
4. Save Client ID and Client Secret
5. Save Token Endpoint and Authorization Endpoint URLs
6. Generate initial refresh token via "Manage Refresh Tokens for Integrations"

Verify: Exchange refresh token for access token and confirm 200 response.

3. Authenticate and Obtain Access Token (REST)

Exchange the refresh token for an access token. [src5]

curl -X POST "https://wd2-impl-services1.workday.com/ccx/oauth2/{tenant}/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "{client_id}:{client_secret}" \
  -d "grant_type=refresh_token&refresh_token={refresh_token}"

Verify: Response contains access_token and token_type: Bearer.

4. Execute a SOAP Request (Get Workers)

Construct an XML envelope with WS-Security credentials. [src1, src3]

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:wd="urn:com.workday/bsvc">
  <env:Header>
    <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/...">
      <wsse:UsernameToken>
        <wsse:Username>ISU_MyIntegration@{tenant}</wsse:Username>
        <wsse:Password>your_password</wsse:Password>
      </wsse:UsernameToken>
    </wsse:Security>
  </env:Header>
  <env:Body>
    <wd:Get_Workers_Request wd:version="v45.2">
      <wd:Response_Filter>
        <wd:Page>1</wd:Page>
        <wd:Count>100</wd:Count>
      </wd:Response_Filter>
    </wd:Get_Workers_Request>
  </env:Body>
</env:Envelope>

Verify: Response contains <wd:Get_Workers_Response> with worker data.

5. Handle Pagination (SOAP)

SOAP responses include total results and total pages. Loop through all pages. [src1]

page = 1
all_workers = []
while True:
    # Build SOAP envelope with Response_Filter Page={page}, Count=100
    response = requests.post(soap_endpoint, data=envelope, headers=headers)
    root = ElementTree.fromstring(response.content)
    workers = root.findall('.//{urn:com.workday/bsvc}Worker')
    all_workers.extend(workers)
    total_pages = int(root.find('.//{urn:com.workday/bsvc}Total_Pages').text)
    if page >= total_pages:
        break
    page += 1

Verify: len(all_workers) matches Total_Results from first page.

6. Implement Rate Limit Handling

Respect the ~10 calls/sec limit with exponential backoff. [src4]

def workday_request(url, headers, data, max_retries=5):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, data=data)
        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 2 ** attempt))
            time.sleep(retry_after)
            continue
        response.raise_for_status()
        return response
    raise Exception(f"Max retries ({max_retries}) exceeded")

Verify: Integration completes without unhandled 429 errors during load testing.

Code Examples

Python: Query Workers via REST API

# Input:  OAuth access token, tenant name
# Output: List of active workers in JSON format

import requests

BASE_URL = "https://wd2-impl-services1.workday.com"
TENANT = "your_tenant"
ACCESS_TOKEN = "your_access_token"

headers = {
    "Authorization": f"Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json"
}

offset, limit, all_workers = 0, 100, []
while True:
    url = f"{BASE_URL}/ccx/api/v1/{TENANT}/workers?limit={limit}&offset={offset}"
    resp = requests.get(url, headers=headers)
    if resp.status_code == 429:
        import time; time.sleep(int(resp.headers.get("Retry-After", 2)))
        continue
    resp.raise_for_status()
    workers = resp.json().get("data", [])
    all_workers.extend(workers)
    if len(workers) < limit: break
    offset += limit
print(f"Retrieved {len(all_workers)} workers")

cURL: Test REST API Authentication

# Step 1: Get access token
curl -X POST "https://wd2-impl-services1.workday.com/ccx/oauth2/{tenant}/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "{client_id}:{client_secret}" \
  -d "grant_type=refresh_token&refresh_token={refresh_token}"

# Step 2: Query workers
curl -X GET "https://wd2-impl-services1.workday.com/ccx/api/v1/{tenant}/workers?limit=10" \
  -H "Authorization: Bearer {access_token}"

Data Mapping

SOAP vs REST Field Naming

Data Type Gotchas

• Dates are tenant-timezone-relative: Workday returns dates in the tenant's configured timezone, not UTC. Integration code must handle timezone conversion. [src1]
• WID vs Reference ID: SOAP uses WID references for cross-object relationships. REST uses more readable IDs. Maintain a WID-to-external-ID mapping table for bidirectional integrations. [src1]
• Boolean handling differs by API surface: SOAP uses "1"/"0" strings. REST/Graph use JSON true/false. [src1, src5]

Error Handling & Failure Points

Common Error Codes

Failure Points in Production

• Payroll window throttling: During payroll processing, API throughput drops significantly. Fix: Schedule non-critical integrations outside payroll windows; implement circuit breaker pattern. [src4]
• RaaS JSON timeout on large datasets: JSON RaaS has no pagination; >50K rows frequently timeout. Fix: Switch to XML format with Response_Filter pagination or use WQL. [src4]
• Domain security policy not activated: ISU silently receives empty results, not errors. Fix: Always activate security changes immediately. [src4]
• Sandbox data drift: Sandbox may have stale/incomplete data vs production. Fix: Test with production-like data volumes; refresh sandbox regularly. [src4]
• Concurrent integration starvation: Multiple integrations sharing ~10 calls/sec pool. Fix: Per-integration rate limiting via shared API gateway. [src4]

Anti-Patterns

Wrong: Using JSON format for large RaaS extracts

# BAD -- JSON RaaS has no pagination; large datasets will timeout
url = f"https://{host}/ccx/service/customreport2/{tenant}/{report}?format=json"
response = requests.get(url, auth=(isu_user, isu_pass))
# This will timeout for >50K rows

Correct: Use XML format with pagination for large RaaS extracts

# GOOD -- XML format supports Response_Filter with Page/Count
page = 1
all_rows = []
while True:
    url = f"https://{host}/ccx/service/customreport2/{tenant}/{report}?format=simplexml&Page={page}&Count=1000"
    response = requests.get(url, auth=(isu_user, isu_pass))
    rows = parse_xml_rows(response.content)
    all_rows.extend(rows)
    if len(rows) < 1000: break
    page += 1

Wrong: Sharing a single ISU across multiple integrations

# BAD -- Permission changes for one integration break all others
ISU: ISU_SharedAccount
  -> Integration A, B, C (all sharing same credentials)

Correct: One ISU per integration system

# GOOD -- Isolated credentials, permissions, and audit trail
ISU: ISU_HCM_Sync         -> Integration A
ISU: ISU_Payroll_Extract   -> Integration B
ISU: ISU_Benefits_Enroll   -> Integration C

Wrong: Hardcoding WWS version without upgrade plan

# BAD -- v37.0 will be deprecated; no upgrade path
SOAP_URL = f"https://{host}/ccx/service/{tenant}/Human_Resources/v37.0"

Correct: Parameterize version and monitor deprecation

# GOOD -- Version is configurable and monitored
WWS_VERSION = os.environ.get("WORKDAY_WWS_VERSION", "v45.2")
SOAP_URL = f"https://{host}/ccx/service/{tenant}/Human_Resources/{WWS_VERSION}"
# Alert when version approaches deprecation (18-month window)

Common Pitfalls

• RaaS pagination only works with XML: JSON pagination attempts yield empty/incomplete results. Fix: Use format=simplexml with Page/Count, or switch to WQL for JSON pagination. [src4]
• Forgetting to activate security policy changes: #1 support issue — ISU returns empty data silently. Fix: Always run 'Activate Pending Security Policy Changes' after any ISU permission modification. [src4]
• Testing only in sandbox: Sandbox may have different limits, data volumes, and business process configs. Fix: Load-test with production-like data volumes. [src4]
• Not pinning WWS version: Using "latest" version risks breaking changes. Fix: Pin to specific version; plan upgrades proactively within 18-month window. [src2]
• Ignoring Retry-After headers: Simple retries without reading Retry-After waste time. Fix: Always parse Retry-After on 429 responses. [src4]
• Running large extracts during business hours: May be throttled or degrade interactive user experience. Fix: Schedule large extracts during off-peak hours. [src4]

Diagnostic Commands

# Test REST API authentication (OAuth token exchange)
curl -X POST "https://wd2-impl-services1.workday.com/ccx/oauth2/{tenant}/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "{client_id}:{client_secret}" \
  -d "grant_type=refresh_token&refresh_token={refresh_token}"

# Check WWS WSDL for a specific service (verify version is accessible)
curl -X GET "https://wd2-impl-services1.workday.com/ccx/service/{tenant}/Human_Resources/v45.2?wsdl"

# Test RaaS report access (XML format, first page)
curl -X GET "https://wd2-impl-services1.workday.com/ccx/service/customreport2/{tenant}/{owner}/{report}?format=simplexml&Page=1&Count=5" \
  -u "ISU_User@tenant:password"

# Test WQL query endpoint
curl -X POST "https://wd2-impl-services1.workday.com/ccx/api/wql/v1/{tenant}" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT worker, fullName FROM allActiveWorkers LIMIT 5"}'

Version History & Compatibility

Deprecation Policy: Workday supports each major WWS API version for a minimum of 18 months. Deprecation is announced through Workday Community and release notes. Backward compatibility is maintained within a version — integrations built for v45.0 continue working with v45.0 even as v46.x is released. Older versions do not receive new features.

When to Use / When Not to Use

Important Caveats

• Rate limits are not officially published: The ~10 calls/sec limit is observed by integration partners but not guaranteed by Workday. Actual throughput varies by tenant size and load.
• No native CDC (Change Data Capture): Unlike Salesforce or SAP, Workday does not offer streaming change detection. Detecting changes requires polling via RaaS or WQL with timestamp filters.
• Sandbox rate limits may differ: Preview and implementation tenants may have different constraints than production.
• Workday Data Cloud (2026): Workday announced Data Cloud for early adopter availability in H1 2026, enabling zero-copy data sharing with Snowflake and Databricks. This may change the outbound data extraction landscape significantly.
• Rate limits and quotas are subject to change with each Workday release. Always verify against current release notes and Workday Community documentation.