Editor's note: This is a series on API-based integrations. Check out Merge if you're looking to add 40+ HRIS integrations with one HR API.
â
If youâre building a direct integration with Workday, one of the most basic things youâll want to do is pull employees from the Workday API. The following article covers how you can start interacting with Workdayâs SOAP API.
As a note from the authors (whoâve built an entire Workday integration), we truly believe the quickest way to get a Workday integration is via a unified API provider, such as Merge.Â
In this article, we'll cover how to understand Workday's SOAP API, how to set proper permissions in Workday, and how to write a GET request to Workday's SOAP API in Python.
Understanding Workdayâs SOAP API
While most modern applications structure their APIs with a REST architecture, Workday employs an architecture known as SOAP. SOAP stands for Simple Object Access Protocol, and returns information with the following format:
Authentication and Permissions with the Workday API
Getting Permissions for Workday HRIS and ATS
In order to begin receiving SOAP responses from Workday, you need to create an Integrated System User (ISU) with the proper permissions. Workday configures their permissions on a field level, so youâll need to grant yourself access to a number of fields to get things up and running.Â
Please note that the following steps will need to be accomplished by a Workday user with administrative access.Â
- Access the Create Integration System User task through Workdayâs search bar and create a new user
- Add the new user to the list of System Users in order to guarantee the password you created does not expire
- Access the Create Security Group task and create a new User-Based Security Group
- Add the Integration System User youâve created to the group and save your progress
After step four, youâll need to follow different processes depending on which Workday API endpoints you wish to pull data from.Â
Accessing the Workday HRIS API
- Search Workday for Public Web Services
- Open the report
- Hover over Human Resources and click the three dots to access the menu
- Click Web Service, then View WSDL
- Navigate to the bottom of the WSDL page to find the hostname
- Look for the Username, Password, Tenant Name (https://wd5-services1.workday.com/TENANT_NAME), and Endpoint URL. Save these somewhere secure for later
Accessing the Workday ATS API
- Navigate to the Domain Security Policy tab under Web ServiceÂ
- Search for Recruiting Web Services
- Add permissions to the Userâs Security Group for the endpoints youâll be accessing (for example Get_Applicants, Get_Job_Postings, etc.)
- Look for the Username, Password, Tenant Name (https://wd5-services1.workday.com/TENANT_NAME), and Endpoint URL under the Userâs Security Group. Save these somewhere secure for later.
How to Get Employees from the Workday API in Python
Set Up Your Request File
Open up a new Python file, and call it workday_requester.py
Import json, requests, and xmltodict from parse.Â
As we mentioned above, the Workday API returns responses in XML. You, like most developers, are probably used to a dictionary. xmltodict lets us parse the response by returning an ordered dictionary that we can then turn into a dictionary.
â
Create and store the tenant_name, your username, password, and url from Step 4 as variables.
Construct Your SOAP Request Body
Below is an example of the request body you would use to fetch employees using the Get Workers Endpoint. Youâll need to tweak this request body to fit the API endpoint youâd like to call.
Note that to deal with pagination, you need to set a page number for the request as well. Save this as a variable.
SOAP requests contain 2-4 blocks. You can think of a block as similar structure HTML, which requires both an opening and closing tag. The SOAP blocks are Envelope, Header, Body, and Fault. The syntax for these are:
<soapenv:{blockname}> </soapenv:{blockname}>
For a basic SOAP request, only the Envelope and Body are required.Â
To get employees, weâll need to use the Envelope, Header, and Body blocks.
To help you think about the structure of SOAP, you can think of a SOAP Request as a âpackage/â The Envelope is being the âpackaging,â the Header is the âSent from Addressâ, and the Body is the âletter/contentsâ of the package.
Weâll first create the Envelope with a namespace attribute xmlns:soapenv=âhttps://schemas.xmlsoap.org/soap/envelope/â .Â
Our opening Envelope block will look something like this:
The other two blocks (the Header and Body) will be wrapped inside this Envelope.Â
The Header will contain our API access credentials and the security needed to access it. Alone, the header will look like this:
The bulk of our actual request will be in the Body. There, we will define the parameters and data weâd like to fetch.Â
For our example, weâre making a Get_Workers_Request, and because weâre also using pagination weâll want to pass page_number as a parameter.
To call a different endpoint, change the bsvc payload in the SOAP body to the endpoint of your choosing.
Note how weâre leaving out soapenv:Fault, which would generally be used to catch error codes when your SOAP API call is incomplete.
Look at the example below to see how the Envelope, Header, and Body all fit together in a SOAP request.
Pull and Format your Workday API Employee Request
Weâll then want to make the call by calling requests with the URL and request body. In a traditional REST API call we would use method=âGETâ, but with SOAP weâll be calling âPOSTâ to the Get_Workers_Request endpoint to access this data.
In order to make the resulting response more readable, we can use json.loads and the parse method to convert the response to a dictionary.
The resulting response will look similar to this:
Weâve shortened the response here, but the response will likely include fields like the employees contact information, hire date, weekly hours and more!
And thatâs it! Youâve successfully pulled the employees object from the Workday API.
At Merge, weâve built an API that lets you easily pull from Workday using REST (no SOAP required). Our Unified API has also smoothed out pagination and authentication.Â
We offer over 60+Â integrations, including Workday, BambooHR, and UKG.
If you already have Workday credentials, you can sign-up for a Merge account here, learn how to add a test linked account here, and begin testing Merge endpoints here. Interested in our other categories like Merge Accounting? We've written a similar tutorial on getting invoices from the Netsuite API using Python here!
â