Workday REST API: A Developer's Complete Guide

Workday REST APIs let developers interact with Workday data using standard HTTP methods and JSON payloads. They support OAuth 2.0 authentication, offset-based pagination with configurable limits, and structured error codes that map to specific HTTP status codes. Whether you're building Extend apps, calling endpoints from Orchestrations, or integrating external systems, understanding how these APIs work is essential for building reliable Workday solutions.

Understanding Workday REST API Architecture

Workday exposes REST APIs across multiple functional areas — staffing, compensation, learning, and more. Each API follows a consistent URL pattern:

/api/{service}/{version}/{tenant}/{resource}

For example, the Workers endpoint in the Staffing API follows this structure:

GET https://{hostname}/staffing/{version}/{tenant}/workers

These endpoints support standard HTTP methods: GET for reading data, POST for creating resources, PUT for updating, and DELETE for removing them. Responses are returned in JSON format with consistent envelope structures that include the data payload and metadata like pagination totals.

Before making any API calls, you need to understand three foundational concepts: authentication, pagination, and error handling. Each one has specific patterns in Workday that differ from generic REST API conventions.

Authentication: OAuth 2.0 Flows for Workday REST APIs

All Workday REST API requests require OAuth 2.0 authentication. You pass a Bearer access token in the Authorization header of every request:

GET /common/v1/workers
Authorization: Bearer 7c3obrknwd6nnkxv0r64jdpbx

Getting Started with API Client Registration

Before generating tokens, you must register an API client on the Workday Developer Site. Registration provides you with the credentials needed to request tokens:

• Token Endpoint: https://auth.api.workday.com/v1/token
• Authorization Endpoint: https://auth.api.workday.com/v1/authorize
• Client ID: A unique identifier for your registered client
• Client Secret: Used alongside the Client ID to obtain access tokens

Your company's region determines the base URL for these authorization endpoints. Consult the official Workday documentation on Workday Extend API Gateways and Authorization Base URLs for region-specific values.

PKCE with Authorization Code Grant

The PKCE (Proof Key for Code Exchange) flow is the recommended approach for most integrations. After completing the authorization flow, the token endpoint returns an access token and a refresh token:

{
    "access_token": "7c3obrknwd6nnkxv0r64jdpbx",
    "refresh_token": "yxsiqvdkakj0tp9a4i2xe1fbg4blgrq1noqz2nt1cr4f8dfjpazw0jwe18a2wn656854pzb5vmcqnhpqspytg0cf5jlidyjgnfg",
    "token_type": "Bearer"
}

The token timeout is tied to the session timeout configured by the Workday administrator. When the token expires, submit another request to the authorize endpoint to retrieve a new one.

SAML Bearer Grant

For environments that use SAML 2.0 identity providers, Workday supports the SAML Bearer grant type. The flow works as follows:

1. Register your API client with the SAML Bearer Grant client grant type, selecting the x509 certificate for your Identity Provider (IdP).
2. Call your IdP's API to retrieve a SAML assertion. Extract and base64url-encode the signed SAML assertion.
3. Send an HTTPS POST to the token endpoint:

POST https://auth.api.workday.com/v1/token

grant_type=urn:ietf:params:oauth:grant-type:saml2bearer&assertion={base64url-encoded SAML Assertion}&client_id={API Client ID}

4. Use the returned access token in subsequent API calls:

curl -H "Authorization: Bearer {myAccessToken}" \
  https://{Workday REST API Endpoint}/{resource}

Authentication in Extend Apps vs. Integrations

The authentication approach differs depending on your context:

• Extend Apps: For REST API calls from Extend pages and Orchestrations, you choose an authentication scheme defined in the app's security configuration. This includes Orchestration Authentication and Endpoint Authentication as described in Workday's Extend App Security documentation.
• Integrations: For external apps and integrations, register your API client on the Developer Site and use one of the OAuth flows described above.

RaaS API Authentication

Reports as a Service (RaaS) endpoints support both Basic and OAuth authentication:

• Basic Authentication: Base64-encode the username:password string and pass it in the header:

GET /rpt_Name
Authorization: Basic bG1jbmVpbDpXb3JrZGF5MTIzIQ==

• OAuth Authentication: Use the same Bearer token approach as standard REST APIs:

GET /rpt_Name
Authorization: Bearer 111fq660e8q46sh5x5q17hdht60mgpg8uwmlk0hqf

Endpoints and PMD Configuration

Workday REST API endpoints are organized by functional service areas. When building Extend apps, your endpoints are defined in Process Metadata Documents (PMDs). The PMD declares which authentication types each endpoint requires and how the app interacts with Workday's API Gateway.

Before configuring endpoints in your PMD:

1. Determine the authentication types required by the REST API endpoints.
2. Declare those authentication types in the Site Metadata (SMD).

For external REST API calls from an Extend app, consult the Workday documentation on calling external REST APIs in Extend Apps.

You can also configure a responseErrorDetail property on your inbound and outbound endpoints to surface error messages directly in the endpoint response — a useful technique for debugging during development.

Pagination: Retrieving Large Data Sets

Workday REST APIs use offset-based pagination. GET collection endpoints accept two query parameters:

Parameter	Description	Default	Maximum
limit	Maximum number of items per response	20	100 (some APIs allow up to 1,000)
offset	Zero-based index of the first item to return	0	—

Nested prompt endpoints have both a default and maximum of 1,000.

Pagination in Practice

Here's how pagination works with the GET /workers endpoint:

# First page — returns workers 1-20 (default behavior)
GET /workers
# Equivalent to:
GET /workers?limit=20&offset=0

# Second page — returns workers 21-40
GET /workers?limit=20&offset=20

# Third page — returns workers 41-60
GET /workers?limit=20&offset=40

Each response includes a total field indicating the full size of the result set. Use this value to calculate how many subsequent requests are needed.

Pagination Best Practices

• Always paginate large collections. If you skip pagination, Workday returns only the default number of items (20), and you risk missing data.
• Respect the maximum limit. Setting limit above 100 (or 1,000 for APIs that support it) will not return extra results.
• Use the total field from the first response to calculate loop iterations and avoid unnecessary requests.
• Workday sorts paginated data in ascending instance ID order by default. Any sort parameters you provide on the endpoint take precedence over this default.

Note that RaaS does not natively support limit/offset pagination. If you need paginated results from custom reports, consider using WQL (Workday Query Language) instead. See the WQL and RaaS Comparisons documentation for details.

Error Handling and System Error Codes

Workday REST API errors fall into three categories:

1. Authentication issues — Improper credentials, expired tokens, or missing credentials.
2. Authorization and access issues — Accessing non-existent resources or lacking required permissions.
3. Invalid request issues — Return HTTP 400 Bad Request when the request body contains malformed syntax, missing required parameters, or data that violates business logic validation rules.

System Error Code Reference

The REST API framework returns structured error codes with corresponding HTTP status codes:

Code	HTTP Status	Description	Solution
S1	500	Runtime Object Creation Failure	Retry the request. If it persists, contact Workday Support.
S3	400	Unsupported Version	Verify the version number in your URL path (e.g., v1).
S4	500	Internal Server Error	Retry the request.
S5	400	Failed To Parse Request	Ensure your payload is well-formed JSON/XML and matches the schema.
S6	400	Invalid Reference ID	Check the format and value of IDs in your payload.
S7	400	Invalid Reference Type	Ensure the type definition matches the API documentation.
S9	400	Unsupported Operation	Check if the HTTP method (GET, POST, PUT) is valid for this endpoint.
S10	400	Multiple Processing Options Not Supported	Simplify the request to a single processing flow.
S11	400	Representation Not Found	Verify the content-type and resource identifiers.

Handling Errors in Orchestrations

When building Orchestrations in Workday Extend, pay attention to how error responses flow through your logic:

• HTTP Settings Success Code Range: If you define a success code range in your HTTP settings, any status code outside that range triggers the global error handler (unless a local error handler is defined). If you want to capture non-200 responses for custom processing, consider removing the success code range restriction.
• Local vs. Global Error Handlers: Local error handlers on specific steps take precedence over the global error handler. Use local handlers when you need step-specific error recovery logic.

Rate Limits and Performance Considerations

Workday does not publicly document specific rate limit numbers for REST APIs, and limits can vary by tenant configuration and API. To build resilient integrations:

• Implement exponential backoff when you receive HTTP 429 (Too Many Requests) or 500-series errors.
• Use pagination to break large data requests into smaller chunks instead of fetching everything at once.
• Cache responses where business logic allows, especially for reference data that changes infrequently.
• Monitor your API usage through Workday's integration monitoring tools.

Consult the official Workday documentation or your Workday administrator for tenant-specific rate limit policies.

Best Practices for Workday REST API Development

1. Always use OAuth 2.0. Basic authentication is only supported for RaaS endpoints. All other REST API endpoints require OAuth Bearer tokens.
2. Version your API calls. Include the API version in every request URL to avoid breaking changes when Workday releases updates.
3. Validate payloads before sending. Many 400-series errors come from malformed JSON, missing required fields, or invalid reference IDs. Validate locally before making the API call.
4. Handle token expiration gracefully. Store refresh tokens securely and implement automatic token renewal in your integration logic.
5. Use the Workday Developer Site to explore available endpoints, test API calls, and review response schemas before writing integration code.
6. Log error responses thoroughly. Capture the full error response body — Workday error codes (S1–S12) map to specific problems and solutions that speed up debugging.

Frequently Asked Questions

What authentication method should I use for Workday REST APIs?

Use OAuth 2.0. For most integrations, the PKCE with Authorization Code Grant flow is recommended. For environments using SAML 2.0 identity providers, the SAML Bearer Grant is an option. Basic authentication is only supported for RaaS (Reports as a Service) endpoints, not standard REST APIs.

How do I paginate through large result sets?

Use the limit and offset query parameters on GET collection endpoints. The default page size is 20 items, with a maximum of 100 (or 1,000 for some APIs). The response includes a total field that tells you the full size of the result set, which you can use to calculate the number of pages.

Why am I getting a 400 Bad Request error?

HTTP 400 errors in Workday REST APIs typically indicate malformed request syntax, missing required parameters, or data that violates business logic validation rules. Check the error code in the response body — codes like S5 (Failed To Parse Request), S6 (Invalid Reference ID), and S3 (Unsupported Version) point to specific issues with clear solutions.

Can I use pagination with RaaS custom reports?

RaaS does not natively support limit/offset pagination. If you need paginated results from report data, consider using WQL (Workday Query Language) instead, which does support pagination through the standard REST API pagination mechanism.

How do I handle errors in Workday Extend Orchestrations?

Configure local error handlers on individual Orchestration steps for step-specific recovery logic. Be aware that if you define a success code range in your HTTP settings, any response outside that range automatically triggers the error handler. Remove the success code range if you need to process non-200 responses in your business logic.

Key Takeaways

• All Workday REST API calls require OAuth 2.0 authentication with a Bearer token in the Authorization header. Register your API client on the Workday Developer Site to get started.
• Pagination uses limit and offset parameters with a default page size of 20 and a maximum of 100 (up to 1,000 for select APIs). Always paginate when working with collection endpoints.
• Workday returns structured error codes (S1 through S12) that map to specific HTTP status codes and include actionable solutions. Log and parse these codes for faster debugging.
• Endpoint configuration in Extend apps is managed through PMDs and SMDs, where you declare authentication types and error handling behavior.
• RaaS and standard REST APIs have different authentication and pagination support. Choose WQL over RaaS when you need paginated query results.

For the most current API specifications and endpoint documentation, visit the Workday Developer Portal and the Workday Community.