---
title: "Building a Workday SOAP API Integration for B2B SaaS"
url: "https://getknit.dev/blog/build-a-workday-soap-api-integration-for-b2b-saas/"
date: "2026-11-18T14:15:10+00:00"
modified: "2026-11-18T14:15:10+00:00"
type: "post"
---

# Building a Workday SOAP API Integration for B2B SaaS

[Blog](https://getknit.dev/blog) / [Tutorials](https://getknit.dev/blogs/tutorials/) / Building a Workday SOAP API Integration for B2B SaaS [Tutorials](https://getknit.dev/blogs/tutorials/) · November 18, 2026 

Building a Workday SOAP API Integration for B2B SaaS
====================================================

 ![](https://storage.googleapis.com/knit-website-media/2026/08/6480513e451645aedc97356f_640d682a695339041d6fad07_Yash-3-112x112.jpeg)Yasharth Mishra

11 min read

 

 

 [](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fgetknit.dev%2Fblog%2Fbuild-a-workday-soap-api-integration-for-b2b-saas%2F) [](https://twitter.com/intent/tweet?url=https%3A%2F%2Fgetknit.dev%2Fblog%2Fbuild-a-workday-soap-api-integration-for-b2b-saas%2F&text=Building%20a%20Workday%20SOAP%20API%20Integration%20for%20B2B%20SaaS)  

 

 

 

  Table of Contents - [How Workday Web Services Are Organized](#how-workday-web-services-are-organized)
- [Constructing the Workday SOAP Endpoint URL](#constructing-the-workday-soap-endpoint-url)
- [Setting Up the Integration System User](#setting-up-the-integration-system-user)
- [Authenticating with the WS-Security Header](#authenticating-with-the-ws-security-header)
- [Fetching Workers with Get\_Workers](#fetching-workers-with-get_workers)
- [Incremental sync with the transaction log](#incremental-sync-with-the-transaction-log)
- [Handling SOAP Faults](#handling-soap-faults)
- [Workday SOAP vs. REST API: Making the Right Choice](#workday-soap-vs-rest-api-making-the-right-choice)
- [Managing the Connection with Knit](#managing-the-connection-with-knit)
- [Frequently Asked Questions](#frequently-asked-questions)
 
  A Workday SOAP API integration connects a B2B SaaS product to a customer’s Workday tenant through Workday Web Services: XML requests, sent over HTTPS to a tenant-specific URL, authenticated with a WS-Security header. This guide covers the parts that trip teams up on the first build: the endpoint URL, the Integration System User and its permissions, a working `Get_Workers` request with paging and incremental sync, and how to handle SOAP faults.

**Key takeaways**

- **Endpoint:** send SOAP calls to `https://{host}/ccx/service/{tenant}/{Service}/v{version}`, where the host is the customer’s Workday data-center host, not the tenant name.
- **Authentication:** put a WS-Security `UsernameToken` in the SOAP header, with the user name as `isu_name@tenant` and a `PasswordText` password.
- **Permissions:** the Integration System User needs a security group with Get/Put domain permissions, and the security policy changes must be activated.
- **Paging:** set `Page` and `Count` in `Response_Filter` and loop until `Total_Pages`.
- **Errors:** Workday returns a SOAP Fault in the body with HTTP 500.

How Workday Web Services Are Organized
--------------------------------------

Workday groups its SOAP operations into named web services, each with its own WSDL and version. Worker data lives in the `Human_Resources` service, which holds the `Get_Workers` operation most HR integrations start with. Other services cover other functional areas, such as Staffing, Compensation and Recruiting. Workday lists them in its [public web services directory](https://community.workday.com/sites/default/files/file-hosting/productionapi/index.html), with the request and response schema for each operation.

Every request body uses the `urn:com.workday/bsvc` namespace and states the version it was written against, for example `<Get_Workers_Request bsvc:version="v42.0">`. Microsoft’s [Workday integration reference](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/workday-integration-reference) shows the full requests its own Workday connector sends, and it is one of the best public examples of production `Get_Workers` calls.

Constructing the Workday SOAP Endpoint URL
------------------------------------------

A SOAP request goes to a URL built from three customer-specific values: the Workday host for the customer’s data center, the tenant name, and the service with its version:

```text
https://{host}/ccx/service/{tenant}/{Service_Name}/v{version}

# example
https://wd2-impl-services1.workday.com/ccx/service/acme/Human_Resources/v42.0

```

Store the host, tenant and version per customer; never hardcode them. Pin the version in the URL. Microsoft’s [Workday provisioning tutorial](https://learn.microsoft.com/en-us/entra/identity/saas-apps/workday-inbound-tutorial) shows why: when the URL stops at `/ccx/service/tenantName` or `/ccx/service/tenantName/Human_Resources`, its connector falls back to v21.1, and only `/Human_Resources/v##.#` uses the version you specify.

Don’t mix this up with the REST URL. Workday’s REST API uses a different pattern under `/api/{service}/{version}/{tenant}`, so a host-and-tenant pair that works for one API won’t simply drop into the other.

Setting Up the Integration System User
--------------------------------------

SOAP calls authenticate as an Integration System User (ISU), a non-human account the customer’s Workday admin creates for your integration. The setup is the same for every customer, so put it in your onboarding guide. Microsoft’s tutorial walks through the tasks:

1. **Create Integration System User**: a user name and password for the integration.
2. **Create a security group** of type Integration System Security Group (Unconstrained), or (Constrained) to limit which workers the ISU can see, and add the ISU to it.
3. **Grant domain permissions**: add the domains your integration reads to the group’s “Domain Security Policies permitting Get access” list, and the domains it writes to “permitting Put access”.
4. **Activate Pending Security Policy Changes**, or none of the permissions take effect.

Missing domain permissions are the usual reason a request succeeds but returns less data than expected. Microsoft’s reference notes that each Workday entity is protected by a domain security policy; reading skill data, for example, needs Get access on the domain *Worker Data: Skills and Experience*. A constrained group is also how a customer limits your integration to certain supervisory organizations.

Authenticating with the WS-Security Header
------------------------------------------

The ISU’s credentials travel in a WS-Security `UsernameToken` inside the SOAP header. The user name is the ISU name with the tenant appended (`isu_name@tenant`), and the password is sent as `PasswordText`, so the request must go over HTTPS:

```xml
<soapenv:Header>
  <wsse:Security soapenv:mustUnderstand="1"
      xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
    <wsse:UsernameToken>
      <wsse:Username>isu_name@acme</wsse:Username>
      <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">ISU_PASSWORD</wsse:Password>
    </wsse:UsernameToken>
  </wsse:Security>
</soapenv:Header>

```

Treat the ISU password like any other customer secret: encrypt it at rest, and plan for rotation, since the customer’s password policy may expire it.

Fetching Workers with Get\_Workers
----------------------------------

A full envelope combines the header above with a `Get_Workers_Request` body. `Response_Filter` controls paging (`Page` and `Count`), and `Response_Group` controls which parts of the worker record come back:

```xml
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:bsvc="urn:com.workday/bsvc">
  <soapenv:Header>
    <!-- the wsse:Security block from the previous section -->
  </soapenv:Header>
  <soapenv:Body>
    <bsvc:Get_Workers_Request bsvc:version="v42.0">
      <bsvc:Response_Filter>
        <bsvc:Page>1</bsvc:Page>
        <bsvc:Count>100</bsvc:Count>
      </bsvc:Response_Filter>
      <bsvc:Response_Group>
        <bsvc:Include_Reference>1</bsvc:Include_Reference>
        <bsvc:Include_Personal_Information>1</bsvc:Include_Personal_Information>
        <bsvc:Include_Employment_Information>1</bsvc:Include_Employment_Information>
        <bsvc:Include_Organizations>1</bsvc:Include_Organizations>
      </bsvc:Response_Group>
    </bsvc:Get_Workers_Request>
  </soapenv:Body>
</soapenv:Envelope>

```

The diagram below shows the full exchange: your app builds the envelope, posts it to the tenant’s service URL, and either pages through the results or reads a SOAP Fault.

```mermaid
sequenceDiagram
    accTitle: Workday Get_Workers request flow
    participant App as Your app
    participant WD as Workday /ccx/service/{tenant}/Human_Resources/v{version}
    App->>App: Build envelope with WS-Security UsernameToken
    App->>WD: POST Get_Workers_Request (Page 1)
    alt Valid request
        WD-->>App: HTTP 200, worker data + Response_Results
        App->>WD: Repeat with Page + 1 until Total_Pages
    else Invalid request or credentials
        WD-->>App: HTTP 500 with SOAP Fault
    end

```

The response reports the totals in `Response_Results`:

```xml
<wd:Response_Results>
  <wd:Total_Results>509</wd:Total_Results>
  <wd:Total_Pages>17</wd:Total_Pages>
  <wd:Page_Results>30</wd:Page_Results>
  <wd:Page>1</wd:Page>
</wd:Response_Results>

```

To read the next page, send the same request with `Page` incremented, until you reach `Total_Pages`. A minimal loop in Python:

```python
import requests
import xml.etree.ElementTree as ET

URL = "https://wd2-impl-services1.workday.com/ccx/service/acme/Human_Resources/v42.0"
NS = {"wd": "urn:com.workday/bsvc",
      "soapenv": "http://schemas.xmlsoap.org/soap/envelope/"}

def fetch_workers(envelope_for_page):
    """envelope_for_page(n) returns the Get_Workers envelope above with Page = n."""
    page, total_pages = 1, 1
    while page <= total_pages:
        resp = requests.post(URL, data=envelope_for_page(page).encode("utf-8"),
                             headers={"Content-Type": "text/xml; charset=utf-8"},
                             timeout=120)
        root = ET.fromstring(resp.content)
        fault = root.find(".//soapenv:Fault", NS)
        if fault is not None:
            raise RuntimeError(fault.findtext("faultstring"))
        total_pages = int(root.findtext(".//wd:Response_Results/wd:Total_Pages", namespaces=NS))
        for worker in root.iterfind(".//wd:Response_Data/wd:Worker", NS):
            yield worker
        page += 1

```

### Incremental sync with the transaction log

After the first full load, don’t re-read every worker. `Get_Workers` accepts `Transaction_Log_Criteria_Data` in `Request_Criteria`, so you can ask only for workers changed in a time window. This is how Microsoft’s connector runs its incremental syncs: `Updated_From`/`Updated_Through` catches entries made in that window, and `Effective_From`/`Effective_Through` catches effective-dated changes such as terminations that take effect in it:

```xml
<bsvc:Request_Criteria>
  <bsvc:Transaction_Log_Criteria_Data>
    <bsvc:Transaction_Date_Range_Data>
      <bsvc:Updated_From>2026-11-17T00:00:00Z</bsvc:Updated_From>
      <bsvc:Updated_Through>2026-11-18T00:00:00Z</bsvc:Updated_Through>
    </bsvc:Transaction_Date_Range_Data>
  </bsvc:Transaction_Log_Criteria_Data>
</bsvc:Request_Criteria>

```

Save the end of each window as your watermark and start the next run from it. Future-dated hires need care: Microsoft’s connector looks them up again by WID, effective on the hire date, so their record shows the job they are about to start. For one worker, use `Request_References` with a `Worker_Reference` ID instead of criteria.

For a step-by-step example on another Workday data set, see [Get Employee Leave Data from Workday API using Python](https://getknit.dev/blog/get-employee-leave-data-from-workday-api-using-python/).

Handling SOAP Faults
--------------------

Workday reports errors as a SOAP Fault in the response body, not as a JSON error object. Under the SOAP 1.1 specification, a server that hits an error while processing a request [must answer with HTTP 500](https://www.w3.org/TR/2000/NOTE-SOAP-20000508/#_Toc478383529) and a Fault element, so don’t treat a 500 as a crash: parse the body and log the `faultstring`, as the loop above does.

When a call fails or returns less than expected, check these first:

- **Credentials rejected**: the user name must be `isu_name@tenant`, and the tenant in the user name must match the one in the URL.
- **Request rejected as invalid**: the request must match the schema of the version in the URL and in `bsvc:version`; check the operation’s page in Workday’s directory for that version.
- **Fields or workers missing, no error**: the ISU’s security group lacks Get access on a domain, or a constrained group hides those workers.

Workday SOAP vs. REST API: Making the Right Choice
--------------------------------------------------

Workday also offers a JSON REST API. Requests are simpler, and it suits lighter reads. According to [Workday’s documentation](https://developer.workday.com/documentation/dan1370797991225/ReferenceWorkers), `GET /workers?limit=5&offset=99` retrieves 5 workers starting with the 100th, and `GET /workers/{id}?view=workerSummary` returns one worker with a different view. [REST pagination](https://developer.workday.com/documentation/lvb1611857200890/ConceptWorkdayRESTAPIPagination) uses `limit` and `offset`, with a default limit of 20 and a maximum of 100.

SOAP is the established route for full worker syncs: `Get_Workers` returns the whole worker record, controlled by `Response_Group`, and the transaction-log criteria give you incremental sync. REST needs its own OAuth client registered in the tenant, so if you use both APIs you manage two sets of credentials per customer. Pick per data set: whichever API documents the data you need with the permissions the customer will grant. For a REST-first walkthrough, read the [Workday API Integration Guide: Setup &amp; Examples](https://getknit.dev/blog/workday-api-integration-in-depth/). To compare Workday’s XML with another HRIS, see the [SAP SuccessFactors employee data example](https://getknit.dev/blog/developer-guide-to-get-employee-data-from-sap-success-factors-api/).

Managing the Connection with Knit
---------------------------------

With Knit, you don’t build the WS-Security header or the tenant URL yourself. The customer connects Workday by entering their Workday URL, Integration System User name and password, and tenant name. Knit builds the `isu_name@tenant` token and the service URL for each call. REST-only data, such as bank accounts, also needs a REST client ID, client secret and refresh token from the customer’s tenant. For the data Knit covers for Workday, see the [Workday integration page](https://getknit.dev/integration/workday-api/).

Your app then receives normalized HRIS data through Knit’s [syncs](https://developers.getknit.dev/docs/register-webhook-url), delivered to your webhook, instead of parsing Workday XML. Every Knit API call uses the base URL `https://api.getknit.dev/v1.0` with two headers: `Authorization: Bearer <YOUR_KNIT_API_KEY>` and `X-Knit-Integration-Id: <YOUR_INTEGRATION_ID>`.

To check a connection, call [GET /integration.details](https://developers.getknit.dev/reference/get-integration-details) and read `data.apps[].isActive`. When a customer disconnects their HR system, turn the integration off with [POST /integration.deactivate](https://developers.getknit.dev/reference/deactivate-integration); the details endpoint then fills in `data.apps[].deactivatedAt`.

Frequently Asked Questions
--------------------------

**What is the Workday SOAP API endpoint URL format?**
Workday SOAP requests go to `https://{host}/ccx/service/{tenant}/{Service_Name}/v{version}`, for example `https://wd2-impl-services1.workday.com/ccx/service/acme/Human_Resources/v42.0`. The host depends on the customer’s data center, and the version should be stated explicitly in the URL.

**How does Workday SOAP authentication work?**
Workday SOAP uses a WS-Security `UsernameToken` in the SOAP header. The user name is an Integration System User with the tenant appended (`isu_name@tenant`), and the password is sent as `PasswordText` over HTTPS. The ISU’s security group needs domain permissions for every operation it calls.

**How do I paginate Workday Get\_Workers results?**
You paginate `Get_Workers` with `Page` and `Count` in `Response_Filter`. Each response reports `Total_Results` and `Total_Pages` in `Response_Results`, so you send the same request with `Page` incremented until you reach `Total_Pages`.

**Why does a Workday SOAP call return HTTP 500?**
A Workday SOAP call returns HTTP 500 with a SOAP Fault in the body when Workday rejects the request, as the SOAP 1.1 specification requires. Parse the Fault’s `faultstring`: the usual causes are a wrong `isu_name@tenant` user name or a request that doesn’t match the schema of the version in the URL.

**Should I use the Workday SOAP API or the REST API?**
Use SOAP for full worker syncs: `Get_Workers` returns the complete worker record and supports incremental sync through the transaction log. Use REST for lighter JSON reads that it documents, keeping in mind it needs a separate OAuth client in the customer’s tenant.

Building integrations into your product?

Knit gives you three ways to build them. Pick the one that fits.

- [Unified API](/products/unified-api/)
    
    Your customers use many tools in one category (HRIS, ATS, CRM, accounting). Build one integration and get normalised read and write data with real-time webhooks.
    
    [Try free](https://dashboard.getknit.dev/signup)
- [Integrations Agent](/products/integrations-agent/)
    
    You need one specific workflow. Describe it in plain English and get production-ready code, not fixed iPaaS blocks.
    
    [Try free](https://agent.getknit.dev/)
- [MCP Servers](/products/mcp-servers/)
    
    Your AI agent needs to read and act in your customers' apps. Use pre-built, hosted MCP servers instead of writing integration code.
    
    [Try free](https://mcphub.getknit.dev/)

Knit's Unified API connects to 190+ apps across HRIS, ATS, CRM, accounting and more.

Knit never stores your end users' data and is SOC 2, GDPR and ISO 27001 compliant: [How Knit handles security](/security/) · [Security Center](https://compliance.getknit.dev/)

Not sure which fits? [Talk to a human](/book-demo/)

 

 ![](https://storage.googleapis.com/knit-website-media/2026/08/6480513e451645aedc97356f_640d682a695339041d6fad07_Yash-3-112x112.jpeg)Written by Yasharth Mishra

Unifying the world of integration with Knit

 

 

 

 

 

  Keep Reading
------------

  ![How to Build an Attio API Integration to Sync CRM Data](https://storage.googleapis.com/knit-website-media/2026/08/blog-banner-red-scaled-640x400.png) [Tutorials](https://getknit.dev/blogs/tutorials/) 

### [How to Build an Attio API Integration to Sync CRM Data](https://getknit.dev/blog/build-an-attio-api-integration-for-crm-data-sync/)

Building an Attio API integration requires querying object endpoints, paginating through record results, and handling HTTP 429 responses to stay…

 November 18, 2026 · 8 min read 

 

   ![How to Build a Reliable GoHighLevel API Integration](https://storage.googleapis.com/knit-website-media/2026/08/blog-banner-green-640x400.png) [Tutorials](https://getknit.dev/blogs/tutorials/) 

### [How to Build a Reliable GoHighLevel API Integration](https://getknit.dev/blog/how-to-build-a-reliable-gohighlevel-api-integration/)

A GoHighLevel API integration connects B2B applications directly to this CRM platform. This connection allows developers to sync contacts, trigger…

 November 13, 2026 · 7 min read 

 

   ![How to Read and Write Data with the Google Sheets API](https://storage.googleapis.com/knit-website-media/2026/08/blog-banner-yellow-scaled-640x400.png) [Tutorials](https://getknit.dev/blogs/tutorials/) 

### [How to Read and Write Data with the Google Sheets API](https://getknit.dev/blog/how-to-read-and-write-data-google-sheets-api/)

The Google Sheets API is a RESTful interface that lets you read and modify a spreadsheet’s data. Engineers build integrations…

 November 3, 2026 · 6 min read 

 

  

 

  \#1 in Ease of Integrations
---------------------------

![4.9 out of 5 stars](/wp-content/themes/knit/assets/images/g2/g2-star-rating.svg)

4.9 out of 5 stars on G2

![G2 Leader, Spring 2026](/wp-content/themes/knit/assets/images/g2/g2-leader.svg)![G2 Fastest Implementation, Spring 2026](/wp-content/themes/knit/assets/images/g2/g2-fastest-implementation.svg)![G2 High Performer, Spring 2026](/wp-content/themes/knit/assets/images/g2/g2-high-performer.svg)![G2 Best Est. ROI, Spring 2026](/wp-content/themes/knit/assets/images/g2/g2-best-roi.svg)

 

  Put Integrations on Autopilot. Talk to Experts.
-----------------------------------------------

Knit is loved by customers across the globe due to our seamless product and white glove support. You'll love us too!

 [Talk to a Human](/book-demo)
