What you'll accomplish: By the end of this guide, your Workday tenant will allow Yardstik to poll for background check orders when a recruiter advances a candidate (or initiates a worker re-screen), and Yardstik will post results back into Workday's Background Check History — all over OAuth 2.0. Yardstik calls the Workday Web Services (WWS) SOAP API directly. You'll work almost entirely in your Workday tenant, then enter six values into the Yardstik Workday integration card.
📌 How the Credentials Flow
All calls are Yardstik → Workday (outbound). You create these credentials in Workday and enter them into the Yardstik card — nothing is configured back on the Workday side.
Value | Created In | Entered Into | Used For |
Client ID + Client Secret | Workday — OAuth API Client (Stage 1.2) | Yardstik Workday card (Stage 2) | Client-auth to the token endpoint to mint an access token |
Refresh Token | Workday — Manage Refresh Tokens for Integrations (Stage 1.3) | Yardstik card (Stage 2) | Long-lived credential Yardstik uses to mint access tokens |
OAuth Token Endpoint URL | Workday (derived, Stage 1.4) | Yardstik card (Stage 2) | Where Yardstik POSTs grant_type=refresh_token to get a Bearer token |
Workday Endpoint Base URL | Workday (derived, Stage 1.4) | Yardstik card (Stage 2) | Target host/tenant for Yardstik's WWS SOAP calls |
Workday account (ISU's User Name) | Workday — the ISU (Stage 1.1) | Yardstik card (Stage 2) | Sent as the wd-external-originator-id header on Yardstik's transactional WWS calls |
✅ Before You Start
Your organization has a live Workday tenant
You'll need an admin holding Workday's System Administrator security group — or equivalent rights to:
Create integration system users
Register API clients
Manage refresh tokens
Configure security
Edit business processes
Workday Terminology: "Run the '{Task Name}' task" = type the task name into the Workday search bar and open it. "Related Actions" = the ⋯ menu on an object.
Stage 1 · Workday — Security Setup
(ISU + OAuth API Client + Domains)
1.1 · Create the Integration System User (ISU)
Run the "Create Integration System User" task and fill in the following:
User Name: e.g.
ISU_Yardstik_OAuth💡 This ISU User Name is also entered on the Yardstik card as Workday account (Stage 2) — it becomes the
wd-external-originator-idheader on transactional calls.New Password + New Password Verify: Set one meeting the on-screen rules.
(Yardstik never uses this password — authentication is OAuth — but Workday requires it. Record it anyway.)
Require New Password at Next Sign In: Leave unchecked (an ISU cannot sign in to reset a password)
Session Timeout Minutes: Enter
0⚠️ Note the read-only "Session Timeout Minutes Enforced" value: if the tenant enforces a floor (e.g. 120), that value wins and becomes the effective session timeout. This matters because the OAuth access-token lifetime follows the ISU's session timeout. Yardstik polls ~every 15 minutes and re-mints the token ~every 2 hours, so any effective timeout ≥ the poll interval is safe.
Do Not Allow UI Sessions: ✅ Check → OK
After saving, Workday auto-adds the ISU to baseline system security groups (All Users, Viewer, etc.) — none of these grant background check access. BGC domains are granted explicitly in Stage 1.5.
1.2 · Register the OAuth API Client for Integrations
Run the "Register API Client for Integrations" task and configure the following:
Field | Value |
Client Name | e.g. |
Enforce Customized Access Token Expiry | Leave unchecked (expiry then follows the ISU session timeout per 1.1) |
Refresh Token Timeout (in days) |
|
Non-Expiring Refresh Tokens | ✅ Check |
Scope (Functional Areas) | Recruiting, Staffing, Personal Data, Contact Information |
Include Workday Owned Scope | ✅ Check |
→ Click OK
Important Notes:
There is no "Client Grant Type" field on this task — it auto-registers the client as Authorization Code Grant / Access Token Type = Bearer (visible on the resulting View API Client page)
Workday displays the Client ID and Client Secret on the View page — copy both immediately (the secret is viewable only at registration or when you generate a new secret). They go on the Yardstik card in Stage 2.
⚠️ Gotcha: Scope binds at refresh-token creation. If you change the client's scope later, you must regenerate the refresh token (1.3) and re-enter it on the card.
1.3 · Generate the Refresh Token Bound to the ISU
This is not a standalone searchable task — reach it from the API Client's Related Actions:
Run "View API Clients" → click the API Clients for Integrations tab → select your API Client
Click Related Actions (⋯) → API Client → Manage Refresh Tokens for Integrations
In the prompt, the API Client is pre-filled → set Workday Account = the ISU from Step 1.1 → OK
On the "Delete or Regenerate Refresh Token" screen:
Check "Generate New Refresh Token" → OK
(Leave "Confirm Delete" unchecked on a first mint)
⚠️ On a later re-mint, an existing token is listed and you check both boxes — note that regenerating deletes the old refresh token, so any integration using it breaks until the card is updated.
"Successfully Regenerated Refresh Token" confirms it, showing Non-Expiring = Yes
Copy the refresh token (shown only here) → enter it on the Yardstik card in Stage 2
1.4 · Get the Endpoint URLs
Both URLs depend only on the tenant's host + tenant name and do not change with the ISU/client:
URL | Format |
Workday Endpoint Base URL |
|
OAuth Token Endpoint URL |
|
💡 Use the tenant's SOAP/services host (e.g. impl-services1.wd12.myworkday.com), not the interactive UI host (impl.wd12…) shown in the browser bar.
To find the host + tenant if unknown: Open the "Public Web Services" report → any service (e.g. Human Resources) → Related Actions → Web Service → View WSDL → the <soapbind:address> @location at the bottom is https://{host}/ccx/service/{tenant}/… — the Base URL is everything up to and including {tenant}.
1.5 · Grant the ISU Its Background Check Domains (Security Group)
Step 1 — Create the Security Group:
Run "Create Security Group":
Type: Integration System Security Group (Unconstrained)
Name: e.g.
ISSG_Yardstik_BC→ OK
On the edit screen, add your ISU from Step 1.1 under Integration System Users → OK
Step 2 — Set Domain Permissions:
Run "Maintain Permissions for Security Group":
Operation: Maintain
Source Security Group: the group you just created → OK
Add each of the following domains under Domain Security Policy Permissions:
# | Domain | Functional Area | Access | Needed For |
1 | Candidate Data: Background Check History | Recruiting | Get and Put | Poll Get_Background_Check + status postback Put_Background_Check |
2 | Pre-Hire Data: Background Check Status | Pre-Hire Process | Get and Put | Poll + postback (applicant/pre-hire recipients) |
3 | Worker Data: Background Check Status | Personal Data | Get and Put | Poll + postback (worker recipients) |
4 | Candidate Data: Job Application | Recruiting | Get | Get_Candidates — applicant enrichment (name/email/phone/address/education/employment) |
5 | Worker Data: Public Worker Reports | Staffing | Get | Get_Workers — worker enrichment (name/email/phone/home address) |
6 | Set Up: Background Checks | Pre-Hire Process | Get and Put | Package sync (Get/Put_Background_Check_Packages) |
7 | Worker Data: Skills and Experience | Worker Profile and Skills | Get | Get_Workers — worker education & employment |
⚠️ This is a least-privilege set — grant only these seven domains. Each is verifiable with Workday's own "View Security for Securable Item" on the corresponding operation.
Do not grant any of the following — the integration does not use them: Integration Event, Job Requisition Data, Manage Pre-Hire Process: Manage Pre-Hires, Manage: Evergreen Requisitions, Pre-Hire: Skills and Experience, System All/Report Background Processes.
💡 Domain #7 (Worker Data: Skills and Experience) is only required if worker re-screens should prefill education/employment. Without it, worker orders still succeed but omit that prefill (no error).
Step 3 — Activate Changes:
Run "Activate Pending Security Policy Changes"
⚠️ Do not skip this step — grants stay inactive until activated.
Stage 2 · Yardstik — Workday Integration Card
Navigate to Developer Tools → Integrations → Workday card and enter the six values from Stage 1:
Field | Value |
Workday Endpoint Base URL |
|
OAuth Token Endpoint |
|
Client ID | From the API Client (1.2) |
Client Secret | From the API Client (1.2) |
Refresh Token | From Manage Refresh Tokens (1.3) |
Workday account | The ISU's User Name from Stage 1.1 (e.g. |
Toggle the integration On → UPDATE
On enable, Yardstik mints an access token and syncs your enabled packages into Workday via Put_Background_Check_Package.
📏 Keep each Yardstik package name ≤ 47 characters / first 44 unique (Yardstik auto-prefixes YS|; Workday enforces a unique 50-character display-name limit).
One Yardstik account binds to exactly one Workday tenant.
Credential Rotation:
If you later rotate the client secret or refresh token:
Re-enter the new value on the card
The new credential takes effect at Yardstik's next scheduled token refresh (~2h) unless a refresh is forced — plan rotations accordingly
Enter credentials in one place (the card) to avoid a stale form overwriting them
⚠️ The masked Secret/Refresh-Token fields must be cleared and re-pasted to change
Please note - The System Administrator will need to setup a Yardstik User profile. This is to ensure the Yardstik Packages are created properly. For assistance, please contact your Customer Success Manager or visit our support page yardstik.com/support
Stage 3 · Workday — Background Check Configuration
3.1 · Create the 22 Background Check Statuses + Reference IDs
Yardstik posts results as Workday Background Check Status Reference IDs of the form ys_<status>, so your tenant must pre-create all 22.
Step 1: Run "Maintain Background Check Statuses" and add each row below
Set Restricted To = Overall Status + Package Status + Test Status on every entry
Step 2: Run "Maintain Reference IDs" (Business Object = Background Check Status) and set each Reference ID Value to the exact ys_… string below
⚠️ Reference IDs are case-sensitive — skipping this step or entering incorrect casing fails the status push with HTTP 500 / Invalid_Reference.
# | Status Label | Maps To | Reference ID |
1 | Pass | Passed |
|
2 | Pending | Pending |
|
3 | Consider | Pending |
|
4 | Processing | Pending |
|
5 | Created | Pending |
|
6 | Clear | Passed |
|
7 | Fail | Did Not Pass |
|
8 | Archived | Pending |
|
9 | Expired | Pending |
|
10 | Canceled | Pending |
|
11 | Exception | Pending |
|
12 | Dispute | Pending |
|
13 | Proceed | Passed |
|
14 | Final Adverse | Did Not Pass |
|
15 | Pre-Adverse | Pending |
|
16 | Yardstik QA Review | Pending |
|
17 | Info Requested | Pending |
|
18 | On Hold | Pending |
|
19 | Queued | Pending |
|
20 | Approved To Process | Pending |
|
21 | Pending Approval | Pending |
|
22 | Closed | Did Not Pass |
|
💡 ys_ys_qa_review is the intentional doubled prefix.
3.2 · Package Selection — The Poll Trigger
Yardstik's poller only picks up events where a package has been selected (Package_Selected = true), and only within a ~5-day window of the Background Check step (Workday's Get_Background_Check Submission_Date = the event-initiation date).
A Yardstik package must be selected at/near the BGC step via one or both of:
✅ Recruiter selection at the Background Check step (standard), and/or
✅ "Maintain Background Check Package Condition Rules" → check Automatically Initiate Background Check → map a Job Application Condition Rule (e.g. worker type) to a Yardstik package (customer-specific)
⚠️ Important: The package must be selected within ~5 days of reaching the Background Check step, or the event ages out of the poll window.
If no Yardstik packages show, then something is incorrectly setup with the initial configuration step.
Stage 4 · Workday — Business Process
(Customer-Owned)
The recruiting Background Check business process is configured by you and varies by customer — Yardstik does not set it up. The only requirement is that candidates route to a definition that includes the standard Background Check step and end up with a Yardstik package selected (Stage 3.2).
When that happens, Workday creates a Background Check event that Yardstik's poller finds. The Workday-owned recruiter steps (Select Background Check Overall Status, Make Background Check Decision) are how your recruiters act on Yardstik's posted result.
No integration or document-delivery steps are needed in the business process.
Auto-Skip / Org-Scoped Definitions:
A Background Check BP can have multiple definitions scoped by organization. Make sure candidates route through a definition that includes the Background Check step — if they land on one that doesn't, the check will silently not happen.
Requirement of the background check step and Yardstik package selection is crucial for a background check to begin. If 3.2 is not setup properly, the integration will not work.
Stage 5 · ✅ Setup Complete!
Once a recruiter can advance a candidate (or initiate a worker re-screen) with a Yardstik package selected, setup is done.
From here, Yardstik will automatically:
🔍 Poll for new background check orders
📋 Create the order and enrich candidate data (applicant via Get_Candidates, worker via Get_Workers)
📧 Invite the candidate for consent + SSN/DOB
📤 Post results back to Workday's Background Check History (Overall + Package status + Results URL)
All account Users who are decisioning reports will need to have a Yardstik User profile. For assistance, please contact your Customer Success Manager or visit our support page yardstik.com/support
⛔ Important Reminder: Do not place test background check orders in Production. Every order advances a real candidate and creates a real, billable Yardstik report plus a real candidate invitation.
Questions? Reach out to your Yardstik Customer Success Manager or visit yardstik.com/support.