Workday unlocks a powerful HR ecosystem, but integrating Workday with your existing tools can be complex. endeavour. This guide empowers developers to navigate those challenges and unlock the full potential of Workday integrations.
Introduction to Workday API
Overview of Workday
Ever wondered why Gartner named Workday Leader for Cloud ERP for Service-Centric Enterprise and why top companies use it. Workday is a cloud-based enterprise management platform designed to simplify workforce management. From HR to Payroll to finance and analytics processes, all in one integrated system. Workday Integration API streamlines data exchange, enabling seamless integration between Workday and external systems.
Importance of Integrating with Workday
- Streamlined Processes: Manual data entry is a persistent challenge, but it can be very well tackled by Workday. It automates workflows, minimizes errors, and reduces manual data entry.
- Real-Time Data Sync: Real-time synchronization of data via integration helps improve decision-making.
- Enhanced Analytics and Reporting: Deeper insights into business performance is the heart of growth for an organization, which Workday can easily help you with.
- Scalability and Flexibility: Workday can scale with your needs, which allows easy addition of new features as per our requirements.
Benefits of Workday API Integration
- Streamlined Workflows: Automate data exchange, saving HR professionals valuable time and boosting efficiency.
- Real-Time Business Insights: Gain access to a unified view of your data, enabling data-driven decisions for business leaders.
- Scalability and Flexibility: Integrate new applications as your needs evolve, ensuring your systems grow with your organization.
While this guide equips developers with the skills to build robust Workday integrations through clear explanations and practical examples, the benefits extend beyond the development team. You can also expand your HRIS integrations with the Workday API integration and automate tedious tasks like data entry, freeing up valuable time to focus on other important work. Business leaders gain access to real-time insights across their entire organization, empowering them to make data-driven decisions that drive growth and profitability. This guide empowers developers to build integrations that streamline HR workflows, unlock real-time data for leaders, and ultimately unlock Workday's full potential for your organization.
Important Terminology of Workday API
Understanding key terms is essential for effective integration with Workday. Let’s look upon few of them, that will be frequently used ahead -
- Workday Tenant: Imagine your Workday tenant as your company’s own secure vault within the workday system. It’s a self-contained environment, and it will contain all your company’s data and configuration. Companies typically have separate tenants for development, testing, and production.
- Integration System User (ISU): An ISU is a dedicated user account within Workday specifically designed for integrations with third party systems. ISU’s eliminate the need to share individual user credentials for accessing and manipulating data. Setting up an ISU involves creating the user, assigning security roles, and generating API credentials. For security reasons, each ISU should be restricted to a single integration system.
- OAuth 2.0: OAuth is a widely used authorization framework that allows applications to access resources on behalf of a user without requiring the user to share their credentials. Workday's REST API requires an OAuth 2.0 client setup for authentication. Once setup, the ISU uses the Workday OAuth 2.0 tokens to authenticate and authorize the integration.
Overview of Workday API Documentation
1. API Types: Workday offers REST and SOAP APIs, which serve different purposes. REST APIs are commonly used for web-based integrations, while SOAP APIs are often utilized for complex transactions.
2. Endpoint Structure: You must familiarize yourself with the Workday API structure as each endpoint corresponds to a specific function. A common workday API example would be retrieving employee data or updating payroll information. You can find a comprehensive listing of the Workday API endpoints and directory here.
3. API Documentation: Workday API documentation provides a comprehensive overview of both REST and SOAP APIs.
- Workday REST API: The REST API allows developers to interact with Workday's services using standard HTTP methods. It is well-documented and provides a straightforward way to integrate with Workday.
- Workday REST API Documentation: Workday's REST API documentation provides detailed information on using the API, including endpoints, parameters, and response formats. It is a valuable resource for developers looking to integrate with Workday.
- Workday SOAP API Documentation: Workday's SOAP API documentation provides information on how to use the SOAP API for more complex transactions. SOAP APIs are often used for integrations that require a higher level of security and reliability.
- Workday SOAP API Example: An example of using Workday's SOAP API could be retrieving employee information from Workday's HR system to update a payroll system. This example demonstrates the use of SOAP APIs for complex transactions.
Authentication and Authorization in Workday
Handling authentication and authorization in Workday depends on what Workday API protocol you are choosing to use for building your integration. If you are using Workday SOAP API, you will need the ISU user name and password for authenticating your API requests. On the other hand, if you are building your integration with Workday REST APIs you will need to use Workday's OAuth 2.0 mechanism to authorize your requests. This guide will walk you through the exact steps needed to set up an ISU and OAuth in Workday in detail.
Steps for building a Workday API Integration
To ensure a secure and reliable connection with Workday's APIs, this section outlines the essential prerequisites. These steps will lay the groundwork for a successful integration, enabling seamless data exchange and unlocking the full potential of Workday within your existing technological infrastructure.
- Setup up a Workday Developer Account: If you are new to Workday, sign up for a Workday developer account. This grants access to documentation, sample code, and APIs
- Explore Workday's API Playground: Get familiar with Workday API endpoints and resources. Download the API docs – they'll be your roadmap.
- Setup a Workday Tenant: A workday tenant is basically an instance of the Workday software. It is your orgs private area within Workday. You will need Tenant Credentials (Tenant Name, Username, Password), and appropriate roles and permissions within Workday.
- Setup an Integration System User (ISU): Once the Workday tenant is set up, you will need to enable API access in it. This typically involves creating a dedicated Integration System User (ISU) in Workday, assigning it to a security group, and configuring the necessary domain security policies.
- Register API Client: Register your API client within Workday to get a unique client ID and secret (like a secret handshake) for secure API calls. Store these credentials safely!
- Setup up OAuth 2.0: Workday supports OAuth 2.0. After registering your API client in the Workday system to obtain a Client ID and Client Secret, just use these credentials to request OAuth 2.0 access tokens, which are required by the Integration System User (ISU) for authenticating API calls.
- Pick between REST and SOAP: Workday supports both REST and SOAP protocols. You must pick between the two based on your requirements of integration performance, complexity, security and flexibility. While SOAP offers more security and is better suited for complex integrations, it can be slower in terms of data transfer speeds. On the other hand, REST is flexible and often recommended for lightweight integrations.
- Build your integration use case: Once you have decided which Workday API protocol suits you best, you need to write the actual code using the right APIs for your integration use case.
- Test your integration in a sandbox: After writing the integration code using Workday APIs, it is highly recommended to test the integration in a Workday sandbox. At times, it can be difficult to get access to a Workday sandbox, because Workday only provisions sandbox access to paid customers on certain plans. This is where working with Knit can help. Knit API provides Workday Sandbox access to its customers on the Scale and Enterprise plans for development and testing Workday integrations. Get in touch here.
- Deploy to production: Once tested on the Workday sandbox, your Workday API integration is all set to go live! Keep an eye on your integration – implement logging and monitoring for API calls. Review and update your integration settings as needed.
Now that you have a comprehensive overview of the steps required to build a Workday API Integration and an overview of the Workday API documentation, lets dive deep into each step so you can build your Workday integration confidently!
STEP 1: Setting up a Workday tenant and obtaining Web Services Endpoint
The Web Services Endpoint for the Workday tenant serves as the gateway for integrating external systems with Workday's APIs, enabling data exchange and communication between platforms. To access your specific Workday web services endpoint, follow these steps:
- Locate Public Web Services:
- In Workday, search for "Public Web Services".
- Open the "Public Web Services Report".
- Access the Human Resources WSDL:
- Hover over the "Human Resources" section.
- Click the three dots (ellipses) to open the menu.
- Select "Web Services" and then click "View WSDL".
- Find the Endpoint Host:
- On the page that opens, scroll to the bottom.
- Locate the host URL, which will look something like https://wd5-services1.myworkday.com/ccx.
- Copy the URL before /service.
STEP 2: Setting up an Integration System User (ISU) in Workday
Next, you need to establish an Integration System User (ISU) in Workday, dedicated to managing API requests. This ensures enhanced security and enables better tracking of integration actions. Follow the below steps to set up an ISU in Workday:
- Log into Workday:
- Access your Workday portal and log into your Workday tenant.
- Create an Integration System User:
- In the search field, type "Create Integration System User" and select the corresponding task.
- Fill in User Details:
- On the "Create Integration System User" page, go to the "Account Information" section.
- Enter a username, and then enter and confirm the password.
- Do not select the Require New Password at the Next Sign In check box
- Type 0 (zero) for Session Timeout Minutes to prevent session expiration
- Click "OK" to save.
- Note: You'll want to add this user to the list of System Users to make sure the password doesn't expire.
- Create a Security Group and Assign an Integration System User: Now, add this Integration System User to a Security Group to ensure controlled access to Workday APIs, enhancing security by restricting permissions to authorized entities only:
- Create a Security Group: In the search field, type "Create Security Group" and select the task.
- Click "OK"
- Configure the security group
- On the "Create Security Group" page, select "Integration System Security Group" from the "Type of Tenanted Security Group" drop-down menu.
- In the "Name" field, enter a name for the security group.
- Click "OK".
- Edit the security group
- On the "Edit Integration System Security Group (Unconstrained)" page, enter the same name you used when creating the ISU in the "Name" field.
- Click “OK”.
- Configure Domain Security Policy Permissions: Now, we need to ensure that the Integration System User (ISU) has the necessary access rights to interact with specific domains and perform operations within Workday's ecosystem. Here are the steps to configure Domain Security Policy Permissions for the same:
- Maintain Permissions for the Security Group:
- In the search field, type "Maintain Permissions for Security Group" and select the corresponding task.
- The "Maintain Permissions for Security Group" page will appear.
- Configure the Permissions:
- Select the necessary "Maintain” Operation.
- Ensure the "Source Security Group" name matches your created security group.
- Click “OK”
- Maintain Permissions for the Security Group:
- Add Domain Security Policy Permissions
- Add the required Domain Security Policy Permissions with the "GET" operation
Note: The permissions listed below are necessary for the full HRIS API. These permissions may vary depending on the specific implementation
Parent Domains for HRIS
- Job Requisition Data
- Person Data: Name
- Person Data: Personal Data
- Person Data: Home Contact Information
- Person Data: Work Contact Information
- Worker Data: Compensation
- Worker Data: Workers
- Worker Data: All Positions
- Worker Data: Current Staffing Information
- Worker Data: Public Worker Reports
- Worker Data: Employment Data
- Worker Data: Organization Information
Parent Domains for HRIS
- Candidate Data: Job Application
- Candidate Data: Personal Information
- Candidate Data: Other Information
- Pre-Hire Process Data: Name and Contact Information
- Job Requisition Data
- Person Data: Personal Data
- Person Data: Home Contact Information
- Person Data: Work Contact Information
- Manage: Location
- Worker Data: Public Worker Reports
- Activate Security Policy Changes: Next, we will activate Security Policy Changes to ensure that any modifications made to security settings within the system take effect and are enforced.
- In the search bar, type "Activate Pending Security Policy Changes"
- Review the summary of the changes that need approval
- Approve the pending security policy changes to activate them
STEP 3: Setting up OAuth 2.0 in Workday
Workday offers different authentication methods. Here, we will focus on OAuth 2.0, a secure way for applications to gain access through an ISU (Integrated System User). An ISU acts like a dedicated user account for your integration, eliminating the need to share individual user credentials. Below steps highlight how to obtain OAuth 2.0 tokens in Workday:
- Retrieve Endpoints
- Access "View API Clients"
- Use the Workday search bar to navigate to "View API clients"
- At the top of the page, locate the base REST API endpoint
- Extract Host and Tenant Names
- The Workday REST API Endpoint format is: https://{host name}.workday.com/ccx/api/v1/{tenant name}.
- Retrieve and securely store the hostname and tenant name for future use in connecting to the Workday integration
- Obtain Workday REST Client ID: Now, we will need the Workday REST Client ID, which is necessary for authenticating and authorizing API requests, ensuring secure access to Workday's resources. Here are the steps to get your Workday REST Client ID
- Access Workday Application: Log in to the Workday application
- Register API Client: Navigate to the "Register API Client" section
- Enter Client Details
- In the "Client Name" field, input the desired name for the client
- Choose "Authorization Code Grant" for the "Client Grant Type"
- Set Access Token Type: Select "Bearer" as the access token type.
- Select Scope Values: From the Workday REST API scopes, select the relevant functional areas
- Benefits
- Candidate Engagement
- Core Compensation
- Organizations and Roles
- Performance Enablement
- Pre-Hire Process
- Recruiting
- Staffing
- Time Off and Leave
- Time Tracking
- Worker Profile and Skills
- Generate Client ID and Client Secret: Click "OK" to generate the Client ID and Client Secret.
- Enter Client Details
- Obtain Workday REST Refresh Token: If you want your application to have continuous access to Workday data without needing to reauthenticate frequently, you should use the Workday REST Refresh token. Here are the steps you can follow to obtain your Workday REST Refresh token
- Log in to Workday
- Access API Client Information
- In the search field, type "View API client" and select the corresponding task
- Click on the "API Clients for Integrations" tab.
- Select the relevant API client that you created
- Manage Refresh Tokens
- Choose "Manage Refresh Tokens for Integrations"
- Enter the ISU account you generated in the "Workday Account" field
- Click "OK" and return to the Workday home page
- Generate New Refresh Token
- Select the "Generate New Refresh Token" option on the "Delete or Regenerate Refresh Token" page
- Set "Non-Expiring Refresh Token" to "Yes"
- Click "OK
- Copy Refresh Token
- On the "Successfully Regenerated Refresh Token" page, copy the refresh token provided and store securely. These refresh tokens will be used to generate access tokens for authenticating your ISU when accessing Workday APIs.
STEP 4: SOAP vs. REST: Picking the Right Workday API for the Job
Now as you are ready to build your Workday integration, choosing between SOAP and REST for your Workday integration can feel incredibly challenging. Let us break it down to help you decide:
The Structured Side: SOAP
- Security First: SOAP's rigid rules guarantee iron-clad reliability and top-notch security. Perfect for handling sensitive stuff like payroll.
- Extensible Powerhouse: Need extra security layers? SOAP's got your back with WS-Security.
- Precise Communication: WSDL acts like a detailed contract, ensuring your app and Workday are always on the same page.
Working with SOAP:
- Grab the WSDL: This file is your roadmap to Workday's SOAP services, telling you everything available. You can find the WSDL documentation on the Workday community site.
- Craft Your Requests: Tools like SOAP UI let you send requests with authentication and data, following the WSDL specs.
The Flexible Friend: REST
- Simplicity is King: REST keeps things easy with standard HTTP verbs (GET, POST, PUT, DELETE) you already know and love.
- Stateless Speed: No need to sweat past requests – each one has everything the server needs. Plus, REST is generally faster due to its lightweight design.
- JSON Advantage: Responses are typically in JSON, a human-readable format that your application can easily understand.
Working with REST:
- Talk HTTP: Use familiar HTTP methods to interact with Workday's resources.
- Hit the Endpoints: Access Workday's REST endpoints directly using their URLs. You can find the REST API documentation for your specific Workday version on the Workday community site. Tools like Postman are great for testing requests.
Pick what you need:
- Performance Matters: SOAP's complex structure can lead to slower speeds. For web applications, REST's lightweight design is a clear winner.
- Use Cases in Mind: High-security transactions and complex operations like payroll are a perfect fit for SOAP. For web apps and simple data access, REST is the way to go.
Use Cases:
- SOAP: Best for scenarios requiring high security, transactional reliability, and complex operations (e.g., financial transactions, payroll).
- REST: Ideal for web and mobile applications, simpler integrations, and scenarios needing quick, lightweight data access.
When you need a feature-rich environment that empowers developers for complex tasks, SOAP is the ideal choice (and the one we opted for in this guide)
STEP 5: Building your Workday API integration (With Examples)
Now that you have picked between SOAP and REST, let's proceed to utilize Workday HCM APIs effectively. We'll walk through creating a new employee and fetching a list of all employees – essential building blocks for your integration. Remember, if you are using SOAP, you will authenticate your requests with an ISU user name and password, while if your are using REST, you will authenticate your requests with access tokens generated by using the OAuth refresh tokens we generated in the above steps.
In this guide, we will focus on using SOAP to construct our API requests.
First let's learn about constructing a SOAP Request Body
SOAP requests follow a specific format and use XML to structure the data. Here's an example of a SOAP request body to fetch employees using the Get Workers endpoint:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:bsvc="urn:com.workday/bsvc">
<soapenv:Header>
<wsse:Security>
<wsse:UsernameToken>
<wsse:Username>{ISU USERNAME}</wsse:Username>
<wsse:Password>{ISU PASSWORD}</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
</soapenv:Header>
<soapenv:Body>
<bsvc:Get_Workers_Request xmlns:bsvc="urn:com.workday/bsvc" bsvc:version="v40.1">
</bsvc:Get_Workers_Request>
</soapenv:Body>
</soapenv:Envelope>SOAP requests use XML to structure data. They have a main envelope containing a header and a body. The header includes authentication details, while the body specifies the function being called (e.g., Get Workers) and any parameters it needs.
Now that you know how to construct a SOAP request, let's look at a couple of real life Workday integration use cases:
Use Case 1: Creating a New Employee: Hire Employee API (SOAP Example)
Let's add a new team member. For this we will use the Hire Employee API! It lets you send employee details like name, job title, and salary to Workday. Here's a breakdown:
- What it Does: Adds a new employee to your Workday system.
- What it Needs: Employee details like name, job information.
curl --location 'https://wd2-impl-services1.workday.com/ccx/service/{TENANT}/Staffing/v42.0' \
--header 'Content-Type: application/xml' \
--data-raw '<soapenv:Envelope xmlns:bsvc="urn:com.workday/bsvc" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header>
<wsse:Security>
<wsse:UsernameToken>
<wsse:Username>{ISU_USERNAME}</wsse:Username>
<wsse:Password>{ISU_PASSWORD}</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
<bsvc:Workday_Common_Header>
<bsvc:Include_Reference_Descriptors_In_Response>true</bsvc:Include_Reference_Descriptors_In_Response>
</bsvc:Workday_Common_Header>
</soapenv:Header>
<soapenv:Body>
<bsvc:Hire_Employee_Request bsvc:version="v42.0">
<bsvc:Business_Process_Parameters>
<bsvc:Auto_Complete>true</bsvc:Auto_Complete>
<bsvc:Run_Now>true</bsvc:Run_Now>
</bsvc:Business_Process_Parameters>
<bsvc:Hire_Employee_Data>
<bsvc:Applicant_Data>
<bsvc:Personal_Data>
<bsvc:Name_Data>
<bsvc:Legal_Name_Data>
<bsvc:Name_Detail_Data>
<bsvc:Country_Reference>
<bsvc:ID bsvc:type="ISO_3166-1_Alpha-3_Code">USA</bsvc:ID>
</bsvc:Country_Reference>
<bsvc:First_Name>Employee</bsvc:First_Name>
<bsvc:Last_Name>New</bsvc:Last_Name>
</bsvc:Name_Detail_Data>
</bsvc:Legal_Name_Data>
</bsvc:Name_Data>
<bsvc:Contact_Data>
<bsvc:Email_Address_Data bsvc:Delete="false" bsvc:Do_Not_Replace_All="true">
<bsvc:Email_Address>employee@work.com</bsvc:Email_Address>
<bsvc:Usage_Data bsvc:Public="true">
<bsvc:Type_Data bsvc:Primary="true">
<bsvc:Type_Reference>
<bsvc:ID bsvc:type="Communication_Usage_Type_ID">WORK</bsvc:ID>
</bsvc:Type_Reference>
</bsvc:Type_Data>
</bsvc:Usage_Data>
</bsvc:Email_Address_Data>
</bsvc:Contact_Data>
</bsvc:Personal_Data>
</bsvc:Applicant_Data>
<bsvc:Position_Reference>
<bsvc:ID bsvc:type="Position_ID">P-SDE</bsvc:ID>
</bsvc:Position_Reference>
<bsvc:Hire_Date>2024-04-27Z</bsvc:Hire_Date>
</bsvc:Hire_Employee_Data>
</bsvc:Hire_Employee_Request>
</soapenv:Body>
</soapenv:Envelope>'Elaboration:
- We use `curl` to send a POST request (because we're creating something new).
- The URL points to the specific Workday endpoint for hiring employees. We include our tenant name in the URL to point the API to our corresponding tenant.
- We include the ISU Username and Password in the <wsse:Security> header in the SOAP envelope to authenticate our API call
- The `Content-Type` header specifies we're sending xml data.
- The actual employee data goes in the request body, including details like first name, position, work email.
Response:
<bsvc:Hire_Employee_Event_Response
xmlns:bsvc="urn:com.workday/bsvc" bsvc:version="string">
<bsvc:Employee_Reference bsvc:Descriptor="string">
<bsvc:ID bsvc:type="ID">EMP123</bsvc:ID>
</bsvc:Employee_Reference>
</bsvc:Hire_Employee_Event_Response>If everything goes well, you'll get a success message and the ID of the newly created employee!
Use Case 2: Fetching All Employees: Get Workers API (SOAP Example)
Now, if you want to grab a list of all your existing employees. The Get Workers API is your friend!
- What it Does: Retrieves a list of all employees in your Workday system.
- What it Needs: Your ISU username and password
- Where it's Used: The Workday Get Workers API is part of the Workday Developer API suite, which allows developers to interact with Workday's Human Capital Management (HCM) system programmatically. These APIs are commonly used for integrating Workday data and functionality into other applications and systems.
Below is workday API get workers example:
curl --location 'https://wd2-impl-services1.workday.com/ccx/service/{TENANT}/Human_Resources/v40.1' \
--header 'Content-Type: application/xml' \
--data '<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:bsvc="urn:com.workday/bsvc">
<soapenv:Header>
<wsse:Security>
<wsse:UsernameToken>
<wsse:Username>{ISU_USERNAME}</wsse:Username>
<wsse:Password>{ISU_USERNAME}</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
</soapenv:Header>
<soapenv:Body>
<bsvc:Get_Workers_Request xmlns:bsvc="urn:com.workday/bsvc" bsvc:version="v40.1">
<bsvc:Response_Filter>
<bsvc:Count>10</bsvc:Count>
<bsvc:Page>1</bsvc:Page>
</bsvc:Response_Filter>
<bsvc:Response_Group>
<bsvc:Include_Reference>true</bsvc:Include_Reference>
<bsvc:Include_Personal_Information>true</bsvc:Include_Personal_Information>
</bsvc:Response_Group>
</bsvc:Get_Workers_Request>
</soapenv:Body>
</soapenv:Envelope>'This is a simple GET request to the Get Workers endpoint.
Elaboration:
- The URL points to the specific Workday endpoint for retrieving employees.We include our tenant name in the URL to point the API to our corresponding tenant.
- We include the ISU Username and Password in the <wsse:Security> header in the SOAP envelope to authenticate our API call
- The `Content-Type` header specifies we're sending xml data.
- We include the Count and Page Number parameters in the request to paginate the results. This technique can be used to optimize the results so that we process a batch of data at once.
Response:
<?xml version='1.0' encoding='UTF-8'?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
<env:Body>
<wd:Get_Workers_Response xmlns:wd="urn:com.workday/bsvc" wd:version="v40.1">
<wd:Response_Filter>
<wd:Page>1</wd:Page>
<wd:Count>1</wd:Count>
</wd:Response_Filter>
<wd:Response_Data>
<wd:Worker>
<wd:Worker_Data>
<wd:Worker_ID>21001</wd:Worker_ID>
<wd:User_ID>lmcneil</wd:User_ID>
<wd:Personal_Data>
<wd:Name_Data>
<wd:Legal_Name_Data>
<wd:Name_Detail_Data wd:Formatted_Name="Logan McNeil" wd:Reporting_Name="McNeil, Logan">
<wd:Country_Reference>
<wd:ID wd:type="WID">bc33aa3152ec42d4995f4791a106ed09</wd:ID>
<wd:ID wd:type="ISO_3166-1_Alpha-2_Code">US</wd:ID>
<wd:ID wd:type="ISO_3166-1_Alpha-3_Code">USA</wd:ID>
<wd:ID wd:type="ISO_3166-1_Numeric-3_Code">840</wd:ID>
</wd:Country_Reference>
<wd:First_Name>Logan</wd:First_Name>
<wd:Last_Name>McNeil</wd:Last_Name>
</wd:Name_Detail_Data>
</wd:Legal_Name_Data>
</wd:Name_Data>
<wd:Contact_Data>
<wd:Address_Data wd:Effective_Date="2008-03-25" wd:Address_Format_Type="Basic" wd:Formatted_Address="42 Laurel Street&#xa;San Francisco, CA 94118&#xa;United States of America" wd:Defaulted_Business_Site_Address="0">
</wd:Address_Data>
<wd:Phone_Data wd:Area_Code="415" wd:Phone_Number_Without_Area_Code="441-7842" wd:E164_Formatted_Phone="+14154417842" wd:Workday_Traditional_Formatted_Phone="+1 (415) 441-7842" wd:National_Formatted_Phone="(415) 441-7842" wd:International_Formatted_Phone="+1 415-441-7842" wd:Tenant_Formatted_Phone="+1 (415) 441-7842">
</wd:Phone_Data>
</wd:Worker_Data>
</wd:Worker>
</wd:Response_Data>
</wd:Get_Workers_Response>
</env:Body>
</env:Envelope>This JSON array gives you details of all your employees including details like the name, email, phone number and more.
Use a tool like Postman or curl to POST this XML to your Workday endpoint.
REST Example
If using REST, you’ll pass JSON payloads, include an OAuth 2.0 Bearer token, etc. The overall structure is simpler but the specifics vary.
STEP 6: Test your integration in a Workday Sandbox
To avoid risking any glitches in production, isn’t it amazing to first test our code on test data? A sandbox is your safe zone to test your code before takeoff. As we already had a summarized view of the importance of using sandbox in our preliminary steps, let’s move to detailed steps to execute these steps.
- Request Your Sandbox: Talk to your Workday admin and request a sandbox environment (specify the type you need). If you are a Knit customer on the Scale or Enterprise plan, you will be provided a Workday sandbox by Knit to build and test your integration.
- Prep Your Sandbox: Log in and configure your sandbox to mimic your production environment (company data, user roles).
- Create an ISU: In Security, create a special user (ISU) for your integration testing. Assign it the necessary permissions.
- Secure Your Calls: Register your application in the sandbox to get unique credentials (client ID & secret) for secure API calls.
- Test: Use tools like Postman to bombard your integration with test requests within the sandbox. Iron out any wrinkles before going live.
- Monitor & Debug: Keep an eye on your sandbox and use Workday logs to identify and fix any issues.
STEP 7: Move your integration to Workday production
That’s it! You are now ready to move your integration to production. Change the urls and ISU to the production values and you are good to go. Be sure to implement logging and monitoring mechanisms to make sure you can effectively catch and debug issues if the need arises. Tools like Knit provide integration observability dashboards which can be used to monitor live integrations.
A note on PECI (Payroll Effective Change Interface)
PECI (Payroll Effective Change Interface) lets you transmit employee data changes (like new hires, raises, or terminations) directly to your payroll provider, slashing manual work and errors. Below you will find a brief comparison of PECI and Web Services and also the steps required to setup PECI in Workday
Feature: PECI
- Data Flow: Outbound
- Use Cases: READ
- Country Scope: Some limit
- Setup: Usually Advanced
Feature: Web Services
- Data Flow: Inbound and Outbound
- Use Cases: CREATE, UPDATE, DELETE
- Country Scope: Global
- Setup: Usually Programmatic, Flexible
PECI set up steps :-
- Enable PECI: Talk to your Workday admin and get PECI activated for your tenant.
- Set Up Your Payroll Provider: Configure your external payroll system within Workday, including details and data transfer protocols.
- Define Your Data: Identify the specific data your payroll provider needs (think employee details, compensation, etc.).
- Create an ISU: Just like other integrations, create a special user (ISU) with permissions to access and move payroll data.
- Transform Your Data: Set up Workday to transform your data into the format your payroll provider expects. Think of it as translating languages!
- Schedule Transfers: Automate the process! Set up a schedule to regularly send payroll changes to your provider (e.g., daily or after each payroll run).
- Test It Out: Before going live, use the Workday sandbox to thoroughly test the PECI integration. Make sure all changes get sent correctly.
- Monitor & Maintain: Keep an eye on things! Regularly monitor the integration and use Workday's reports to track data transfers and fix any errors.
Things to keep in mind for Workday Integration security
- Craft Security Groups: In Workday Security, create a security group specifically tailored for your integration. Think of it as a club with specific access rules.
- Set Up Security Policies: Define security policies to control how data can be accessed and modified. Assign these policies to your security group for an extra layer of protection.
- Assign Permissions Wisely: Adopt a least privilege policy. Add the necessary permissions to your security group. Make sure your ISU has access to everything it needs, but nothing it doesn't.
- Activate & Audit: Activate your newly defined security policies and regularly review their effectiveness. Conduct security audits to ensure everything is running smoothly.
- Store Secrets Safely: Keep sensitive info like client secrets in environment variables, not in your code.
- Encryption is Key: Encrypting credentials for added protection is a must for integration.
- Rotate Regularly: Keep changing credentials periodically to reduce risk.
Troubleshooting common issues with Workday Integration
Getting stuck with errors can be frustrating and time-consuming. Although many times we face errors that someone else has already faced, and to avoid giving in hours to handle such errors, we have put some common errors below and solutions to how you can handle them.
- Authentication Woes:
- Error Message: "Invalid client ID or secret."
- Possible Solution: Double-check your OAuth setup. Are your client ID, secret, and redirect URLs all correct? Ensure your tokens aren't expired!
- Permission Denied:
- Error Message: "Access denied!"
- Possible Solution: Verify your ISU has the right permissions. Check security group settings and policies. It might not have the key to the data vault!
- Data Mismatch Blues:
- Error Message: "Incorrect or missing data fields."
- Possible Solution: Ensure your data mappings are on point and match Workday's data model. Validate your input data before making those API calls. Garbage in, garbage out!
- Rate Limiting Roadblock:
- Error Message: "Whoa there! Too many requests!"
- Possible Solution: Implement throttling and retry logic in your integration. Respect Workday's API rate limits – don't be a data hog!
Pro Tips for Smooth Sailing
- Log It All: Use detailed logs for API calls and responses. Logs are like breadcrumbs – they help you find your way back when you get lost.
- Sandbox First: Always test in Workday's sandbox environment. Catch issues early on before your code goes live and wreaks havoc on real data.
- Monitor Your Performance: Keep an eye on your integration's performance. Use monitoring tools to track API response times and error rates. Don't let errors become silent assassins!
- The Power of Community: Connect with the Workday developer community. Forums and user groups can be lifesavers – share your war stories and learn from others' battles.
How can Knit help you with Workday API Integration?
We know you're here to conquer Workday integrations, and at Knit (rated #1 for ease of use as of 2025!), we're here to help! Knit offers a unified API platform which lets you connect your application to multiple HRIS, CRM, Accounting, Payroll, ATS, ERP, and more tools in one go.
Advantages of Knit for Workday Integrations
- Unified APIs: Interact with multiple HRIS systems (including Workday) via a single REST interface.
- Developer-Friendly: Clear documentation, fewer complexities.
- Scalability: Designed to handle high-volume data flows.
- Support & Reliability: Helpful support team, robust error handling.
Getting Started with Knit
- Sign Up for a Knit account.
- Connect Workday: Provide your Workday tenant details.
- Leverage Unified API: Perform typical Workday operations without dealing directly with SOAP.
REST Unified API Approach with Knit
- Freed from SOAP complexities.
- Straightforward JSON requests.
- Centralized platform to manage data from multiple HRIS solutions.
Appendix
A. Key Terms
- API: Lets applications talk to Workday (RESTful or SOAP).
- Authentication: Verifies you're who you say you are (login).
- Authorization: Grants access to specific Workday data (permissions).
- Client ID & Secret: Uniquely identify your application (secure handshake).
- Data Model: Structure of Workday data (like fields in a form).
- Endpoint: Specific URL to access Workday functions (like a door to a room).
- ISU: Special user for integrations (low access, high security).
- OAuth 2.0: Secure way to get temporary access tokens (like a one-time pass).
- REST API: Flexible API using regular commands (GET, POST, PUT, DELETE).
- Sandbox: Test environment with dummy data (safe zone for experimentation).
- SOAP API: Structured API using XML (more complex, more secure).
- Token: Temporary permission to access Workday (like a short-term pass).
- Workday Tenant: Your company's secure space within Workday (separate for dev, test, production).
B. Sample Code
- Adapted from Workday API documentation. Remember to replace placeholders like "your_workday_tenant", "isu_username", “isu_password” with your actual details. For comprehensive API reference and code samples, visit the Workday Developer Center
.webp)
.png)
.webp)
