Workday API Integration

Recruitment Marketing


This guide will take you through the process of integrating your Workday account with Recruitment Marketing. This integration uses the Workday Web Services SOAP API as opposed to the legacy integration which exclusively utilised Workday Reports.

Whilst this method primarily uses web services to obtain job requisition / posting and candidate data, it is necessary to also create a customer report in Workday which provides the recruitment marketing module with visibility to the candidate's status updates.

Configuring Workday API

  • Your Workday administrator should configure a user account that has a username and password and can be used to make SOAP API calls.
  • The account needs to be in the Integration Developers group.
  • Recruitment Marketing will be making calls to the API end points: get_Candidates and get_Job_Postings which are part of the Recruiting web service
  • The account will need permission to access:
    Recruiting: get_candidates

    Recruiting: put_candidates (used for Direct Apply)
    Recruiting: get_job_postings
    Recruiting: get_evergreen_requisitions
    Recruiting: get_job_requisition

    Human Resources: get_locations
    Human Resources: get_job_families
    Human Resources: get_job_family_groups
    Human Resources: get_work_shifts
    Human Resources: get_job_profiles
    Human Resources: get_organizations (optional)
    Human Resources: get_workers (optional)

  • The tenant name should be known as it is used in the Endpoint URL and the username, for example: [user-name]@[tenant-name]

Additionally, you will also need to create a custom report in Workday. The definition for this report is available at Workday Candidate Report.

Once created, you will need the URL of the report, along with the credentials required to access the report.

Authentication Strategy

There are two methods of authentication that PageUp can be configured to use to communicate with Workday API. OAuth is an optional layer of security using the OAuth tokens.

  • Basic Auth - Username and Password
  • OAuth1.0 - Refresh Token ( if using OAuth )

Configuring Recruitment Marketing

Creating a new Workday ATS Integration:

  1. From the side menu, under Integrations click ATS.
  2. Click the New button.
  3. Click the Workday Web Services logo.

Workday API integration form


A Recruitment Marketing company account can have multiple ATS integrations. This field is used to distinguish those integrations.

How is candidate data retrieved?

Ideally, a customer is able to provide Workday API credentials and a custom made report which will tell Recruitment Marketing which candidates have been recently updated. Without this custom report, Recruitment Marketing has to import all candidates from Workday, every time a synchronisation is run.

If the customer is able to provide both Workday API settings and a Workday Report, then set this field to "Workday Web Services and Reports." If a report is unavailable, then set it to "Workday Web Services only."

For more information refer to the Workday Candidate Report.

Workday Web Services

Tenant Name
Provided by customer e.g. acmecorp

Tenant Hostname
Provided by customer e.g.
Note: the hostname should be entered without the HTTP protocol, and will be similar in format the example above

e.g. ISU_RM_Job_Report

Provided by customer

Authentication Strategy
By default, the integration uses Basic Auth. However, optionally, OAuth 2.0 can be utilised. If using OAuth, a refresh token also needs to be provided in the relevant field.

API Version
e.g v35.1

Workday Reports

Description: Workday Candidate Report

Candidates URL - the URL of the candidate status report created as per the definition above. This report is an XML file containing a list of email addresses of recently updated candidates.

Candidates Report Username
Provided by customer

Candidates Report Password
Provided by customer

XPath to emails
The XPath used to access the email node in the report  (e.g. wd:Report_Data/wd:Report_Entry/wd:email)

Job Data

Apply URLs
An apply URL is the URL that a candidate is redirected to when they complete a Recruitment Marketing job application Call-to-Action. There is an apply URL for each job that has been read from Workday. This setting determines which Workday field to use for the apply URL. Possible values are "External Apply URL" (default) and "External Job Path."

Level mapping
This is the field used to populate the level field for a job. Options are "Job Level" and "Management Level."

Which job postings should be used?
Sometimes only a subset of jobs need to be imported from Workday. If chosen, the "Only job postings with specified Job Posting site id" setting restricts the jobs imported by a supplied Workday site identifier. When this option is selected, an additional field will be displayed to allow entry of the relevant job posting site ID. The additional field supports a comma delimited list of Job Posting Site IDs in the event that multiple site IDs are being utilised.

How are jobs identified in the ATS?
Each imported job has an associated identifier in Workday. It possible to use Workday's Job Posting Identifier or Requisition Identifier

Requisition Field Overrides

It is possible, subject to the appropriate configuration of your Workday system, to request additional job requisition related data fields via Workday's Integration_Field_Override_Data functionality. Once the requisition field overrides have been configured within the Workday system, the WID of the field or group of fields should be entered into this field. A comma separated list of field overrides can be entered. These WIDs are then appended to the requests made to the Get_Job_Requisitions end point via the Request_Criteria > Field_And_Parameter_Criteria_Data > Provider Reference nodes within the SOAP request.

The returned data can then be referenced in the response via the Integration_Field_Override_Data nodes and can be mapped to Job Template Fields using the ATS Field Mapping functionality.

For detailed information on how configure Integration Override fields, please review this article.

Use additional job profiles?
It is possible to read Workday Additional Job Profile feature which will create additional jobs in Recruitment Marketing

Use additional locations?
When this field is checked, and the "Create on job per location" option has been chosen, additional jobs will be created using Workday's Job Posting Additional Location data

Use salary information?
Salary information will be read from Workday and associated with each job

Enrich jobs with job family groups
The Workday job import process will make additional calls to Workday to read Job Family Groups and associate them with the job

Enrich jobs with cost center data
The Workday job import process will make additional calls to Workday to read Organization data and associate it with the job

Filter location usage
This filter should be used if the customer has a large number of locations defined in Workday which are not relevant to recruitment. By applying this filter, only relevant locations are queried, thus improving the efficiency of the integration. If this field is selected, a relevant filter value should be entered (e.g. JOB POSTING).

Filter requisition status
This filter should be used if the customer has a large volume of job requisitions within Workday. By default, the integration pulls all requisitions and then filters down to just the open requisitions. By applying this filter, only relevant requisitions are queried, thus improving the efficiency of the integration. If this field is selected, a relevant filter value should be entered (e.g. OPEN)

Exclude jobs without a requisition
When selected, only job posting attached to a requisition are queried.

What should happen when reading a job that has multiple locations?
It is possible to create one job per location or multiple locations per job

How are remote jobs identified?
A remote job can be identified via a word in a title or description e.g. Sales Manager - Remote. In these cases, a regular expression is supplied to identify the exact phrase e.g. \A.*Remote\Z. Note the \A and \Z are supplied for you.

It is also possible to scan the Workday id of the job location for a regular expression, or for customers able to use v39.2 or above of the workday API, the system can be configured to utilise the Job Posting Remote Type Data.

Regex to match remote job locations

The regular expression used to identify fully remote jobs.

Regex to match hybrid job locations

The regular expression used to identify hybrid jobs (partially remote / partially on-site).

How are hidden job identified?

Hidden jobs are only accessible via a direct link to the job description page. Enter a query to define how hidden jobs should be identified (e.g. title ~ "test")

Candidate Data

Import unknown candidates?
This will import candidates from Workday who have recently been updated, but have not interacted with the Recruitment Marketing careers site and don't exist in the CRM

Ignore historical candidate events before this date
When importing a recently changed candidate, ignore any status updates before this date

Candidate read timeout (advanced)

This timeout prevents the integration failing if the API takes an extended period to return the details for a particular candidate. Can occur if the candidate has a large amount of application data in Workday.

Source Attribution

Append candidate source to the apply url
This will append any utm_source from a candidate's browsing activity to the apply url, sending it straight to Workday to populate candidate attribution

Candidate source fallback
In the event that a candidate source cannot be determined by Recruitment Marketing, it is possible to append a default value e.g. careers_site to the apply url, allowing Workday to set some level of candidate attribution

Synchronisation Settings

How often do you want to read jobs from the ATS?
15 minutes is the recommended amount of time to synchronise jobs. For slow integrations, the value should be adjusted

How often do you want to read candidate data from the ATS?
If the candidate synchronisation process can be completed quickly, then 15 minutes is ideal for this setting. For slow integrations, the value should be adjusted

Sync translation content
If a site has been localised into multiple languages, then this setting should be checked.

Direct apply settings

What is the default stage of the candidate when uploaded?
Select the application status which a candidate uploaded directly to Workday should be added to.

Getting started

To activate the integration, click the Play icon.
Alternatively, to deactivate it click the Pause icon.

Advanced Information - Job Data

API endpoints

The following Workday API endpoints are referenced by the integration:

  • Human_Resources - Get_Job_Postings
  • Human_Resources - Get_Job_Profiles
  • Human_Resources - Get_Locations
  • Recruiting - Get_Evergreen_Requisitions
  • Recruiting - Get_Job_Requisitions
  • Human_Resources - Get_Job_Families
  • Human_Resources - Get_Job_Family_Groups (optional)
  • Human_Resources - Get_Work_Shifts
  • Recruiting - Get_Organizations (optional)


A paginated call is made to Human_Resources - Get_Job_Postings. A Workday Job Posting is mapped to a Clinch job. Several filters are passed to Workday so that archived or draft postings aren’t used e.g. the following parameters are set:

  • Show_Only_Active_Job_Postings: true
  • Exclude_Future_Job_Postings: true
  • Job_Posting_Site_ID. This filter is optional and is useful for companies that support external and internal job postings.

The data returned is processed as follows, with calls made to relevant endpoints to obtain the related look-up data.

Recruitment Marketing Workday
ATS id Job_Posting/Job_Posting_ID
Title Job_Posting/Job_Posting_Title
Description Job_Posting/Job_Posting_Description
Requisition ATS id Job_Posting/Job_Requisition_ID
Start Date Job_Posting/Job_Posting_Start_Date
Note the time zone used to convert this date to UTC is stored in Job_Posting/Job_Posting_Location_Data/Primary_Location_Reference/ID[@type="Location_ID"]
Apply URL Job_Posting/External_Job_Path or Job_Posting/External_Apply_URL


This value is used to look up the full Location details from the Location lookup table. Once found, the Address_Data/Formatted_Address value is sent to Google’s Location API which returns data such as latitude, longitude, Google Place ID etc.

Note: Once a Clinch location has been created from a Workday LocationID, it is not automatically updated. This means if there is an update to a Workday location (as opposed to assigning a new location to a job) it will not be reflected in Clinch. The workaround is to delete the Clinch location and run the Job sync process

Additional Locations


If the “Use additional locations” checkbox in the ATS configuration has been checked, then the above Workday values are used to add additional locations to the job.


When “Remote” is set based on an ATS field, All location and additional location ids are concatenated and the resulting string is checked against a regular expression. For example, if any of the location ids for the job contain the word “Remote”, this field is checked

Workday v39.0 has built in support for remote jobs/locations. We can now read the remote value from Job_Posting_Remote_Type_Data/External_Name.

Payment Amount Requisition/Amount
Payment Frequency Requisition/Frequency_Reference/ID[@type="Frequency_ID"]
Payment Plan Requisition/Pay_Plan_Reference/ID[@type="Compensation_Plan_ID"]
Payment Currency Code Requisition/Currency_Reference/ID[@type="Currency_ID"]

Note: By default, the Workday job posting identifier is mapped to the Clinch job's identifier. However this can be modified using the How are jobs identified in the ATS option, so that the Workday requisition identifier is mapped to both the Clinch job id and the Clinch requisition id.


Recruitment Marketing Workday
ATS id Location/ID[@type="Location_ID"]
Street Location/Address_Line_Data
City Location/Municipality
State Location/Country_Region_Descriptor
Postcode Location/Postal_Code
Country code Location/Country_Reference/ID[@type="ISO_3166-1_Alpha-2_Code"]
Time Zone Location/Time_Zone_Reference/ID[@type="Time_Zone_ID"]
Full Address Location/Address_Data/Formatted_Address
Usage Location/Location_Usage_ID


Recruitment Marketing Workday
ATS id Job_Family/Job_Family_Data/Name
ATS Name Job_Family/Job_Family_Data/Name


Recruitment Marketing Workday
ATS id Job_Family_Group/Job_Family_Group_Data/Name
ATS Name Job_Family_Group/Job_Family_Group_Data/Name


If Level setting is configured to "Job Level":

Recruitment Marketing Workday
ATS id Job_Posting/Job_Level_Reference/[@type="WID"]
ATS Name Job_Posting/Job_Level_Reference/[@type="Job_Level_ID"]

If Level setting is configured to "Management Level":

Recruitment Marketing Workday
ATS id Job_Posting/Management_Level_Reference/[@type="WID"]
ATS Name Job_Posting/Management_Level_Reference/[@type="Management_Level_ID"]

Employment Type

Recruitment Marketing Workday
ATS id Job_Posting/Time_Type_Reference//ID[@type="WID"]
ATS Name Job_Posting/Time_Type_Reference//ID[@type="Position_Time_Type_ID"]

Job Template Fields (Custom Mappings)

A number of Workday fields that don’t map to Clinch built-in fields have been made available for mapping to Clinch job template fields. To use these, make a new ATS field mapping, choose Liquid as the language, and fill in the value on the right hand side as the path to the ATS field.

Description Workday Liquid Mapping Code Organization/Organization_Data//Reference_ID {{}} Organization/Organization/Organization_Data//Name {{}} Job_Posting/Job_Type_Reference//ID[@type="WID"] {{}}
job_type.code Job_Posting/Job_Type_Reference//ID[@type="Employee_Type_ID"] {{job_type.code}} Work_Shifts/Work_Shift_Data/Work_Shift_ID {{}} Work_Shifts/Work_Shift_Data/Work_Shift_Name {{}} Job_Posting/Position_Worker_Type_Reference//ID[@type="WID"] {{}}
worker_sub_type.code Job_Posting/Position_Worker_Type_Reference//ID[@type="Employee_Type_ID"] {{worker_sub_type.code}}

Additional Job Profiles

If the Use additional job profiles checkbox is enabled, and the current Workday job posting has supplied a Additional_Job_Profiles_Reference//ID[@type="Job_Profile_ID"] field, then this will result in an extra job being created under the same requisition.

Additional Job Locations

If the Use additional locations checkbox is enabled, the Job_Posting_Location_Data/Job_Posting_Additional_Location_Data/Additional_Location_Reference/ID[@type="Location_ID"] values will be used to create additional locations assigned to the job.

Advanced Information - Candidate Data

API endpoints

The following Workday API endpoints are referenced by the integration:

  • Recruiting - Get_Candidates


This part of the integration does the following.

  1. Find out what candidates have recently changed
  2. Get the candidate from Workday and import them

Workday does not currently have an endpoint which is able to provide the information required for the first step. Therefore, customers are required to create a custom Workday report which provides a list of email addresses for candidates who have changed since the date of the last successful candidate synchronisation.

Once the email addresses of the recently changed candidates have been acquired, a request to Recruiting - Get_Candidates is made


Recruitment Marketing Workday
ATS id Candidate_ID
First name First_Name
Last name Last_Name
Email address Email_Address
Phone number Phone_Number and
Location Country_code: Location_Data//Country_Reference//ID[@type="ISO_3166-1_Alpha-2_Code"]
Address Line 1: Location_Data//Address_Line_1
City: Location_Data//City
State: Location_Data//Country_Region_Reference//ID[@type="ISO_3166-2_Code"]
Zip: Location_Data//Postal_Code
Employee ID Worker_Reference//ID[@type="Employee_ID"]
Job Applications Each Job_Application_Data entry is examined

Job Application

Recruitment Marketing Workday
Status The ATS status uid, text, and time of creation fields are mapped to:
Requisition ID Job_Requisition_Reference//ID[@type="Job_Requisition_ID"]
Source Source_Reference//ID[@type="Applicant_Source_ID"]




Recruitment Marketing Workday
Company name Experience_Data/Company_Name
Job title Experience_Data/Title
Start date Experience_Data/Start_Month, Experience_Data/Start_Year
End date Experience_Data/End_Month, Experience_Data/End_Year
Is current Experience_Data/Currently_Work_Here


Recruitment Marketing Workday
School ID Education_Data/School_Reference//ID[@type="School_ID"]
School Name Education_Data/School_Name
Degree ID Education_Data/Degree_Reference//ID[@type="Degree_ID"]
Field of study ID Education_Data/Field_of_Study_Reference//ID[@type="Field_Of_Study_ID"]


Recruitment Marketing Workday
Name (maximum length is 50) Skill_Data/Skill_Name

Note: max length for skills is 50 characters

Useful information

Example URLs

WSDL URL: This is the URL of the Workday Recruiting WSDL file. Most likely it will look like this (note the version number)

Endpoint URL: This is the URL of your workday installation

Was this article helpful?
0 out of 0 found this helpful