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
UsernameTokenin the SOAP header, with the user name asisu_name@tenantand aPasswordTextpassword. - Permissions: the Integration System User needs a security group with Get/Put domain permissions, and the security policy changes must be activated.
- Paging: set
PageandCountinResponse_Filterand loop untilTotal_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, 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 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:
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 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:
- Create Integration System User: a user name and password for the integration.
- 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.
- 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”.
- 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:
<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:
<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.
The response reports the totals in Response_Results:
<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:
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:
<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.
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 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, 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 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 & Examples. To compare Workday’s XML with another HRIS, see the SAP SuccessFactors employee data example.
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.
Your app then receives normalized HRIS data through Knit’s syncs, 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 and read data.apps[].isActive. When a customer disconnects their HR system, turn the integration off with POST /integration.deactivate; 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.