Workday API Guide: REST, SOAP, and OAuth Setup

The Workday API gives developers programmatic access to one of the most widely used enterprise HR and finance platforms. Whether you’re syncing employee records to a downstream system, automating payroll workflows, or building custom dashboards, the API is your entry point.

Workday exposes two distinct API flavors — a modern REST API that speaks JSON and uses OAuth 2.0, and a comprehensive set of SOAP Web Services (WWS) that use XML with WS-Security. Choosing the right one depends on what you’re building, and most production integrations end up using both.

This guide covers the REST and SOAP APIs side by side, walks through OAuth 2.0 and Integration System User (ISU) authentication setup, and addresses the practical realities of rate limits, sandbox access, and error handling that you’ll encounter in production.

REST vs. SOAP: Choosing the Right Workday API

Workday maintains two API surfaces that serve different purposes. Understanding their differences upfront saves you from hitting dead ends mid-implementation.

Workday REST API

The REST API is Workday’s newer, more developer-friendly interface. It uses standard HTTP methods, returns JSON, and authenticates via OAuth 2.0. If you’re building a modern SaaS integration or a web application that reads Workday data, REST is typically the right starting point.

REST API strengths include:

• JSON payloads — Smaller, easier to parse, and native to JavaScript/TypeScript environments
• OAuth 2.0 authentication — Scope-based access control with token refresh
• Standard HTTP verbs — GET, POST, PUT, DELETE map to familiar CRUD operations
• Simpler tooling — Works with curl, fetch, and any HTTP client library

Key REST endpoint categories include Workers (employee data), Organizations, Compensation, Staffing, Payroll, Benefits, and Recruitment.

However, the REST API has narrower coverage than SOAP. Not every Workday business object is exposed via REST yet, and Workday continues to expand coverage incrementally.

Workday SOAP Web Services (WWS)

The SOAP API is Workday’s original integration interface and remains the most comprehensive. The current version (v46.1) exposes dozens of web services covering every Workday module — HR, payroll, financials, recruiting, benefits, learning, and more. Each service has a formal WSDL contract and XML schema.

SOAP API strengths include:

• Full CRUD operations — Create, read, update, and delete against virtually all Workday business objects
• Complete module coverage — Payroll, compliance-critical operations, and modules not yet available via REST
• WS-Security — Message-level security with encryption and digital signatures
• Formal contracts — WSDL definitions provide strict type safety and validation

Choose SOAP when you need deep access to payroll processing, complex staffing operations, or any domain that the REST API hasn’t exposed yet. For a deeper dive into the trade-offs, see our guide on transitioning from SOAP to REST APIs.

When to Use Which

Start with REST if you’re building a cloud-native integration, need real-time data access, and the endpoints you need are available. REST is simpler to implement and easier to maintain.

Use SOAP for bulk data operations, payroll and compliance workflows, or any business process that requires WSDL-level strictness. Many production Workday integrations use both — REST for real-time reads and SOAP for write-heavy or batch operations.

Workday API Authentication: OAuth 2.0 and ISU Setup

Workday’s authentication model ties directly to the API flavor you’re using. REST uses OAuth 2.0, SOAP uses Integration System Users (ISUs) with WS-Security headers, and in practice you’ll often configure both.

Integration System User (ISU)

An ISU is a dedicated service account created specifically for API integrations. Instead of using a real employee’s credentials — which would break if that person leaves the organization — an ISU provides a stable, auditable identity for your integration.

Setting up an ISU involves:

1. Create the ISU — Search for “Create Integration System User” in Workday. Set a username and password. Set Session Timeout Minutes to 0 to prevent the account from timing out during long-running operations.
2. Exempt from password expiration — Use the “Maintain Password Rules” task to add the ISU to the “System Users exempt from password expiration” list.
3. Create a security group — Create an integration system security group and assign the ISU to it. This group controls which Workday domains and data the ISU can access.
4. Configure domain security policies — Grant the security group access to the specific functional areas your integration needs (e.g., Worker Data, Compensation, Payroll). Each domain has granular permission levels: Get, Put, and Delete.

Workday recommends limiting each ISU to a single integration system. If you’re building multiple integrations, create separate ISUs for each one — this isolates permissions and simplifies auditing.

OAuth 2.0 for the REST API

For REST API access, you layer OAuth 2.0 on top of the ISU. The flow works like this:

1. Register an API client — Search for “Register API Client for Integrations” in Workday. Give your client a name, select “Non-Expiring Refresh Tokens,” and specify the required scopes. At minimum, include the Integration scope.
2. Generate a refresh token — Use “Manage Refresh Tokens for Integrations” and select your ISU as the Workday Account.
3. Request access tokens — Exchange the refresh token for an access token using the token endpoint:

curl -X POST "https://YOUR_DOMAIN.workday.com/ccx/oauth2/YOUR_TENANT/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -d "grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN"

Access tokens expire after one hour. For long-running batch jobs, you’ll need to handle token refresh in your integration logic — request a new token before the current one expires, or catch 401 responses and re-authenticate automatically.

SOAP Authentication with WS-Security

SOAP requests authenticate using WS-Security headers that embed the ISU’s credentials directly in the XML envelope:

<soapenv:Envelope
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:bsvc="urn:com.workday/bsvc">
  <soapenv: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_USERNAME@TENANT</wsse:Username>
        <wsse:Password>ISU_PASSWORD</wsse:Password>
      </wsse:UsernameToken>
    </wsse:Security>
  </soapenv:Header>
  <soapenv:Body>
    <!-- Your request here -->
  </soapenv:Body>
</soapenv:Envelope>

For production deployments, consider using X.509 certificate-based authentication instead of username/password for stronger security. Understanding API authentication best practices helps you make the right choice for your security requirements.

Making Your First Workday API Requests

Once authentication is configured, you can start querying Workday data. Here are practical examples for both API flavors.

REST API: Retrieve Worker Data

Use curl to fetch a worker’s profile by employee ID:

curl -X GET \
  "https://YOUR_DOMAIN.workday.com/ccx/api/v1/YOUR_TENANT/workers/EMPLOYEE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

A typical response includes the worker’s personal data, employment details, and organizational assignments:

{
  "id": "3aa5550b7fe348b98d7b5741afc65534",
  "descriptor": "Jane Smith",
  "primaryWorkEmail": "jane.smith@example.com",
  "primarySupervisoryOrganization": {
    "descriptor": "Engineering"
  },
  "businessTitle": "Senior Software Engineer"
}

To list multiple workers with pagination:

curl -X GET \
  "https://YOUR_DOMAIN.workday.com/ccx/api/v1/YOUR_TENANT/workers?limit=100&offset=0" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

SOAP API: Retrieve Worker Data

The equivalent SOAP request uses the Human_Resources web service and the Get_Workers operation:

<soapenv:Envelope
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:bsvc="urn:com.workday/bsvc">
  <soapenv: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_USERNAME@TENANT</wsse:Username>
        <wsse:Password>ISU_PASSWORD</wsse:Password>
      </wsse:UsernameToken>
    </wsse:Security>
  </soapenv:Header>
  <soapenv:Body>
    <bsvc:Get_Workers_Request bsvc:version="v46.1">
      <bsvc:Request_References
        bsvc:Skip_Non_Existing_Instances="false">
        <bsvc:Worker_Reference>
          <bsvc:ID bsvc:type="Employee_ID">123456</bsvc:ID>
        </bsvc:Worker_Reference>
      </bsvc:Request_References>
      <bsvc:Response_Group>
        <bsvc:Include_Personal_Information>true</bsvc:Include_Personal_Information>
        <bsvc:Include_Employment_Information>true</bsvc:Include_Employment_Information>
      </bsvc:Response_Group>
    </bsvc:Get_Workers_Request>
  </soapenv:Body>
</soapenv:Envelope>

Send this request with curl:

curl -X POST \
  "https://YOUR_DOMAIN.workday.com/ccx/service/YOUR_TENANT/Human_Resources/v46.1" \
  -H "Content-Type: text/xml;charset=UTF-8" \
  -d @get_workers_request.xml

The SOAP Response_Group element is important — it lets you control exactly which data fields Workday returns. Without it, you’ll get the full data set for each worker, which can be significantly larger than what you need.

Rate Limits and Performance Considerations

Workday enforces rate limits to protect tenant performance. While Workday doesn’t publish comprehensive rate limit documentation publicly, here’s what you need to know:

• General limit: Approximately 10 requests per second per tenant
• Some endpoints are stricter: Certain APIs (like Strategic Sourcing) enforce limits as low as 5 requests per second
• HTTP 429 responses: When you exceed the limit, Workday returns a 429 Too Many Requests status with a Retry-After header

Handling Rate Limits in Production

Design your integration to respect rate limits from the start. Key strategies include:

• Exponential backoff — When you receive a 429, wait for the duration specified in the Retry-After header before retrying. Increase the delay with each subsequent retry.
• Request batching — Group related operations where possible instead of making individual calls.
• Caching reference data — Cache frequently accessed data like organization structures and cost centers locally to reduce API calls.
• Paginate all list operations — Always use pagination regardless of expected result size. Avoid polling intervals shorter than 5 minutes for background sync jobs.

For integrations that need to handle high-throughput data synchronization behind Workday’s rate limits, an API gateway with built-in rate limiting can help you manage request flow, implement retry logic at the infrastructure level, and avoid overwhelming the Workday API.

Sandbox Access and Testing

Unlike many SaaS platforms that offer free developer sandboxes, Workday only provisions sandbox environments for paid customers on certain plans. This means:

• You need an active Workday commercial relationship to get sandbox access
• Sandbox tenants may not perfectly mirror production — custom fields and configurations can differ
• Test data creation requires understanding Workday’s business logic and data relationships

Working Around Limited Sandbox Access

If you’re building an integration and don’t yet have sandbox access:

1. Use the Workday Community documentation — The WWS Directory provides WSDL definitions and schema documentation
2. Mock the API — Build mock endpoints based on Workday’s published schemas to develop and test your integration logic
3. Start with read-only operations — When you do get access, begin with GET requests and validate your authentication flow before attempting write operations
4. Separate environment credentials — Always use different ISUs and OAuth clients for sandbox versus production

Common Integration Scenarios

Organizations use the Workday API across a wide range of operational workflows. Here are the most common patterns.

Employee Data Synchronization — The most popular use case: keeping employee data consistent across multiple systems. When someone changes departments, gets promoted, or updates their contact information in Workday, those changes propagate to corporate directories, email services, identity providers, and access management platforms.

Payroll and Benefits Integration — Workday’s SOAP API provides deep access to payroll processing and benefits administration. Organizations connect Workday to third-party benefits providers, ensuring accurate deductions, enrollment synchronization, and streamlined benefits management.

Custom Reporting and Analytics — By extracting Workday data through the API, teams build reporting solutions that combine HR metrics with other business data. This enables executive dashboards that blend workforce analytics with financial performance, diversity metrics, and headcount planning.

Onboarding Automation — When a new hire is created in Workday, the API can trigger automated workflows: provisioning accounts in email and collaboration tools, enrolling in benefits, assigning training modules, and notifying managers — all without manual intervention.

Identity and Access Management — The Workday API serves as a source of truth for identity data. Organizations synchronize worker records to identity providers, automatically granting and revoking access to internal applications based on employment status, role, and department.

Securing Your Workday Integrations

Workday handles sensitive employee and financial data, so API security isn’t optional — it’s a compliance requirement. Beyond the authentication mechanisms covered above, consider these additional protections:

• Least-privilege access — Configure each ISU and OAuth client with only the permissions needed for that specific integration. Avoid broad security group assignments.
• IP allowlisting — Restrict API access to known networks and IP ranges to reduce the attack surface.
• Credential rotation — Rotate ISU passwords and OAuth client secrets on a regular schedule. Use secrets management tools rather than storing credentials in code.
• TLS everywhere — All Workday API communication uses HTTPS/TLS, but verify that your integration client enforces certificate validation.
• Audit logging — Monitor all API activity through Workday’s integration logs. Set up alerting for failed authentication attempts and unusual access patterns.

For organizations running multiple Workday integrations, an API gateway provides a centralized layer for enforcing authentication policies, rate limits, and request validation — reducing the security burden on individual integration code.

Workday API Alternatives

While the Workday API is powerful, its enterprise focus and licensing model aren’t the right fit for every organization. Here’s how it compares to alternatives:

• BambooHR — A well-documented REST API designed for small to mid-sized businesses. BambooHR’s developer experience is more accessible than Workday’s, though it covers fewer enterprise HR functions.
• ADP Workforce Now — Strong payroll and compliance APIs with a pre-built marketplace of integrations. ADP is particularly competitive for payroll-focused use cases.
• Gusto — Developer-friendly REST APIs designed for startups and small businesses. Simple implementation, modern API design, but limited enterprise-scale features.
• SAP SuccessFactors — Enterprise-grade alternative with OData-based APIs. Comprehensive talent management and core HR coverage, comparable to Workday’s scope.
• UKG (Ultimate Kronos Group) — Strong time tracking and workforce management APIs. UKG excels at labor analytics and scheduling use cases.

The right choice depends on your organization’s size, compliance requirements, and the specific HR/finance workflows you need to automate.

FAQ

What rate limits does the Workday API enforce?

Workday enforces a general limit of approximately 10 requests per second per tenant. Some endpoints have stricter limits — for example, the Strategic Sourcing API allows only 5 requests per second. When you exceed the limit, Workday returns an HTTP 429 Too Many Requests response with a Retry-After header. Design your integration with exponential backoff and request batching to stay within these limits.

Can I get a free Workday sandbox for development?

No. Unlike many SaaS platforms, Workday only provisions sandbox environments for paid customers on certain plans. You need a commercial relationship with Workday to access a sandbox tenant. For development without sandbox access, you can use Workday’s published WSDL schemas to build mock endpoints and test your integration logic locally.

Should I use the REST API or SOAP API?

Start with the REST API if your required endpoints are available — it’s simpler to implement, uses JSON, and supports OAuth 2.0. Use the SOAP API for payroll, compliance-critical operations, or any Workday module not yet exposed via REST. Many production integrations use both APIs depending on the operation.

How long do Workday OAuth 2.0 access tokens last?

Workday OAuth 2.0 access tokens expire after one hour. For long-running batch jobs, implement token refresh logic that either proactively requests a new token before expiration or catches 401 Unauthorized responses and re-authenticates. If you configure non-expiring refresh tokens when registering your API client, you can generate new access tokens indefinitely without re-authorization.

What is an Integration System User (ISU)?

An ISU is a dedicated Workday service account created specifically for API integrations. Instead of using a real employee’s credentials — which would break if that person changes roles or leaves the company — an ISU provides a stable, auditable identity for each integration. Workday recommends creating a separate ISU for each integration system.

How do I handle Workday API errors?

Workday returns standard HTTP status codes for REST (e.g., 400 for bad requests, 401 for authentication failures, 429 for rate limiting) and SOAP faults for web services. Always implement error handling that logs the full error response, retries transient failures with backoff, and alerts on persistent errors. Pay special attention to 429 responses — hitting rate limits repeatedly can indicate a design issue in your integration.

Streamline Your Workday Integrations

The Workday API is a capable but complex integration surface. Between REST and SOAP, OAuth 2.0 and ISU setup, rate limits and sandbox restrictions, there’s significant operational overhead in building and maintaining Workday integrations at scale.

An API management platform can absorb much of this complexity. Zuplo helps you add rate limiting, authentication enforcement, request validation, and monitoring to your Workday integrations — without embedding that logic in every integration service. Sign up for free and see how a programmable API gateway simplifies your Workday integration architecture.