Connecting to Workday

Last updated: August 5, 2026

This guide shows you how to connect Workday as an HRIS in YeshID, and the specific steps within Workday. For background on how people sources work, see HRIS with YeshID.

YeshID reads your workers using the Workday Query Language (WQL) REST API. Nothing is written back to Workday — Workday stays the system of record, and YeshID uses it to create and update people, and to trigger onboarding and offboarding.

Before you start, you’ll need a Workday administrator who can create an Integration System User and register an API client. Set aside about 20 minutes.

1. Create an Integration System User (ISU)

YeshID connects as a dedicated integration account rather than as a person, so the connection doesn’t break when an employee leaves.

  1. In Workday, search for and run the Create Integration System User task.

  2. Enter a User Name (for example, YeshID_ISU) and a password.

  3. Check Do Not Allow UI Sessions.

  4. Leave Session Timeout Minutes at 0 so the session doesn’t expire mid-import.

  5. Click OK.

Note: Store the ISU password in your password manager. You won’t paste it into YeshID, but you’ll need it if you ever have to regenerate the refresh token in step 3.

2. Give the ISU access to your worker data

A new ISU can’t see anything until you put it in a security group and grant that group access.

  1. Search for and run the Create Security Group task.

  2. For Type of Tenanted Security Group, choose Integration System Security Group (Unconstrained).

  3. Name the group (for example, YeshID Integration) and click OK.

  4. Add your ISU to the group’s Integration System Users field, then click OK.

  5. Search for the Workday Query Language domain, and from its related actions choose Domain → Edit Security Policy Permissions. Add your new security group with Get access.

  6. Repeat step 5 for Worker Data: Public Worker Reports, and for any other worker domains covering fields you plan to import.

  7. Search for and run Activate Pending Security Policy Changes, enter a comment, and confirm.

Note: Security policy changes don’t take effect until you run Activate Pending Security Policy Changes. If your import returns no workers, this step is the first thing to check.

3. Register the API client and generate a refresh token

  1. Search for and run the Register API Client for Integrations task.

  2. Enter a Client Name (for example, YeshID).

  3. Check Non-Expiring Refresh Tokens.

  4. For Scope (Functional Areas), select System. This is what allows WQL access.

  5. Click OK. Workday shows the Client ID and Client Secret on the confirmation screen — copy both now.

  6. Search for and run View API Clients, then open the client you just created.

  7. From the client’s related actions, choose API Client → Manage Refresh Tokens for Integrations.

  8. Select your ISU as the Workday Account, check Generate New Refresh Token, and click OK. Copy the refresh token.

Note: The Client Secret and the Refresh Token are each shown only once. If you navigate away before copying them, regenerate them rather than guessing — YeshID will report a 401 on the first import otherwise.

You should now have three values: Client ID, Client Secret, and Refresh Token.

4. Build your token URL

YeshID works out your Workday API address and tenant from a single field, so you need your Workday host and tenant name.

Both appear in any Workday URL while you’re signed in. For example, in https://wd2-impl-services1.workday.com/acme_preview/d/home.htmld, the host is wd2-impl-services1.workday.com and the tenant is acme_preview.

Assemble them into a token URL in this form:

https://<host>/ccx/oauth2/<tenant>/token

For the example above, that gives:

https://wd2-impl-services1.workday.com/ccx/oauth2/acme_preview/token

Note: Use your implementation host for a sandbox or preview tenant, and your production host for production. Getting the host wrong is the most common cause of a failed connection.

5. Connect Workday in YeshID

  1. In YeshID, go to Applications, find Workday, and click Connect.

  2. In the Authentication section, set Grant Type to Refresh Token.

  3. Fill in the fields:

    • Token URL — the URL you assembled in step 4.

    • Client ID — from step 3.

    • Client Secret — from step 3.

    • Refresh Token — from step 3.

  4. Click Save.

Out of the box, YeshID imports each worker’s Workday ID, Employee ID, first and last name, display name, work email, home email, and home phone.

6. Import more than names and email (optional)

Workday field names differ from tenant to tenant, so anything beyond core identity is opt-in. Add the fields you want in Additional WQL fields as comma-separated field AS alias pairs.

YeshID maps these aliases:

Alias

Becomes

title

Job title

department

Department

location

Location

company

Company

employmentStatus

Employment status

employmentType

Employment type

hireDate

Start date

terminationDate

End date

managerEmployeeId

Manager

For example:

businessTitle AS title, hireDate AS hireDate, terminationDate AS terminationDate

The alias on the right of each AS must match the table above — that’s what YeshID maps. The field name on the left is whatever your tenant calls it.

To find the exact field names in your tenant, run the Workday Query Language report in Workday and browse the allWorkers data source, or call GET /ccx/api/wql/v1/{tenant}/dataSources followed by GET /ccx/api/wql/v1/{tenant}/dataSources/{id}/fields.

Note: To link managers, you must supply the manager’s Employee ID as managerEmployeeId. Workday’s plain manager field returns an internal Workday ID, which doesn’t match the employee IDs YeshID uses, so YeshID shows it as a name only and won’t build a reporting line from it.

7. Test the import and review field mappings

  1. Click Test Import. YeshID runs your query and previews up to 500 workers.

  2. Review the field mappings and confirm each YeshID field is drawing from the Workday field you expect.

  3. Save the integration to start syncing.

Notes

  • The default query reads the allWorkers data source, which returns your currently employed workers. If you want YeshID to see terminations, put a full query in the WQL query field against a data source that includes terminated workers, keeping the same aliases.

  • WQL query replaces the built-in query entirely and ignores Additional WQL fields. Use it when you need a different data source or a WHERE clause; use Additional WQL fields for everything else.

  • Workers without an Employee ID (some contingent workers) are identified by their Workday ID instead, so they still import.

  • Syncing is on a polling schedule, not real-time. A change in Workday appears in YeshID on the next sync.

  • Workday returns only the fields your ISU is permitted to read, so missing data usually points at a security domain rather than a broken connection.

Troubleshooting

  • 401 on the first import. The client ID, client secret, or refresh token is wrong, or the refresh token was generated for a different ISU. Regenerate the refresh token in Manage Refresh Tokens for Integrations and re-enter all three values.

  • “OAuth token URL still contains placeholders.” The Token URL field still has <host> or <tenant> in it. Replace both with your real host and tenant, as in step 4.

  • 403, or an error mentioning the Workday Query Language domain. The API client is missing the System scope, or the ISU’s security group doesn’t have Get access to the Workday Query Language domain. Check both, then run Activate Pending Security Policy Changes.

  • “Invalid WQL” or “unknown field”. A field name in Additional WQL fields doesn’t exist in your tenant. The error names the field. Look it up in the allWorkers data source and correct it — no YeshID change is needed.

  • Import succeeds but returns no workers. The ISU can authenticate but can’t see any worker data. Confirm the security group has Get on the worker domains and that you activated the pending security policy changes.

  • Job titles or dates are empty. Those fields are opt-in. Add them in Additional WQL fields as described in step 6.

  • Terminated employees have no end date. allWorkers only returns currently employed workers. Use the WQL query override against a data source that includes terminated workers.

Related articles