---
# === IDENTITY ===
id: business/erp-integration/workday-rest-soap-api-capabilities/2026
canonical_question: "What are Workday REST and SOAP (WWS v45+) API capabilities - rate limits, 55+ services, version policy?"
aliases:
  - "Workday API capabilities and rate limits"
  - "Workday Web Services SOAP API documentation"
  - "Workday REST API integration guide"
  - "Workday WWS v45 API services list"
entity_type: erp_integration
domain: business > erp-integration > workday-rest-soap-api-capabilities
region: global
jurisdiction: global
temporal_scope: 2025-2026

# === SYSTEM PROFILE ===
systems:
  - name: "Workday HCM / Financials"
    vendor: "Workday"
    version: "WWS v45.2 (2025R2) / REST v1"
    edition: "All editions (capabilities vary by subscription)"
    deployment: cloud
    api_surface: "REST, SOAP (WWS), RaaS, WQL, Graph API"

# === VERIFICATION ===
last_verified: 2026-03-02
confidence: 0.88
version: 1.0
first_published: 2026-03-02

# === TEMPORAL VALIDITY ===
temporal_validity:
  status: evolving
  last_breaking_change: "v45.0 (2025R2, September 2025)"
  next_review: 2026-08-29
  change_sensitivity: high

# === CONSTRAINTS ===
constraints:
  - "Rate limit: ~10 API calls/second per tenant (undocumented but widely observed); 429 returned when exceeded"
  - "RaaS report output limit: 2 GB max for advanced custom reports exposed via web services"
  - "RaaS pagination: not natively supported in JSON — must use XML with page/count parameters or WQL for large datasets"
  - "RaaS timeout: 30-minute execution limit per report — large datasets (>50K rows) may timeout"
  - "WWS version support: minimum 18 months per major version — deprecated versions removed after notice period"
  - "ISU requirement: each integration requires a dedicated Integration System User with domain security policy grants"
  - "OAuth 2.0 mandatory for REST API — no API key or basic auth alternative"
  - "Graph API (2023R1+) enforces per-tenant rate limits with 429 responses and Retry-After headers"

# === SKIP CONDITIONS ===
skip_this_unit_if:
  - condition: "User needs Workday Adaptive Planning API (separate product)"
    use_instead: "business/erp-integration/workday-adaptive-planning-api/2026"
  - condition: "User needs Workday Extend/App Platform APIs"
    use_instead: "business/erp-integration/workday-extend-platform-api/2026"
  - condition: "User needs cross-system comparison of ERP APIs"
    use_instead: "business/erp-integration/erp-api-comparison-hcm/2026"

# === AGENT HINTS ===
inputs_needed:
  - key: integration_pattern
    question: "What integration pattern do you need?"
    type: choice
    options:
      - "real-time sync (individual records, <1s latency)"
      - "batch/bulk (scheduled, high volume)"
      - "event-driven (business process notifications)"
      - "reporting (RaaS / WQL data extraction)"
  - key: data_volume
    question: "What's your daily data volume?"
    type: choice
    options:
      - "< 1,000 records/day"
      - "1,000-100,000 records/day"
      - "> 100,000 records/day"
  - key: direction
    question: "What's the data flow direction?"
    type: choice
    options:
      - "inbound (writing to Workday)"
      - "outbound (reading from Workday)"
      - "bidirectional sync"

# === DISTRIBUTION ===
canonical_source: "https://knowledgelib.io/business/erp-integration/workday-rest-soap-api-capabilities/2026"
suggested_citation: "Source: knowledgelib.io — AI Knowledge Library (verified 2026-03-02)"

# === RELATED UNITS ===
related_kos:
  depends_on: []
  related_to:
    - id: "business/erp-integration/workday-extend-platform-api/2026"
      label: "Workday Extend platform APIs for custom apps"
  solves: []
  alternative_to:
    - id: "business/erp-integration/sap-successfactors-api-capabilities/2026"
      label: "SAP SuccessFactors HCM API capabilities"
  often_confused_with:
    - id: "business/erp-integration/workday-adaptive-planning-api/2026"
      label: "Workday Adaptive Planning — separate API surface"

# === SOURCES ===
sources:
  - id: src1
    title: "Workday Web Services (WWS) Directory v45.2"
    author: Workday
    url: https://community.workday.com/sites/default/files/file-hosting/productionapi/index.html
    type: official_docs
    published: 2026-01-09
    reliability: authoritative
  - id: src2
    title: "Workday WWS Version Directory — All Supported Versions"
    author: Workday
    url: https://community.workday.com/sites/default/files/file-hosting/productionapi/versions/index.html
    type: official_docs
    published: 2026-01-09
    reliability: authoritative
  - id: src3
    title: "Workday SOAP API Reference"
    author: Workday
    url: https://community-content.workday.com/en-us/public/products/platform-and-product-extensions/soap-api-reference.html
    type: official_docs
    published: 2025-09-01
    reliability: authoritative
  - id: src4
    title: "Workday API Integration Guide (In-Depth)"
    author: Knit
    url: https://www.getknit.dev/blog/workday-api-integration-in-depth
    type: technical_blog
    published: 2025-06-15
    reliability: moderate_high
  - id: src5
    title: "Workday REST API Integration and Security Guide"
    author: Reco
    url: https://www.reco.ai/hub/workday-rest-api-integration-security
    type: technical_blog
    published: 2025-08-01
    reliability: moderate_high
  - id: src6
    title: "Introducing Workday Graph API: An Overview"
    author: Makse Group
    url: https://www.maksegroup.com/blog/introducing-workday-graph-api-an-overview-5anyx-zfwtw-l9nsk-9z57s-lf2hy-cbjm6
    type: technical_blog
    published: 2025-03-01
    reliability: moderate
  - id: src7
    title: "Workday Web Services: Everything You Should Know"
    author: Surety Systems
    url: https://www.suretysystems.com/insights/workday-web-services-everything-you-should-know/
    type: technical_blog
    published: 2025-05-01
    reliability: moderate_high
---

# 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 a REST API (v1), RaaS for reporting, WQL for queries, and Graph API (2023R1+) for modern JSON access. SOAP remains the primary integration surface for complex operations. [src1]
- **Key limit**: ~10 API calls/second per tenant (observed, not officially published); RaaS reports capped at 2 GB output with 30-minute timeout. [src4]
- **Watch out for**: RaaS does NOT support native JSON pagination — only XML supports page/count parameters. Large JSON reports will timeout or fail for datasets >50K rows. Use WQL or XML format instead. [src4]
- **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. [src4, src5]

## 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 — there is no database-level access. 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). [src1, src2]

Workday does not have traditional "editions" like Salesforce or SAP. Instead, capabilities depend on which modules (HCM, Financials, Payroll, Student, Prism Analytics) are licensed. All licensed modules expose their corresponding API services. [src7]

| Property | Value |
|---|---|
| **Vendor** | Workday |
| **System** | Workday HCM / Financial Management |
| **API Surface** | SOAP (WWS), REST v1, RaaS, WQL, Graph API |
| **Current API Version** | WWS v45.2 (2025R2) / REST v1 / Graph API v1 |
| **Editions Covered** | All licensed modules — HCM, Financials, Payroll, Student |
| **Deployment** | Cloud (multi-tenant SaaS only) |
| **API Docs URL** | [WWS Directory v45.2](https://community.workday.com/sites/default/files/file-hosting/productionapi/index.html) |
| **Status** | GA (all API surfaces) |

## API Surfaces & Capabilities

Workday provides five distinct API surfaces, each suited to different integration patterns. [src1, src4, src7]

| API Surface | Protocol | Best For | Max Records/Request | Rate Limit | Real-time? | Bulk? |
|---|---|---|---|---|---|---|
| SOAP (WWS v45.2) | HTTPS/XML (WSDL) | Complex CRUD, payroll, financial transactions | Configurable via Response_Filter (page/count) | ~10 calls/sec per tenant | Yes | Via pagination |
| REST API v1 | HTTPS/JSON | Worker data, staffing, modern integrations | Paginated (default page size varies) | ~10 calls/sec per tenant | Yes | No |
| RaaS (Reports as a Service) | HTTPS/XML or JSON | Reporting, scheduled data extracts | 2 GB output, 30-min timeout | Shared with SOAP/REST | Semi (on-demand) | Yes (single report) |
| WQL (Workday Query Language) | HTTPS/JSON | Ad-hoc data queries, analytics | Paginated | ~10 calls/sec per tenant | Yes | Yes (paginated) |
| Graph API (2023R1+) | HTTPS/JSON | Modern read/write, mobile/web apps | Paginated | Per-tenant, 429 on exceed | Yes | No |

### SOAP (WWS) — 55 Services

The SOAP API is Workday's most comprehensive integration surface with 55 named services as of v45.2. [src1]

**Core HCM Services**: Human_Resources, Staffing, Compensation, Compensation_Review, Benefits_Administration, Absence_Management, Talent, Performance_Management, Recruiting, Time_Tracking, Learning, Workforce_Planning, Scheduling

**Financial Services**: Financial_Management, Cash_Management, Revenue_Management, Settlement_Services, Professional_Services_Automation, Resource_Management

**Payroll Services**: Payroll, Payroll_Interface, Payroll_AUS, Payroll_CAN, Payroll_FRA, Payroll_GBR

**Student Services**: Student_Core, Student_Finance, Student_Records, Student_Recruiting, Student_Transfer_Credit, Academic_Advising, Academic_Foundation, Admissions, Campus_Engagement, Financial_Aid

**Platform Services**: Integrations, Identity_Management, External_Integrations, Workday_Connect, Workday_Extensibility, Notification, Metadata_Translations, Tenant_Data_Translation, Prism_Analytics, Dynamic_Document_Generation, Drive, Org_Studio, Flex_Team, Moments, Requests, Adoption, Inventory

**Partner Services**: ACA_Partner_Integrations, Benefits_Partner_Program_Integrations

### RaaS (Report as a Service)

RaaS exposes any Workday custom or advanced report as a REST endpoint. Reports can return XML, JSON, CSV, or RSS. RaaS is the most common outbound data extraction method, but has critical limitations around pagination and size. [src4, src7]

### WQL (Workday Query Language)

WQL provides SQL-like query access to Workday data. Available since 2020R1, WQL supports pagination natively and is the recommended alternative to RaaS for large datasets. WQL queries are exposed via REST endpoints. [src6]

## Rate Limits & Quotas

### Per-Request Limits

| Limit Type | Value | Applies To | Notes |
|---|---|---|---|
| API calls per second | ~10 per tenant | All API surfaces | Observed limit; not officially published. 429 returned when exceeded [src4] |
| Strategic Sourcing API | 5 requests/sec | Sourcing endpoints only | Documented per-endpoint limit [src4] |
| RaaS output size | 2 GB | Advanced custom reports | Maximum output for web-service-enabled reports [src4] |
| RaaS execution timeout | 30 minutes | All RaaS reports | Large reports (>50K rows) may timeout [src4] |
| SOAP response page size | Configurable | WWS SOAP requests | Set via Response_Filter element (Count + Page) [src1] |
| REST response page size | Default varies | REST API | Pagination via offset/limit parameters [src5] |

### Rolling / Daily Limits

| Limit Type | Value | Window | Edition Differences |
|---|---|---|---|
| Per-tenant throughput | ~10 calls/sec (observed) | Per-second | Same across all subscriptions [src4] |
| Concurrent integrations | Tenant-dependent | Ongoing | Workday may throttle during peak windows (payroll runs, year-end) |
| Graph API rate limit | Per-tenant (undisclosed) | Per-second | 429 + Retry-After header returned [src6] |
| RaaS concurrent reports | Limited | Per-tenant | Running too many large reports simultaneously causes queuing |

[src4, src6]

### 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 as Workday prioritizes interactive users over API consumers. [src4]

## Authentication

| Flow | Use When | Token Lifetime | Refresh? | Notes |
|---|---|---|---|---|
| OAuth 2.0 (Authorization Code) | REST API, Graph API, WQL | Access token: configurable (default ~60 min) | Yes (refresh token) | Register API client via "Register API Client for Integrations" task [src5] |
| WS-Security (ISU credentials) | SOAP (WWS) | Session-based | N/A | Username/password embedded in SOAP header; ISU must have domain security grants [src4] |
| OAuth 2.0 (Client Credentials) | Server-to-server REST | Access token: configurable | Yes | For non-interactive/daemon integrations [src5] |
| RaaS URL with ISU | RaaS report access | Per-request | N/A | ISU credentials in URL or basic auth header |

[src4, src5]

### Authentication Gotchas

- **Each integration needs its own ISU**: Workday recommends one Integration System User per integration system. Sharing ISUs across integrations creates audit confusion and risks cascading permission changes breaking multiple integrations. [src4]
- **Domain Security Policies must be explicitly granted**: ISU access requires Put and/or Get permissions on specific security domains. Forgetting a domain means silent "no data returned" errors, not permission-denied errors. [src5]
- **OAuth refresh tokens can expire**: If an integration goes unused for an extended period, the refresh token may expire. Implement token refresh monitoring and alerting for unattended integrations. [src5]
- **Activate Pending Security Policy Changes**: After modifying ISU permissions, you must run the "Activate Pending Security Policy Changes" task. Changes are NOT immediate — they require explicit activation. [src4]
- **Sandbox ISU credentials differ from production**: ISU accounts exist per tenant. Sandbox and production tenants have separate ISU configurations. Migration scripts must account for different credentials per environment. [src4]

## Constraints
<!-- Agents: read this section before recommending any integration approach from this unit.
     These are hard constraints that must not be violated. -->

- **Cloud-only**: Workday has no on-premise deployment. All integrations must go through cloud API endpoints. No direct database access exists. [src7]
- **No native bulk import API**: Unlike Salesforce (Bulk API 2.0) or SAP (FBDI), Workday has no dedicated bulk ingestion API. Large inbound data loads must use SOAP with pagination or EIB (Enterprise Interface Builder) file-based imports. [src4]
- **RaaS JSON has no pagination**: JSON-formatted RaaS output does not support pagination. Only XML output supports Response_Filter with Count/Page parameters. For large datasets in JSON, use WQL instead. [src4]
- **Rate limits are per-tenant, not per-ISU**: All integrations sharing a tenant compete for the same ~10 calls/sec limit. Multiple concurrent integrations can starve each other. [src4]
- **WWS version support is 18 months minimum**: Workday guarantees at least 18 months of support per major WWS version. After deprecation notice, integrations MUST upgrade to a supported version. [src2]
- **Module licensing gates API access**: SOAP services are only available for licensed modules. If HCM is licensed but Financials is not, Financial_Management WWS endpoints will not be accessible. [src7]
- **WQL availability requires Prism Analytics or specific licensing**: WQL endpoints may require Prism Analytics or specific module licensing for full access. [src6]

## 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) with Get operations
|   |   +-- Writing data?
|   |       |-- Standard business process (hire, terminate, etc.) -> SOAP (WWS) with Submit/Put operations
|   |       +-- Custom object data -> REST API or Workday Extend
|   |-- Batch/Bulk (scheduled, high volume)
|   |   |-- Outbound (extracting from Workday)?
|   |   |   |-- < 50K rows -> RaaS (XML format with pagination)
|   |   |   |-- > 50K rows -> WQL with pagination or RaaS XML with page chunking
|   |   |   +-- Need calculated fields? -> RaaS (supports calculated fields natively)
|   |   +-- Inbound (loading into Workday)?
|   |       |-- File-based -> EIB (Enterprise Interface Builder) with CSV/XML
|   |       |-- Record-by-record -> SOAP Put/Submit operations with retry logic
|   |       +-- Mass data migration -> Workday's migration tools (not API-based)
|   |-- Event-driven (business process notifications)
|   |   |-- Need outbound notifications? -> Integration Event (Subscribe to business process step)
|   |   +-- Need real-time change detection? -> No native CDC — poll via RaaS/WQL with timestamp filters
|   +-- Reporting / Analytics
|       |-- Ad-hoc queries -> WQL via REST
|       |-- Scheduled reports -> RaaS (schedule in Workday, deliver via EIB)
|       +-- Advanced analytics -> Prism Analytics API
|-- Which direction?
|   |-- Inbound (writing to Workday) -> SOAP WWS (Put/Submit) or EIB
|   |-- Outbound (reading from Workday) -> RaaS, WQL, REST, or Graph API
|   +-- Bidirectional -> design separate inbound/outbound flows with conflict resolution
+-- Error tolerance?
    |-- Zero-loss required -> implement idempotency keys + error logging + retry queues
    +-- Best-effort -> fire-and-forget with exponential backoff on 429s
```

## Quick Reference

### Key SOAP Operations by Service

| Service | Common Operations | Method | Payload | Notes |
|---|---|---|---|---|
| Human_Resources | Get_Workers, Put_Worker, Get_Organizations | POST (SOAP) | XML | Core worker data CRUD [src1] |
| Staffing | Hire_Employee, Terminate_Employee, Change_Job | POST (SOAP) | XML | Business process operations [src1] |
| Compensation | Get_Compensation_Plans, Put_Compensation | POST (SOAP) | XML | Salary, bonus, stock data [src1] |
| Financial_Management | Get_Journals, Submit_Accounting_Journal | POST (SOAP) | XML | GL, AP, AR operations [src1] |
| Payroll | Get_Payroll_Results, Get_Payroll_Input | POST (SOAP) | XML | Payroll data extraction [src1] |
| Benefits_Administration | Get_Benefit_Plans, Enroll_In_Benefits | POST (SOAP) | XML | Benefits enrollment/changes [src1] |
| Recruiting | Get_Job_Requisitions, Get_Candidates | POST (SOAP) | XML | Requisitions and applicant data [src1] |
| Time_Tracking | Get_Time_Entries, Put_Time_Entry | POST (SOAP) | XML | Time clock and timesheet data [src1] |
| Integrations | Get_Integration_Events, Get_Integration_Systems | POST (SOAP) | XML | Integration monitoring [src1] |
| Identity_Management | Get_Workday_Account, Put_Workday_Account | POST (SOAP) | XML | User provisioning/deprovisioning [src1] |

### REST API Key Endpoints

| Resource | Method | Endpoint | Notes |
|---|---|---|---|
| Workers | GET | `/ccx/api/v1/{tenant}/workers` | List/search workers [src5] |
| Worker by ID | GET | `/ccx/api/v1/{tenant}/workers/{id}` | Single worker detail [src5] |
| Organizations | GET | `/ccx/api/v1/{tenant}/organizations` | Org hierarchy [src5] |
| Job Postings | GET | `/ccx/api/v1/{tenant}/jobPostings` | Active job postings [src5] |
| Time Off | GET | `/ccx/api/v1/{tenant}/timeOffRequests` | Time off requests [src5] |

## Step-by-Step Integration Guide

### 1. Create an Integration System User (ISU)

Every Workday integration starts with a dedicated ISU. This is not optional — Workday requires ISUs 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 you can access the required data via Workday search.

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

Required for REST API, Graph API, and WQL access. Not needed for SOAP-only integrations. [src5]

1. Search "Register API Client for Integrations" in Workday
2. Set Client Name, select Non-Expiring Refresh Tokens (recommended for server integrations)
3. Add required scopes (e.g., `HCM`, `Financials`, `Staffing`)
4. Save the Client ID and Client Secret
5. Save the Token Endpoint and Authorization Endpoint URLs
6. Search "Manage Refresh Tokens for Integrations" to generate an initial refresh token

**Verify**: Use the token endpoint to 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]

```bash
# Input:  Client ID, Client Secret, Refresh Token, Token Endpoint
# Output: Access token (JSON response with access_token field)

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` with 200 status.

### 4. Execute a SOAP Request (Get Workers)

For SOAP integrations, construct an XML envelope with WS-Security credentials. [src1, src3]

```xml
<!-- Input:  ISU credentials, tenant endpoint -->
<!-- Output: Worker data in XML format -->

<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/oasis-200401-wss-wssecurity-secext-1.0.xsd">
      <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:Response_Group>
        <wd:Include_Personal_Information>true</wd:Include_Personal_Information>
        <wd:Include_Employment_Information>true</wd:Include_Employment_Information>
      </wd:Response_Group>
    </wd:Get_Workers_Request>
  </env:Body>
</env:Envelope>
```

**Verify**: Response contains `<wd:Get_Workers_Response>` with worker data and total pages count.

### 5. Handle Pagination (SOAP)

SOAP responses include total results and total pages. Loop through pages until all data is retrieved. [src1]

```python
# Input:  SOAP endpoint, ISU credentials
# Output: All worker records across all pages

import requests
from xml.etree import ElementTree

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 the first response page.

### 6. Implement Rate Limit Handling

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

```python
import time
import requests

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 for {url}")
```

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

## Code Examples

### Python: Query Workers via REST API

```python
# 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"
}

# Fetch workers with pagination
offset = 0
limit = 100
all_workers = []

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()
    data = resp.json()
    workers = data.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

```bash
# Input:  Client ID, Client Secret, Refresh Token
# Output: Access token JSON response

# 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 with the access token
curl -X GET "https://wd2-impl-services1.workday.com/ccx/api/v1/{tenant}/workers?limit=10" \
  -H "Authorization: Bearer {access_token}" \
  -H "Accept: application/json"
```

### cURL: Test SOAP API (Get Workers)

```bash
# Input:  ISU credentials, SOAP endpoint
# Output: XML response with worker data

curl -X POST "https://wd2-impl-services1.workday.com/ccx/service/{tenant}/Human_Resources/v45.2" \
  -H "Content-Type: text/xml;charset=UTF-8" \
  -d '<?xml version="1.0" encoding="UTF-8"?>
<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/oasis-200401-wss-wssecurity-secext-1.0.xsd">
      <wsse:UsernameToken>
        <wsse:Username>ISU_User@tenant</wsse:Username>
        <wsse:Password>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>5</wd:Count>
      </wd:Response_Filter>
    </wd:Get_Workers_Request>
  </env:Body>
</env:Envelope>'
```

## Data Mapping

### SOAP API Field Naming Conventions

| Workday Field (SOAP) | REST API Field | Type | Transform | Gotcha |
|---|---|---|---|---|
| Worker_ID/ID | id | String | Direct | SOAP returns composite ID element; REST returns simple string [src1] |
| Legal_Name_Data/First_Name | legalName.firstName | String | Direct | SOAP uses nested XML; REST uses dot-notation JSON [src5] |
| Position_Data/Business_Title | businessTitle | String | Direct | May differ from Job_Profile title [src1] |
| Worker_Status_Data/Active | active | Boolean | XML "1"/"0" to JSON true/false | SOAP returns string; REST returns boolean [src1, src5] |
| Compensation_Data/Total_Base_Pay | N/A | Currency | Requires Compensation WWS | Not available via basic REST worker endpoint [src1] |
| Organization_Data/Organization_Reference | supervisoryOrganization | Object | XML Reference to JSON object | SOAP uses WID reference; REST uses nested object [src1] |
| Effective_Date | effectiveDate | Date | YYYY-MM-DD in both | Workday stores dates in tenant timezone; API returns in tenant timezone [src1] |

### Data Type Gotchas

- **Dates are tenant-timezone-relative**: Workday stores and returns dates in the tenant's configured timezone, not UTC. Integration code must account for timezone conversion when synchronizing with UTC-based systems. [src1]
- **WID (Workday ID) vs Reference ID**: SOAP uses WID references for cross-object relationships. REST uses more readable IDs. When building bidirectional integrations, maintain a WID-to-external-ID mapping table. [src1]
- **Boolean handling differs by API surface**: SOAP represents booleans as "1"/"0" strings. REST and Graph API use JSON true/false. Data transformation logic must handle both formats. [src1, src5]
- **Currency fields lack explicit currency code in some services**: Some SOAP responses return amounts without the currency ISO code. Always fetch the currency from the worker's or organization's default currency settings. [src1]

## Error Handling & Failure Points

### Common Error Codes

| Code | Meaning | Cause | Resolution |
|---|---|---|---|
| 429 | Rate limit exceeded | Too many API calls per second per tenant | Exponential backoff with Retry-After header; reduce concurrency [src4] |
| 401 | Unauthorized | Invalid/expired credentials or token | Re-authenticate; check ISU account is active; refresh OAuth token [src5] |
| 403 | Forbidden | ISU lacks required domain security permissions | Grant Get/Put on required security domains; activate pending security policy changes [src4] |
| 500 | Internal Server Error | Workday server-side error (transient) | Retry with backoff; if persistent, contact Workday support [src4] |
| SOAP Fault: INVALID_REFERENCE | Object reference not found | WID or reference ID does not exist | Validate reference IDs before submission; use Get operations to verify [src1] |
| SOAP Fault: VALIDATION_ERROR | Business rule violation | Data fails Workday validation (e.g., missing required field) | Check Workday business process rules; review error detail message [src1] |
| SOAP Fault: VERSION_ERROR | Unsupported WWS version | Requested version is deprecated or invalid | Update to a supported WWS version (check version directory) [src2] |

[src1, src4, src5]

### Failure Points in Production

- **Payroll window throttling**: During payroll processing windows, API throughput drops significantly as Workday prioritizes payroll calculations. Integrations that run during these windows will experience elevated 429 rates and timeouts. Fix: `Schedule non-critical integrations outside payroll processing windows; implement circuit breaker pattern`. [src4]
- **RaaS JSON timeout on large datasets**: JSON-formatted RaaS reports do not support pagination. Reports returning >50K rows or >2GB frequently timeout at the 30-minute mark. Fix: `Switch to XML format with Response_Filter pagination or use WQL for large datasets`. [src4]
- **Domain security policy not activated**: After granting ISU permissions, failing to run "Activate Pending Security Policy Changes" means the ISU silently receives empty results, not errors. Fix: `Always activate security changes immediately; add to ISU setup checklist`. [src4]
- **Sandbox data drift**: Sandbox tenants may have stale or incomplete data compared to production. Integrations tested in sandbox may behave differently in production due to data volume and business process configuration differences. Fix: `Test with production-like data volumes; refresh sandbox regularly`. [src4]
- **OAuth token storage insecurity**: Storing refresh tokens in plaintext or application code risks credential exposure. Fix: `Use a secrets manager (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault); rotate refresh tokens periodically`. [src5]
- **Concurrent integration starvation**: Multiple integrations hitting the same tenant consume from a shared ~10 calls/sec pool. A runaway integration can starve others. Fix: `Implement per-integration rate limiting; use a shared API gateway with per-integration quotas`. [src4]

## Anti-Patterns

### Wrong: Using JSON format for large RaaS extracts

```python
# 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 and return incomplete/empty data
```

### Correct: Use XML format with pagination for large RaaS extracts

```python
# 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 — If ISU permissions change for one integration, all break.
# Audit logs become impossible to trace to a specific integration.
ISU: ISU_SharedAccount
  -> Integration A (HCM sync)
  -> Integration B (Payroll extract)
  -> Integration C (Benefits enrollment)
```

### Correct: One ISU per integration system

```
# GOOD — Each integration has isolated credentials, permissions, and audit trail.
ISU: ISU_HCM_Sync         -> Integration A (HCM sync)
ISU: ISU_Payroll_Extract   -> Integration B (Payroll extract)
ISU: ISU_Benefits_Enroll   -> Integration C (Benefits enrollment)
```

### Wrong: Hardcoding WWS version without upgrade plan

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

### Correct: Parameterize version and monitor deprecation notices

```python
# 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}"
# Add monitoring: alert when WWS_VERSION approaches deprecation (18-month window)
```

## Common Pitfalls

- **RaaS pagination only works with XML**: Developers frequently attempt JSON pagination with RaaS and get empty or incomplete results. JSON output returns the entire report in a single response with no pagination support. Fix: `Use format=simplexml and add Page/Count parameters, or switch to WQL for JSON pagination`. [src4]
- **Forgetting to activate security policy changes**: This is the #1 support issue. ISU permissions appear correct in configuration but the ISU returns empty data because activation was not run. Fix: `Always run 'Activate Pending Security Policy Changes' after any ISU permission modification`. [src4]
- **Testing only in sandbox**: Sandbox tenants may have different rate limits, data volumes, and business process configurations than production. Fix: `Load-test against a sandbox with production-like data volumes; validate business process behavior matches production`. [src4]
- **Not pinning WWS version**: Using the "latest" version means your integration may break when a new version introduces schema changes. Fix: `Always pin to a specific WWS version in your endpoint URLs and plan version upgrades proactively based on the 18-month support window`. [src2]
- **Ignoring Retry-After headers**: Simple retry loops without reading the Retry-After header waste time and may extend rate limiting. Fix: `Always parse Retry-After header on 429 responses and sleep for the specified duration before retrying`. [src4]
- **Running large extracts during business hours**: Large RaaS or SOAP extracts during peak interactive usage hours may be throttled or cause performance degradation for interactive users. Fix: `Schedule large data extracts during off-peak hours (evenings, weekends) for the tenant's timezone`. [src4]

## Diagnostic Commands

```bash
# 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}"

# Test SOAP API authentication (simple Get_Workers with 1 record)
curl -X POST "https://wd2-impl-services1.workday.com/ccx/service/{tenant}/Human_Resources/v45.2" \
  -H "Content-Type: text/xml" \
  -d '<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/oasis-200401-wss-wssecurity-secext-1.0.xsd"><wsse:UsernameToken><wsse:Username>ISU@tenant</wsse:Username><wsse:Password>pass</wsse:Password></wsse:UsernameToken></wsse:Security></env:Header><env:Body><wd:Get_Workers_Request wd:version="v45.2"><wd:Response_Filter><wd:Count>1</wd:Count></wd:Response_Filter></wd:Get_Workers_Request></env:Body></env:Envelope>'

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

# 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 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

| API Version | Release Date | Status | Breaking Changes | Migration Notes |
|---|---|---|---|---|
| WWS v45.2 (2025R2) | 2026-01-09 | Current | None (patch release) | Latest patch for 2025R2 cycle [src2] |
| WWS v45.1 (2025R2) | 2025-11-14 | Current | None (patch release) | Mid-cycle patch [src2] |
| WWS v45.0 (2025R2) | 2025-09-19 | Current | New services/operations added | Base 2025R2 release [src2] |
| WWS v44.2 (2025R1) | 2025-07-11 | Supported | None (patch release) | Final patch for 2025R1 [src2] |
| WWS v44.0 (2025R1) | 2025-03-14 | Supported | New services/operations added | Base 2025R1 release [src2] |
| REST API v1 | 2019 (initial) | Current | Evolving (additive) | No breaking changes; new resources added per release [src5] |
| Graph API v1 | 2023R1 | Current (GA) | N/A (first release) | Introduced in 2023R1; evolving [src6] |
| WWS v37.0 | 2021-09-17 | Nearing EOL | — | Minimum for some legacy operations; plan upgrade [src2] |

[src1, src2]

### Deprecation Policy

Workday supports each major WWS API version for a minimum of 18 months. Deprecation is announced through Workday Community and release notes. After the deprecation period, unsupported versions may stop working without further notice. Workday maintains backward compatibility within a version — integrations built for v45.0 will continue working with v45.0 even as v46.x is released. However, older versions do not receive new features or operations. [src2]

## When to Use / When Not to Use

| Use When | Don't Use When | Use Instead |
|---|---|---|
| Full CRUD on HCM data (workers, orgs, compensation) | Simple read-only report extraction | RaaS with XML pagination |
| Complex business process operations (hire, terminate, transfer) | Lightweight mobile/web data access | Graph API or REST v1 |
| Financial transactions requiring SOAP security | Bulk data migration (>100K records) | EIB file-based import or Workday migration tools |
| Need access to all 55 WWS services | Real-time change notifications (CDC) | Integration Events + polling (no native CDC) |
| Integration with middleware (MuleSoft, Boomi, Workato) | Direct database-level access | N/A — Workday has no DB access |
| Ad-hoc analytical queries | Need Salesforce-style Platform Events | WQL for ad-hoc; no equivalent event system in Workday |

## Important Caveats

- **Rate limits are not officially published**: The ~10 calls/sec limit is observed by integration partners and documented in community forums, but Workday does not guarantee or publish official rate limits for most API surfaces. Actual throughput may vary by tenant size and load. [src4]
- **No native CDC (Change Data Capture)**: Unlike Salesforce or SAP, Workday does not offer a streaming change detection API. Detecting changes requires polling via RaaS or WQL with timestamp filters, which introduces latency and additional API call overhead. [src7]
- **Sandbox rate limits may differ**: Preview and implementation tenants may have different rate limits and data volumes than production. Integration performance testing in sandbox may not accurately reflect production behavior. [src4]
- **Workday Data Cloud (2026)**: Workday announced Data Cloud for early adopter availability in H1 2026, which will enable zero-copy data sharing with Snowflake and Databricks. This may significantly change the outbound data extraction landscape for Workday integrations. [src6]
- **Rate limits and quotas are subject to change with each Workday release. Always verify against current release notes and Workday Community documentation before building production integrations.** [src4]

## Related Units

- [Workday Extend Platform APIs](https://knowledgelib.io/business/erp-integration/workday-extend-platform-api/2026)
- [SAP SuccessFactors API Capabilities](https://knowledgelib.io/business/erp-integration/sap-successfactors-api-capabilities/2026)
- [ERP API Comparison — HCM Systems](https://knowledgelib.io/business/erp-integration/erp-api-comparison-hcm/2026)