Workday API Integration: What to Know Before You Build

April 23, 2026

Workday is not a developer-first SaaS API. It's an enterprise application that exposes data through three different protocols (SOAP, REST, and Reports-as-a-Service), uses tenant-specific authentication that varies by surface, has a deeply nested data model where every customer has a different schema in practice, and ships biannual releases that introduce deprecations and schema changes. For B2B SaaS products integrating with Workday, the API itself is rarely the hard part — the hard parts are everything around it.

This guide covers the three Workday API surfaces, the operational reality of building and maintaining a Workday integration, and where the per-tenant complexity becomes the dominant cost.

Key takeaways

• Workday exposes three API surfaces: SOAP Web Services (broadest coverage), REST API (modern but partial), and Reports-as-a-Service (custom report extraction). Most production integrations use a combination of all three.
• Authentication is surface-specific: SOAP uses Integration System Users (ISU) with WS-Security; REST uses OAuth 2.0 with tenant-registered API clients. Both are configured per tenant.
• Workday does not provide first-class webhooks. Real-time event delivery is built on polling — either by your application or by an integration layer that wraps polling in webhook-style delivery.
• The data model is deeply nested and effective-dated: Worker → Position → Job Profile → Supervisory Organization, with every change carrying an effective date and an entry date. Every customer adds custom fields and custom objects to this baseline.
• Workday ships biannual releases (R1 in spring, R2 in fall) that introduce deprecations, schema changes, and new required fields. These aren't always immediate breaking changes, but they become breaking when deprecated APIs or fields are eventually removed.
• Build-vs-buy depends on integration scope: a single Workday integration with one customer is tractable. Supporting Workday at scale alongside other HRIS integrations becomes a sustained engineering investment.

What is the Workday API?

Workday API integration is the process of connecting external applications to Workday's HR, payroll, and financial data through a combination of SOAP web services, REST endpoints, and report-based extraction. Unlike modern SaaS APIs, Workday integrations require handling multiple protocols, tenant-specific configuration, and a deeply nested, effective-dated data model.

There is no single Workday API. Engineers building a Workday integration end up working with three distinct surfaces, each with its own protocols, authentication, and coverage limits.

What APIs does Workday actually provide?

SOAP Web Services (WWS)

• XML-based, versioned via WSDL
• Broadest functional coverage across HCM, payroll, and financials
• Required for complex transactional operations (hire, compensation changes, payroll processing)
• Authentication via Integration System User (ISU) with WS-Security UsernameToken headers

REST API

• JSON over HTTP, OAuth 2.0 authentication
• Easier to use than SOAP, faster to integrate against
• Coverage is partial — many operations available in SOAP do not have REST equivalents
• Best for read-heavy patterns (worker data, organizational structures)
• Documented publicly in the Workday REST API community documentation

Reports-as-a-Service (RaaS)

• Custom Workday Advanced reports exposed as web service endpoints
• Returns XML, CSV, or JSON depending on URL parameters
• Used for analytics, ETL extraction, and custom data shapes that don't map cleanly to standard endpoints
• Each call executes the underlying report on demand, so freshness reflects whatever is committed in Workday at call time

Most production integrations use a combination of all three: REST for simple reads, SOAP for complex writes, RaaS for custom extraction.

How does Workday authentication work?

Authentication depends on which API surface you're using.

SOAP authentication: Integration System User (ISU)

The standard pattern for SOAP integrations is to create a dedicated ISU — a non-person, API-only Workday user — and grant it permissions through an Integration System Security Group (ISSG).

The setup pattern:

1. Create the ISU. Use the Create Integration System User task to create a non-person user, typically with "Do Not Allow UI Sessions" enabled so it can only authenticate via integrations.
2. Create an Integration System Security Group. Use Create Security Group and choose Integration System Security Group (Unconstrained) for most integrations. Add the ISU to this group.
3. Grant domain security policies. Use Maintain Permissions for Security Group to assign domain policies with the appropriate Get/Put permissions. Domain policy names are tenant-specific, but illustrative examples include Worker Data: Public, job and position domains, and Compensation if pay data is in scope.
4. Activate security changes. Pending domain security changes don't take effect until you run the security activation task.

Best practice is one ISU per integration (or per integration family) for isolation and auditing, with least-privilege domain policies — only the domains your integration actually needs.

REST authentication: OAuth 2.0

REST APIs use OAuth 2.0 with tenant-registered API clients.

The setup pattern:

1. Enable OAuth 2.0 in tenant setup. A Workday admin runs Edit Tenant Setup – Security and enables "OAuth 2.0 Clients."
2. Register an API client. Run the Register API Client task to create an OAuth client with name, redirect URI, grant type, and scopes. Workday generates a client ID and (depending on configuration) a client secret.
3. Implement the OAuth flow. Standard authorization code flow. Access tokens are short-lived — commonly around 1 hour, configurable per tenant. Refresh tokens are often configured as non-expiring at the tenant level, but this is also a tenant configuration option.

Both authentication models are tenant-scoped. You must store per-customer URLs, client credentials, and ISU details — there is no global Workday endpoint.

What does a Workday REST API call actually look like?

A typical Workday REST URL follows this pattern:

https://{host}.workday.com/ccx/api/v1/{tenant}/{resource}

Where:

• {host} is your tenant's Workday hostname (varies by environment and data center)
• {tenant} is your Workday tenant name
• {resource} is the REST collection (e.g., workers)

A concrete example, retrieving a single worker:

GET https://{host}.workday.com/ccx/api/v1/{tenant}/workers/{worker_id}
Authorization: Bearer {access_token}

This guide uses publicly documented v1 endpoints for examples. Workday also offers newer REST APIs and product-specific services with their own versioning, but exact schema and behavior of newer endpoints varies by release and tenant — consult your tenant's API explorer before hard-coding assumptions about versions beyond v1.

Should you use SOAP or REST?

How does the Workday data model work?

Workday is not flat. The HCM model is a deeply nested object graph centered on four core concepts.

Effective dating

Every change in Workday carries two dates:

• Effective date — when the change applies to the data
• Entry date — when the change was recorded in the application

This means the same worker can return different data depending on the date parameters in your query. Effective dating is critical for any integration that reads historical or future-dated changes (e.g., compensation adjustments scheduled in advance, position changes effective at the start of next quarter).

Custom fields and tenant variability

Every Workday customer adds custom fields, calculated fields, and custom objects to the baseline schema. These are not discoverable by default — they require explicit configuration to surface through the API, and they differ across tenants.

In practice, this means every Workday customer behaves like a different API. Code that works against one tenant may fail against another because of custom field references, security configuration, or the specific subset of objects each tenant has enabled.

How does Workday handle real-time event delivery?

Workday does not provide first-class webhooks. There is no "register a URL and we'll POST events to it" API for HR events, and no Workday-defined webhook signing scheme.

Real-time event delivery in Workday integrations is built on one of three patterns:

• Polling REST or RaaS on a schedule, detecting changes via timestamps or cursors
• Business Process notifications that trigger emails or tasks, which an integration platform consumes
• Virtual webhooks — an integration layer (IPaaS or unified API) polls Workday on your behalf and pushes change events to your application as if they were native webhooks

If you build event delivery yourself, you own the change-detection logic, the polling cadence, the deduplication, the retry and backoff, and any signature scheme on outbound events to your application. Workday's role is limited to serving the API responses your integration polls against.

This is fundamentally different from SaaS APIs that natively push events. For deeper coverage of polling vs. webhook patterns, see our article on polling vs. webhooks.

What are Workday's API rate limits?

Workday enforces tenant-level rate limits across SOAP, REST, and RaaS, but it doesn't publish a single public table the way some SaaS vendors do. Limits vary by tenant and by API, and much of the detail is only available in customer-only documentation. Third-party integrators report different numbers based on their partner testing, but those aren't authoritative for all tenants or all APIs.

Practically, this means:

• Treat throttling as a normal failure mode, not an exception
• Implement retry with exponential backoff on HTTP 429 responses
• Confirm effective limits for your tenant with your Workday admin
• Design polling cadences and batch sizes assuming you can hit limits under load

The lack of canonical published limits is itself part of the operational reality of Workday integration — you can't optimize against numbers Workday won't commit to publicly.

How does Workday handle versioning and breaking changes?

Workday ships biannual releases, typically R1 in spring (around March) and R2 in fall (around September). Each release can introduce:

• API deprecations (still supported, but flagged for eventual removal)
• Schema changes (new fields, modified field semantics)
• New required fields (which can break existing write operations)
• Eventual retirement of previously deprecated APIs

The accurate framing is deprecations that can become breaking changes rather than biannual breaking changes. Workday typically deprecates first, then retires in a later release. If your integration adopts new patterns before deprecated ones are removed, you avoid the break. If it doesn't, the next release after retirement is when things actually fail.

In practice, this means every Workday integration needs roughly 2–3 weeks of regression testing per release cycle to keep up. That's a recurring engineering cost, not a one-time investment.

Why are Workday integrations so difficult?

Several factors compound:

• Multiple protocols. SOAP, REST, and RaaS each have their own auth, request format, and operational characteristics. Engineers building a Workday integration need familiarity with all three.
• Tenant-specific configuration. Per-tenant URLs, per-tenant API clients, per-tenant ISU credentials, per-tenant security policies. None of this is shareable across customers.
• Schema variability across tenants. Custom fields, custom objects, and custom calculated fields differ per customer. Code that works for one customer's tenant may need adjustment for another.
• Deep, nested, effective-dated data model. The Worker → Position → Job Profile → Supervisory Org graph plus effective dating means most queries return more data than expected and require careful date parameter handling.
• No native webhooks. Real-time event delivery requires polling infrastructure your team owns and maintains.
• Biannual release cadence. Continuous regression testing required.
• Cross-team buy-in for setup. A new Workday integration typically requires coordination across HR, IT security, and the customer's Workday admin team. Integrations are rarely "just wire it up."

How long does a Workday integration take?

Rough benchmarks for a B2B SaaS team building directly:

• Read-only sync (workers, organizational data, basic reporting): 2–6 weeks
• Bi-directional integration (with writes for hire, compensation, position changes): 6–12+ weeks
• Production maintenance: ongoing — testing each biannual release, handling schema drift per customer, updating mappings as customers add custom fields

These are time-to-first-customer estimates. Adding additional customers adds work because of tenant variability, even with the integration "built."

For broader context on how integration architecture choices affect long-term engineering overhead, our article on ETL vs. iPaaS vs. Unified API breaks down the trade-offs across approaches.

How does Unified simplify Workday integration?

Unified.to provides a category-level HRIS API that standardizes worker, position, employment, payroll, and time-off objects across Workday, BambooHR, ADP, Rippling, Personio, and other HRIS integrations.

Setup

Configure your OAuth redirect URI to point to Unified, register the integration in your Unified workspace, and authorize each customer's Workday tenant. Authorization produces a connection_id your application uses for every subsequent call.

Calling the API

Example calls:

GET https://api.unified.to/hris/employee/{connection_id}?limit=50
Authorization: Bearer YOUR_API_KEY

GET https://api.unified.to/hris/employment/{connection_id}?limit=50
Authorization: Bearer YOUR_API_KEY

GET https://api.unified.to/hris/group/{connection_id}?limit=50
Authorization: Bearer YOUR_API_KEY

The same endpoints work for BambooHR, ADP, Rippling, and other HRIS integrations — only the connection_id changes. For full API documentation, see docs.unified.to.

What Unified handles

• ISU and OAuth lifecycle management per tenant
• SOAP-vs-REST surface routing (you don't choose; the unified call routes to whichever surface is appropriate)
• Effective-dated query handling
• Tenant-specific schema mapping including custom fields via the metadata APIs
• RaaS-based extraction for objects that aren't covered by REST
• Rate limit handling and retry logic
• Change detection through scheduled polling, surfaced as virtual webhooks
• Biannual release adaptation — Unified updates the integration; your application code doesn't change

For Workday-specific fields not in the normalized HRIS schema, raw passthrough provides direct access to provider-specific endpoints while keeping the unified authentication and connection management.

Direct vs. Unified — when to choose each

Build directly if

• Workday is your only HRIS integration
• You need deep workflow control across SOAP transactions
• You have engineering capacity to absorb biannual release testing as a recurring cost
• Your customers are willing to wait the full integration cycle for each tenant

Use Unified if

• You support (or plan to support) multiple HRIS integrations
• You want time-to-first-customer measured in days, not months
• You'd rather not build polling infrastructure for change detection
• You want consistent webhook semantics across HRIS integrations
• You want to avoid the recurring cost of biannual release adaptation

Sync2Hire, a post-application collaboration platform for recruiting teams, used Unified to ship 19 ATS integrations including Workday, Greenhouse, and Lever in two weeks. "Integrating with ATS platforms typically involves extensive discussions with technical and sales teams," says Neal Akyildirim, Co-founder and COO. "However, Unified's streamlined approach, clear setup, and thorough documentation have made the process remarkably simple and effortless."

If you're evaluating unified API platforms specifically for HRIS coverage, our Merge vs. Unified comparison breaks down the architectural and pricing differences between the two leading providers.

Frequently asked questions

Does Workday have a REST API?

Yes, but coverage is partial. The REST API handles many read operations cleanly but does not cover all functionality available in SOAP. Most production integrations use both REST and SOAP.

Does Workday support webhooks?

Not in the conventional sense. Workday does not push HTTP events to registered URLs the way modern SaaS APIs do. Real-time event delivery in Workday integrations is built on polling — either by your application or by an integration layer that wraps polling in webhook-style delivery.

Why is the Workday API so complex?

Several factors compound: multiple protocols (SOAP + REST + RaaS), tenant-specific configuration, deeply nested and effective-dated data model, per-customer schema variability through custom fields and objects, biannual release cycles requiring regression testing, and security configuration that requires Workday admin involvement to set up.

How long does a Workday integration take?

Read-only syncs typically take 2–6 weeks of engineering time for an experienced team. Bi-directional integrations take 6–12+ weeks. Maintenance is ongoing, not one-time.

Do all Workday tenants have the same schema?

No. Core objects (Worker, Position, Job Profile, Supervisory Organization) are consistent. Beyond that, every tenant has custom fields, custom objects, calculated fields, security policies, and API versions that differ. In practice, every Workday customer behaves like a different API.

Can I get real-time data from Workday?

Sort of. There's no real-time push mechanism — no native webhooks, no event stream. Near-real-time access requires polling at the cadence your use case demands. Most B2B SaaS Workday integrations land somewhere between every-few-minutes polling and hourly batch extraction depending on the data type and rate-limit headroom.

How does Unified help with Workday integration?

Unified abstracts the SOAP/REST/RaaS surface routing, handles ISU and OAuth lifecycle, normalizes the data model into a unified HRIS schema, manages effective dating, surfaces change events as virtual webhooks, and adapts to biannual Workday releases without requiring your application code to change.

Final thoughts

Workday API integration is fundamentally different from modern SaaS API integration. The complexity isn't in the endpoints — it's in the multi-protocol architecture, the per-tenant configuration, the schema variability across customers, the lack of native webhooks, and the biannual release cycle that requires continuous engineering investment.

For B2B SaaS products that need to support Workday alongside other HRIS integrations (BambooHR, ADP, Rippling, Personio, etc.), building each one separately means repeating the lifecycle work per integration. A unified HRIS API removes most of the per-vendor implementation work while preserving the customer-side setup that Workday fundamentally requires.

Unified.to's HRIS API supports Workday alongside BambooHR, ADP, Rippling, Personio, SAP SuccessFactors, and others through a single normalized schema.

Start a free trial or book a demo to see it work.