Skip to main content

​
About Workday

Workday is a human capital management (HCM) platform. The Serval Workday integration is a per-tenant connection to your Workday environment: it gives Serval workflows live access to Workday’s REST sub-APIs (30+ modules including Staffing, Person, Absence Management, Payroll, and Recruiting), Workday Query Language (WQL), and ten Workday Web Services (SOAP) services. It also ships two installable workflow bundles - Worker Lookup, and Time Off & Benefits - so common HR lookups work out of the box. Every connection is specific to your tenant: the REST API Base URL, Token Endpoint, and optional user-auth endpoints all belong to your Workday environment. Authentication: Service account via OAuth 2.0 refresh-token grant, tied to an Integration System User (ISU) and an API Client for Integrations registered in your Workday tenant. An optional, feature-flagged per-user (3-legged) OAuth path lets certain actions run as the end user. Data sync: On-demand only. Nothing is mirrored into Serval on a schedule - workflow actions and health checks call Workday live, and a fresh access token is obtained from your tenant’s token endpoint for every call.

​
What the Workday integration enables

CapabilityDescription
REST requests across 30+ Workday modulesTyped request actions for Workday’s REST sub-APIs, including Staffing, Person, Absence Management, Compensation, Payroll, Global Payroll, Recruiting, Talent Management, Time Tracking, Expense, Procurement, Projects, Custom Reports (RaaS), Workday Help, Prism Analytics, Student modules, Workday Connect messaging, and more.
WQL (Workday Query Language) queriesRun WQL queries against standard data sources such as allWorkers, allActiveWorkers, and allActiveAndTerminatedWorkers - used by worker lookups and the WQL health check.
SOAP (Workday Web Services) requestsTyped SOAP actions for ten services: Staffing, Human Resources, Absence Management, Benefits Administration, Compensation, Integrations, Payroll, Performance Management, Recruiting, and Time Tracking. Common operations include Get_Workers, Hire_Employee, Terminate_Employee, Get_Job_Postings, and Get_Organization_Goals.
Worker lookup and change-request helpersHigher-level actions such as find worker by email or employee ID, find eligible absence types, get organization goals, and update a worker’s primary home phone number or home address (including adding a home phone number where none exists).
Worker Lookup bundleSix prebuilt workflows: Search for Workday Worker by Name, Get Workday Worker ID by Email, Get Workday Worker, List Workday Workers, Get Workday Worker Absence, and Get Workday Holiday Events. All default to no-approval.
Time Off & Benefits bundleFour prebuilt workflows: Get User PTO Balance from Workday, Get Workday Eligible Absence Types, Lookup Workday Team Member Time Off Requests, and Get Workday Worker Benefit Elections. All default to no-approval.
Write workflowsTwo additional prebuilt write workflows: Update Workday Worker Primary Home Phone Number and Update Workday Worker Primary Home Address. Both default to installer-approval.
Per-user (as-user) requestsWhen the optional per-user OAuth app is configured, a user-scoped variant of the REST request action calls Workday as the acting user with their own credential (currently the Request sub-API). The user must have connected their personal Workday account first.
Anything defined in the Workday API can be accessed through Serval.

​
Get your credentials

Setting up the connection requires a Workday administrator. You will create an Integration System User (ISU), grant it the security it needs, register an API Client for Integrations, and generate a refresh token. Workday’s official API reference is the Workday REST Services Directory.
1

Create the Integration System User

In Workday, search for Create Integration System User and create the ISU (for example, ServalIntegration). The password cannot contain the characters &, <, or >.
2

Exempt the ISU from password expiration

Search for Maintain Password Rules and add the ISU to System Users exempt from password expiration.
3

Create a security group

Search for Create Security Group, choose the type Integration System Security Group (Unconstrained) (for example, Serval Integration Group), and add the ISU under Integration System Users.
4

Grant domain security policies

Search for Maintain Permissions for Security Group (Operation: Maintain; Source Security Group: your group) and add the Domain Security Policies your use case needs. The minimum for worker reads is Worker Data: Public Worker Reports with Get Only access.
Only grant the permissions you actually need. Every Serval action runs with the ISU’s permissions.
5

Activate the security changes

Search for Activate Pending Security Policy Changes and confirm.
6

Allow the group to authenticate

Search for Manage Authentication Policies, add your security group to an authentication rule with Allowed Authentication Types User Name Password or Any, then run Activate All Pending Authentication Policy Changes.
7

Register the API client

Search for Register API Client for Integrations. Set a name (for example, Serval Workday API Client), make it a confidential client, enable the Refresh Token grant, allow Non-Expiring Refresh Tokens, and save. Copy the Client ID and Client Secret.
The Client Secret may only be shown once. Copy it immediately and store it securely.
8

Generate the refresh token

Search for Manage Refresh Tokens for Integrations, select your API client, add the ISU as the Authorized User, choose an expiration, generate, and copy the Refresh Token - it is not viewable again.
Choose Never for expiration if your policy allows. Every Serval-to-Workday call depends on this refresh token; if it expires, all Workday actions stop working until you update the connection.
9

Copy the endpoints

Search for View API Clients, open your API client, and copy two values: the REST API endpoint (ends with /ccx/api/<tenant> - this maps to Serval’s REST API Base URL field) and the Token endpoint (ends with /ccx/oauth2/token - this maps to Serval’s Token Endpoint field).
10

Copy the SOAP WSDL URL

Search for Public Web Services, locate the SOAP service you use (for example, Human Resources (Public)), choose Web Services → View WSDL, and copy the service URL for Serval’s WSDL URL field.
11

Find your tenant name

Your tenant name appears in your Workday URL (for example, https://wd2-impl.workday.com/<tenant>/d/home.html), or ask your administrator.

​
Connect in Serval

1

Open the Workday connect form

In Serval, add a new Workday connection. The form collects your tenant details, OAuth credentials, and SOAP fields.
2

Enter your Tenant Name

Tenant Name (required) - for example, mycompany. This becomes the connection’s name in Serval. Saving without it fails with: Invalid Workday configuration: tenant name is required
3

Enter the OAuth credentials

Client ID (required), Client Secret (required), and Refresh Token (required) - from the API client and refresh token you created in Workday. All three are stored encrypted. Missing values fail with, respectively: Invalid Workday configuration: client ID is required, Invalid Workday configuration: client secret is required, and Invalid Workday configuration: refresh token is required
4

Enter the endpoints

REST API Base URL (required) - for example, https://wd2-impl-services1.workday.com/ccx/api/mycompany. It must start with https:// and contain /ccx/api/ - Serval derives every REST and SOAP endpoint from this one URL. Errors on create: Invalid Workday configuration: REST API base URL is required or Invalid Workday configuration: REST API base URL must start with https://. When editing: REST API base URL must start with https:// or Invalid REST API base URL formatToken Endpoint (required) - for example, https://wd2-impl-services1.workday.com/ccx/oauth2/token. Must start with https://. Errors on create: Invalid Workday configuration: token endpoint is required or Invalid Workday configuration: token endpoint must start with https://. When editing: Token endpoint must start with https:// or Invalid token endpoint format
5

Enter the SOAP fields

WSDL URL (required by the form) - for example, https://wd2-impl-services1.workday.com/ccx/service/amn1/Human_Resources/v28.2. ISU Username (required by the form) - for example, ServalIntegration. ISU Password (required by the form) - stored encrypted.
These three fields are required by the form but are not validated when the connection is saved, and they are not used to make requests - SOAP endpoints and authentication are derived from the REST API Base URL and OAuth credentials (see Gotchas and troubleshooting below).
6

(Optional) Configure per-user OAuth

If the per-user OAuth feature is enabled for your team, three optional fields appear: User-Auth OAuth Client ID, User-Auth OAuth Client Secret, and User-Auth Authorize Endpoint (placeholder https://wd2-impl-services1.workday.com/<tenant>/authorize). Leave them blank if this connection only uses the service account. These endpoints are validated when the user OAuth flow runs (not at save): both the authorize and token endpoints must be HTTPS URLs on *.workday.com or *.myworkday.com.
7

Save the connection

Save, then run the health checks below to verify everything works.
Edit behavior differs by field type. The six secret fields (Client ID, Client Secret, Refresh Token, ISU Password, User-Auth OAuth Client ID, User-Auth OAuth Client Secret) display obfuscated (•••• plus the last 4 characters) and keep their stored value if you leave them blank or unchanged. The six non-secret fields (Tenant Name, REST API Base URL, Token Endpoint, WSDL URL, ISU Username, User-Auth Authorize Endpoint) are saved exactly as submitted - clearing one of them clears the stored value. The edit form prefills current values; don’t delete them unless you mean to. The connection’s display name and API domain update only when you submit a new, non-empty Tenant Name or REST API Base URL.

​
Verifying the connection

Four health checks verify the connection on demand: List Workday Workers - lists up to 10 workers through the Staffing API using the service-account credential, verifying REST connectivity and worker-read permissions.
  • Success: Successfully listed [number] workers
  • Failure: Unable to list workers. - on permission errors (401/403) it adds The API credentials may be invalid or the integration user may not have the required permissions.; on Workday server errors (500/502/503) it adds Workday returned a server error. This is likely a temporary issue - please try again later.
List Supervisory Organizations - lists up to 5 supervisory organizations through the Staffing API, verifying org-structure read access.
  • Success: Successfully listed [number] supervisory organizations
  • Failure: Unable to list supervisory organizations. - with the same conditional permission and server-error suffixes as above.
Execute WQL Query - runs a one-row WQL query (SELECT worker, fullName FROM allWorkers LIMIT 1) to verify Workday Query Language access.
  • Success: Successfully executed WQL query (returned [number] result(s))
  • Failure: Unable to execute WQL query. - with the same conditional permission and server-error suffixes as above.
SOAP API - Get Workers - calls the Staffing SOAP service’s Get_Workers operation requesting a single worker, verifying SOAP connectivity.
  • Success: Successfully connected to Workday SOAP API (retrieved [number] worker(s))
  • Failure: Unable to connect to Workday SOAP API. - with SOAP-specific suffixes: on authentication errors, The ISU username or password may be invalid. Please check your integration configuration.; on forbidden errors, The ISU does not have permission to access the Staffing SOAP service. Please check Workday security group assignments.; on WSDL errors, Could not connect to the WSDL URL. Please verify the WSDL URL is correct and accessible.; on connection errors, Could not connect to Workday. Please verify the WSDL URL and network connectivity.; otherwise the generic permission and server-error suffixes.
If the two REST checks and the SOAP check pass but Execute WQL Query fails, your tenant likely has WQL disabled - the connection itself is fine. Worker lookups that depend on WQL (finding a worker by email or employee ID) will keep failing until WQL is enabled in your tenant, or those workflows are switched to the equivalent SOAP-based lookup (the Get_Workers operation).

​
Gotchas and troubleshooting

Serval fetches a fresh access token from your Token Endpoint on every single call - there is no token caching for the service account. If the refresh token expires, is revoked, or the API client secret is rotated in Workday, every Workday call fails immediately until you update the connection with new credentials. Use non-expiring refresh tokens where your policy allows.
Some Workday tenants have WQL disabled. A failing Execute WQL Query check does not necessarily mean the connection is broken - if the REST and SOAP checks pass, the connection works. However, worker lookups that depend on WQL (such as finding a worker by email or employee ID) will not succeed until WQL is enabled, or those workflows are adapted to use the SOAP Get_Workers operation instead - the switch is not automatic.
The backend only validates Tenant Name, REST API Base URL, Token Endpoint, Client ID, Client Secret, and Refresh Token at save time. WSDL URL, ISU Username, and ISU Password are required by the form but are stored without validation and never used when requests are made - a typo in them neither blocks saving nor breaks the SOAP check. When the SOAP check fails, look at the values that actually drive SOAP calls: the REST API Base URL (every SOAP endpoint is derived from it - see the next accordion), the OAuth credentials (Client ID, Client Secret, Refresh Token), and the ISU’s security group permissions in Workday (the health check needs access to the Staffing SOAP service). Although the SOAP failure guidance mentions the ISU username and password, live SOAP requests authenticate with the same OAuth bearer token as REST requests - the ISU matters because it underpins the refresh token and the permissions model, not through the stored ISU Password field.
Every REST and SOAP endpoint Serval calls is derived from the REST API Base URL at request time - the stored WSDL URL field is not used to build request URLs. The base URL must contain /ccx/api/; if it doesn’t, SOAP endpoint derivation fails with an Unexpected API domain format error. If anything looks wrong across the board, verify this field first against the View API Clients task in Workday.
Only the secret fields keep their stored value when left blank during an edit. The non-secret fields - Tenant Name, REST API Base URL, Token Endpoint, WSDL URL, ISU Username, and User-Auth Authorize Endpoint - are written exactly as submitted, so submitting one of them empty blanks it out (clearing the Token Endpoint, for example, breaks every call). The connection’s display name and API domain are only updated when you submit a new, non-empty value. The edit form prefills current values; leave them in place unless you intend to change them.
The three User-Auth fields only appear once the per-user OAuth feature is enabled for your team. The user-auth app is a separate Workday OAuth API client (Authorization Code grant) stored on the service-account connection - leaving the fields blank changes nothing about the service account. Both the authorize and token endpoints are validated when the OAuth flow runs (not when you save): they must be HTTPS on *.workday.com or *.myworkday.com, since the client secret travels to these URLs. If someone tries to connect their personal Workday account before the app is configured, the attempt fails with: workday connection has no user-auth OAuth app configured (set the User-Auth OAuth Client ID/Secret). Other endpoint errors include: workday connection is missing the user-auth authorize/token endpoint, workday user-auth authorize endpoint "<url>" must use https, and workday user-auth authorize endpoint "<url>" is not an allowed workday host. An as-user workflow action fails at run time if the acting user has not connected their personal Workday account. User tokens are refreshed only near expiry and always against the exact connection that minted them.
Earlier versions of this documentation described SOAP support as “coming soon” and used different field names. SOAP is fully supported today, with ten Workday Web Services available. The current form labels are REST API Base URL (previously described as “REST API Endpoint”) and WSDL URL (previously “Web Services Endpoint URL”). The WSDL URL should now be a full versioned service URL (for example, https://wd2-impl-services1.workday.com/ccx/service/amn1/Human_Resources/v28.2), not a bare /ccx address.
Need help? Contact support@serval.com for assistance with your Workday integration.