Dayforce RESTful Web Services

Developer Guide
Dayforce Release 2023.2.0
This document contains confidential and proprietary information of Ceridian HCM, Inc.
(“Ceridian”) or its affiliates and is intended only for the person(s) to whom it is transmitted by
Ceridian. Any reproduction of this document, in whole or in part, or the divulgence of any of the
information without the prior written consent of Ceridian is prohibited. Ceridian reserves any and
all rights in the information contained in this document. Neither Ceridian nor any of its affiliates
shall in any circumstances be held liable for any damages howsoever caused by reliance on
information contained herein.

Ceridian, Dayforce, the respective logos, and Makes Work Life Better are either trademarks or
registered trademarks of Ceridian or its affiliates in the United States and/or other countries.

All other brand and product names referenced herein are the trademarks or registered trademarks
of their respective holder.

Release Version: 2023.2.0

Document Version: Rev 1
Publication Date: 8/17/2023
Table of Contents

About This Guide 13

Run a Keyword Search 13
Additional Resources 14

Before You Begin 15

Getting Started with RESTful Web Services 16

Integrate with the REST Service 16
Create a Sample .NET Console Client Application 17
Create a Project 18
Add a Reference 18
Add Source Code 18
Authentication 19
Add the Web Services Role Feature 19
Token-Based Authentication 19
Determine Which URL to Use 22
HTTP Verbs 23
GET 23
PATCH 23
POST 24

RESTful Add and Update Background Screening Data 25

POST Background Screening Billing Codes 25
Parameters 25
Response Objects 26
POST Background Screening Packages 27
Parameters 27
Response Objects 27
POST Background Screening Provider Statuses 28
Parameters 29
Response Objects 29
PATCH Candidate Background Screening 29
Parameters 30
PATCH Candidate Background Screening Right to Work 31

Page 3 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 Parameters 31
CandidateRightToWorkResults Parameters 31
PATCH Candidate Background Screening Personal Identifiable Information 35
Parameters 36
PATCH Candidate Background Screening Adjudication Status 36
Parameters 37
PATCH Candidate Background Screening Status 37
Parameters 37
Background Screening Data Models 38
Response Body Schema Description 42

REST Services for Retrieving Employee Information 45

URL Endpoint 45
Employee API Proxy Class 45
Use Specific Criteria to Retrieve Employee XRefCodes 46
Sample Code for Retrieving Employee XRefCodes 48
Retrieve Details for Individual Employees 48

REST Services for Updating Employee Information 54

URL Endpoint 54
Request to Update an Employee 54
Validation of Employee Data 57
POST and PATCH Employee Subordinate Resources 57
ProcessResult Messages 58

REST Service for Adding Employee Information 60

URL Endpoint 60
Submit a Request to Add an Employee 60

RESTful Retrieve Department Data 62

RESTful Get Department XRefCodes 62
Overview 62
Response 62
Available Data 62
Security and Data Returned 63

Page 4 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 RESTful Get Department Details 63
Response 63
Security 63

RESTful Add and Update Departments 64

POST Department Data 64
Overview 64
Parameters 64
Request Body 65
PATCH Department Data 65
Overview 65
Parameters 66
Request Body 66

RESTful Add and Update Positions 67

POST Position Data 67
Overview 67
Parameters 67
Request Body 68
PATCH Position Data 68
Overview 68
Parameters 68
Request Body 69

RESTful Retrieve Position Data 70

RESTful Get Position XRefCodes 70
Overview 70
Response 70
Available Data 70
Security and Data Returned 71
RESTful Get Position Details 71
Parameters 71
Response 72
Security 72

RESTful Add and Update Jobs 73

POST Job Data 73

Page 5 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 Overview 73
Parameters 73
Request Body 74
PATCH Job Data 74
Overview 74
Parameters 74
Request Body 75

RESTful Retrieve Job Data 76

RESTful Get Job XRefCodes 76
Overview 76
Response 76
Available Data 76
Security and Data Returned 77
RESTful Get Job Details 77
Response 77
Security 77

RESTful Retrieve HR Admin Data 78

RESTful Get HR Admin XRefCodes 78
Overview 79
Response 79
Available Data 79
Security and Data Returned 79
RESTful Get HR Admin Details 79
Response 79
Security 80

REST Services for Retrieving WFM Data 81

RESTful Retrieve Employee Retro Data 98

RESTful Add and Update Employee Pay Adjustment Data 101

POST Employee Pay Adjustments 101
Endpoint URL 101
Overview 101
Parameters 102

Page 6 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 Request Body 102
PATCH Employee Pay Adjustments Data 103
Overview 103
Parameters 104
Request Body 104

RESTful Add and Update Employee Schedules 106

POST Employee Schedules Data 106
Endpoint URL 106
Overview 106
Parameters 107
Request Body 107
PATCH Employee Schedules Data 108
Endpoint URL 108
Overview 109
Parameters 109
Request Body 110

RESTful Retrieve Org Unit Data 112

RESTful Get Org Unit XRefCodes 112
Overview 112
Response 112
Available Data 113
Security and Data Returned 113
RESTful Get Org Unit Details 113
Parameters 113
Response 114
Security 115

RESTful Add and Update Org Units 116

POST Org Unit Data 116
Overview 116
Parameters 116
Request Body 117
PATCH Org Unit Data 117
Overview 117
Parameters 118

Page 7 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 Request Body 118

RESTful Add Employee Availability Data 119

POST Availability 119
Endpoint URL 119
Parameters 119
Request Body 120
Security 120

REST Service for Adding Employee Raw Punches 121

Endpoint URL 121
IsValidateOnly Parameter 121
Request Body 121
Fields 122
Responses 124
Success Responses 124
Error Responses 124

RESTful Delete Employee Punches 127

RESTful Retrieve Labor Metrics 128

RESTful Get Labor Metrics XRefCodes 128
Parameters 128
Response 128
RESTful Get Labor Metric Type XRefCodes 129
Parameters 129
Response 129

RESTful Add and Update Labor Metrics 131

POST Labor Metrics 131
Endpoint URL 131
Parameters 131
Request Body 132
Security 132
PATCH Labor Metrics 132
Overview 132
Parameters 132

Page 8 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 Request Body 133
Security 133
POST Labor Metric Types 133
Endpoint URL 133
Parameters 134
Request Body 134
Security 134
PATCH Labor Metric Types 134
Overview 134
Parameters 135
Request Body 135
Security 135

RESTful Retrieve and Delete Legacy Labor Metrics 136

RESTful Get Legacy Labor Metrics 136
RESTful Delete Legacy Labor Metrics 137

RESTful Add and Update Legacy Labor Metrics 139

POST Legacy Labor Metrics 139
PATCH Legacy Labor Metrics 140

RESTful Retrieve and Delete Labor Validation Policy Rules 142

RESTful Get Labor Validation Policy Rule XRefCodes 142
RESTful Delete Labor Validation Policy Rule XRefCodes 144

RESTful Add and Update Labor Validation Policies 145

POST Labor Validation Policy Rules 145
PATCH Labor Validation Policy Rules 147
Search Labor Validation Policy Rule Data 149

RESTful Get KPI Data 151

POST and PATCH KPI Data 152
POST KPI Data 152
PATCH KPI Data 153

RESTful Get Plan Targets 155

Page 9 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 POST and PATCH Plan Targets 156
PATCH Plan Targets 156
POST Plan Targets 157

RESTful Get Operating Hours 159

POST and PATCH Operating Hours 160
POST Operating Hours 160
PATCH Operating Hours 161

RESTful Retrieve Projects Data 163

RESTful Get Projects 163
Parameters 163
Response 166
RESTful Get Projects XRefCodes 166
Parameters 166
Response 166

RESTful Add and Update Projects Data 169

POST Projects Data 169
Endpoint URL 169
Parameters 169
Request Body 170
Validation of Org Unit Level 171
Validation of IFRS Classification 171
Security 171
PATCH Projects Data 171
Overview 172
Parameters 172
Request Body 172
Validation of Org Unit Level 173
Validation of IFRS Classification 174
Validation of Parent Project 174
Security 174

REST Services for Retrieving Documents 175

URL Endpoint 175
Documents API Proxy Class 175

Page 10 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 Retrieve List of Documents Based on Employee 176
Sample Code: Retrieve List of Documents Based on Employee 177
Retrieve a Single Document 177
Sample Code: Retrieve and Save a Single Document 177
Sample Code - Saving Function for a Single Document 178

REST Services for Retrieving Report Metadata and Report Data 179
URL Endpoint 179
Report API Proxy Class 179
Retrieve List of Report Metadata 180
Retrieve Report Metadata for One Report 181
Retrieve Data for One Report 181

REST Services for Updating an Employee's I-9 Order Status 183

Overview 183
Parameters 183
Request Body 183
i9OrderId (string) 184
IsValidateOnly (boolean) 184
Response 184

REST Services for Retrieving Job Posting Feeds 185

Integrations with Candidate Assessment Providers 190

RESTful GET Assessment List 190
RESTful POST Candidate Assessment Registration 191
RESTful POST Candidate Assessment Status 193
RESTful POST Candidate Reports 193
RESTful POST Candidate Scores 194

Pagination of Response Data 197

Data Authorization and Filtering 199

Field Level Filtering 199
Access Authorizations 199

Page 11 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Check for Errors 200

Page 12 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
About This Guide

This guide is intended for developers who create code to interact with the Dayforce REST
services API.

Run a Keyword Search

You can search for words or phrases in this guide by pressing Ctrl+F or Command+F. This opens
a search field where you can type the text that you want to find. The field looks like this in Acrobat
Reader:

Type a word or phrase and press the Enter key to go to the closest match in the document. You
can keep pressing the Enter key to move through each instance.

Note: Search is not case sensitive, but it finds only exact word or phrase matches. If you don’t find
a term (for example, policy), try a variation of the word (for example, policies). This lets you find
instances of the word or phrase in headings or within a paragraph.

For example, say you want to learn more about the Favorites button of Dayforce. To do this, type
favorites in the search field. Then, press the Enter key to move to the closest instance of the
word "favorites" in the document.

Page 13 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Additional Resources
It is recommended that you read the Dayforce Web Services Introduction Guide before beginning
a development project. It contains important information about using Dayforce web services,
including acceptable use, request parameters, design considerations and limitations.

The entire documentation set is available at help.dayforce.com.

To register on the Dayforce Help Portal:

1. On the Dayforce Help Portal login page, click Sign Up (it's in the top right corner).
2. Enter your name and email address, and choose a password.
3. Click Sign Up.
4. Select the Remember me checkbox to bypass the login page in the future.

You can also access help directly in Dayforce by clicking the help icon in the toolbar.

Page 14 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Before You Begin

Before you begin: It's strongly recommended that you thoroughly read the Dayforce Web
Services Introduction Guide.

The Dayforce Web Services Introduction Guide contains critical information about using Dayforce
Web Services, including:
l Acceptable use of Dayforce Web Services.
l Detailed information for the parameters available in each type of request.
l Example program flows for frequently used requests.
l Limitations of POST and PATCH operations.
l Design considerations for working with the Dayforce Rate Limits.

The content noted above ensures that the design of web services-consuming applications
remains in line with Dayforce expectations and also provides valuable insight into using the
available requests in an efficient and effective manner.

To use Dayforce Web Services, you must first configure Dayforce. The basic configuration of
Dayforce to use Web Services follows this general process flow:
l Setting up a web services user account and role
l Configuring a password policy, and
l Configuring security, including access authorizations and field-level accesses.

These configuration steps might have already been completed for your organization. Contact a
Dayforce Support or Implementation representative before using these features.

Page 15 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Getting Started with RESTful Web
Services

This guide is intended for developers who create code to interact with the Dayforce REST
Services API. As RESTful services, many development platforms can interact with them.

Topics covered in this guide include how to locate the correct version of the service to use,
authentication and authorization, and how to make a request and interpret the response, including
error responses.

This guide is divided into the following topics:

l Integrate with the REST Service
l Create a .NET Console Client Application
l Retrieve a list of Employee XRefCodes
l Update Employee Data
l Adding a New Employee
l Retrieve List of Documents based on Employee
l Retrieve a Single Document
l Authorize and Filter Data
l Check for Errors

You must perform the following configuration steps in Dayforce before you can begin using
Dayforce Web Services:
l Set up a web services user account and role
l Configure a password policy
l Configure security, including access authorizations and field-level accesses

These configuration steps might have already been completed for your organization. Contact a
Dayforce Support or Implementation representative before using these features.

Integrate with the REST Service

The REST service uses the HTTP protocol for communication and supports JSON for request and
response payloads. There are many options for integrating with a REST service. This section will
discuss primarily using .NET C# for integration.

It's recommended when developing a client with C# to use the Model classes and API classes
built into the sample application. Using these classes will help you in understanding the object
model and with formatting proper requests.

Page 16 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
The URL for the REST services is the following:

https://www.dayforcehcm.com/api/{clientName}/v1

The REST service is also described using the OpenAPI specification which allows you to use
tools capable of consuming the OpenAPI specification to generate client-side source code or
applications. The URL for the OpenAPI specification is the following:

https://www.dayforcehcm.com/api/{clientName}/swagger/docs/v1

The service was developed using Microsoft .NET technologies and is hosted within Microsoft IIS.

Important: The OpenAPI specification and services at the above URLs will be updated as new
features and functionality are added to the Dayforce REST Services. For this reason, you should
design your solution in a way that makes it easy to upgrade your client.

Note that while the REST service will be updated as new versions of the application are released,
it will continue to be compatible with previous versions of the application.

Breaking changes will be released with a URL having a new version number.

Create a Sample .NET Console Client

Application
This section provides detailed steps for creating a sample console application.

Important: The code provided in this section is a sample only, and not production ready code.
You must add the code qualities needed to make it production ready, such as better error
handling.

To create a sample .NET console client application, you must:

l Create a project.
l Add references.
l Add source code from the provided samples applications into the Main method in the Pro-
gram.cs source file.
l Compile and execute the sample application.

Each of these is described in the following topics:

l Create a Project (see page 18)
l Add a Reference (see page 18)
l Add Source Code (see page 18)

Page 17 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Create a Project
When creating a .NET console client application, you must first create a project.

To create a project:
1. Go to Visual Studio and click File > New Project.
2. Select Console Application.
3. Name the console application DayforceRestSampleClient.

Add a Reference
Before you begin: The following instructions are specific to .NET. If you are developing with
Java, read the readme.txt file with the Java sample code for information about which third party
components to add.
1. In Visual Studio, in the Solution Explorer view, right-click the Day-
forceRestSampleClient project, and select Manage NuGet Packages.
2. Search for the following packages and install them:
o Json.NET: this package is needed for serializing and deserializing JSON
o RestSharp: this package is the REST client API

3. Right-click the References folder and click Add Reference and add Sys-
tem.Runtime.Serialization.

Note: To complete the sample client application, insert the logic shown in the following sections
into the main method in the Program.cs source file, then compile and execute.

Add Source Code

To complete the sample client application, insert the logic shown in the following sections into the
Main method in the Program.cs source file, then compile and execute.
1. Ensure that you have downloaded and extracted the .NET Sample application.
2. Right-click the project and click Add > New Folder and name it Models.
3. Right-click the new Models folder, then click Add > Existing Item.
4. In the location where you extracted the Sample application, go to \RestNetCli-
ent\Model, select all, and click Add.
5. Right-click the project and click Add > Existing Item.
6. In the location where you extracted the Sample application, go to \RestNetClient and
select the following classes:
o ApiResponse.cs
o AuthenticationModule.cs
o Authenticator.cs
o Constants.cs

Page 18 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 o EmployeeApi.cs
o EmployeeGetRequest.cs
o EmployeePatchRequest.cs
o EmployeePostRequest.cs
o EmployeesGetRequest.cs
7. Click Add.

Authentication
Each request you submit must include credentials that can be authenticated, and the user
account must have access to the Web Services feature on its default role. The Dayforce REST
services use the HTTP basic authentication protocol for passing credentials.

Note: Some third-party REST client APIs don't include the credentials on requests that result from
a redirect response from the server. If you are receiving a 401 Unauthorized response, it might be
due to this limitation. In the sample code, we use the RestSharp third party component for a REST
client and we have implemented an IAuthenticator, which will pass the credentials on every
request.

Add the Web Services Role Feature

You must add Web Services feature access to the default role of the user account to use Dayforce
Web Services. At a minimum, you must add the Web Services role feature, and the Read Data
sub-feature under Web Services.

It's advisable to add the other role sub-features in the Web Services feature: Explorer,
Notification Status, Notification Subscriptions, and PutWorkflowValidationAction, which is
required for the role to perform actions such as reading and updating data.

To add the Web Services feature to a role:

1. Go to System Admin > Roles.
2. Select the default role associate with the user.
3. Click the Features tab.
4. Expand HCM Anywhere > Web Services.
5. Select the checkboxes for Web Services and, at a minimum, Read Data.
6. Click Save, and then click Refresh.

Token-Based Authentication
Dayforce supports the ability to request Dayforce APIs using an access token. When you use an
access token to call an API, you aren't required to authenticate using your user name and
password. You can obtain an access token by calling the Dayforce identity service API with your

Page 19 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Web Services login credentials. The access token can then be used to perform an API request.
Using token-based authentication reduces the risk of exposing your login credentials to potential
attackers as they're not sent with each API request. The token is valid for a limited amount of time,
which reduces the risk of the token being compromised. For these reasons, Ceridian highly
recommends the use of token-based authentication.

The following diagram illustrates the process of requesting an access token:

Important: Access tokens cannot be revoked. Hence, they must be handled responsibly.

Token-based authentication is available for Dayforce users that are already configured for Web
Services. No additional configuration is required.

Request an Access Token

An access token can be retrieved with an API request to Dayforce Identity servers.

To retrieve an access token, you must make a POST request to any of the following URLS:
l Production: https://dfid.dayforcehcm.com/connect/token
l Test: https://dfidtst.np.dayforcehcm.com/connect/token

The following parameters must be included in the body of your request:

l Grant_type: Value is always password.
l CompanyId: Client namespace, used to connect to Dayforce UI or APIs.
l Username: Name of the Dayforce user dedicated to Web Services calls.
l Password: Password of the specific user.
l Client_Id: Scope of the token, the value is always Dayforce.HCMAnywhere.Client.

After you request an access token, the Dayforce Identity server verifies the credentials you
provided in the request. If the credentials are successfully verified, the server returns a JSON
Web Token that contains the access token needed to request Dayforce APIs. The JSON Web
Token also contains the scope of the access token as well as the number of seconds it will remain
valid.

The following example illustrates the corresponding Curl script for a token request:

Page 20 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
curl--location--request POST "https://dfid.dayforcehcm.com/connect/token"--
header "Content-Type: application/x-www-form-urlencoded"--data-urlencode
"grant_type=password"--data-urlencode "companyId=Company123"--data-urlencode
"username=WebServiceUser123"--data-urlencode "password=?@55w0rD"--data-
urlencode "client_id=Dayforce.HCMAnywhere.Client"

The following is an example of a JSON Web Token response:

{

"access_token":
"eyJhbGciOiJSUzI1NiIsImtpZCI6IjYwMkZDQTBGNDk3NEUzMUE5OEEyNDBDN0QyNDA5QTFFRTU1
MzE1RTQiLCJ0eXAiOiJhdCtqd3QiLCJ4NXQiOiJZQ19LRDBsMDR4cVlva0RIMGtDYUh1VlRGZVEif
Q.eyJuYmYiOjE1OTIyNTgwMDksImV4cCI6MTU5MjI2MTYwOSwiaXNzIjoiaHR0cHM6Ly9kZmlkcWE
ubnAuZGF5Zm9yY2VoY20uY29tIiwiYXVkIjpbImRmLmhjbWFueXdoZXJlLmNsaWVudCIsImh0dHBz
Oi8vZGZpZHFhLm5wLmRheWZvcmNlaGNtLmNvbS9yZXNvdXJjZXMiXSwiY2xpZW50X2lkIjoiRGF5Z
m9yY2UuSENNQW55d2hlcmUuQ2xpZW50Iiwic3ViIjoiMTAwMUBNRkFSVFhfMTk3NzUuZGF5Zm9yY2
UuY29tIiwiYXV0aF90aW1lIjoxNTkyMjU4MDA5LCJpZHAiOiJsb2NhbCIsImRmLnVzZXJpZCI6IjE
wMDEiLCJkZi5ucyI6Ik1GQVJUWF8xOTc3NSIsInByZWZlcnJlZF91c2VybmFtZSI6IkNBZG1pbiIs
ImRmLmN1bHR1cmUiOiJ7XCJJZFwiOjEwMzMsXCJDb2RlXCI6XCJlbi1VU1wifSIsInNjb3BlIjpbI
mRheWZvcmNlIiwib3BlbmlkIiwicHJvZmlsZSIsImRmLmhjbWFueXdoZXJlLmNsaWVudCJdLCJhbX
IiOlsicGFzc3dvcmQiXX0.kyBxU_aPTm2Lec4yZDZ4niVlPVuEN5VoqjMa7r3e6sKrrkawi_
8Hd3WWMFUchLnj90_YWNKfWY0yB1H9wfzmC2Vi250TXTIXgyKI3d3F9rEt-kJUj2VF5-
C7jvfQmMZLDK_B-HGemG5oWTgRdjKS1W81q-g39cwj_
mcnIZQ9QhTn7PmtbzS0vMgBnawWCfZFDd1RnXpNZn-gAQteLGl4h_HcjsJGj7ZX_
uX4jy1TYFsn96exd1xXi_sAcxtOXgrF21t3bJgKC_
wmTzXSnonrS81cFxeRpedXNhLTFersA7XWW8hnsscDEJNy5Fh9wepqXXTEkIzutQ-Uv0wKailaMg",

"expires_in": 3600,

"token_type": "Bearer",

"scope": "dayforce df.hcmanywhere.client openid profile"

Note: The value of the expires_in parameter indicates the number of seconds that the access
token will remain valid. The standard duration is 3,600 seconds. You can request a new token
when needed.

Request Dayforce APIs Using an Access Token

After you obtain an access token, you can use it to request Dayforce APIs. You must include the
Bearer key word in the authorization header when making requests. In this situation, you aren't
required to provide a user name or password.

The following example illustrates the corresponding Curl script for an API request:
curl --location --request GET
'https://www.dayforcehcm.com/api/Company123/v1/ClientMetadata' -- header
'Authorization: Bearer eyJhbGciOiJSUzI1[…]MyHYa7k0nvK1g'

Page 21 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Note: When you make an API request using an access token, the security access associated with
your user account is enforced.

Determine Which URL to Use

Dayforce hosts multiple versions of this service to support multiple clients. All clients use the same
URL, and Dayforce issues an HTTP redirect on every request to ensure that your request is
processed with the correct service.

If you are submitting many requests in a short period of time, you will benefit from obtaining the
target redirect URL which will allow you to bypass the automatic redirect. To obtain the target
URL, you should make the following REST service request, replacing {clientName} with your
organization name:

https://www.dayforcehcm.com/api/{clientName}/V1/ClientMetadata

Important: This method must be called at a minimum of once a day if you store the URL returned
from this method.

The client and version specific URL returned from this service will look very similar to this root
URL, but will likely have a version number embedded within it.

Example Response
{
"ServiceVersion":"58.x.x.x",
"ServiceUri":"https://www.dayforcehcm.com/58/api"
}

Sample Code - Acquire Client Site URL

Program.cs

EmployeeApi.cs:

Page 22 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
The main program (Program.cs) creates a URI object that contains the target URL. It will then
use the URI object to initialize EmployeeApi along with the user name and password. If this is
successful, it will return a formatted URL that should be used on subsequent REST API calls. If
this fails, it will throw an exception. This method will work on other API objects, for example,
DocumentsApi.

HTTP Verbs
Dayforce follows the REST standards regarding the use of HTTP verbs to retrieve and update
data. Below is a description of the verbs that are currently supported.

GET
GET is used to retrieve resource data, with responses in JSON format. Resources can be
retrieved individually by using an XRefCode or as collections if an XRefCode is not specified.

PATCH
PATCH is used to make changes to existing resources. The query string indicates which resource
to update by specifying an XRefCode, and the request body contains the data. The data in the
request body has the same structure as the response from the GET request.

Null and Missing Properties on the Request

It is important to understand how a null value on the request is treated differently from a property
that is missing on the request. Failing to understand the difference could cause unintentional data
changes.

The standard use case is to provide only the property values that you need to change. Excluding a
property from the request implies that you don't want to change the value of that property in the
Dayforce database.

If you include properties with a value of Null in the request, the REST service will update the
corresponding property in the Dayforce database to Null.

While the above seems simple and intuitive, you must be careful when producing the request
JSON from the response body because some JSON APIs will produce null valued properties in
the output by default. The sample app has been coded to handle this situation.

As an example, suppose you need to change the last name of an employee and also remove their
home phone number. The request for this follows where any employee property not shown in the
request remains unchanged, but the HomePhone value is removed from the database.
{
"HomePhone":null,
"LastName":"newName",

Page 23 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 "MaidenName":"priorName"
}

POST
POST is used to add new entities to the system. This should be familiar as it's the same process
used by web browsers to submit form data to a web server.

Like updating a resource with a PATCH request, the query string will indicate the XRefCode of the
resource to add, and the request body will contain the data. The data in the request body has the
same structure as the response from the GET request.

Note: XRefCodes must be unique. To add a new resource, you must come up with an XRefCode
that is unique to that resource. Using an XRefCode that is already in use will result in an error
when the data is validated.

Page 24 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
RESTful Add and Update Background
Screening Data

The HTTP verbs POST and PATCH are used to process inserts and updates to candidate
background screening information. Insert and update capabilities support adding new
background screening data for a candidate and updating Dayforce with the list of Packages and
Billing Codes from background screening providers.

The following topics contain more information about the POST and PATCH background screening
endpoints:
l POST Background Screening Billing Codes (see page 25)
l POST Background Screening Packages (see page 27)
l POST Background Screening Provider Statuses (see page 28)
l PATCH Candidate Background Screening (see page 29)
l PATCH Candidate Background Screening Right to Work (see page 31)
l PATCH Candidate Background Screening Personal Identifiable Information (see
page 35)
l PATCH Candidate Background Screening Adjudication Status (see page 36)
l PATCH Candidate Background Screening Status (see page 37)

POST Background Screening Billing Codes

POST Background Screening Billing Codes endpoint enables the provider to send a list of Billing
Codes to Dayforce. The provider can also send the list of associated packages (if any) together.

Note: Billing Codes that aren't part of the request are considered deleted or inactive.

The URL for POST Background Screening Billing Codes uses the following base URL:
https://www.dayforcehcm.com/api/CompanyName/V1/BackgroundScreening/BillingCode

Parameters
ProviderReference parameter type and description
Parameters Type Description
ProviderReference* String Provider Unique Identifier.

Page 25 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Response Objects
Properties, type and descriptions of response objects
Object Name Object Properties Type Description
BillingCodeId* String Provider billing code id
Name String Billing code name
BillingCodes Description String Billing code description
List of associated packages
AssociatedPackages N/A
to a billing code
PackageId* String Provider package id
Name* String Package name
AssociatedPackages Description String Package description
Defines whether the package
IncludeRTW Boolean
supports Right to Work

Below is a sample response that Dayforce is expecting from the provider:

{
"ProviderReference": "BS_GENERIC",
"BillingCodes": [
{
"BillingCodeId": "3",
"Name": "Billing Code 3",
"Description": "Billing Code 3 Description"
"AssociatedPackages": [
{
"PackageId": "4",
"Name": "Package 4",
"Description": "Package 4 Description",
"IncludeRTW": true
},
{
"PackageId": "5",
"Name": "Package 5",
"Description": "Package 5 Description",
}

]
}
]
}

Page 26 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
POST Background Screening Packages
POST Background Screening Packages endpoint enables the provider to send a list of packages
to Dayforce. The provider can also send the list of associated billing codes (if any) together.

Note: Packages that aren't part of the request are considered deleted or inactive.

The URL for POST Background Screening Packages uses the following base URL:
https://www.dayforcehcm.com/api/CompanyName/V1/BackgroundScreening/Package

Parameters
ProviderReference parameter type and description
Parameters Type Description
ProviderReference* String Provider unique identifier

Response Objects
Properties, type and descriptions of response objects
Object Name Properties Type Description
PackageId* String Provider package id
Name* String Package name
Description String Package description
Packages Defines whether the pack-
IncludeRTW Boolean age supports Right to
Work
List of associated billing
AssociatedBillingCodes N/A
codes to a package
BillingCodeId* String Provider billing code id
AssociatedBillingCodes Name String Billing code name
Description String Billing code description

Below is a sample response that Dayforce is expecting from the provider:

{
"ProviderReference": "BS_GENERIC",
"Packages": [
{
"PackageId": "1",
"Name": "Package 1",
"Description": "Package 1 Description",
"IncludeRTW": true,

Page 27 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 "AssociatedBillingCodes": [
{
"BillingCodeId": "1",
"Name": "Billing Code 1",
"Description": "Billing Code 1 Description"
},
{
"BillingCodeId": "2",
"Name": "Billing Code 2",
"Description": "Billing Code 2 Description"
}
]
},

"PackageId": "2",
"Name": "Package 2",
"Description": "Package 2 Description",
"AssociatedBillingCodes": [
{
"BillingCodeId": "1",
"Name": "Billing Code 1",
"Description": "Billing Code 1 Description"
},
{
"BillingCodeId": "3",
"Name": "Billing Code 3",
"Description": "Billing Code 3 Description"
}
]
}
]
}

POST Background Screening Provider

Statuses
POST Background Screening Provider Statuses endpoint enables the provider to send
background screening statuses to Dayforce.

Each of the statuses are optional: Order Status, Adjudication Status and Result Status. However,
the provider needs to send at least one status in the request.

The URL for POST Background Screening Provider Statuses uses the following base URL:

Page 28 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
https://www.dayforcehcm.com/api/CompanyName/V1/BackgroundScreening/
ProviderStatuses POST {Background Screening Provider Statuses}

Parameters
Parameters, types, and descriptions of statuses
Parameters Type Description
ProviderReference String Provider unique identifier
OrderStatuses List of strings List of strings of the screening order statuses
AdjudicationStatuses List of strings List of strings of the screening adjudication statuses
ResultStatuses List of strings List of strings of the screening result statuses

Response Objects
Below is a sample response that Dayforce is expecting from the provider:

{
"ProviderReference": "BS_GENERIC",
"OrderStatuses": ["Order Status 1", "Order Status 2"],
"ResultStatuses": ["Result Status 1", "Result Status 2"],
"AdjudicationStatuses": ["Adjudication Status 1", "Adjudication Status 2"]
}

PATCH Candidate Background Screening

Patch Candidate Background Screening to Dayforce. Candidate Background Screening enables
the provider to update the background screening status, URL, Report containing Personal
Identifiable Information (PII) to Dayforce.

The URL for PATCH Candidate Background Screening uses the following base URL:
https://www.dayforcehcm.com/api/CompanyName/V1/BackgroundScreening

Page 29 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Parameters
Object name, properties, type, and description for parameters
Object
Parameters Object Properties Type Description
Name
Dayforce candidate
ScreeningRequestId* N/A N/A String background screening
reference
Partner background
screening link to access
URL N/A N/A String
candidate result or link
towards Partner site.
Candidate background
Status String
Screening screening status
ScreeningStatus Status Candidate background
object AdjudicationStatus String screening adjudication
status
DateOfBirth String Candidate date of birth
Candidate security num-
SocialSecurityNumber String
Candidate ber
CandidatePII
PII object Candidate social insur-
SocialInsuranceNumber String
ance number
DriverLicense String Candidate driver license

Below is a sample response that Dayforce is expecting from the provider:

{
"ScreeningRequestId": "398741C26EF646E58C85AF9033BC7960",
"Url": "http://www.example.com/?id=1bf0969a-3f08-499d-b64f-c6a0348baa32",
"ScreeningStatus": {
"Status": "Complete",
"AdjudicationStatus": "Done"
},
"CandidatePII": {
"DateOfBirth": "1990-04-20",
"SocialSecurityNumber": "351762213",
"SocialInsuranceNumber": "111111",
"DriverLicense": "RV046216"
}
}

Page 30 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
PATCH Candidate Background Screening
Right to Work
Patch Candidate Background Screening Right to Work to Dayforce. Candidate work rights status
is displayed on the candidate grid in the Indicators field.

The URL for PATCH Candidate Background Screening uses the following base URL:
https://www.dayforcehcm.com/api/CompanyName/V1/BackgroundScreening/CandidateR
ightToWorkResults

Parameters
Object name, properties, type, and description for parameters
Parameters Subparameters Type Description
Dayforce candidate
ScreeningRequestId* N/A String background screen-
ing reference ID
The candidate right
to work results. See
CandidateRightToWorkResults See next table N/A
next table for para-
meters.

CandidateRightToWorkResults Parameters
Object name, properties, type and description for parameters for CandidateRightToWorkResults
CandidateRightToWorkRes
Subparameters Subparameters Type Description
ults Parameters
The candidate
CandidateRightToWorkRe
Int right to work res-
sultId
ult identifier
The right to work
status. One of:
WorkRightStatus String “UNLIMITED”,
“LIMITED” or
“NONE”
The status of the
process. For
Status String
example,
"Pending.

Page 31 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Object name, properties, type and description for parameters for CandidateRightToWorkResults
CandidateRightToWorkRes
Subparameters Subparameters Type Description
ults Parameters
The date the right
DateTi-
DateIssued to work request
me
was issued
The partner iden-
PartnerIdentifier Int tifier for the can-
didate
The date the right
DateTi-
DateCompleted to work process
me
was completed
The effective start
DateTi-
WorkRightEffectiveStart date of the right to
me
work.
The effective end
DateTi-
WorkRightEffectiveEnd date of the right to
me
work.
Rejec- The rejection or
tionOrCancellationReasons cancellation reas-
ons
The reason code
ReasonCode String for rejec-
tion/cancellation
The reason
ReasonDe- description for
String
scription rejec-
tion/cancellation
Documents
CandidateRTW The unique iden-
Int
DocumentId tifier
The document
DocumentName String
name
Docu- The document
String
mentExtension extension
The date the
DateTi- document was
DateAdded
me added or
uploaded

Page 32 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Object name, properties, type and description for parameters for CandidateRightToWorkResults
CandidateRightToWorkRes
Subparameters Subparameters Type Description
ults Parameters
The expiry date of
DateTi-
DateExpire the document if
me
any.
The type of doc-
Type String ument e.g.
“PASSPORT”
The pathway code
PathwayCode String (not applicable for
every provider)
CountryCode String The country code
The documents’
Sources
source
If the document is
a single doc-
SingleDocu-
String ument, then the
mentBase64
base64 is
provided here.
If the document is
a front-page
document, then
Docu- the base64 is
String
mentFrontBase64 provided here. For
example, the front
page of a
passport.
If the document is
a back-page
document, then
Docu- the base64 is
String
mentBackBase64 provided here. For
example, the back
page of a
passport.
The document
Details
details
The name of the
document detail.
Name String For example,
"Passport
Number".

Page 33 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Object name, properties, type and description for parameters for CandidateRightToWorkResults
CandidateRightToWorkRes
Subparameters Subparameters Type Description
ults Parameters
The value of the
Value String
document detail
The document
DocumentErrors
errors
Code String The error code
The message of
Message String the document
error

Below is a sample response that Dayforce is expecting from the provider:

{
"ScreeningRequestId": "2BED0FA964C747B4B69B4E42C646E254",
"CandidateRightToWorkResults": {
"WorkRightStatus": "UNLIMITED",
"Status": "DONE",
"DateIssued": "2023-04-28T13:22:58.740Z",
"PartnerIdentifier": 12,
"DateCompleted": "2023-04-28T13:22:58.740Z",
"WorkRightEffectiveStart": "2023-04-28T13:22:58.740Z",
"WorkRightEffectiveEnd": null,
"RejectionOrCancellationReasons": null,
"Documents": [
{
"CandidateRTWDocumentId": 9,
"DocumentName": "PASSPORT_FRONT",
"DocumentExtension": "jpg",
"DateAdded": "2023-03-15T13:22:58.740Z",
"DateExpire": "2024-03-15T13:22:58.740Z",
"Type": "PASSPORT",
"PathwayCode": "PASSPORT_UK_CITIZEN",
"CountryCode": "CAN",
"Sources": {
"SingleDocumentBase64": "",
"DocumentFrontBase64": "INSERT_BASE64_HERE",
"DocumentBackBase64": ""
},
"Details": [
{
"Name": "Passport Number",
"Value": "223321234"
},
{
"Name": "Other",
"Value": "example"

Page 34 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 }
],
"DocumentErrors": null
},
{
"CandidateRTWDocumentId": 10,
"DocumentName": "PASSPORT_BACK",
"DocumentExtension": "jpg",
"DateAdded": "2023-03-15T13:22:58.740Z",
"DateExpire": "2024-03-15T13:22:58.740Z",
"Type": "PASSPORT",
"PathwayCode": "PASSPORT_UK_CITIZEN",
"CountryCode": "CAN",
"Sources": {
"SingleDocumentBase64": "",
"DocumentFrontBase64": "",
"DocumentBackBase64": "INSERT_BASE64_HERE"
},
"Details": [
{
"Name": "SSN",
"Value": "223321234"
},
{
"Name": "TRV",
"Value": "example"
}
],
"DocumentErrors": null
}
]
}
}

PATCH Candidate Background Screening

Personal Identifiable Information
Patch Candidate Background Screening Personal Identifiable Information (PII) to Dayforce. It
enables the provider to update the candidate PII to Dayforce.

The URL for PATCH Candidate Background Screening Personal Identifiable Information uses the
following base URL:
https://www.dayforcehcm.com/api/CompanyName/V1/BackgroundScreening/PersonalId
entifiableInformation

Page 35 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Parameters
Object name, properties, type and description for parameters
Parameters Object Name Object Properties Type Description
Dayforce candidate
ScreeningRequestId* N/A N/A String background screen-
ing reference
DateOfBirth String Candidate date of birth
Candidate social secur-
SocialSecurityNumber String
ity number
CandidatePII
CandidatePII* Candidate social insur-
object SocialInsuranceNumber String
ance number
Candidate driver
DriverLicense String
license

Below is a sample response that Dayforce is expecting from the provider:

{
"ScreeningRequestId": "C45E625A85DA437BBDDB23FA25B46D4E",
"CandidatePII": {
"DateOfBirth": "1990-04-20",
"SocialSecurityNumber": "351762213",
"SocialInsuranceNumber": "111111",
"DriverLicense": "RV046216"
}
}

PATCH Candidate Background Screening

Adjudication Status
Patch Candidate Background Screening Adjudication Status to Dayforce. Candidate Background
Screening Adjudication Status is displayed on the candidate grid as part of the Screening Order
Field. It is displayed side by side with the Background Screening Status.

The URL for PATCHCandidate Background Screening Adjudication Status uses the following base
URL:
https://www.dayforcehcm.com/api/CompanyName/V1/BackgroundScreening/Adjudicati
onStatus

Page 36 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Parameters
This endpoint is used to post candidate background screening adjudication status to Dayforce
when there is an update with regards to the background screening adjudication status

Type and description for parameters

Parameters Type Description
ScreeningRequestId* String Dayforce candidate background screening reference
AdjudicationStatus* String Candidate background screening adjudication status

Below is a sample response that Dayforce is expecting from the provider:

{
"ScreeningRequestId": "C45E625A85DA437BBDDB23FA25B46D4E",
"AdjudicationStatus": "Processing"
}

PATCH Candidate Background Screening

Status
Patch Candidate Background Screening Status to Dayforce. Candidate Background Screening
Status is displayed on the candidate grid as part of the Screening Order Field.

The URL for PATCH Candidate Background Screening Status uses the following base URL:
https://www.dayforcehcm.com/api/CompanyName/V1/BackgroundScreening/Status

Parameters
This endpoint is used to post candidate background screening status to Dayforce when there is
an update with regards to the background screening status order.

Type and description of parameters

Parameters Type Description
ScreeningRequestId* String Dayforce candidate background screening reference
ScreeningStatus* String Candidate background screening order status

Below is a sample response that Dayforce is expecting from the provider:

Page 37 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
{
"ScreeningRequestId": "C45E625A85DA437BBDDB23FA25B46D4E",
"ScreeningStatus": "Completed"
}

Background Screening Data Models

The following is a list of all background screening models:

POST Model

This is the main model that will be sent to a background screening provider.

POST model parameters

Parameters Type Description
Screening Reference ID – An identifier to
ScreeningReferenceId String facilitate linking candidates back to entities
in your own system. It will be unique.
String (yyyy-MM-
ScreeningRequestedDate Screening Requested Date.
ddTHH:mm:ss.fffZ)
OrderDetails OrderDetails Model Information around Order Details.
CandidatePersonal
CandidatePersonal Information around Candidate.
Model
CandidateProfile Information around Candidate Education
CandidateProfile
Model history, Work history, Reference.
Information around job requisition being
JobRequisition JobRequisitionModel
applied.

The OrderDetails, CandidatePersonal, CandidateProfile, and JobRequisition models are detailed

in the next section.

OrderDetails Model

This model contains the Package Id, Billing Code, and Recruiter Email. All information is with
regards to the screening order.

OrderDetails model parameters

Parameters Type Description
PackageId String Provider Package ID
BillingCode String Provider Billing Code
RecruiterEmail String Recruiter Email Address

Page 38 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
CandidatePersonal Model

This model contains information related to the candidate personal information.

CandidatePersonal model parameters

Parameters Type Description
CandidateId Number Unique Identifier for Candidate
FirstName String Candidate First Name
LastName String Candidate Last Name
MiddleName String Candidate Middle Name
Boolean value to indicate if there is a middle
ConfirmedNoMiddleName Boolean
name.
PreferredGivenName String Candidate Preferred Given Name / Alias
Email* String Candidate Email
Phone String Candidate Phone Number
PostalAddress
PostalAddress Candidate Postal Address
Model

PostalAddress Model

This is a sub-model of the CandidatePersonal model. It contains information related to the

candidate address.

PostAddress model parameters

Parameters Type
Address1 String
Address2 String
Address3 String
City String
StateCode String
PostalCode String
CountryCode String

CandidateProfile Model

This model contains information related to the Education History, Employment History, and
References of the candidate.

Page 39 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
CandidateProfile model parameters
Parameters Type Description
List of CandidateEducationHistory Candidate Education History Inform-
EducationHistory
model ation
List of Can- Candidate Employment History
EmploymentHistory
didateEmploymentHistory model Information
References List of CandidateReferences model Candidate References Information

CandidateEducationHistory Model

This model forms the list of objects in the EducationHistory model. It contains information about
the education history of the candidate.

CandidateEducationHistory model parameters

Parameters Type
EducationHistoryId Number
SchoolName String
SchoolType String
StartDate String (YYYY-MM-DD)
EndDate String (YYYY-MM-DD)
Degree Degree Model
SchoolLocation SchoolLocation Model

Degree Model

This is a sub-model of CandidateEducationHistory model. It contains information specific to the

degree.

Degree model parameters

Parameters Type
DegreeName String
Major String
DegreeCompleted Boolean
GraduationDate String (YYYY-MM-DD)
Comments String

SchoolLocation Model

This is a sub-model of CandidateEducationHistory model. It contains information specific to the

school location.

Page 40 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
SchoolLocation model parameters
Parameters Type
City String
State String
Country String
PostalCode String

CandidateEmploymentHistory Model

This model forms the list of objects in the EmploymentHistory model. It contains information about
the education history of the candidate.

CandidateEmploymentHistory model parameters

Parameters Type
EmploymentHistoryId Number
Employername String
CurrentEmployer Boolean
JobTitle String
Department String
StartDate String (YYYY-MM-DD)
EndDate String (YYYY-MM-DD)
Salary String
Location Location Model

Location Model

This is a sub-model of CandidateEmploymentHistory model. It contains information specific to the

Employment location.

Location model parameters

Parameters Type
City String
State String
Country String
PostalCode String

CandidateReferences Model

This model forms the list of objects in the References model. It contains information about the
candidate references.

Page 41 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
CandidateReference model parameters
Parameters Type
ReferenceId Number
FirstName String
LastName String
MiddleName String
PositionTitle String
Relationship String
ReferenceEmail String
BusinessPhone String
MobilePhone String

JobRequisition Model

This model contains information related to the job requisition being applied by candidate.

JobRequisition model parameters

Parameters Type Description
JobRequisitionId Number Job Requisition ID
JobRequisitionTitle String Job Requisition Title
JobLocation String Job Location
DepartmentName String Job Department Name
DepartmentName String Job Requisition Hiring Manager
Recruiter String Job Requisition Recruiter

Response Body Schema Description

Required*

Response parameters and descriptions

Parameters Type Description
ScreeningRequestId Dayforce candidate background screening reference
id* Provider candidate background screening reference
Link Candidate Background screening URL link
Errors List of Errors (if Any)
Code Status of the request
Message Status of the request

Page 42 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Below is a sample response that Dayforce is expecting back from the provider after the POST call.
Note that Id is the background screening provider’s unique identifier of the screening request
order.

{
"ScreeningRequestId”: "F7145A1047FD44C1A0CBADEF89C99C22",
"Id": "123",
"Link": "http://sample-background-screening-url.com"

Below is a sample request that Dayforce send to Provider:

{
"ScreeningReferenceId": "F7145A1047FD44C1A0CBADEF89C99C22",
"ScreeningRequestedDate": "2020-09-01T11:27:41.216Z",
"OrderDetails": {
"PackageId": "Package1",
"BillingCode": "BillCode1",
"RecruiterEmail": "[email protected]"
},
"CandidatePersonal": {
"CandidateId": 10001,
"FirstName": "CandidateFirstName",
"LastName": " CandidateLastName ",
"ConfirmedNoMiddleName": true,
"PreferredGivenName": "CandidatePreferreGivenName",
"Email": "[email protected]",
"Phone": "123456789",
"PostalAddress": {
"Address1": "Address1",
"Address2": "Address2",
"Address3": "Address3",
"City": "City",
"PostalCode": "123456"
}
},
"CandidateProfile": {
"EducationHistory": [
{
"EducationHistoryId": 20001,
"SchoolName": "CandidateSchoolName",
"StartDate": "2020-01-01",
"EndDate": "2020-07-01",
"Degree": {
"DegreeName": "Bachelor's",
"Major": "Accounting",

Page 43 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 "DegreeCompleted": true
},
"SchoolLocation": {
"City": "CandidateSchoolCity",
"State": " CandidateSchoolState",
"Country": " CandidateSchoolCountry"
}
}
],
"EmploymentHistory": [
{
"EmploymentHistoryId": 20002,
"EmployerName": "CandidateEmployerName",
"CurrentEmployer": false,
"Department": "CandidateDepartment",
"JobTitle": "CandidateJobTitle",
"StartDate": "2020-01-01",
"EndDate": "2020-07-01",
"Salary": "15000.00000",
"Location": {
"City": "CandidateEmployerCity",
"Country": "CandidateEmploymentCountry"
}
}
],
"References": [
{
"ReferenceId": 20003,
"FirstName": "CandidateReferenceFirstName",
"LastName": " CandidateReferenceLastName",
"ReferenceEmail": "[email protected]",
"BusinessPhone": "1234567899",
"MobilePhone": "9854245256"
}
]
},
"JobRequisition": {
"JobRequisitionId": 30001,
"JobRequisitionTitle": "JobRequisitionTilte",
"JobLocation": "JobLocation",
"DepartmentName": "DepartmentName",
"HiringManager": "HiringManagerFirstName HiringManagerLastName",
"Recruiter": "RecruiterFirstName RecruiterLastName"
}
}

Page 44 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
REST Services for Retrieving Employee
Information

The following topics describe the foundational concepts and methods for retrieving employee
information using RESTful Web Services:
l URL Endpoint (see page 45)
l Employee API Proxy Class (see page 45)
l Use Specific Criteria to Retrieve Employee XRefCodes (see page 46)
l Retrieve Details for Individual Employees (see page 48)

URL Endpoint
The base URL for the Employees API is as follows, replacing <clientName> with your
organization’s name:

https://www.dayforcehcm.com/api/<clientName>/v1/Employees

Employee API Proxy Class

In the Sample application, there is a class named EmployeesApi. This class is a proxy class
provided to act as a façade on top of the REST layer. Using this class is optional. Note that the
examples in this topic provide the pure raw REST request and response details, but the sample
code uses the EmployeesApi class.

In your application, you’ll want to instantiate the EmployeesApi class using either the root URL
or the target redirect URL embedded in a URI object. The following sample code demonstrates
instantiating the EmployeesApi class:

Page 45 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Use Specific Criteria to Retrieve Employee
XRefCodes
To perform a query for one or more employees, you’ll need to pass a collection of query string
parameters which indicate the criteria for which employees must meet. As an example, here’s
what a request would look like to retrieve employees who have been updated in January of 2017.
https://www.dayforcehcm.com/api/
<clientName>/v1/Employees?UpdateStartDate=2017-01-01&UpdateEndDate=2017-01-31

The complete list of query string parameters that can be used to filter the list of employees are
listed in the following table:

Query string parameters to filter employees

Query String Description
The context date specifies the version of the employee data that
ContextDate
should be returned. Employees change over time, and this property is
used to retrieve employee data as of a particular date. If you don't spe-
cify a date, this value defaults to the current date.
EmployeeNumber Specify an employee number to limit the result to one employee.
EmployeeXRefCode Specify an employee XRefCode to limit the result to one employee.
EmploymentStatusXRe
fCode
Filter by employment status groups of Active, Inactive, or Terminated.

FilterHireEndDate Specify to return employees hired on or before the date provided.

FilterHireStartDate
Specify to return all returned employees hired on or after the date
provided.

Page 46 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Query string parameters to filter employees
Query String Description
FilterTerminationEn Specify to return employees terminated on or before the date
dDate provided.
FilterTerminationSt
artDate
Specify to return employees terminated on or after the date provided.

OrgUnitXRefCode Filter by organization XRefCode.

FilterUpdatedEndDat
e
Specify to return employees updated on or before the date provided.

FilterUpdatedStartD
ate
Specify to return employees updated on or after the date provided.

Specify to return employees updated within the range defined by the

filterUpdatedStartDate and filterUpdatedEndDate
parameters by specific employee entities. This parameter allows
comma-separated values of employee entity names. For example:
filterUpdatedEntiti filterUpdatedEntities=EmploymentStatuses,WorkAssignment
es s,Addresses,Contacts

It requires a
filterUpdatedStartDate/filterUpdatedEndDate range to
be provided, otherwise it's ignored and all relevant employee entities
are searched.

Note: For this sample to display the employee name properties, the default role of the
authenticating user account must have the Employee Personal Information access authorization
to read the data. In addition, the field-level filtering configuration must be set up.

The response will include the XRefCode of employees that match the filter criteria, as illustrated
here:
{
"Data":[
{
"XRefCode":"7734"
},
{
"XRefCode":"8089"
},
{
"XRefCode":"84003"
}
]
}

Page 47 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Sample Code for Retrieving Employee
XRefCodes
The following sample code shows how to query for employees that started after a given date. This
sample uses the EmployeesApi class that was previously instantiated:

In this sample, a request is constructed using the EmployeesGetRequest class, which is

provided in the Sample applications. The request is submitted to the EmployeesGet method of
the EmployeesApi.

The response object is an ApiResponse. As a best practice, you should check the
HttpStatusCode property of the response to ensure that it was a success. For more
information, see Check for Errors on page 200.

Once you confirm that the request was successful, you can access the Payload property. In this
case, the Payload property contains a list of employees that you can view. The sample application
serializes the list of employees to the console window.

Retrieve Details for Individual Employees

Once you have an understanding of how to query for a list of employees, and after you have a list
of employee XRefCodes, you can retrieve data for each of those employees. The URL for this
type of request specifies the Employee XRefCode as the last segment of the query string path.
Here is an example:
https://www.dayforcehcm.com/api/[clientName]/v1/Employees/[XRefCode]

Page 48 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
The response from this request will be high level information about the employee. Here is an
example response:
{
"Data":{
"BioExempt":false,
"BirthDate":"2017-01-02T00:00:00",
"Culture":{
"XRefCode":"en-US",
"ShortName":"English (US)",
"LongName":"English (US)"
},
"Gender":"M",
"HireDate":"2017-02-02T00:00:00",
"HomePhone":"111 222 3456",
"OriginalHireDate":"2017-02-02T00:00:00",
"PhotoExempt":false,
"RequiresExitInterview":false,
"SocialSecurityNumber":"111221234",
"StartDate":"2017-02-02T00:00:00",
"FirstTimeAccessEmailSentCount":0,
"FirstTimeAccessVerificationAttempts":0,
"SendFirstTimeAccessEmail":false,
"PreStartDate":"2017-01-27T00:00:00",
"PayrollKey":"ICP_Key",
"LoginId":"first.lastl",
"XRefCode":"abc123",
"DisplayName":"First Middle Last",
"FirstName":"First",
"LastName":"Last"
}
}

Retrieve a Specific Version of an Employee

To retrieve data about an employee as-of a particular date, you should use the ContextDate
query string parameter. Setting this date will result in data being returned that was effective on the
given date. In the example above, the current date was used to obtain the current version of the
employee. If the context date is not provided, it defaults to the current date.

Requests for Additional Employee Details: Expand Query Strong Parameter

There are two methods you can use to get specific details about employees. The first is to include
the expand query string parameter and provide a comma delimited list of additional properties to
return; for example:
https://www.dayforcehcm.com/api/[clientName]/v1/Employees/
[XRefCode]?expand=Addresses,Contacts,WorkAssignments

Page 49 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
The response will contain the base employee information, but will also include the additional
Addresses, Contacts, and WorkAssignments properties.

The following code sample shows how you would make this request using the EmployeesApi
proxy class. The sample also shows a partial list of properties that can be expanded on the
Employee object. A partial list can also be found in the Constants.cs source file provided in
the Sample application.

Page 50 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Note: Collections such as Addresses or WorkAssignments aren't standard collections. They
are classes which have two properties, a DateInsertBehavior property and an Items

Page 51 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
property. The Items property contains the list. The DateInsertBehavior is used when
submitting requests to indicate how to insert the new record into an existing collection. See the
HrCollection class in the Sample app for the complete definition of a collection.

Requests for Additional Employee Details: Subordinate Endpoints

The second method is to use one of the subordinate endpoints that are available for requesting
employee HR details. The URL for the subordinate calls is constructed as follows:
https://www.dayforcehcm.com/api/[CompanyName]/V1/Employees/[XRefCode]/[entity
name as listed below]

The following entities can be used in the URL endpoint structure above to retrieve employee HR
information:
l Addresses: Retrieve employee address information.
l AuthorizationAssignments: Retrieve employee access authorization information from the
Work > Authorization Assignments screen in People.
l CANFederalTaxes: Retrieve Canadian federal taxes information.
l CANStateTaxes: Retrieve Canadian state taxes information.
l CANTaxStatuses: Retrieve Canadian provincial tax filing status information, such as single
or married.
l ClockDeviceGroups: Retrieve clock device group assignments.
l CompensationSummary: Retrieve historical employee compensation changes.
l Contacts: Retrieve employee contact information.
l Courses: Retrieve employee course assignments.
l DirectDeposits: Retrieve employee direct deposit information.
l DocumentManagementSecurityGroups: Retrieve employee document security groups.
l EIRates: Retrieve employee legal entity and premium rate information.
l EmergencyContacts: Retrieve employee emergency contact information.
l EmployeeManagers: Retrieve employee manager assignments.
l EmployeeProperties: Retrieve employee property information.
l EmployeePayAdjustCodeGroups: Retrieve employee pay adjustment groups inform-
ation.
l EmployeeWorkAssignmentManagers: Retrieve employee direct manager assignments.
l EmploymentAgreements: Retrieve employee employment agreement information.
l EmploymentStatuses: Retrieve employment status information.
l EmploymentTypes: Retrieve employee employment types, such as contractor, pensioner,
or employee.
l Ethnicities: Retrieve employee ethnicity information.
l GLSplit: Retrieve GL split data from the Payroll > GL Splits screen of People.
l HealthWellnessDetails: Retrieve employee health and wellness information.
l HighlyCompensatedEmployees: Retrieve the highly compensated employee indicator.
l HRIncidents: Retrieve employee HR incident details.
l LaborDefaults: Retrieve employee labor default details.
l Locations: Retrieve employee location and authority assignments.

Page 52 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 l MaritalStatuses: Retrieve employee marital status information.
l OnboardingPolicies: Retrieve employee onboarding policy assignments.
l OrgUnitInfos: Retrieve employee organization assignment information.
l PayGradeRates: Retrieve employee pay grade rates related to their position rate policies.
l PerformanceRatings: Retrieve employee performance rating information.
l Roles: Retrieve employee role assignment details.
l Skills: Retrieve employee skill information.
l SSOAccounts: Retrieve employee SSO account assignments.
l TrainingPrograms: Retrieve information about employee training program assignments.
l UnionMemberships: Retrieve employee union membership information.
l UserPayAdjustCodeGroups: Retrieve users' pay adjustment code groups.
l USFederalTaxes: Retrieve employee US federal tax information.
l USStateTaxes: Retrieve employee US state tax information.
l USTaxStatuses: Retrieve US tax status information, such as state filing status single or
married.
l WorkAssignments: Retrieve employee work assignment details.
l WorkContracts: Retrieve employee work contract and associated work pattern inform-
ation.

Most of the subordinate endpoints listed above support the ContextDate,

ContextDateRangeFrom, and ContextDateRangeTo parameters. See REST Services for
Retrieving Employee Information on page 45.
l Courses
l DirectDeposits
l DocumentManagementSecurityGroups
l EmployeePayAdjustCodeGroups
l HRIncidents
l OrgUnitInfos
l PerformanceRatings
l TrainingPrograms
l UserPayAdjustCodeGroups

Page 53 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
REST Services for Updating Employee
Information

The following topics describe the foundational concepts and methods for retrieving employee
information using RESTful Web Services:
l URL Endpoint (see page 54)
l Request to Update an Employee (see page 54)
l Validation of Employee Data (see page 57)

URL Endpoint
The base URL for the Employees API is as follows:
https://www.dayforcehcm.com/api/{clientName}/v1/Employees

Request to Update an Employee

To update an employee, you’ll need to make a request using the HTTP verb PATCH. The URL
indicates the XRefCode of the employee to update and the body of the request is a JSON
serialization of an Employee object. Here is an example:
PATCH https://www.dayforcehcm.com/api/<clientName>/v1/Employees/abc123

Body:
{
"Contacts":{
"Items":[
{
"ContactInformationType":{
"XRefCode":"HomePhone"
},
"ContactNumber":"555-222-3333",
"Country":{
"XRefCode":"USA"
},
"EffectiveStart":"2017-02-24T15:26:28.3146168-06:00",
"IsPreferredContactMethod":true,
"ShowRejectedWarning":true,
"NumberOfVerificationRequests":3
}

Page 54 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 ]
}
}

The EmployeesApi provides a method to update an employee. The request object is

EmployeePatchRequest, in which the Employee property is defined as an Object. This is done
to allow you to provide either an Employee type, or an anonymous type. If you provide an
Employee type, no null valued properties are passed to the REST service. If you provide an
anonymous type for the Employee, then all properties, regardless of value, are passed to the
REST service. The only time you would use the anonymous type is when you need to set all
values to Null.

The following code example uses an Employee object so that no properties will be set to Null:

Page 55 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
If you need to set a property to null, you would use an anonymous type for the Employee property
on the request as shown in the code below:

Page 56 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Making the determination to pass null valued properties based on type provided for the
Employee property is a feature build in the EmployeesApi proxy class. You aren't required to
use this proxy class, but you should have logic in place to control if Null valued properties are
passed to the REST service.

Validation of Employee Data

Employee data is always validated prior to saving it in the Dayforce database. If you have the
need to check if data is valid without saving it, you can include a query string parameter named
isValidateOnly, as illustrated in the following example:
https://www.dayforcehcm.com/api/<clientName>/v1/Employees/abc123?isValidateOn
ly=true

Body:
{
"BirthDate":"1980-02-30"
}

If the request is valid, it will result in an HTTP Status code of 200 (OK). If the request is not valid, it
will result in an HTTP Status code of 400 (Bad Request). In addition, on an invalid request, you’ll
receive ProcessResult messages indicating what is not valid.

POST and PATCH Employee Subordinate

Resources
You can use the POST and PATCH HTTP verbs to add and update employee HR data in Dayforce.
There are a number of subordinate resources that you can use to insert and update employee HR
data in Dayforce. The URL for the subordinate calls is constructed as follows:

https://www.dayforcehcm.com/api/[CompanyName]/V1/Employees/[XRefCode]/
[sub-resource name as listed below]

Page 57 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
The following is the list of sub-resources that can be used in the URL structure above to insert and
update employee HR information:
l Addresses: Insert or update employee address information.
l CANFederalTaxes: Insert or update Canadian federal taxes information.
l CANStateTaxes: Insert or update Canadian provincial taxes information.
l CANTaxStatuses: Insert or update Canadian provincial tax filing status information, such
as single or married.
l ClockDeviceGroups: Insert or update employee clock device group assignments.
l Contacts: Insert or update employee contact information.
l DirectDeposits: Insert or update employee direct deposit information.
l DocumentManagementSecurityGroups: Insert or update employee document security
groups.
l EmergencyContacts: Insert or update employee emergency contact information.
l EmployeePayAdjustCodes
l EmployeeWorkAssignmentManagers: Insert or update employee direct manager assign-
ments.
l EmploymentAgreements: Insert or update employee employment agreement information.
l EmployeeProperties: Insert or update employee property information.
l EmploymentStatuses: Insert or update employment status information.
l Ethnicities: Insert or update employee ethnicity information.
l HealthWellnessDetails: Insert or update employee health and wellness information.
l HighlyCompensatedEmployees: Insert or update the highly compensated employee
indicator.
l Locations: Insert or update employee location and authority assignments.
l MaritalStatuses: Insert or update employee marital status information.
l OnboardingPolicies: Insert or update employee onboarding policy assignments.
l Roles: Insert or update employee role assignment details.
l SSOAccounts: Insert or update employee SSO account assignments.
l UserPayAdjustCodeGroups: Insert or update users' pay adjustment code groups.
l USFederalTaxes: Insert or update employee US general tax information.
l USStateTaxes: Insert or update employee US State tax information.
l USTaxStatuses: Retrieve US tax status information, such as state filing status single or
married.
l WorkAssignments: Insert or update employee work assignment details.
l WorkContracts: Insert or update employee work contract and associated work pattern
information.

ProcessResult Messages
The following is an example of what is generated from the preceding example query - this
message also shows a deserialization error:

Page 58 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
{
"requestId":"f2645d08-358f-4ebd-839d-66537061f3f7",
"processResults":[
{
"code":"SYS_DESERIALIZATION_ERROR",
"context":"employee.BirthDate",
"level":"ERROR",
"message":"Could not convert string to DateTime: 1980-02-30. Path
'BirthDate', line 2, position 26."
}
]
}

The values in the response have the following meaning or purpose:

l requestId: This is a unique ID that can be provided to Dayforce Support if additional
assistance is needed to troubleshoot why the request is not valid.
l processResults: A collection of messages having the following properties:
l code: A code value representing the specific message.

l context: Indicates the specific property in the request to which the message per-

tains. If this represents an item in a collection, it uses the following format: employ-
ee.collection[n].property
l level: Indicates the level of the message: information, warning, or error.

l message: The actual message text in human readable format.

The following example contains information about business validation rules failing:
{
"requestId":"02119c5d-6618-4144-9646-ac4a4493e808",
"processResults":[
{
"Code":"HR_Employee_EmployeeDataSaveFailure",
"Context":"Employee",
"Level":"ERROR",
"Message":"Failed to Save Employee Data"
},
{
"Code":"HR_Employee_SocialSecurityNumberDuplicate",
"Context":"Employee.SocialSecurityNumber",
"Level":"ERROR",
"Message":"Provided Social Security Number already exists"
}
]
}

Page 59 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
REST Service for Adding Employee
Information

The following topics describe the foundational concepts and methods for adding employee
information using RESTful Web Services:
l URL Endpoint (see page 60)
l Submit a Request to Add an Employee (see page 60)

URL Endpoint
The base URL for the Employees API is as follows:
https://www.dayforcehcm.com/api/{clientName}/v1/Employees

Important: Employees are forever persistent in the Dayforce database. Once an employee has
been added to the Dayforce database, they cannot be removed.

Submit a Request to Add an Employee

Adding an employee is very much like updating an employee but you use the HTTP verb POST
instead of PATCH. In addition, the request body is a more complete representation of an
employee. Validation logic remains the same has updating an employee, and you can force
validation only by using the same isValidateOnly query string parameter. Here is an example:
POST https://www.dayforcehcm.com/api/<clientName>/v1/Employees/abc123

Body:
{
"BioExempt":false,
"BirthDate":"1970-01-01T00:00:00",
"Gender":"M",
"PhotoExempt":true,
"RequiresExitInterview":true,
"SocialSecurityNumber":"999999999",
"FirstTimeAccessEmailSentCount":0,
"FirstTimeAccessVerificationAttempts":0,
"SendFirstTimeAccessEmail":false,
"XRefCode":"Sample760",
"FirstName":"FSample",

Page 60 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 "LastName":"LSample"
}

The EmployeesApi provides a method to add an employee. The request object is of the type
EmployeePostRequest. Unlike using PATCH to update an employee, when you use POST,
there is no concern about null versus missing property values because there is no existing data for
this new employee in the database. The following screenshot shows the code that would be used
to add an employee using the EmployeesApi proxy class. This code is setting the
IsValidateOnly property of the request to true to ensure that you don't add an employee with
sample code.

Page 61 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
RESTful Retrieve Department Data

To retrieve data about departments, the consuming application first queries Dayforce for a list of
unique identifiers (called XRefCodes) for the departments whose data needs to be processed. It
then requests details for those departments in subsequent calls. The consuming application must
make one request for each XRefCode to retrieve the department information.

The following topics contain more information about each of the steps involved in retrieving
department data using Dayforce web services:
l RESTful Get Department XRefCodes (see page 62)
l RESTful Get Department Details (see page 63)

RESTful Get Department XRefCodes

The GET Departments XRefCodes request allows the consuming application to retrieve a list
of XRefCodes for departments. This request returns only a list of XRefCodes and is the first step
in a two-step process that includes a GET Departments By XRefCodes request. See
RESTful Get Department Details on page 63.

Overview
The base URL used to retrieve a list of XRefCodes for departments is:

https://www.dayforcehcm.com/api/[CompanyName]/V1/Departments

This query returns a list of XRefCodes for all of the departments configured in your organization.
You can use these XRefCodes to retrieve more information about the departments using the Get
Departments by XRefCode request. See RESTful Get Department Details on page 63.

Response
This call returns a list of XRefCodes for departments. It is returned in a JSON format.

Available Data
Zero, one, or many XRefCodes. The request doesn't return any departments that don't have
XRefCodes.

Page 62 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Security and Data Returned
No additional access control is applied to the results of this web services call.

RESTful Get Department Details

The consuming application can use the department XRefCodes it has retrieved using the Get
Department XRefCodes request to retrieve further information about departments using a
series of Get Department Detail by XRefCode requests.

The consuming application will need to make one request for each XRefCode. The XRefCode is
added to the base URL as shown here:

https://www.dayforcehcm.com/api/CompanyName/V1/Departments/[XRefCode]

Response
The response of the RESTful Get Department Detail by XRefCode request is returned in
a JSON format. You can see an example of the response on the Dayforce Developer Network.

Security
To retrieve department data, the web service user's primary role must have the HCM Anywhere
> Web Services > Read Data checkbox selected in the Features tab of System Admin >
Roles.

Page 63 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
RESTful Add and Update Departments

The HTTP verbs POST and PATCH are used to process inserts and updates to department
information. Insert and update capabilities support adding new departments to the organization
and updating existing ones.

The following topics contain more information about the POST and PATCH departments endpoints:
l POST Department Data (see page 64)
l PATCH Department Data (see page 65)

POST Department Data

Dayforce RESTful services use the POST verb to create a department.

Overview
Consuming applications can use the POST Department request to create a department record
in Dayforce.

The URL for POST operations uses the following base URL:

https://www.dayforcehcm.com/api/CompanyName/V1/Departments

To create a department, a unique identifier (XRefCode) must be provided. This is done within the
data that is sent for processing (referred to as the request body). The XRefCode must be
generated by the requester and it must be unique. It is the consuming application’s responsibility
to assign a unique identifier (XRefCode) to the department when it's sent in a POST operation.
Dayforce web services will return an error if the XRefCode provided in the request body matches
the value of an existing department record in Dayforce. If this occurs, the consuming application
must determine whether to raise an error (requesting manual intervention) or resubmit the request
using the PATCH verb.

Important: This request writes data into Dayforce. When using this request, be sure that the
consuming application/requester is using the correct Dayforce instance (test or production).
Watch out for inadvertently updating the wrong instance of Dayforce (for example, adding test
data to a production instance).

Parameters
IsValidateOnly (boolean)

Page 64 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 l Used to specify that all of the validations need to be performed without committing any
changes.
l Use this parameter to control whether committing information to your instance of Dayforce
is your responsibility.
l https://www.dayforcehcm.com /ap-
i/CompanyName/V1/Departments?isValidateOnly=true

Request Body
The request body contains the values that need to be inserted. The request body should be
structured so that it can be interpreted by Dayforce web services. Therefore, consuming
applications should use the JSON structure that they retrieve when using the RESTful Get
Department Detail by XRefCode request. See RESTful Get Department Details on page
63.

PATCH Department Data

Dayforce RESTful services use the PATCH verb to update departments.

Overview
The URL for PATCH operations uses the base URL and department XRefCode:
https://www.dayforcehcm.com/api/CompanyName/V1/Departments/[XRefCode]

The XRefCode must be included in the request URL because Dayforce web services assumes
the requester means to update an existing department when PATCH is used. The XRefCode
doesn't need to be included in the request body. If included in the request body, the XRefCode
must match the XRefCode in the request URL.

The request body needs to include the data entities and elements that need to be inserted or
updated only. The request doesn't need to include values for all of the information available in the
department data model.

Additionally, you assume the responsibility for committing data to your instance of Dayforce web
services. If data isn't to be committed (for example, test data in a production instance), you must
send the request using the parameter and value IsValidateOnly=true.

Important: This request modifies existing data in Dayforce. When using this request, be sure that
the consuming application/requester is using the correct instance of Dayforce (for example, Test
or Production). Watch out for inadvertently modifying the wrong Dayforce instance (for example,
test data in a production instance).

Page 65 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Parameters
IsValidateOnly (boolean)
l Used to specify that all of the validations need to be performed without committing any
changes
l Using this parameter to control whether committing information to your instance of Dayforce
is your responsibility.
l The URL syntax is: https://www.day-
forcehcm.com/api/CompanyName/V1/Departments/[XRe-
fCode]?isValidateOnly=true

Request Body
The request body contains the data entities and elements that need to be processed within a
structure that can be interpreted by Dayforce web services. The same JSON structure used to
return data retrieved from Dayforce using the RESTful Get Department Data by XRefCode
request is used for PATCH operations.

Page 66 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
RESTful Add and Update Positions

The HTTP verbs POST and PATCH are used to process inserts and updates to position
information. Insert and update capabilities support adding new positions to the organization
updating existing ones.

The following topics contain more information about the POST and PATCH positions endpoints:
l POST Position Data (see page 67)
l PATCH Position Data (see page 68)

POST Position Data

Dayforce RESTful services use the POST verb to create a position.

Overview
Consuming applications can use the POST Position request to create a position record in
Dayforce.

The URL for POST operations uses the following base URL:

https://www.dayforcehcm.com/api/CompanyName/V1/Positions

To create a position, a unique identifier (XRefCode) must be provided. This is done within the data
that is sent for processing (referred to as the request body). The XRefCode must be generated by
the requester and it must be unique. It is the consuming application’s responsibility to assign a
unique identifier (XRefCode) to the position when it's sent in a POST operation. Dayforce web
services will return an error if the XRefCode provided in the request body matches the value of an
existing position record in Dayforce. If this occurs, the consuming application must determine
whether to raise an error (requesting manual intervention) or resubmit the request using the
PATCH verb.

Important: This request writes data into Dayforce. When using this request, be sure that the
consuming application/requester is using the correct Dayforce instance (test or production).
Watch out for inadvertently updating the wrong instance of Dayforce (for example, adding test
data to a production instance).

Parameters
IsValidateOnly (boolean)

Page 67 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 l Used to specify that all of the validations need to be performed without committing any
changes.
l Use this parameter to control whether committing information to your instance of Dayforce
is your responsibility.
l The URL syntax is: https://www.dayforcehcm.com /ap-
i/CompanyName/V1/Positions?isValidateOnly=true

Request Body
The request body contains the values that need to be inserted. The request body should be
structured so that it can be interpreted by Dayforce web services. Therefore, consuming
applications should use the JSON structure that they retrieve when using the RESTful Get
Position Detail by XRefCode request. See RESTful Get Position Details on page 71.

PATCH Position Data

Dayforce RESTful services use the PATCH verb to update positions.

Overview
The URL for PATCH operations uses the base URL and position XRefCode:
https://www.dayforcehcm.com/api/CompanyName/V1/Positions/[XRefCode]

The XRefCode must be included in the request URL because Dayforce web services assumes
the requester means to update an existing position when PATCH is used. The XRefCode doesn't
need to be included in the request body. If included in the request body, the XRefCode must
match the XRefCode in the request URL.

The request body needs to include the data entities and elements that need to be inserted or
updated only. The request doesn't need to include values for all of the information available in the
position data model.

Additionally, you assume the responsibility for committing data to your instance of Dayforce web
services. If data isn't to be committed (for example, test data in a production instance), you must
send the request using the parameter and value IsValidateOnly=true.

Important: This request modifies existing data in Dayforce. When using this request, be sure that
the consuming application/requester is using the correct instance of Dayforce (for example, Test
or Production). Watch out for inadvertently modifying the wrong Dayforce instance (for example,
test data in a production instance).

Parameters
IsValidateOnly (boolean)

Page 68 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 l Used to specify that all of the validations need to be performed without committing any
changes
l Using this parameter to control whether committing information to your instance of Dayforce
is your responsibility.
l The URL syntax is: https://www.dayforcehcm.com/api/CompanyName/V1/Positions/
[XRefCode]?isValidateOnly=true

Request Body
The request body contains the data entities and elements that need to be processed within a
structure that can be interpreted by Dayforce web services. The same JSON structure used to
return data retrieved from Dayforce using the RESTful Get Position Data by XRefCode
request is used for PATCH operations.

Page 69 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
RESTful Retrieve Position Data

To retrieve data about positions, the consuming application first queries Dayforce for a list of
unique identifiers (called XRefCodes) for the positions whose data needs to be processed. It then
requests details for those positions in subsequent calls. The consuming application must make
one request for each XRefCode to retrieve the position information.

The following topics contain more information about each of the steps involved in retrieving
department data using Dayforce web services:
l RESTful Get Position XRefCodes (see page 70)
l RESTful Get Position Details (see page 71)

RESTful Get Position XRefCodes

The GET Positions XRefCodes request allows the consuming application to retrieve a list of
XRefCodes for positions. This request returns only a list of XRefCodes and is the first step in a
two-step process that includes a GET Positions By XRefCodes request. See RESTful Get
Position Details on page 71.

Overview
The base URL used to retrieve a list of XRefCodes for positions is:

https://www.dayforcehcm.com/api/[CompanyName]/V1/Positions

This query returns a list of XRefCodes for all of the positions configured in your organization. You
can use these XRefCodes to retrieve more information about the positions using the Get
Positions by XRefCode request. See RESTful Get Position Details on page 71.

Response
This call returns a list of XRefCodes for positions. It is returned in a JSON format.

Available Data
Zero, one, or many XRefCodes. The request doesn't return any positions that don't have
XRefCodes.

Page 70 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Security and Data Returned
No additional access control is applied to the results of this web services call.

RESTful Get Position Details

The consuming application can use the position XRefCodes it has retrieved using the Get
Position XRefCodes request to retrieve further information about positions using a series of
Get Position Detail by XRefCode requests.

The consuming application will need to make one request for each XRefCode. The XRefCode is
added to the base URL as shown here:

https://www.dayforcehcm.com/api/CompanyName/V1/Positions/[XRefCode]

The full position history isn't included in the response. Instead, the consuming application can use
the ContextDate parameter to request data as of a specified point in time. See the
ContextDate parameter description below for more information.

Parameters
Consumers can retrieve position details by using combinations of the following common query
parameters:

ContextDate (datetime)
l The ContextDate value is always used as an as-of date in determining which position
data to return.
l The service defaults to the current datetime if the requester doesn't specify a value.
l The datetime value should be expressed as yyyy-mm-ddThh:mm:ss where T is a sep-
arator used between the date and time; for example, 2017-01-01T13:24:56.
l The URL syntax is: https://www.dayforcehcm.com/api/[Com-
panyName]/V1/Positions/[XRefCode]?ContextDate=20170201T14:59:59

Expand (string)
l Dayforce recommends optimizing requests for position details so that only the details from
the required position assignments are included in the results.
l The following is an example of the URL syntax:
https://www.dayforcehcm.com/api/
[CompanyName]/V1/Positions/
[XRefCode]?ContextDate=20170201T14:59:59&expand=PositionAssignments

Page 71 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Response
The response of the RESTful Get Position Detail by XRefCode request is returned in a
JSON format. You can see an example of the response on the Dayforce Developer Network.

Security
To retrieve position data, the web service user's primary role must have the HCM Anywhere >
Web Services > Read Data checkbox selected in the Features tab of System Admin > Roles.

Page 72 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
RESTful Add and Update Jobs

The HTTP verbs POST and PATCH are used to process inserts and updates to job information.
Insert and update capabilities support adding new jobs to the organization and updating existing
ones.

The following topics contain more information about the POST and PATCH jobs endpoints:
l POST Job Data (see page 73)
l PATCH Job Data (see page 74)

POST Job Data

Dayforce RESTful services use the POST verb to create a job.

Overview
Consuming applications can use the POST Jobs request to create a job record in Dayforce.

The URL for POST operations uses the following base URL:

https://www.dayforcehcm.com/api/CompanyName/V1/Jobs

To create a job, a unique identifier (XRefCode) must be provided. This is done within the data that
is sent for processing (referred to as the request body). The XRefCode must be generated by the
requester and it must be unique. It is the consuming application’s responsibility to assign a unique
identifier (XRefCode) to the job when it's sent in a POST operation. Dayforce web services will
return an error if the XRefCode provided in the request body matches the value of an existing job
record in Dayforce. If this occurs, the consuming application must determine whether to raise an
error (requesting manual intervention) or resubmit the request using the PATCH verb.

Important: This request writes data into Dayforce. When using this request, be sure that the
consuming application/requester is using the correct Dayforce instance (test or production).
Watch out for inadvertently updating the wrong instance of Dayforce (for example, adding test
data to a production instance).

Parameters
IsValidateOnly (boolean)
l Used to specify that all of the validations need to be performed without committing any
changes.

Page 73 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 l Use this parameter to control whether committing information to your instance of Dayforce
is your responsibility.
l https://www.dayforcehcm.com /api/CompanyName/V1/Jobs?isValidateOnly=true

Request Body
The request body contains the values that need to be inserted. The request body should be
structured so that it can be interpreted by Dayforce web services. Therefore, consuming
applications should use the JSON structure that they retrieve when using the RESTful Get Job
Detail by XRefCode request. See RESTful Get Job Details on page 77.

PATCH Job Data

Dayforce RESTful services use the PATCH verb to update jobs.

Overview
The URL for PATCH operations uses the base URL and job XRefCode:
https://www.dayforcehcm.com/api/CompanyName/V1/Jobs/[XRefCode]

The XRefCode must be included in the request URL because Dayforce web services assumes
the requester means to update an existing job when PATCH is used. The XRefCode doesn't need
to be included in the request body. If included in the request body, the XRefCode must match the
XRefCode in the request URL.

The request body needs to include the data entities and elements that need to be inserted or
updated only. The request doesn't need to include values for all of the information available in the
job data model.

Additionally, you assume the responsibility for committing data to your instance of Dayforce web
services. If data isn't to be committed (such as test data in a production instance), you must send
the request using the parameter and value IsValidateOnly=true.

Important: This request modifies existing data in Dayforce. When using this request, be sure that
the consuming application/requester is using the correct instance of Dayforce (for example, Test
or Production). Watch out for inadvertently modifying the wrong Dayforce instance (for example,
test data in a production instance).

Parameters
IsValidateOnly (boolean)

Page 74 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 l Used to specify that all of the validations need to be performed without committing any
changes.
l Using this parameter to control whether committing information to your instance of Dayforce
is your responsibility.
l The URL syntax is: https://www.dayforcehcm.com/api/CompanyName/V1/Jobs/[XRe-
fCode]?isValidateOnly=true

Request Body
The request body contains the data entities and elements that need to be processed within a
structure that can be interpreted by Dayforce web services. The same JSON structure used to
return data retrieved from Dayforce using the RESTful Get Job Data by XRefCode request
is used for PATCH operations.

Page 75 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
RESTful Retrieve Job Data

To retrieve data about jobs, the consuming application first queries Dayforce for a list of unique
identifiers (called XRefCodes) for the jobs whose data needs to be processed. It then requests
details for those jobs in subsequent calls. The consuming application must make one request for
each XRefCode to retrieve the job information.

The following topics contain more information about each of the steps involved in retrieving job
data using Dayforce web services:
l RESTful Get Job XRefCodes (see page 76)
l RESTful Get Job Details (see page 77)

RESTful Get Job XRefCodes

The GET Jobs XRefCodes request allows the consuming application to retrieve a list of
XRefCodes for jobs. This request returns only a list of XRefCodes and is the first step in a two-
step process that includes a GET Jobs By XRefCodes request. See RESTful Get Job Details
on page 77.

Overview
The base URL used to retrieve a list of XRefCodes for jobs is:

https://www.dayforcehcm.com/api/[CompanyName]/V1/Jobs

This query returns a list of XRefCodes for all of the jobs configured in your organization. You can
use these XRefCodes to retrieve more information about the jobs using the Get Jobs by
XRefCode request. See RESTful Get Job Details on page 77.

Response
This call returns a list of XRefCodes for jobs. It is returned in a JSON format.

Available Data
Zero, one, or many XRefCodes. The request doesn't return any jobs that don't have XRefCodes.

Page 76 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Security and Data Returned
No additional access control is applied to the results of this web services call.

RESTful Get Job Details

The consuming application can use the job XRefCodes it has retrieved using the Get Job
XRefCodes request to retrieve further information about jobs using a series of Get Job
Detail by XRefCode requests.

The consuming application will need to make one request for each XRefCode. The XRefCode is
added to the base URL as shown here:

https://www.dayforcehcm.com/api/CompanyName/V1/Jobs/[XRefCode]

Response
The response of the RESTful Get Jobs Detail by XRefCode request is returned in a JSON
format. You can see an example of the response on the Dayforce Developer Network.

Security
To retrieve job data, the web service user's primary role must have the HCM Anywhere > Web
Services > Read Data checkbox selected in the Features tab of System Admin > Roles.

Page 77 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
RESTful Retrieve HR Admin Data

You can retrieve data from the following sub-features of HR Admin:

l Contact Information Types
l Status
l Employment Status Reason
l Pay Class
l Pay Type

To retrieve this data, the consuming application first queries Dayforce for a list of unique identifiers
(called XRefCodes) for the records that need to be processed. It then requests details for those
records in subsequent calls. The consuming application must make one request for each
XRefCode to retrieve the data.

The following topics contain more information about each of the steps involved in retrieving HR
Admin records using Dayforce web services:
l RESTful Get HR Admin XRefCodes (see page 78)
l RESTful Get HR Admin Details (see page 79)

RESTful Get HR Admin XRefCodes

The following requests allow the consuming application to retrieve a list of XRefCodes for HR
Admin sub-features:

Requests to retrieve XRefCodes

Request HR Admin Sub-Feature
GET ContactInformationTypes XRefCodes Contact Information Types
GET EmploymentStatuses XRefCodes Status
GET EmploymentStatusReasons XRefCodes Employment Status Reason
GET PayClass XRefCodes Pay Class
GET PayTypes XRefCodes Pay Type

These requests only return a list of XRefCodes. This is the first step in a two-step process that
includes a request for records by XRefCodes. See RESTful Get HR Admin Details on page 79.

Page 78 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Overview
A base URL like the following is used to retrieve a list of XRefCodes for sub-features of HR Admin
(in this example, the base URL is for contact information types):

https://www.dayforcehcm.com/api/
[CompanyName]/V1/ContactInformationTypes

In this example, the query returns a list of XRefCodes for all of the contact information types
configured in your organization. You can use these XRefCodes to retrieve more information about
the contact information types using the Get ContactInformationTypes by XRefCode
request. See RESTful Get HR Admin Details on page 79.

Response
This call returns a list of XRefCodes for the specific HR Admin records. It is returned in a JSON
format.

Available Data
Zero, one, or many XRefCodes. The request doesn't return any records that don't have
XRefCodes.

Security and Data Returned

No additional access control is applied to the results of this web services call.

RESTful Get HR Admin Details

The consuming application can use the XRefCodes it has retrieved for records from sub-features
of HR Admin to retrieve further information about those records using a series of requests.

The consuming application will need to make one request for each XRefCode. The XRefCode is
added to the base URL as shown in the following example for contact information types:
https://www.dayforcehcm.com/api/CompanyName/V1/ContactInformationTypes/
[XRefCode]

Response
The response of this request is returned in a JSON format. You can see an example of the
response on the Dayforce Developer Network.

Page 79 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Security
To retrieve records from sub-features of HR Admin, the web service user's primary role must have
the HCM Anywhere > Web Services > Read Data checkbox selected in the Features tab of
System Admin > Roles.

Page 80 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
REST Services for Retrieving WFM Data

You can query WFM data for a specific employee. You can use RESTful web services to retrieve
the following WFM data: Availability, Schedules, Time Away From Work, Employee Punches, and
Employee Raw Punch Data.

Retrieve Availability Data

You can retrieve the availability data for a specific employee. The URL for this type of request
specifies the Employee XRefCode as part of the query string path, and the filter start date and end
date, as parameters. Here is an example:
https://www.dayforcehcm.com/api/{clientName}/V1/Employees/
{xRefCode}/Availability?filterAvailabilityStartDate=2018-05-
14&filterAvailabilityEndDate=2018-05-17

Query string parameters to filter availability

Parameter Description
The unique identifier (external reference code) of the employee to be
xRefCode (required) retrieved. The value provided must be the exact match for an
employee; otherwise, a bad request (400) error will be returned.
filterAvailabilityStartDate Inclusive period start date to determine which employee availability
(required) data to retrieve. Example: 2017-01-01T00:00:00.
filterAvailabilityEndDate Inclusive period end date to determine which employee availability
(required) data to retrieve. Example: 2017-01-01T00:00:00.

The response from this request will be information about the employee’s availability. Here is an
example response:
{
"Data": [
{
"DateOfRequest": "2018-05-14T00:00:00",
"UnAvailable": true,
"IsDefault": true
},
{
"DateOfRequest": "2018-05-15T00:00:00",
"IsDefault": true,
"StartTime1": "06:30:00",
"EndTime1": "22:00:00"
},
{

Page 81 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 "DateOfRequest": "2018-05-16T00:00:00",
"IsDefault": true,
"StartTime1": "06:30:00",
"EndTime1": "22:00:00"
},
{
"DateOfRequest": "2018-05-17T00:00:00",
"IsDefault": true,
"StartTime1": "06:30:00",
"EndTime1": "22:00:00"
}
]
}

Sample Code – Retrieve Availability Data

The following figure shows the sample code used to retrieve a single employee’s availability:

Retrieve Schedule Data

You can retrieve the schedules (also called Time and Attendance) for a specific employee. The
URL for this type of request specifies the Employee XRefCode as part of the query string path,
and the filter start date, end date, isPosted and expand, as parameters. All parameters are
detailed bellow. Here is an example:
https://www.dayforcehcm.com/api/{clientName}/V1/Employees/
{xRefCode}/Schedules?filterScheduleStartDate=2018-05-
19&filterScheduleEndDate=2018-05-
24&expand=Activities,Breaks,LaborMetrics,Skills

Page 82 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Query string parameters to filter schedules
Parameter Description
The unique identifier (external reference code) of the employee to be
xRefCode (required) retrieved. The value provided must be the exact match for an
employee; otherwise, a bad request (400) error will be returned.
Inclusive period start aligned to the employee business day start date
filterScheduleStartDate
to determine which employee schedule data to retrieve. Example:
(required)
2017-01-01T00:00:00.
Inclusive period end aligned to the employee business day start to
filterScheduleEndDate
determine which employee availability data to retrieve. Example:
(required)
2017-01-01T00:00:00.
A flag to determine whether to display posted schedules. By default it
isPosted
searches for published schedules.
This parameter accepts a comma-separated list of top-level entities
that contain the data elements needed for downstream processing.
expand When this parameter is not used, only data elements from the master
record will be included. See the Dayforce Web Services Introduction
Guide.

The response from this request will be schedule data for the employee. Here is an example
response:
{
"Data": [
{
"TimeStart": "2018-05-22T09:00:00",
"TimeEnd": "2018-05-22T17:00:00",
"NetHours": 7.5,
"DepartmentXRefCode": "26",
"JobXRefCode": "Produce Clerk",
"OrgUnitXRefCode": "Store 32026",
"Published": true,
"Breaks": [
{
"TimeStart": "2018-05-22T11:15:00",
"TimeEnd": "2018-05-22T11:45:00",
"NetHours": 0.5,
"Type": "Meal"
}
],
"Activities": [],
"Skills": [],
"LaborMetrics": []
},
{
"TimeStart": "2018-05-23T09:00:00",

Page 83 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 "TimeEnd": "2018-05-23T17:00:00",
"NetHours": 7.5,
"DepartmentXRefCode": "26",
"JobXRefCode": "Produce Clerk",
"OrgUnitXRefCode": "Store 32026",
"Published": true,
"Breaks": [
{
"TimeStart": "2018-05-23T11:15:00",
"TimeEnd": "2018-05-23T11:45:00",
"NetHours": 0.5,
"Type": "Meal"
}
],
"Activities": [],
"Skills": [],
"LaborMetrics": []
}
]
}

Sample Code – Retrieve Schedule Data

Expanding for more Schedule Details

Page 84 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
In the above example, you can see the usage of the expand parameter, with the full list of the
additional information options. This code will create the expand parameter as a comma separated
string, as can be seen in the example above.

Retrieve Time Away

You can retrieve time away from work (TAFW) requests for a specific employee. The URL for this
type of request specifies the Employee XRefCode as part of the query string path, and the filter
start date, end date and status, as parameters. Here is an example:
https://www.dayforcehcm.com/api/{clientName}/V1/Employees/
{xRefCode}/TimeAwayFromWork?filterTAFWStartDate=2018-05-
01&filterTAFWEndDate=2018-07-01&status=PENDING

Query string parameters to filter time away requests

Parameter Description
The unique identifier (external reference code) of the employee to be
xRefCode (required) retrieved. The value provided must be the exact match for an employee;
otherwise, a bad request (400) error will be returned.
filterTAFWStartDate Inclusive period start date to determine which employee time away from
(required) work data to retrieve. Example: 2017-01-01T13:24:56.
filterTAFWEndDate Inclusive period end date to determine which employee time away from
(required) work data to retrieve. Example: 2017-01-01T13:24:56.
A case-sensitive field containing status for time away from work values.
Examples: [APPROVED, PENDING, CANCELED, DENIED,
status (required)
CANCELPENDING]. These values are defined in the database and can
be overridden by customers.

The response from this request will be information about the employee’s availability. Here is an
example response:
{
"Data": [
{
"TAFWXRefCode": "string",
"DateOfRequest": "2018-01-31T10:58:00",
"TimeStart": "2018-06-06T00:00:00",
"TimeEnd": "2018-06-08T00:00:00",
"NetHours": 16,
"ManagerComment": "",
"EmployeeComment": "Going to Disneyland with the family!",
"ReasonName": "Vacation",
"AllDay": true
"HalfDay": true,
"DailyElapsedHours": 0
}

Page 85 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 ]
}

Sample Code – Retrieve Time Away Data

Retrieve Employee Punches Data

The following function will retrieve a list of employee punch data for all employees within the
specified date range via RESTful web service.
GET
https://www.dayforcehcm.com/api/<clientName>/v1/EmployeePunches?filterTransac
tionTimeEndUtc=2019-01-21&filterTransactionTimeStartUtc=2019-01-
01&EmployeeXRefCode=30896

Page 86 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
{
"Data": [
{
"PunchXRefCode": "#DF_826251",
"EmployeeXRefCode": "30896",
"PunchStatus": "c",
"TimeStart": "2018-12-17T10:15:00",
"TimeEnd": "2018-12-17T15:00:00",
"NetHours": 4.75,
"LocationXRefCode": "3",
"PositionXRefCode": "Womens Assoc.",
"DepartmentXRefCode": "3",
"JobXRefCode": "5",
"BusinessDate": "2018-12-17T00:00:00",
"IsDeleted": false,
"IsOnCall": false,
"FuturePunch": false,
"LastModifiedTimestampUtc": "2019-01-07T15:09:56.057"
},
{
"PunchXRefCode": "#DF_826252",
"EmployeeXRefCode": "30896",
"PunchStatus": "c",
"TimeStart": "2018-12-21T08:30:00",
"TimeEnd": "2018-12-21T15:00:00",
"NetHours": 6,
"LocationXRefCode": "3",
"PositionXRefCode": "Womens Assoc.",
"DepartmentXRefCode": "3",
"JobXRefCode": "5",
"BusinessDate": "2018-12-21T00:00:00",
"IsDeleted": false,
"IsOnCall": false,
"FuturePunch": false,
"LastModifiedTimestampUtc": "2019-01-07T15:09:56.057",
"MealBreaks": [
{
"PunchXRefCode": "#DF_826252",
"Type": "m",
"TimeStart": "2018-12-21T11:30:00",
"TimeEnd": "2018-12-21T12:00:00",
"NetHours": 0.5,
"IsAutoInjected": false,
"LastModifiedTimestampUtc": "2019-01-07T15:09:56.057"
}
]
}
],
"HttpStatusCode": 200

Page 87 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
}

Note: The EmployeePunches Api supports pagination. It returns the response in multiple pages
depending on the size of the payload. In case if you are using your own implementation and call
the EmployeePunches Api endpoint directly, you should always check for the next page of the
response. See Pagination of Response Data on page 197.

Retrieve Employee Raw Punches Data

The following function will retrieve a list of employee raw punch data for all employees within the
specified date range via RESTful web service:
GET
https://www.dayforcehcm.com/api/<clientName>/v1/EmployeeRawPunches?filterTran
sactionTimeEndUtc=2019-01-21&filterTransactionTimeStartUtc=2019-01-01

Query string parameters to filter raw punch requests

Parameter Description
FilterTransactionStartTimeUTC The start time of the period for which to retrieve raw punch
(required) records. Example: 2017-01-01T13:24:56.
FilterTransactionEndTimeUTC The end time of the period for which to retrieve raw punch
(required) records. Example: 2017-01-01T13:24:56.
Reference code associated with the employee whose raw
EmployeeXRefCode
punch data is to be retrieved.
The badge number for the employee whose raw punch data is
EmployeeBadge
to be retrieved.
Reference code for the state of the punch. Accepted values:

PunchState
l ALL
l REJECTED
l PROCESSED

Page 88 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Query string parameters to filter raw punch requests
Parameter Description
The type of punches to be retrieved. Accepted values:
l ANY
l NONE
l PUNCH_IN
l BREAK_OUT
l BREAK_IN
l MEAL_OUT
l MEAL_IN
l PUNCH_OUT
l JOB_TRANSFER
PunchTypes
l DECLARE_TIPS
l DIRECTIONLESS
l SHIFT_OVERRIDE
l LOCATION_TRANSFER
l DOCKET
l PROJECT
l RELAY_CONTROL
l QUANTITY
l COMBINED_TRANSFER
l MEAL_SUBSIDY
l TRANSFER
l LABOR_METRICS_TRANSFER

Response

The response from this request will contain data from employees' raw punches. Here is an
example response:
{
"Data": [
{
"RawPunchXRefCode": "string",
"PunchState": "string",
"PayDate": "2022-11-22T18:46:27.206Z",
"EmployeeXRefCode": "string",
"EmployeeBadge": "string",
"RawPunchTime": "2022-11-22T18:46:27.207Z",
"WasOfflinePunch": true,
"ExtraData": {
"DocketXRefCode": "string",
"ProjectXRefCode": "string",
"PositionXRefCode": "string",
"LocationXRefCode": "string",

Page 89 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 "Quantity": 0,
"MealWaiver": "string",
"BreakAttestation": true,
"BioFailure": true,
"FaceVerificationFailure": true,
"LaborMetrics": [
{
"TypeXRefCode": "string",
"CodeXRefCode": "string",
"TypeClockTransferCode": "string",
"CodeClockTransferCode": "string"
}
],
"DocketClockTransferCode": "string",
"ProjectClockTransferCode": "string",
"PositionClockTransferCode": "string",
"LocationClockTransferCode": "string"
},
"PunchType": "string",
"Comment": "string",
"PunchDevice": "string",
"SupervisorBadge": "string",
"IsDuplicate": true,
"RejectedReason": "string",
"LocationXRefCode": "string",
"PositionXRefCode": "string",
"DepartmentXRefCode": "string",
"JobXRefCode": "string",
"IPAddress": "string",
"PunchOrigin": "string",
"Latitude": 0,
"Longitude": 0,
"Accuracy": 0,
"PunchXRefCode": "string"
}
],

Note: The EmployeeRawPunches API supports pagination. It returns the response in multiple
pages depending on the size of the payload. In case if you are using your own implementation
and call the EmployeeRawPunches API endpoint directly, you should always check for the next
page of the response. See Pagination of Response Data on page 197.

Retrieve Employee Pay Summary Data

The following function will retrieve a list of employee pay summary data for all employees within
the specified date range via RESTful web service:
GET
https://www.dayforcehcm.com/api/<clientName>/v1/EmployeePaySummaries?filterTr
ansactionTimeEndUtc=2020-01-21&filterTransactionTimeStartUtc=2020-01-01

Page 90 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Query string parameters to filter pay summary requests
Parameter Description
filterTransactionStartTimeUTC The start time of the period for which to retrieve pay summary
(required) records. Example: 2017-01-01T13:24:56.
filterTransactionEndTimeUTC The end time of the period for which to retrieve pay summary
(required) records. Example: 2017-01-01T13:24:56.
Reference code associated with the employee whose pay
employeeXRefCode
summary data is to be retrieved.
Reference code for the location of the pay summary to be
locationXRefCode
retrieved.
payGroupXRefCode Reference code of the position to be retrieved.
payCategoryXRefCode Reference code of the pay category to be retrieved

Response

The response from this request will contain data from employees' pay summary. Here is an
example response:
{
"Data": [
{
"EmployeeXRefCode": "string",
"PositionXRefCode": "string",
"DepartmentXRefCode": "string",
"JobXRefCode": "string",
"PayCodeXRefCode": "string",
"PayCategoryXRefCode": "string",
"PayDate": "2020-08-20T13:17:03.822Z",
"BusinessDate": "2020-08-20T13:17:03.822Z",
"TimeStart": "2020-08-20T13:17:03.822Z",
"TimeEnd": "2020-08-20T13:17:03.822Z",
"PunchSegmentStart": "2020-08-20T13:17:03.822Z",
"LocationXRefCode": "string",
"NetHours": 0,
"MinuteDuration": 0,
"Rate": 0,
"PayAmount": 0,
"IsPremium": true,
"ProjectXRefCode": "string",
"DocketXRefCode": "string",
"PieceQuantity": 0,
"LaborMetricsCode0XRefCode": "string",
"LaborMetricsCode1XRefCode": "string",
"LaborMetricsCode2XRefCode": "string",
"LaborMetricsCode3XRefCode": "string",
"LaborMetricsCode4XRefCode": "string",

Page 91 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 "LaborMetricsCode5XRefCode": "string",
"LaborMetricsCode6XRefCode": "string",
"LaborMetricsCode7XRefCode": "string",
"LaborMetricsCode8XRefCode": "string",
"LaborMetricsCode9XRefCode": "string"
}
],
"ProcessResults": [
{
"Code": "string",
"Context": "string",
"Level": "string",
"Message": "string"
}
],
"Paging": {
"Next": "string"
}
}

Retrieve Employee Pay Adjustment Data

The following function will retrieve a list of employee pay adjustment data for all employees within
the specified date range via RESTful web service:
GET
https://www.dayforcehcm.com/api/<clientName>/v1/EmployeePayAdjustments?filter
TransactionTimeEndUtc=2020-01-21&filterTransactionTimeStartUtc=2020-01-01

Query string parameters to filter pay adjustment requests

Parameter Description
filterPayAdjustmentStartDate The start time of the period for which to retrieve employee pay
(required) adjustment data. Example: 2017-01-01T13:24:56.
filterPayAdjustmentEndDate The end time of the period for which to retrieve employee pay
(required) adjustment data. Example: 2017-01-01T13:24:56.
Inclusive start date (in UTC format) of the filter period for
filterLastModifiedStartDateUTC
which pay adjustments were modified.
Inclusive end date (in UTC format) of the filter period for which
filterLastModifiedEndDateUTC
pay adjustments were modified.
orgUnitXRefCode A case-sensitive field that identifies a unique organization.
employeeXRefCode A case-sensitive field that identifies a unique employee.
A case-sensitive field that identifies a unique pay adjustment
payAdjustmentCodeXRefCode
code.

Page 92 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Query string parameters to filter pay adjustment requests
Parameter Description
projectXRefCode A case-sensitive field that identifies a unique project.
departmentXRefCode A case-sensitive field that identifies a unique department.
jobXRefCode A case-sensitive field that identifies a unique job.
docketXRefCode A case-sensitive field that identifies a unique docket.
Inclusive period reference date in UTC to determine which
referenceDate employee pay adjustment data to retrieve. Example: 2017-01-
01T00:00:00.
managerAuthorized A flag to determine if a pay adjustment is manager authorized.
A flag to determine if a pay adjustment is employee author-
employeeAuthorized
ized.
isDeleted A flag to determine if a pay adjustment is deleted.

Response

The response from this request will contain data from employees’ pay adjustments. Here is an
example response:
{
"Data": [
{
"EmployeePayAdjustXRefCode": "string",
"AdjustPeriodStartDate": "2023-02-02T16:27:54.244Z",
"AdjustPeriodEndDate": "2023-02-02T16:27:54.244Z",
"EmployeeXRefCode": "string",
"DepartmentXRefCode": "string",
"JobXRefCode": "string",
"PayAdjustmentCodeXRefCode": "string",
"PayCategoryXRefCode": "string",
"PayDate": "2023-02-02T16:27:54.244Z",
"OrgUnitXRefCode": "string",
"IsPremium": true,
"IsDeleted": true,
"TimeStart": "2023-02-02T16:27:54.244Z",
"TimeEnd": "2023-02-02T16:27:54.244Z",
"Hours": 0,
"Rate": 0,
"Amount": 0,
"ReferenceDate": "2023-02-02T16:27:54.244Z",
"ProjectXRefCode": "string",
"DocketXRefCode": "string",
"EmployeeComment": "string",
"ManagerComment": "string",
"EmployeeAuthorized": true,
"ManagerAuthorized": true,

Page 93 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 "LaborMetrics": [
{
"LaborMetricsTypeXRefCode": "string",
"LaborMetricsCodeXRefCode": "string"
}
],
"LastModifiedTimestampUtc": "2023-02-02T16:27:54.244Z"
}
],
"ProcessResults": [
{
"Code": "string",
"Context": "string",
"Level": "string",
"Message": "string"
}
],
"Paging": {
"Next": "string"
}
}

Note: The EmployeePayAdjustments API supports pagination. It returns the response in multiple
pages depending on the size of the payload. In case if you are using your own implementation
and call the EmployeePayAdjustments API endpoint directly, you should always check for the
next page of the response. See Pagination of Response Data on page 197.

Retrieve Employee Schedule Data

The following function will retrieve a list of employee schedule data for all employees within the
specified date range via RESTful web service:
GET
https://www.dayforcehcm.com/api/<clientName>/v1/EmployeeSchedules?filterTrans
actionTimeEndUtc=2020-01-21&filterTransactionTimeStartUtc=2020-01-01

Query string parameters to filter employee schedule requests

Parameter Description
OrgUnitXRefCode (required) Filter by organization XRefCode.
FilterTransactionStartTimeUTC The start time of the period for which to retrieve employee
(required) schedule records. Example: 2017-01-01T13:24:56.
FilterTransactionEndTimeUTC The end time of the period for which to retrieve employee
(required) schedule records. Example: 2017-01-01T13:24:56.
Reference code associated with the employee whose sched-
EmployeeXRefCode
ule data is to be retrieved.

Page 94 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Query string parameters to filter employee schedule requests
Parameter Description
departmentXRefCode A case-sensitive field that identifies a unique department.
jobXRefCode A case-sensitive field that identifies a unique job.
PositionXRefCode A case-sensitive field that identifies a unique position.
This parameter accepts a comma-separated list of top-level
entities that contain the data elements needed for down-
stream processing. When this parameter is not used, only
Expand
data elements from the master record will be included. See
the Dayforce Web Services Introduction Guide. This para-
meter is optional.

Response

The response from this request will contain data from employees' schedules. Here is an example
response:
{
"Data": [
{
"EmployeeScheduleXRefCode": "string",
"EmployeeXRefCode": "string",
"TimeStart": "2020-08-19T14:15:04.770Z",
"TimeEnd": "2020-08-19T14:15:04.770Z",
"NetHours": 0,
"DepartmentXRefCode": "string",
"JobXRefCode": "string",
"PositionXRefCode": "string",
"OrgUnitXRefCode": "string",
"OrgLocationTypeXRefCode": "string",
"PayAdjCodeXRefCode": "string",
"DocketXRefCode": "string",
"ProjectXRefCode": "string",
"Comment": "string",
"Published": true,
"Breaks": [
{
"TimeStart": "2020-08-19T14:15:04.770Z",
"TimeEnd": "2020-08-19T14:15:04.770Z",
"NetHours": 0,
"Type": "string"
}
],
"Activities": [
{
"TimeStart": "2020-08-19T14:15:04.770Z",
"TimeEnd": "2020-08-19T14:15:04.770Z",

Page 95 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 "XRefCode": "string"
}
],
"Skills": [
{
"SkillXRefCode": "string",
"SkillLevelXRefCode": "string",
"IsMandatory": true
}
],
"LaborMetrics": [
{
"CodeXRefCode": "string",
"TypeXRefCode": "string"
}
]
}
],
"ProcessResults": [
{
"Code": "string",
"Context": "string",
"Level": "string",
"Message": "string"
}
],
"Paging": {
"Next": "string"
}
}

Note: The EmployeeSchedules API supports pagination. It returns the response in multiple pages
depending on the size of the payload. In case if you are using your own implementation and call
the EmployeeSchdedules API endpoint directly, you should always check for the next page of the
response. See Pagination of Response Data on page 197.

Retrieve Employee Payroll Tax Data

The following function will retrieve a list of employee schedule data for all employees within the
specified date range via RESTful web service:
GET
https://www.dayforcehcm.com/api/<clientName>/v1/EmployeePayrollTax?filterTran
sactionTimeEndUtc=2020-01-21&filterTransactionTimeStartUtc=2020-01-01

Page 96 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Query string parameters to filter payroll tax requests
Parameter Description
The unique identifier (external reference code) of the employee whose data will be
XRefCode
retrieved. The value provided must be the exact match for an employee or a bad
(required)
request (400) error will be returned.

Response

The response from this request will contain data from employees' payroll. Here is an example
response:
[
{
"TaxAuthority": "string",
"TaxType": "string",
"Name": {
"TaxName": "string",
"Description": "string"
},
"EmployeeTax": true,
"EmployerTax": true,
"LegalEntity": "string",
"ResidentCode": "string",
"ManuallyAddedTax": true,
"Addresses": [
"string"
],
"TaxAuthorityInstance": "string",
"LegalEntityXrefCode": "string",
"LastModifiedTimestamp": "2020-08-19T14:32:25.204Z"
}
]

Page 97 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
RESTful Retrieve Employee Retro Data

The RESTful GET Employee Pay Summaries Retro operation returns a list containing
employee pay summary retros. The operation uses the following URL:

https://www.dayforcehcm.com/api/CompanyName/V1/EmployeePaySummariesRet
ro

Parameters
Consumers can retrieve retro data by using combinations of the following parameters:

payGroupXRefCode (string)

Pay group reference code value. Use this to retrieve employees who are assigned to a specific
pay group. This parameter is required.

periodStartDate (string)

Inclusive period start date to determine which employee retro data to retrieve.

periodEndDate (string)

Inclusive period end date to determine which employee retro data to retrieve.

payDate (string)

The retro pay date. Use this to retrieve retros that were paid on a specific date.

employeeXRefCode (string)

Employee reference code value. Use this to retrieve specific employees.

locationXRefCode (string)

Location reference code value. Use this to retrieve employees who are assigned to a specific
location.

payCategoryXRefCode (string)

Pay category reference code value. Use this to retrieve employees who have the specific pay
category in their pay summary.

onlyRetros (boolean)

Determines whether the operation retrieves only retro data or all pay summary data.

Page 98 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Response
The response from this request contains data from the referenced retro. Here is an example
response:
{
"Data": [
{
"IsRetro": true,
"EmployeeXRefCode": "string",
"PositionXRefCode": "string",
"DepartmentXRefCode": "string",
"JobXRefCode": "string",
"PayCodeXRefCode": "string",
"PayCategoryXRefCode": "string",
"PayDate": "2023-01-31T17:40:31.996Z",
"BusinessDate": "2023-01-31T17:40:31.996Z",
"TimeStart": "2023-01-31T17:40:31.996Z",
"TimeEnd": "2023-01-31T17:40:31.996Z",
"PunchSegmentStart": "2023-01-31T17:40:31.996Z",
"LocationXRefCode": "string",
"NetHours": 0,
"MinuteDuration": 0,
"Rate": 0,
"PayAmount": 0,
"IsPremium": true,
"ProjectXRefCode": "string",
"DocketXRefCode": "string",
"PieceQuantity": 0,
"LaborMetricsCode0XRefCode": "string",
"LaborMetricsCode1XRefCode": "string",
"LaborMetricsCode2XRefCode": "string",
"LaborMetricsCode3XRefCode": "string",
"LaborMetricsCode4XRefCode": "string",
"LaborMetricsCode5XRefCode": "string",
"LaborMetricsCode6XRefCode": "string",
"LaborMetricsCode7XRefCode": "string",
"LaborMetricsCode8XRefCode": "string",
"LaborMetricsCode9XRefCode": "string"
}
],
"ProcessResults": [
{
"Code": "string",
"Context": "string",
"Level": "string",
"Message": "string"
}
],

Page 99 of 200
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 "Paging": {
"Next": "string"
}
}

Page 100 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
RESTful Add and Update Employee Pay
Adjustment Data

The HTTP verbs POST and PATCH are used to process inserts and updates to employee pay
adjustment information. Insert and update capabilities support adding new pay adjustment
information for an employee and updating pay adjustment information for an existing employee.

The following topics contain more information about the POST and PATCH employee pay
adjustment endpoints:
l POST Employee Pay Adjustments (see page 101)
l PATCH Employee Pay Adjustments Data (see page 103)

POST Employee Pay Adjustments

Dayforce RESTful services use the POST verb to create an instance of the resource. In the case of
the Employee Pay Adjustments resource, POST refers to creating a new pay adjustment.

Endpoint URL
The URL for POST Employee Raw Punches uses the following base URL:

https://www.dayforcehcm.com/api/CompanyName/V1/EmployeePayAdjustments

Important: This request writes data into Dayforce. When using this request, be sure that the
consuming application/requester is using the correct Dayforce instance (for example, Test or
Production). Watch out for inadvertently updating the wrong instance of Dayforce (for example,
inserting test data in a production instance).

Overview
You can insert employee pay adjustment data using the POST Employee Pay Adjustments
endpoint. The following is a list of some of the data entities that can be created using this
endpoint:
l Pay Adjustment Date
l Hours
l Amount
l Department
l Pay Category

Page 101 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 l Docket Data
l Rate
l Pay Date
l Reference Date
l Adjustment Period Start Date
l Adjustment Period End Date

Parameters
IsValidateOnly (boolean)
l Used to specify that all of the validations need to be performed without committing any
changes.
l Use this parameter to control whether committing information to your instance of Dayforce
is your responsibility. See the Important note above.
l The URL syntax is:
https://www.dayforcehcm.com
/api/CompanyName/V1/EmployeePayAdjustments?isValidateOnly=true

Request Body
The request body contains the values that need to be inserted into the available data entities. The
example below shows all of the possible fields in the correct JSON format.
{
"EmployeePayAdjustXRefCode": "string",
"OrgUnitXRefCode": "string",
"EmployeeXRefCode": "string",
"PayAdjustmentCodeXRefCode": "string",
"PayAdjustmentDate": "2020-08-19T16:42:34.710Z",
"Hours": 0,
"Amount": 0,
"JobXRefCode": "string",
"DepartmentXRefCode": "string",
"PayCategoryXRefCode": "string",
"ProjectXRefCode": "string",
"DocketXRefCode": "string",
"IsPremium": true,
"IsDeleted": true,
"Rate": 0,
"PayDate": "2020-08-19T16:42:34.710Z",
"ReferenceDate": "2020-08-19T16:42:34.710Z",
"EmployeeComment": "string",
"ManagerComment": "string",
"ManagerAuthorized": true,
"EmployeeAuthorized": true,

Page 102 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 "AdjustPeriodStartDate": "2020-08-19T16:42:34.710Z",
"AdjustPeriodEndDate": "2020-08-19T16:42:34.710Z",
"LaborMetrics": [
{
"LaborMetricsTypeXRefCode": "string",
"LaborMetricsCodeXRefCode": "string"
}
]
}

PATCH Employee Pay Adjustments Data

Dayforce RESTful services use the PATCH verb to update employee pay adjustments.

Overview
Use the PATCH request to do the following:
l Create an effective-dated subordinate record (LaborMetrics)
l Update an existing pay adjustment for an employee or a currently-effective subordinate
record

The URL for PATCH operations uses the base URL and employee pay adjustments XRefCode:
https://www.dayforcehcm.com/api/CompanyName/V1/EmployeePayAdjustments/
[XRefCode]

The XRefCode must be included in the request URL because Dayforce web services assumes
the requester means to update an existing employee pay adjustment when PATCH is used. The
XRefCode doesn't need to be included in the request body. If included in the request body, the
XRefCode must match the XRefCode in the request URL.

The request body needs to include the data entities and elements that need to be inserted or
updated only. The request doesn't need to include values for all of the information available in the
employee pay adjustments data model.

Additionally, you assume the responsibility for committing data to your instance of Dayforce web
services. If data is not to be committed (for example, test data in a production instance), you must
send the request using the parameter and value IsValidateOnly=true.

Important: This request modifies existing data in Dayforce. When using this request, be sure that
the consuming application/requester is using the correct instance of Dayforce (for example, Test
or Production). Watch out for inadvertently modifying the wrong Dayforce instance (for example,
test data in a production instance).

Page 103 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Parameters
IsValidateOnly (boolean)
l Used to specify that all of the validations need to be performed without committing any
changes
l Use this parameter to control whether committing information to your instance of Dayforce
is your responsibility.
l The URL syntax is: https://www.day-
forcehcm.com/api/CompanyName/V1/EmployeePayAdjustments/[XRe-
fCode]?isValidateOnly=true

Request Body
The request body contains the data entities and elements that need to be processed within a
structure that can be interpreted by Dayforce web services. The same JSON structure used to
return data retrieved from Dayforce using the RESTful Get Employee Pay Adjustments by
XRefCode request is used for PATCH operations.
{
"EmployeePayAdjustXRefCode": "string",
"OrgUnitXRefCode": "string",
"EmployeeXRefCode": "string",
"PayAdjustmentCodeXRefCode": "string",
"PayAdjustmentDate": "2020-11-05T14:24:43.690Z",
"Hours": 0,
"Amount": 0,
"JobXRefCode": "string",
"DepartmentXRefCode": "string",
"PayCategoryXRefCode": "string",
"ProjectXRefCode": "string",
"DocketXRefCode": "string",
"IsPremium": true,
"IsDeleted": true,
"Rate": 0,
"PayDate": "2020-11-05T14:24:43.690Z",
"ReferenceDate": "2020-11-05T14:24:43.690Z",
"EmployeeComment": "string",
"ManagerComment": "string",
"ManagerAuthorized": true,
"EmployeeAuthorized": true,
"AdjustPeriodStartDate": "2020-11-05T14:24:43.690Z",
"AdjustPeriodEndDate": "2020-11-05T14:24:43.690Z",
"LaborMetrics": [
{
"LaborMetricsTypeXRefCode": "string",
"LaborMetricsCodeXRefCode": "string"
}

Page 104 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 ]
}

Page 105 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
RESTful Add and Update Employee
Schedules

The HTTP verbs POST and PATCH are used to process inserts and updates to employee
schedules. Insert and update capabilities support getting adding a new schedule for an employee
and updating a schedule for an existing employee.

The following topics contain more information about the POST and PATCH employee schedules
endpoints:
l POST Employee Schedules Data (see page 106)
l PATCH Employee Schedules Data (see page 108)

POST Employee Schedules Data

Dayforce RESTful services use the POST verb to create an instance of the resource. In the case of
the Employee Schedules resource, POST refers to creating a new employee schedule.

Endpoint URL
The URL for POST Employee Schedules uses the following base URL:

https://www.dayforcehcm.com/api/CompanyName/V1/EmployeeSchedules

Important: This request writes data into Dayforce. When using this request, be sure that the
consuming application/requester is using the correct Dayforce instance (for example, Test or
Production). Watch out for inadvertently updating the wrong instance of Dayforce (for example,
inserting test data in a production instance).

Overview
You can insert employee schedule data using the POST Employee Schedules endpoint. The
following is a list of some of the data entities that can be created using this endpoint:
l Start Time
l End Time
l Position
l Docket Data
l Pay Category
l Docket Data

Page 106 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Parameters
OrgUnitXRefCode (string)
l When this parameter is included, all employee schedules in the specified org unit are
returned.
l Multiple levels of the employees’ organization are searched; the search is not limited to
department and location.
l The URL syntax is:
https://www.dayforcehcm.com/api/CompanyName/V1/EmployeeSchedules?OrgUnit
XRefCode=LOC1

IsValidateOnly (boolean)
l Used to specify that all of the validations need to be performed without committing any
changes.
l Use this parameter to control whether committing information to your instance of Dayforce
is your responsibility. See the Important note above.
l The URL syntax is: https://www.dayforcehcm.com /ap-
i/CompanyName/V1/EmployeeSchedules?isValidateOnly=true

Request Body
The request body contains the values that need to be inserted into the available data entities. The
example below shows all of the possible fields in the correct JSON format.

[
{
"EmployeeXRefCode": "string",
"TimeStart": "2020-11-05T14:45:12.128Z",
"TimeEnd": "2020-11-05T14:45:12.128Z",
"PositionXRefCode": "string",
"Breaks": [
{
"TimeStart": "2020-11-05T14:45:12.128Z",
"TimeEnd": "2020-11-05T14:45:12.128Z",
"Type": 1
}
],
"Activities": [
{
"XRefCode": "string",
"TimeStart": "2020-11-05T14:45:12.128Z",
"TimeEnd": "2020-11-05T14:45:12.128Z"
}
],

Page 107 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 "Segments": [
{
"TimeStart": "2020-11-05T14:45:12.128Z",
"TimeEnd": "2020-11-05T14:45:12.128Z",
"PositionXRefCode": "string",
"DocketXRefCode": "string",
"PayAdjCodeXRefCode": "string",
"OrgLocationTypeXRefCode": "string",
"ProjectXRefCode": "string",
"Comment": "string",
"LaborMetrics": [
{
"CodeXRefCode": "string",
"TypeXRefCode": "string"
}
]
}
],
"DocketXRefCode": "string",
"PayAdjCodeXRefCode": "string",
"OrgLocationTypeXRefCode": "string",
"ProjectXRefCode": "string",
"Comment": "string",
"LaborMetrics": [
{
"CodeXRefCode": "string",
"TypeXRefCode": "string"
}
]
}
]

PATCH Employee Schedules Data

Dayforce RESTful services use the PATCH verb to create an instance of the resource. In the case
of the Employee Schedules resource, PATCH refers to creating a new employee schedule.

Endpoint URL
The URL for PATCH Employee Schedules uses the following base URL:

https://www.dayforcehcm.com/api/CompanyName/V1/EmployeeSchedules

Important: This request writes data into Dayforce. When using this request, be sure that the
consuming application/requester is using the correct Dayforce instance (for example, Test or
Production). Watch out for inadvertently updating the wrong instance of Dayforce (for example,
inserting test data in a production instance).

Page 108 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Overview
Use the PATCH request to do the following:
l Create an effective-dated subordinate record (LaborMetrics)
l Update an existing schedule for an employee or a currently-effective subordinate record

The URL for PATCH operations uses the base URL and employee schedules XRefCode:
https://www.dayforcehcm.com/api/CompanyName/V1/EmployeeSchedules

The XRefCode must be included in the request URL because Dayforce web services assumes
the requester means to update an existing employee schedule when PATCH is used.

The request body needs to include the data entities and elements that need to be inserted or
updated only. The request doesn't need to include values for all of the information available in the
employee schedules data model.

Additionally, you assume the responsibility for committing data to your instance of Dayforce web
services. If data is not to be committed (for example, test data in a production instance), you must
send the request using the parameter and value IsValidateOnly=true.

Important: This request modifies existing data in Dayforce. When using this request, be sure that
the consuming application/requester is using the correct instance of Dayforce (for example, Test
or Production). Watch out for inadvertently modifying the wrong Dayforce instance (for example,
test data in a production instance).

Parameters
OrgUnitXRefCode (string)
l When this parameter is included, all employee schedules in the specified org unit are
returned.
l Multiple levels of the employees’ organization are searched; the search is not limited to
department and location.
l The URL syntax is:
https://www.dayforcehcm.com/api/CompanyName/V1/EmployeeSchedules

IsValidateOnly (boolean)
l Used to specify that all of the validations need to be performed without committing any
changes
l Use this parameter to control whether committing information to your instance of Dayforce
is your responsibility.
l The URL syntax is: https://www.day-
forcehcm.com/api/CompanyName/V1/EmployeeSchedules?isValidateOnly=true

Page 109 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Request Body
The request body contains the data entities and elements that need to be processed within a
structure that can be interpreted by Dayforce web services. The same JSON structure used to
return data retrieved from Dayforce using the RESTful Get Employee Schedules request is
used for PATCH operations.

[
{
"EmployeeScheduleXRefCode": "string",
"TimeStart": "2020-11-05T15:05:40.850Z",
"TimeEnd": "2020-11-05T15:05:40.850Z",
"IsDeleted": true,
"EmployeeXRefCode": "string",
"Breaks": [
{
"TimeStart": "2020-11-05T15:05:40.850Z",
"TimeEnd": "2020-11-05T15:05:40.850Z",
"Type": 1
}
],
"Activities": [
{
"XRefCode": "string",
"TimeStart": "2020-11-05T15:05:40.850Z",
"TimeEnd": "2020-11-05T15:05:40.850Z"
}
],
"Segments": [
{
"TimeStart": "2020-11-05T15:05:40.850Z",
"TimeEnd": "2020-11-05T15:05:40.850Z",
"PositionXRefCode": "string",
"DocketXRefCode": "string",
"PayAdjCodeXRefCode": "string",
"OrgLocationTypeXRefCode": "string",
"ProjectXRefCode": "string",
"Comment": "string",
"LaborMetrics": [
{
"CodeXRefCode": "string",
"TypeXRefCode": "string"
}
]
}
],
"PositionXRefCode": "string",
"DocketXRefCode": "string",

Page 110 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 "PayAdjCodeXRefCode": "string",
"OrgLocationTypeXRefCode": "string",
"ProjectXRefCode": "string",
"Comment": "string",
"LaborMetrics": [
{
"CodeXRefCode": "string",
"TypeXRefCode": "string"
}
]
}
]

Page 111 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
RESTful Retrieve Org Unit Data

To retrieve org unit data, the consuming application first queries Dayforce for a list of unique
identifiers (called XRefCodes) for the org units whose data needs to be processed. It then
requests details for those org units in subsequent calls, including child org units. The consuming
application must make one request for each XRefCode to retrieve the org unit information,
including details about child org units.

The following topics contain more information about each of the steps involved in retrieving org
unit data using Dayforce web services:
l RESTful Get Org Unit XRefCodes (see page 112)
l RESTful Get Org Unit Details (see page 113)

RESTful Get Org Unit XRefCodes

The GET OrgUnit XRefCodes request allows the consuming application to retrieve a list of org
unit XRefCodes. This request returns only a list of XRefCodes and is the first step in a two-step
process that includes a GET OrgUnits By XRefCodes request. See RESTful Get Org Unit
Details on page 113.

Overview
The base URL used to retrieve a list of org unit XRefCodes is:

https://www.dayforcehcm.com/api/[CompanyName]/V1/OrgUnits

This query returns a list of XRefCodes for all of the org units in your organization. You can use
these XRefCodes to retrieve more information about the org units using the Get Org Units by
XRefCode request. See RESTful Get Org Unit Details on page 113.

Response
This call returns a list of employee XRefCodes. It is returned in a JSON format, as the following
example illustrates:
{
"Data": [
{
"XRefCode": "Corporate"
},

Page 112 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 {
"XRefCode": "500Operations"
},
{
"XRefCode": "500Packaging"
},
{
"XRefCode": "Shop1"
}
]
}

Available Data
Zero, one, or many XRefCodes. The request doesn't return any org units that don't have
XRefCodes.

Security and Data Returned

No additional access control is applied to the results of this web services call.

RESTful Get Org Unit Details

The consuming application can use the org unit XRefCodes it has retrieved using the Get Org
Unit XRefCodes request to retrieve further information about org units using a series of Get
Org Unit Detail by XRefCode requests.

The consuming application will need to make one request for each XRefCode. The XRefCode is
added to the base URL as shown here:

https://www.dayforcehcm.com/api/CompanyName/V1/OrgUnits/[XRefCode]

The full org unit history isn't included in the response. Instead, the consuming application can use
the ContextDate parameter to request data as of a specified point in time. See the
ContextDate parameter description below for more information.

Parameters
Consumers can retrieve org unit details by using combinations of the following common query
parameters:

ContextDate (datetime)
l The ContextDate value is always used as an as-of date in determining which org unit
data to return.

Page 113 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 l The service defaults to the current datetime if the requester doesn't specify a value.
l The datetime value should be expressed as yyyy-mm-ddThh:mm:ss where T is a sep-
arator used between the date and time; for example, 2017-01-01T13:24:56.
l The URL syntax is: https://www.dayforcehcm.com/api/[Com-
panyName]/V1/OrgUnits/[XRefCode]?ContextDate=20170201T14:59:59

Expand (string)
l Dayforce recommends optimizing org units details requests so that only the details from the
required top-level parent items is included in the results.
l The following is an example of the URL syntax:
https://www.dayforcehcm.com/api/
[CompanyName]/V1/OrgUnits/
[XRefCode]?ContextDate=20170201T14:59:59&expand=OrgUnitLegalEntities,Org
UnitParents

IncludeChildOrgUnits (Boolean)
l If this parameter is set to true, the request retrieves all immediate child org units of the org
unit bring retrieved.
l Child org units include the same expanded entities as specified using the expand para-
meter.
l If this parameter is set to false or not included, then child org units aren't returned.

Response
The response of the RESTful Get Org Unit Detail by XRefCode request is returned in a
JSON format, and the following example illustrates:
{
"Data": {
"OrgLevel": {
"XRefCode": "Site",
"ShortName": "Site",
"LongName": "Site"
},
"OrgUnitLegalEntities": {
"Items": [{
"LegalEntity": {
"XRefCode": "Manufacturing Co. USA ",
"ShortName": "Manufacturing Co. USA ",
"LongName": "Manufacturing Co. USA "
},
"EffectiveStart": "2000-01-01T00:00:00"
}]
},

Page 114 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 "OrgUnitParents": {
"Items": [{
"ParentOrgUnit": {
"ShortName": "District 01",
"LongName": "District 01"
},
"EffectiveStart": "2013-01-01T00:00:00"
}]
},
"ChildOrgUnits": {
"Items": [{
"OrgLevel": {
"XRefCode": "OnSiteDepartment",
"ShortName": "Department",
"LongName": "Department"
},
"OrgUnitLegalEntities": {
"Items": []
},
"OrgUnitParents": {
"Items": [{
"ParentOrgUnit": {
"XRefCode": "Plant4",
"ShortName": "Plant 4",
"LongName": "Plant 4"
},
"EffectiveStart": "2013-01-01T00:00:00"
}]
},
"XRefCode": "Plant48",
"ShortName": "Plant 4 - Assembly 1",
"LongName": "Plant 4 - Assembly 1"
}]
},
"XRefCode": "Plant4",
"ShortName": "Plant 4",
"LongName": "Plant 4"
}
}

Security
To retrieve org unit data, the web service user's primary role must have the HCM Anywhere >
Web Services > Read Data checkbox selected in the Features tab of System Admin > Roles.

Page 115 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
RESTful Add and Update Org Units

The HTTP verbs POST and PATCH are used to process inserts and updates to org unit
information. Insert and update capabilities support adding new org units to the organization
hierarchy and updating existing org units.

The following topics contain more information about the POST and PATCH org units endpoints:
l POST Org Unit Data (see page 116)
l PATCH Org Unit Data (see page 117)

POST Org Unit Data

Dayforce RESTful services use the POST verb to create an org unit.

Overview
Consuming applications can use the POST Org Unit request to create an instance of an org
unit in Dayforce.

The URL for POST operations uses the following base URL:

https://www.dayforcehcm.com/api/CompanyName/V1/OrgUnits

To create an org unit, a unique identifier (XRefCode) must be provided. This is done within the
data that is sent for processing (referred to as the request body). The XRefCode must be
generated by the requester and it must be unique. It is the consuming application’s responsibility
to assign a unique identifier (XRefCode) to the org unit when it's sent in a POST operation.
Dayforce web services will return an error if the XRefCode provided in the request body matches
the value of an existing org unit record in Dayforce. If this occurs, the consuming application must
determine whether to raise an error (requesting manual intervention) or resubmit the request
using the PATCH verb.

Important: This request writes data into Dayforce. When using this request, be sure that the
consuming application/requester is using the correct Dayforce instance (for example, Test or
Production). Watch out for inadvertently updating the wrong instance of Dayforce (for example,
test data in a production instance).

Parameters
IsValidateOnly (boolean)

Page 116 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 l Used to specify that all of the validations need to be performed without committing any
changes.
l Use this parameter to control whether committing information to your instance of Dayforce
is your responsibility. See the Important note above.
l The URL syntax is:
https://www.dayforcehcm.com
/api/CompanyName/V1/OrgUnits?isValidateOnly=true

Request Body
The request body contains the values that need to be inserted into the available data entities. The
request body should be structured so that it can be interpreted by Dayforce web services.
Therefore, consuming applications should use the JSON structure that they retrieve when using
the RESTful Get Org Unit Detail by XRefCode request. See RESTful Get Org Unit
Details on page 113.

PATCH Org Unit Data

Dayforce RESTful services use the PATCH verb to update org units.

Overview
Use the PATCH request to do the following:
l Create a new effective-dated subordinate record (OrgUnitParents, OrgUnitLegalEntities)
l Update an existing org unit or a currently-effective subordinate record

The URL for PATCH operations uses the base URL and org unit XRefCode:
https://www.dayforcehcm.com/api/CompanyName/V1/OrgUnits/[XRefCode]

The XRefCode must be included in the request URL because Dayforce web services assumes
the requester means to update an existing org unit when PATCH is used. The XRefCode doesn't
need to be included in the request body. If included in the request body, the XRefCode must
match the XRefCode in the request URL.

The request body needs to include the data entities and elements that need to be inserted or
updated only. The request doesn't need to include values for all of the information available in the
org unit data model.

Additionally, you assume the responsibility for committing data to your instance of Dayforce web
services. If data isn't to be committed (for example, test data in a production instance), you must
send the request using the parameter and value IsValidateOnly=true.

Page 117 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Important: This request modifies existing data in Dayforce. When using this request, be sure that
the consuming application/requester is using the correct instance of Dayforce (for example, Test
or Production). Watch out for inadvertently modifying the wrong Dayforce instance (for example,
test data in a production instance).

Parameters
IsValidateOnly (boolean)
l Used to specify that all of the validations need to be performed without committing any
changes
l Use this parameter to control whether committing information to your instance of Dayforce
is your responsibility.
l The URL syntax is: https://www.dayforcehcm.com/api/CompanyName/V1/OrgUnits/
[XRefCode]?isValidateOnly=true

Request Body
The request body contains the data entities and elements that need to be processed within a
structure that can be interpreted by Dayforce web services. The same JSON structure used to
return data retrieved from Dayforce using the RESTful Get Org Unit Data by XRefCode
request is used for PATCH operations.

Page 118 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
RESTful Add Employee Availability Data

The HTTP verb POST is used to insert employee availability data. Insert capabilities support
adding new availability information for an employee.

POST Availability
Dayforce RESTful services use the POST verb to create an instance of the resource. In the case of
the Availability resource, POST refers to creating a new availability record for an employee.

Endpoint URL
The URL for POST Availability uses the following base URL:

https://www.dayforcehcm.com/api/CompanyName/V1/
{employeeXRefCode}/EmployeeAvailability

Important: This request writes data into Dayforce. When using this request, be sure that the
consuming application/requester is using the correct Dayforce instance (for example, Test or
Production). Watch out for inadvertently updating the wrong instance of Dayforce (for example,
inserting test data in a production instance).

Parameters
employeeXRefCode (string)

Specify the XRefCode of the employee you want to create an availability record for.

isValidateOnly (boolean)
l Used to specify that all of the validations need to be performed without committing any
changes.
l Use this parameter to control whether committing information to your instance of Dayforce
is your responsibility. See the Important note above.
l The URL syntax is:
https://www.dayforcehcm.com/api/CompanyName/V1/
{employeeXRefCode/EmployeeAvailability?isValidateOnly=true

Page 119 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Request Body
The request body contains the values that need to be inserted into the available data entities. The
example below shows all of the possible fields in the correct JSON format.
{
"IsDefault": true,
"EffectiveStart": "2022-02-24T23:38:41.442Z",
"EffectiveEnd": "2022-02-24T23:38:41.442Z",
"ManagerComments": "string",
"Weeks": [
{
"Days": [
{
"StartTime1": "string",
"EndTime1": "string",
"StartTime2": "string",
"EndTime2": "string",
"IsAvailable": true
}
]
}
]
}

Security
Adding a new availability record requires role access to the HCM Anywhere > Web Services
> Post Employee Availability role feature in the Features tab of System Admin > Roles.

Page 120 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
REST Service for Adding Employee Raw
Punches

The following topics describe the foundational concepts and methods for adding employee raw
punches using RESTful Web Services:
l Endpoint URL (see page 121)
l Request Body (see page 121)
l Fields (see page 122)
l Responses (see page 124)

Endpoint URL
The base URL for the Employee Raw Punches API is as follows:
https://www.dayforcehcm.com/api/{clientName}/v1/EmployeeRawPunches

IsValidateOnly Parameter
This parameter allows for a request to be processed without creating a record. You can use this
parameter for confirming that the request is valid.

To submit such a request, include "IsValidateOnly=true" in the query string of the URL, as in the
following example:
https://<domain>/API/<namespace>/v1/EmployeeRawPunches?IsValidateOnly=true

Request Body
The request body contains the values that need to be inserted into the available data entities. The
example below shows all of the possible fields in the correct JSON format.

Note: A request cannot be submitted with both XRefCode and ClockTransferCode for the
same item (that is, location, position, docket, labor metrics, and project).
{
"EmployeeBadge": "string",
"RawPunchTime": "string",
"PunchType": "string",
"PunchDevice": "string",

Page 121 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 "SupervisorBadge": "string",
"LocationXRefCode": "string",
"LocationClockTransferCode": "string",
"PositionXRefCode": "string",
"PositionClockTransferCode": "string",
"DocketXRefCode": "string",
"DocketClockTransferCode": "string",
"ProjectXRefCode": "string",
"ProjectClockTransferCode": "string",
"LaborMetrics": [
{
"TypeXRefCode": "string",
"CodeXRefCode": "string",
"TypeClockTransferCode": "string",
"CodeClockTransferCode": "string"
}
],
"Quantity": "decimal",
"MealWaiver": "string",
"BreakAttestation": "boolean"
}

Fields
Fields that can be included in a request
Name Data Type Mandatory Description
EmployeeBadge STRING TRUE The badge number of the employee.
The datetime, with UTC offset, of
RawPunchTime STRING TRUE
when the punch occurred.
The type of punch. See the
PunchType STRING TRUE Punch Type section below for a list of
allowed values.
The MAC address of the clock. It must
PunchDevice STRING TRUE be a clock where the device type is
API.
The badge number of the supervisor
SupervisorBadge STRING FALSE punching in on behalf of the
employee.
The reference code for the organ-
LocationXRefCode STRING FALSE
ization.
LocationClockTransferCode STRING FALSE The clock code for the organization.
PositionXRefCode STRING FALSE The reference code for the position.

Page 122 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Fields that can be included in a request
Name Data Type Mandatory Description
PositionClockTransferCode STRING FALSE The clock code for the position.
DocketXRefCode STRING FALSE The reference code for the docket.
DocketClockTransferCode STRING FALSE The clock code for the docket.
DocketQuantity DECIMAL FALSE The quantity for the docket.
ProjectXRefCode STRING FALSE The reference code for the project.
ProjectClockTransferCode STRING FALSE The clock code for the project.
The reference code for the labor met-
TypeXRefCode STRING FALSE
ric type.
The clock code for the labor metric
TypeClockTransferCode STRING FALSE
code.
The reference code for the labor met-
CodeXRefCode STRING FALSE
ric code.
The clock code for the labor metric
CodeClockTransferCode STRING FALSE
code.
Specifies which meal, if any, is being
MealWaiver STRING FALSE waived (0 = None, 1 = First Meal, 2 =
Second Meal).
Specifies whether the employee
BreakAttestation BOOLEAN FALSE
worked through his/her break.

Punch Type Field

Valid punch types

Name Description
Punch_In The start of the employee's shift.
Break_Out The start of the employee's break.
Break_In The end of the employee's break.
Meal_Out The start of the employee's meal.
Meal_In The end of the employee's meal.
Punch_Out The end of the employee's shift.
Can be used for any type of transfer and for multiple transfers (for
Transfer example, docket, project, or combined). This punch type is recommended
for all transfers.
Docket_Transfer Used to transfer dockets and, optionally, quantity.
Quantity Used to change docket quantity without transferring dockets.

Page 123 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Valid punch types
Name Description
Project _Transfer Used to transfer projects.
Combined_Transfer Used for a location and position transfer.
The end of the employee's shift with a meal waiver. To be used when sub-
Meal_Subsidy
mitted MealWaiver.
Labor_Metrics_
Used for labor metric transfer.
Transfer

Responses
The following sections contain details about the responses that can be returned for the POST
Employee Raw Punches request. They are broken down into success responses and error
responses.

Success Responses
Common responses when a request successfully creates a punch
PunchType Level Message
FIRST_NAME LAST_NAME(BADGE_NUMBER) Punched in at
Punch_In Info
TIME AM/PM
FIRST_NAME LAST_NAME(BADGE_NUMBER) Punched out for
Break_Out Info
break at TIME AM/PM
FIRST_NAME LAST_NAME(BADGE_NUMBER) Punched in from
Break_In Info
break at TIME AM/PM
FIRST_NAME LAST_NAME(BADGE_NUMBER) Punched out for
Meal_Out Info
meal at TIME AM/PM
FIRST_NAME LAST_NAME(BADGE_NUMBER) Punched in from
Meal_In Info
meal at TIME AM/PM
FIRST_NAME LAST_NAME(BADGE_NUMBER) Punched out at
Punch_Out Info
TIME AM/PM

Error Responses
There are two types of errors that can be returned:
l An HTTP 400 response is returned when there is an error that prevents the record from
being processed (for example, a mandatory field is missing).
l An HTTP 200 response is returned when the record can be processed but there is a
problem (for example, punch order validation error caused by submitting two punch ins).

Page 124 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
HTTP 400 Responses

HTTP 400 response reasons

Level Code Description
WFM_PUNCH_FIELD_
Error Employee badge is required.
REQUIRED_EMPLOYEE_BADGE
WFM_PUNCH_FIELD_
Error Punch Type is required.
REQUIRED_PUNCH_TYPE
WFM_PUNCH_FIELD_
Error Punch Device is required.
REQUIRED_PUNCH_DEVICE
WFM_PUNCH_FIELD_
Error Raw punch time is required.
REQUIRED_PUNCH_TIME
WFM_PUNCH_FIELD_INVALID_
Error Punch Type is invalid.
PUNCH_TYPE
WFM_PUNCH_FIELDS_ONE_ Invalid specification of transfer code. Transfer must
Error ONLY_REQUIRED _CLOCK_ specify either XRef Code/Reference Code or Clock
CODE_XREF_CODE Code, but not both.
WFM_PUNCH_FIELD_INVALID_
Error Punch Device is invalid. Device Type must be API.
PUNCH_DEVICE
WFM_PUNCH_FIELD_INVALID_
Error Format of raw punch time is invalid.
PUNCH_TIME

HTTP 200 Responses

In the following table, <Value> refers to the value that was submitted in the request.

HTTP 200 response reasons

Level Message
Error Invalid Badge: <value>
Error Format of raw punch time is invalid
Error Punch Type is invalid
Error Punch Device is invalid
Error Invalid location code
Error Invalid position code
Error Invalid project code
Error Invalid docket code
Error Could not convert string to decimal: <value>
Error Invalid labor metrics type code: <value>

Page 125 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
HTTP 200 response reasons
Level Message
Error Invalid labor metrics transfer code: <value>
Error Not a supervisor
Error Unexpected character encountered while parsing value: <value>
Error Invalid labor metrics type code: <value>
Error Invalid labor metrics transfer code: <value>

Page 126 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
RESTful Delete Employee Punches

This DELETE operation deletes a specific employee punch. The operation uses the following URL:
https://www.dayforcehcm.com/api/CompanyName/V1/EmployeePunches

Parameters
Consumers can delete employee punches using the following parameter:

employeePunchXRefCode (string)

The unique identifier (external reference code) of the employee punch that will be deleted. The
value provided must be an exact match, otherwise a bad request (400) error will be returned. This
setting is required.

All data associated with the punch will be deleted, including any tardy pay adjustments, labor
metrics, transfers, meals, and breaks that are linked to the punch.

Page 127 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
RESTful Retrieve Labor Metrics

The consuming application can query Dayforce to retrieve details for specific labor metric codes
and types. You do this by entering specific XRefCodes for labor metric codes and types using one
of the following GET requests:
l RESTful Get Labor Metrics XRefCodes (see page 128)
l RESTful Get Labor Metric Type XRefCodes (see page 129)

RESTful Get Labor Metrics XRefCodes

This GET operation returns the details of a specific labor metric code based on the XRefCode you
enter. The operation uses the following URL:

https://www.dayforcehcm.com/api/CompanyName/V1/LaborMetrics/xRefCode

Parameters
Consumers can retrieve labor metrics data by using the following parameter:

XRefCode (string)

The unique identifier (external reference code) of the labor metric code that will be retrieved. The
value provided must be an exact match, otherwise a bad request (400) error will be returned. This
setting is required.

Response
The response from this request will contain data from the referenced XRefCode. Here is an
example response:
{
"Data": {
"Name": "string",
"Description": "string",
"EffectiveStart": "2022-01-07T17:35:05.182Z",
"EffectiveEnd": "2022-01-07T17:35:05.182Z",
"LaborMetricsCodeXRefCode": "string",
"ClockTransferCode": "string",
"LedgerCode": "string",
"OrgXRefCodes": [
"string"

Page 128 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 ],
"LaborMetricsTypeXRefCode": "string"
},
"ProcessResults": [
{
"Code": "string",
"Context": "string",
"Level": "string",
"Message": "string"
}
]
}

RESTful Get Labor Metric Type XRefCodes

This GET operation returns the details of a specific labor metric type based on the XRefCode you
enter. The operation uses the following URL:

https://www.dayforcehcm.com/api/CompanyName/V1/LaborMetricTypes/xRefCo
de

Parameters
Consumers can retrieve labor metrics data by using the following parameter:

XRefCode (string)

The unique identifier (external reference code) of the labor metric type that will be retrieved. The
value provided must be an exact match, otherwise a bad request (400) error will be returned. This
setting is required.

Response
The response from this request will contain data from the referenced XRefCode. Here is an
example response:
{
"Data": {
"Name": "string",
"Description": "string",
"ClockTransferCode": "string",
"LaborMetricTypeXRefCode": "string"
},
"ProcessResults": [
{
"Code": "string",

Page 129 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 "Context": "string",
"Level": "string",
"Message": "string"
}
]
}

Page 130 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
RESTful Add and Update Labor Metrics

The HTTP verbs POST and PATCH are used to process inserts and updates to labor metrics data.
Insert and update capabilities support adding new labor metrics data for an employee and
updating labor metrics data for an existing employee.

The following topics contain more information about the POST and PATCH endpoints for the
Labor Metrics API:
l POST Labor Metrics (see page 131)
l PATCH Labor Metrics (see page 132)

The following topics contain more information about the POST and PATCH endpoints for the
Labor Metric Types API:
l POST Labor Metric Types (see page 133)
l PATCH Labor Metric Types (see page 134)

POST Labor Metrics

Dayforce RESTful services use the POST verb to create an instance of the resource. In the case of
the Labor Metrics resource, POST refers to creating a new labor metric code.

Endpoint URL
The URL for POST Labor Metrics uses the following base URL:

https://www.dayforcehcm.com/api/CompanyName/V1/LaborMetrics

Important: This request writes data into Dayforce. When using this request, be sure that the
consuming application/requester is using the correct Dayforce instance (for example, Test or
Production). Watch out for inadvertently updating the wrong instance of Dayforce (for example,
inserting test data in a production instance).

Parameters
isValidateOnly (boolean)
l Used to specify that all of the validations need to be performed without committing any
changes.
l Use this parameter to control whether committing information to your instance of Dayforce
is your responsibility. See the Important note above.

Page 131 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 l The URL syntax is:
https://www.dayforcehcm.com/api/CompanyName/V1/LaborMetrics?isValidateOn
ly=true

Request Body
The request body contains the values that need to be inserted into the available data entities. The
example below shows all of the possible fields in the correct JSON format.
{
"ShortName": "string",
"LongName": "string",
"EffectiveFrom": "2022-01-07T18:05:09.164Z",
"EffectiveEnd": "2022-01-07T18:05:09.164Z",
"LaborMetricsCodeXRefCode": "string",
"ClockTransferCode": "string",
"LedgerCode": "string",
"OrgUnitXRefCodes": [
"string"
],
"LaborMetricsTypeXRefCode": "string",
"IsDeleted": true
}

Security
Adding a new labor metric code requires role access to the HCM Anywhere > Web Services
> Patch/Post Labor Metrics Code role feature in the Features tab of System Admin > Roles.

PATCH Labor Metrics

Dayforce RESTful services use the PATCH verb to update labor metric codes.

Overview
You can update labor metrics data using the PATCH Labor Metrics endpoint. The operation uses
the following URL:

https://www.dayforcehcm.com/api/CompanyName/V1/LaborMetrics

Parameters
isValidateOnly (boolean)

Page 132 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 l Used to specify that all of the validations need to be performed without committing any
changes.
l Use this parameter to control whether committing information to your instance of Dayforce
is your responsibility.
l The URL syntax is: https://www.day-
forcehcm.com/api/CompanyName/V1/LaborMetrics?isValidateOnly=true

Request Body
The request body contains the data entities and elements that need to be processed within a
structure that can be interpreted by Dayforce web services. The example below shows all of the
possible fields in the correct JSON format.
{
"ShortName": "string",
"LongName": "string",
"EffectiveFrom": "2022-01-07T18:57:33.897Z",
"EffectiveEnd": "2022-01-07T18:57:33.897Z",
"LaborMetricsCodeXRefCode": "string",
"ClockTransferCode": "string",
"LedgerCode": "string",
"OrgUnitXRefCodes": [
"string"
],
"LaborMetricsTypeXRefCode": "string",
"IsDeleted": true
}

Security
Updating the details of an existing labor metric code requires role access to the HCM Anywhere
> Web Services > Patch/Post Labor Metrics Code role feature in the Features tab of System
Admin > Roles.

POST Labor Metric Types

Dayforce RESTful services use the POST verb to create an instance of the resource. In the case of
the Labor Metric Types resource, POST refers to creating a new labor metric type.

Endpoint URL
The URL for POST Labor Metric Types uses the following base URL:

https://www.dayforcehcm.com/api/CompanyName/V1/LaborMetricTypes

Page 133 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Important: This request writes data into Dayforce. When using this request, be sure that the
consuming application/requester is using the correct Dayforce instance (for example, Test or
Production). Watch out for inadvertently updating the wrong instance of Dayforce (for example,
inserting test data in a production instance).

Parameters
isValidateOnly (boolean)
l Used to specify that all of the validations need to be performed without committing any
changes.
l Use this parameter to control whether committing information to your instance of Dayforce
is your responsibility. See the Important note above.
l The URL syntax is:
https://www.dayforcehcm.com/api/CompanyName/V1/LaborMetricTypes?isValida
teOnly=true

Request Body
The request body contains the values that need to be inserted into the available data entities. The
example below shows all of the possible fields in the correct JSON format.
{
"ShortName": "string",
"LongName": "string",
"LaborMetricTypeXRefCode": "string",
"ClockTransferCode": "string",
"IsDeleted": true
}

Security
Adding a new labor metric type requires role access to the HCM Anywhere > Web Services
> Patch/Post Labor Metrics Type role feature in the Features tab of System Admin > Roles.

PATCH Labor Metric Types

Dayforce RESTful services use the PATCH verb to update labor metric types.

Overview
You can update labor metrics data using the PATCH Labor Metric Types endpoint. The operation
uses the following URL:

Page 134 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
https://www.dayforcehcm.com/api/CompanyName/V1/LaborMetricTypes

Parameters
laborMetricTypeXRefCode (string)

The unique identifier (external reference code) of the labor metric type to be updated. The value
provided must be the exact match for a labor metric type. Otherwise, a bad request (400) error will
be returned.

This parameter is required.

isValidateOnly (boolean)
l Used to specify that all of the validations need to be performed without committing any
changes.
l Use this parameter to control whether committing information to your instance of Dayforce
is your responsibility.
l The URL syntax is: https://www.day-
forcehcm.com/api/CompanyName/V1/LaborMetricTypes?isValidateOnly=true

Request Body
The request body contains the data entities and elements that need to be processed within a
structure that can be interpreted by Dayforce web services. The example below shows all of the
possible fields in the correct JSON format.
{
"ShortName": "string",
"LongName": "string",
"LaborMetricTypeXRefCode": "string",
"ClockTransferCode": "string",
"IsDeleted": true
}

Security
Updating the details of an existing labor metric type requires role access to the HCM Anywhere
> Web Services > Patch/Post Labor Metrics Type role feature in the Features tab of System
Admin > Roles.

Page 135 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
RESTful Retrieve and Delete Legacy
Labor Metrics

The consuming application can query Dayforce to retrieve details for specific legacy labor metrics.
Additionally, the consuming application can query Dayforce to delete specific legacy labor
metrics. You can retrieve and delete this data using the following operations:
l RESTful Get Legacy Labor Metrics (see page 136)
l RESTful Delete Legacy Labor Metrics (see page 137)

RESTful Get Legacy Labor Metrics

This GET operation returns the details of a specific legacy labor metric. The operation uses the
following URL:
https://www.dayforcehcm.com/api/CompanyName/V1/LegacyLaborMetric

Parameters
Consumers can retrieve the data associated with a labor validation rule (and any qualifiers
associated with the rule) using the following parameters:

legacyLaborMetricType (string)

The type of legacy labor metric that will be retrieved, such as project client, project type, project
phase, product group, and product module. This setting is required.

legacyLaborMetricXRefCode (string)

The unique identifier (external reference code) of the legacy labor metric that will be retrieved. The
value provided must be an exact match, otherwise a bad request (400) error will be returned. This
setting is required.

Response
The response is in JSON format as illustrated in the example below:
{
"Data": {
"Name": "string",
"Description": "string",

Page 136 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 "LegacyLaborMetricType": "string",
"LegacyLaborMetricXRefCode": "string"
},
"ProcessResults": [
{
"Code": "string",
"Context": "string",
"Level": "string",
"Message": "string"
}
]
}

Security
Retrieving an existing legacy labor metric requires role access to the following role features in the
Features tab of System Admin > Roles:
l Org Setup
l Labor Metrics

l Legacy Labor Metrics

l HTML Product Group

l HTML Product Module

l HTML Project Client

l HTML Project Phase

l HTML Project Type

RESTful Delete Legacy Labor Metrics

This DELETE operation deletes a specific legacy labor metric. The operation uses the following
URL:
https://www.dayforcehcm.com/api/CompanyName/V1/LegacyLaborMetric

Parameters
Consumers can delete the data associated with a legacy labor metric using the following
parameters:

legacyLaborMetricType (string)

The type of legacy labor metric that will be deleted, such as project client, project type, project
phase, product group, and product module. This setting is required.

legacyLaborMetricXRefCode (string)

Page 137 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
The unique identifier (external reference code) of the legacy labor metric that will be deleted. The
value provided must be an exact match, otherwise a bad request (400) error will be returned. This
setting is required.

Security
Deleting an existing legacy labor metric requires role access to the following role features in the
Features tab of System Admin > Roles:
l HCM Anywhere
l Web Services

l Patch/Post/Delete Legacy Labor Metric

l Org Setup
l Labor Metrics

l Legacy Labor Metrics

l HTML Product Group

l HTML Product Module

l HTML Project Client

l HTML Project Phase

l HTML Project Type

Page 138 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
RESTful Add and Update Legacy Labor
Metrics

You can use the HTTP verbs POST and PATCH to process inserts and updates to legacy labor
metrics. Insert and update capabilities support adding new legacy labor metrics and updating
existing legacy labor metrics.

The following topics contain more information about the POST and PATCH endpoints for the
Legacy Labor Metric API:
l POST Legacy Labor Metrics (see page 139)
l PATCH Legacy Labor Metrics (see page 140)

POST Legacy Labor Metrics

Dayforce RESTful services use the POST verb to create an instance of the resource. In the case of
the Legacy Labor Metric resource, POST refers to creating a new legacy labor metric.

Endpoint URL
The URL for POST Legacy Labor Metric uses the following base URL:

https://www.dayforcehcm.com/api/CompanyName/V1/LegacyLaborMetric

Important: This request writes data into Dayforce. When using this request, be sure that the
consuming application/requester is using the correct Dayforce instance (for example, Test or
Production). Watch out for inadvertently updating the wrong instance of Dayforce (for example,
inserting test data in a production instance).

Parameters
isValidateOnly (boolean)
l Used to specify that all of the validations need to be performed without committing any
changes.
l Use this parameter to control whether committing information to your instance of Dayforce
is your responsibility. See the Important note above.
l The URL syntax is:
https://www.dayforcehcm.com/api/CompanyName/V1/LegacyLaborMetric?isValid
ateOnly=true

Page 139 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Request Body
The request body contains the values that need to be inserted into the available data entities. The
example below shows all of the possible fields in the correct JSON format:
{
"ShortName": "string",
"LongName": "string",
"LegacyLaborMetricType": "string",
"LegacyLaborMetricXRefCode": "string"
}

Security
Creating a new legacy labor metric requires role access to the following role features in the
Features tab of System Admin > Roles:
l HCM Anywhere
l Web Services

l Patch/Post/Delete Legacy Labor Metric

l Org Setup
l Labor Metrics

l Legacy Labor Metrics

l HTML Product Group

l HTML Product Module

l HTML Project Client

l HTML Project Phase

l HTML Project Type

PATCH Legacy Labor Metrics

Dayforce RESTful services use the PATCH verb to update legacy labor metrics.

Overview
You can update legacy labor metrics using the PATCH Legacy Labor Metric endpoint. The
operation uses the following URL:
https://www.dayforcehcm.com/api/CompanyName/V1/LegacyLaborMetric

Parameters
legacyLaborMetricXRefCode (string)

Page 140 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
The unique identifier (external reference code) of the legacy labor metric that will be updated. This
setting is required.

isValidateOnly (boolean)
l Used to specify that all of the validations need to be performed without committing any
changes.
l Use this parameter to control whether committing information to your instance of Dayforce
is your responsibility. See the Important note above.
l The URL syntax is:
https://www.dayforcehcm.com/api/CompanyName/V1/LegacyLaborMetric?isValid
ateOnly=true

Request Body
The request body contains the data entities and elements that need to be processed within a
structure that can be interpreted by Dayforce web services. The example below shows all of the
possible fields in the correct JSON format:
{
"ShortName": "string",
"LongName": "string",
"LegacyLaborMetricType": "string",
"LegacyLaborMetricXRefCode": "string"
}

Security
Updating a legacy labor metric requires role access to the following role features in the Features
tab of System Admin > Roles:
l HCM Anywhere
l Web Services

l Patch/Post/Delete Legacy Labor Metric

l Org Setup
l Labor Metrics

l Legacy Labor Metrics

l HTML Product Group

l HTML Product Module

l HTML Project Client

l HTML Project Phase

l HTML Project Type

Page 141 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
RESTful Retrieve and Delete Labor
Validation Policy Rules

The consuming application can query Dayforce to retrieve details for specific labor validation
policy rules and their qualifiers. Additionally, the consuming application can query Dayforce to
delete specific labor validation policy rules and their qualifiers. You can retrieve and delete this
data by entering specific XRefCodes for labor validation policy rules using one of the following
operations:
l RESTful Get Labor Validation Policy Rule XRefCodes (see page 142)
l RESTful Delete Labor Validation Policy Rule XRefCodes (see page 144)

RESTful Get Labor Validation Policy Rule

XRefCodes
This GET operation returns the details of a specific labor validation policy rule (and its qualifiers, if
configured) based on the XRefCode you enter. The operation uses the following URL:
https://www.dayforcehcm.com/api/CompanyName/V1/LaborValidationPolicy/Rule/
{laborValidationPolicyRuleXRefCode}

Parameters
Consumers can retrieve the data associated with a labor validation rule (and any qualifiers
associated with the rule) using the following parameter:

laborValidationPolicyRuleXRefCode (string)

The unique identifier (external reference code) of the labor validation policy rule that will be
retrieved. The value provided must be an exact match, otherwise a bad request (400) error will be
returned. This setting is required.

Response
The response from this request contains data from the referenced XRefCode. Here is an example
response:
{
"Data": [
{
"PolicyId": 0,

Page 142 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
"PolicyXRefCode": "string",
"XRefCode": "string",
"Name": "string",
"Description": "string",
"EffectiveFrom": "2022-10-25T15:43:14.101Z",
"EffectiveTo": "2022-10-25T15:43:14.101Z",
"Active": true,
"CodeName": "string",
"Sequence": 0,
"ValidationErrorMessage": "string",
"SeverityLevel": 4,
"Models": [
{
"CodeName": "string",
"XRefCode": {}
}
],
"Children": [
{
"XRefCode": "string",
"Name": "string",
"Description": "string",
"Active": true,
"Sequence": 0,
"CodeName": "string",
"Models": [
{
"CodeName": "string",
"XRefCode": {}
}
],
"Children": [
null
]
}
],
"Qualifiers": [
{
"XRefCode": "string",
"Name": "string",
"Description": "string",
"Active": true,
"Sequence": 0,
"CodeName": "string",
"Models": [
{
"CodeName": "string",
"XRefCode": {}
}

Page 143 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 ],
"Children": [
null
]
}
]
}
],
"ProcessResults": [
{
"Code": "string",
"Context": "string",
"Level": "string",
"Message": "string"
}
]
}

RESTful Delete Labor Validation Policy Rule

XRefCodes
Before you begin: This RESTful operation requires role access to the Pay Setup > Labor
Validation Policy feature.

This DELETE operation deletes a specific labor validation policy rule (and its qualifiers, if
configured) based on the XRefCode you enter. The operation uses the following URL:
https://www.dayforcehcm.com/api/CompanyName/V1/LaborValidationPolicy/Rule/
{laborValidationPolicyRuleXRefCode}

Parameters
Consumers can delete the data associated with a labor validation rule (and any qualifiers
associated with the rule) using the following parameter:

laborValidationPolicyRuleXRefCode (string)

The unique identifier (external reference code) of the labor validation policy rule that will be
deleted. The value provided must be an exact match, otherwise a bad request (400) error will be
returned. This setting is required.

Security
Deleting an existing labor validation policy rule requires role access to the HCM Anywhere
> Web Services > Patch/Post/Delete Labor Validation role feature in the Features tab of
System Admin > Roles.

Page 144 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
RESTful Add and Update Labor
Validation Policies

You can use the HTTP verbs POST and PATCH to process inserts and updates to labor validation
policies. Insert and update capabilities support adding new labor validation policy rules and
updating existing labor validation policy rules.

The following topics contain more information about the POST and PATCH endpoints for the
Labor Validation Policy API:
l POST Labor Validation Policy Rules (see page 145)
l PATCH Labor Validation Policy Rules (see page 147)

Additionally, you can use a POST operation to search through your labor validation policy rule
data. The following topic contains more information about this operation:
l Search Labor Validation Policy Rule Data (see page 149)

POST Labor Validation Policy Rules

Dayforce RESTful services use the POST verb to create an instance of the resource. In the case of
the Labor Validation Policy resource, POST refers to creating a new labor validation policy rule.

Endpoint URL
The URL for POST Labor Validation Policy uses the following base URL:

https://www.dayforcehcm.com/api/CompanyName/V1/LaborValidationPolicy/R
ule

To create a labor validation policy rule, a unique identifier (XRefCode) must be provided. This is
done within the data that is sent for processing (referred to as the request body). The XRefCode
must be generated by the requester and it must be unique. It is the consuming application’s
responsibility to assign a unique identifier (XRefCode) to the rule when it's sent in a POST
operation. Dayforce web services will return an error if the XRefCode provided in the request body
matches the value of an existing labor validation policy rule in Dayforce. If this occurs, the
consuming application must determine whether to raise an error (requesting manual intervention)
or resubmit the request using the PATCH verb.

Page 145 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Important: This request writes data into Dayforce. When using this request, be sure that the
consuming application/requester is using the correct Dayforce instance (for example, Test or
Production). Watch out for inadvertently updating the wrong instance of Dayforce (for example,
inserting test data in a production instance).

Request Body
The request body contains the values that need to be inserted into the available data entities. The
example below shows all of the possible fields in the correct JSON format.
{
"PolicyId": 0,
"PolicyXRefCode": "string",
"XRefCode": "string",
"Name": "string",
"Description": "string",
"EffectiveFrom": "2022-10-25T16:54:29.105Z",
"EffectiveTo": "2022-10-25T16:54:29.105Z",
"Active": true,
"CodeName": "string",
"Sequence": 0,
"ValidationErrorMessage": "string",
"SeverityLevel": 4,
"Models": [
{
"CodeName": "string",
"XRefCode": {}
}
],
"Children": [
{
"XRefCode": "string",
"Name": "string",
"Description": "string",
"Active": true,
"Sequence": 0,
"CodeName": "string",
"Models": [
{
"CodeName": "string",
"XRefCode": {}
}
],
"Children": [
null
]
}
],
"Qualifiers": [

Page 146 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 {
"XRefCode": "string",
"Name": "string",
"Description": "string",
"Active": true,
"Sequence": 0,
"CodeName": "string",
"Models": [
{
"CodeName": "string",
"XRefCode": {}
}
],
"Children": [
null
]
}
]
}

Security
Creating a labor validation policy rule using this API requires role access to the HCM Anywhere
> Web Services > Patch/Post/Delete Labor Validation role feature in the Features tab of
System Admin > Roles.

PATCH Labor Validation Policy Rules

Dayforce RESTful services use the PATCH verb to update labor validation policy rules and their
qualifiers.

Overview
You can update labor validation policy rules and their qualifiers using the PATCH Labor Validation
Policy endpoint. The operation uses the following URL:
https://www.dayforcehcm.com/api/CompanyName/V1/LaborValidationPolicy/Rule/
{laborValidationPolicyRuleXRefCode}

Parameters
laborValidationPolicyRuleXRefCode (string)

The unique identifier (external reference code) of the labor validation policy rule (and its qualifiers,
if configured) that will be updated. The value provided must be an exact match, otherwise a bad
request (400) error will be returned. This setting is required.

Page 147 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
isValidateOnly (boolean)

This setting is used to specify that all of the validations need to be performed without committing
any changes.

Use this parameter to control whether committing information to your instance of Dayforce is your
responsibility.

The URL syntax is:

https://www.dayforcehcm.com/api/CompanyName/V1/LaborValidationPolicy/Rule/
{laborValidationPolicyRuleXRefCode}?isValidateOnly=true

Request Body
The request body contains the data entities and elements that need to be processed within a
structure that can be interpreted by Dayforce web services. The example below shows all of the
possible fields in the correct JSON format.
{
"PolicyId": 0,
"PolicyXRefCode": "string",
"XRefCode": "string",
"Name": "string",
"Description": "string",
"EffectiveFrom": "2022-10-25T17:04:18.770Z",
"EffectiveTo": "2022-10-25T17:04:18.770Z",
"Active": true,
"CodeName": "string",
"Sequence": 0,
"ValidationErrorMessage": "string",
"SeverityLevel": 4,
"Models": [
{
"CodeName": "string",
"XRefCode": {}
}
],
"Children": [
{
"XRefCode": "string",
"Name": "string",
"Description": "string",
"Active": true,
"Sequence": 0,
"CodeName": "string",
"Models": [
{
"CodeName": "string",
"XRefCode": {}

Page 148 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 }
],
"Children": [
null
]
}
],
"Qualifiers": [
{
"XRefCode": "string",
"Name": "string",
"Description": "string",
"Active": true,
"Sequence": 0,
"CodeName": "string",
"Models": [
{
"CodeName": "string",
"XRefCode": {}
}
],
"Children": [
null
]
}
]
}

Security
Updating the details of an existing labor validation policy rule requires role access to the HCM
Anywhere > Web Services > Patch/Post/Delete Labor Validation role feature in the Features
tab of System Admin > Roles.

Search Labor Validation Policy Rule Data

Dayforce RESTful services contain a POST operation that searches through your labor validation
policy rule data. This operation returns results based on the labor validation policy, labor metric
code, and labor metric type XRefCodes you specify.

Endpoint URL
The URL for the search operation uses the following base URL:

https://www.dayforcehcm.com/api/CompanyName/V1/LaborValidationPolicy/S
earch

Page 149 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Parameters
pageSize (integer)

The number of records returned per page in the paginated response.

Request Body
The request body contains the values that need to be inserted into the available data entities. The
example below shows all of the possible fields in the correct JSON format.
{
"LaborValidationPolicyXRefCode": "string",
"FilterXRefCodes": [
{
"Criteria": [
{
"CodeName": "string",
"XRefCode": {}
}
]
}
]
}

Page 150 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
RESTful Get KPI Data

This GET operation returns the details of specific KPI data based on the XRefCode that you enter.

Role feature access: HCM Anywhere > Web Services > Patch/Post/Delete KPI Data

The operation uses the following base URL:

https://www.dayforcehcm.com/api/CompanyName/V1/KpiData

Parameters
GET KPI data parameters
Parameter Description
orgUn-
The cross-reference codes of the organizational units to retrieve.
itXRefCode
kpiXRefCode The cross-reference codes of the KPIs to retrieve.
The type of KPI data to retrieve. Supported values are Actual, Forecast, Plan,
kpiDataType
and Supplementary.
timePeriod The data time period. Supported values are minute, day, and week.
filterFrom The filter range's start date.
filterTo The filter range's end date.
zoneXRefCode (Optional) Filter by zone XRefCode.
mdseXRe-
(Optional) Filter by MDSE XRefCode.
fCode
Used to specify that all of the validations need to be performed without
committing any changes. This parameter controls whether committing
isValidateOnly information to your instance of Dayforce is your responsibility. The URL syntax
(boolean) is:
https://www.dayforcehcm.com/api/CompanyName/V1/KpiData?isValid
ateOnly=true

Response
The response from this request will contain data from the referenced XRefCode. Here is an
example response:
{
"Data": [

Page 151 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 {
"OrgUnitXRefCode": "string",
"KpiXRefCode": "string",
"Day": "2023-02-09T20:07:43.380Z",
"Week": "2023-02-09T20:07:43.380Z",
"Value": 0,
"AdjustedValue": 0,
"Forma": "string",
"Forecast": "string",
"ZoneXRefCode": "string",
"MdseXRefCode": "string"
}
],
"ProcessResults": [
{
"Code": "string",
"Context": "string",
"Level": "string",
"Message": "string"
}
]
}

The KpiData RESTful API uses the HTTP verbs POST and PATCH to insert new KPI data and
update existing data. The consuming application can also query Dayforce to retrieve details about
KPI data. You do this by entering specific XRefCodes for KPI data using the Get KpiData
request.

You can also add and update KPI data using the POST and PATCH verbs.

POST and PATCH KPI Data

The KPI Data RESTful API uses the HTTP verbs POST and PATCH to process inserts and
updates to KPI data.

The following topics contain more information about the POST and PATCH endpoints:
l POST KPI Data (see page 152)
l PATCH KPI Data (see page 153)

POST KPI Data

You can use the POST verb to create new KPI data.

Parameters

Page 152 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
POST KPI data parameters
Parameter Description
The cross-reference codes of the organizational
orgUnitXRefCode
units to add.
kpiXRefCode The cross-reference codes of the KPIs to add.
The type of KPI data to add. Supported values are
kpiDataType
Actual, Forecast, Plan, and Supplementary.
The data time period. Supported values are minute,
timePeriod
day, and week.

Reponse
The request body contains the values that need to be inserted into the available data entities. The
example below shows all of the possible fields in the correct JSON format.
[
{
"OrgUnitXRefCode": "string",
"KpiXRefCode": "string",
"Day": "2023-02-09T20:12:58.327Z",
"Week": "2023-02-09T20:12:58.327Z",
"Value": 0,
"AdjustedValue": 0,
"Forma": "string",
"Forecast": "string",
"ZoneXRefCode": "string",
"MdseXRefCode": "string"
}
]

PATCH KPI Data

You can use the PATCH verb to update KPI data.

Parameters
PATCH KPI data parameters
Parameter Description
The cross-reference codes of the organizational
orgUnitXRefCode
units to update.
kpiXRefCode The cross-reference codes of the KPIs to update.

Page 153 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
PATCH KPI data parameters
Parameter Description
The type of KPI data to update. Supported values are
kpiDataType
Actual, Forecast, Plan, and Supplementary.
The data time period. Supported values are minute,
timePeriod
day, and week.
Used to specify that all of the validations need to be
isValidateOnly
performed without committing any changes.
Uniquely identifies the client's Dayforce instance.
clientNamespace
This is needed to log in.

Request Body
The request body contains the data entities and elements that need to be processed within a
structure that can be interpreted by Dayforce web services. The example below shows all of the
possible fields in the correct JSON format.
[
{
"OrgUnitXRefCode": "string",
"KpiXRefCode": "string",
"Day": "2023-02-09T20:33:19.959Z",
"Week": "2023-02-09T20:33:19.959Z",
"Value": 0,
"AdjustedValue": 0,
"Forma": "string",
"Forecast": "string",
"ZoneXRefCode": "string",
"MdseXRefCode": "string"
}
]

Page 154 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
RESTful Get Plan Targets

This GET operation returns the details of a plan target based on the XRefCode that you enter.

Role feature access: HCM Anywhere > Web Services > Patch/Post/Delete Plan Targets

The operation uses the following base URL:

https://www.dayforcehcm.com/api/CompanyName/V1/PlanTargets

Parameters
Consumers can retrieve plan targets data using the following parameters:

GET Plan Targets parameters

Parameter Description
planTargetXRefCode Filter by plan target XRefCode.
orgUnitXRefCode Filter by organization unit XRefCode.
kpiXRefCode (Optional) Filter by KPI XRefCode.
zoneXRefCode (Optional) Filter by zone XRefCode.
axisXRefCode (Optional) Filter by axis XRefCode.
isActive Return only active plan targets.

Response
The response from this request will contain data from the referenced XRefCode. Here is an
example response:
{
"Data": [
{
"PlanTargetXRefCode": "string",
"Name": "string",
"Description": "string",
"EffectiveStart": "2023-02-01T15:49:31.219Z",
"EffectiveEnd": "2023-02-01T15:49:31.219Z",
"TargetValue": 0,
"KpiXRefCode": "string",
"ZoneXRefCode": "string",
"DaysOfWeek": [
"string"

Page 155 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 ],
"OrgUnitXRefCodes": [
"string"
],
"CreationOrgUnitXRefCode": "string"
}
],
"ProcessResults": [
{
"Code": "string",
"Context": "string",
"Level": "string",
"Message": "string"
}
]
}

You can also add and update plan targets using the POST and PATCH verbs. See POST and
PATCH Plan Targets on page 156.

POST and PATCH Plan Targets

The Plan Targets RESTful API uses the HTTP verbs POST and PATCH to process inserts and
updates to plan targets. Insert and update capabilities support adding new plan targets and
updating existing ones.

The following topics contain more information about the POST and PATCH endpoints:
l POST Plan Targets (see page 157)
l PATCH Plan Targets (see page 156)

PATCH Plan Targets

You can use the PATCH verb to update plan targets.

Overview
You can update plan targets using the PATCH Plan Targets endpoint. The operation uses the
following URL:

https://www.dayforcehcm.com/api/CompanyName/V1/PlanTargets

Parameters
isValidateOnly (boolean)

Page 156 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 l Used to specify that all of the validations need to be performed without committing any
changes.
l Use this parameter to control whether committing information to your instance of Dayforce
is your responsibility.
l The URL syntax is: https://www.day-
forcehcm.com/api/CompanyName/V1/PlanTargets?isValidateOnly=true

Request Body
The request body contains the data entities and elements that need to be processed within a
structure that can be interpreted by Dayforce web services. The example below shows all of the
possible fields in the correct JSON format.
{
"PlanTargetXRefCode": "string",
"Name": "string",
"Description": "string",
"EffectiveStart": "2023-01-31T17:37:13.607Z",
"EffectiveEnd": "2023-01-31T17:37:13.607Z",
"TargetValue": 0,
"KpiXRefCode": "string",
"ZoneXRefCode": "string",
"DaysOfWeek": [
"string"
],
"OrgUnitXRefCodes": [
"string"
],
"CreationOrgUnitXRefCode": "string"
}

POST Plan Targets

You can use the POST verb to create new plan targets.

Parameters
isValidateOnly (boolean)
l Used to specify that all of the validations need to be performed without committing any
changes.
l Use this parameter to control whether committing information to your instance of Dayforce
is your responsibility.
l The URL syntax is:
https://www.dayforcehcm.com/api/CompanyName/V1/PlanTargets?isValidateOnl
y=true

Page 157 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Request Body
The request body contains the values that need to be inserted into the available data entities. The
example below shows all of the possible fields in the correct JSON format.
{
"PlanTargetXRefCode": "string",
"Name": "string",
"Description": "string",
"EffectiveStart": "2023-01-31T17:30:46.297Z",
"EffectiveEnd": "2023-01-31T17:30:46.297Z",
"TargetValue": 0,
"KpiXRefCode": "string",
"ZoneXRefCode": "string",
"DaysOfWeek": [
"string"
],
"OrgUnitXRefCodes": [
"string"
],
"CreationOrgUnitXRefCode": "string"
}

Page 158 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
RESTful Get Operating Hours

In Dayforce, operating hours describe when locations are open during each day of the week,
exceptions to this pattern, when the pattern is applied, and what locations it's applied to.
This RESTful operation retrieves locations' operating hours.

Overview
Operating hours can be retrieved for specified locations and periods. The call URL is constructed
using the following base URL:
https://www.dayforcehcm.com/api/CompanyName/V1/OperatingHours/GetOperatingHou
rs

Parameters
startDate (string)
l The start date used to determine the operating hours to retrieve. If omitted, the current date
is used.

endDate (string)
l The end date used to determine the operating hours to retrieve. If omitted, the period start
date is used. If the period start date is also omitted, the current date is used.

orgUnitId (integer)
l The org unit IDs to determine the locations to retrieve operating hours for.

clientNamespace (string)
l Uniquely identifies the client's Dayforce instance. This is needed to log in.

Response
The response is in JSON format as illustrated in the example below:
{
"Data": {
"EffectiveStart": "2023-07-31T19:11:11.967Z",
"EffectiveEnd": "2023-07-31T19:11:11.967Z",
"OrgUnit": 0,
"OperatingHours": [
{

Page 159 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 "Day": "2023-07-31T19:11:11.967Z",
"IsClosed": 0,
"NoDayPattern": 0,
"ShortName": "string",
"LongName": "string",
"OpenTime": "2023-07-31T19:11:11.967Z",
"CloseTime": "2023-07-31T19:11:11.967Z",
"IsException": 0,
"LastModifiedTimestamp": "2023-07-31T19:11:11.967Z",
"Client": 0
}
]
},
"ProcessResults": [
{
"Code": "string",
"Context": "string",
"Level": "string",
"Message": "string"
}
]
}

POST and PATCH Operating Hours

The HTTP verbs POST and PATCH are used to process inserts and updates to operating hours.
Insert and update capabilities support adding new operating hours to the organization and
updating existing ones.

The following topics contain more information about the POST and PATCH jobs endpoints:
l POST Operating Hours (see page 160)
l PATCH Operating Hours (see page 161)

POST Operating Hours

Dayforce RESTful services use the POST verb to create new operating hours.

Overview
Consuming applications can use the POST Operating Hours request to create operating hours in
Dayforce.

The URL for POST operations uses the following base URL:

https://www.dayforcehcm.com/api/CompanyName/V1/OperatingHours/PostOper
atingHoursException

Page 160 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
To create new operating hours, you must provide a unique identifier (XRefCode). This is done
within the data that's sent for processing (referred to as the request body). The XRefCode must be
generated by the requester and it must be unique. It's the consuming application’s responsibility
to assign a unique identifier (XRefCode) to the operating hours when it's sent in a POST
operation. Dayforce web services returns an error if the XRefCode provided in the request body
matches the value of an existing record in Dayforce. If this occurs, the consuming application
must determine whether to raise an error (requesting manual intervention) or resubmit the request
using the PATCH verb.

Important: This request writes data into Dayforce. When using this request, ensure that the
consuming application/requester is using the correct Dayforce instance (for example, Test or
Production). Watch out for inadvertently updating the wrong Dayforce instance (for example, test
data in a production instance).

Parameters
IsValidateOnly (boolean)
l Used to specify that all of the validations need to be performed without committing any
changes.
l When true, the system returns an image of all the problems that exist.
l When false, critical errors prevent saving but all other errors go through.
l Use this parameter to control whether committing information to your Dayforce instance is
your responsibility. See the Important note above.

clientNamespace (string)
l Uniquely identifies the client's Dayforce instance. This is needed to log in.

PATCH Operating Hours

Dayforce RESTful services use the PATCH verb to update operating hours.

Overview
The URL for PATCH operations uses the following base URL:
https://www.dayforcehcm.com/api/
{CompanyName}/V1/OperatingHours/PatchOperatingHoursException

Important: This request writes data into Dayforce. When using this request, ensure that the
consuming application/requester is using the correct Dayforce instance (for example, Test or
Production). Watch out for inadvertently updating the wrong Dayforce instance (for example, test
data in a production instance).

Page 161 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Parameters
IsValidateOnly* (boolean)
l Used to specify that all of the validations need to be performed without committing any
changes.
l Use this parameter to control whether committing information to your Dayforce instance is
your responsibility.
l The URL syntax is: https://www.day-
forcehcm.com/api/CompanyName/V1/OperatingHours/[XRe-
fCode]?isValidateOnly=true

clientNamespace (string)
l Uniquely identifies the client's Dayforce instance. This is needed to log in.

Request Body
The request body contains the data entities and elements that need to be processed within a
structure that can be interpreted by Dayforce web services. The same JSON structure used to
return data retrieved from Dayforce using the GET Operating Hours request is used for
PATCH operations.

Page 162 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
RESTful Retrieve Projects Data

The consuming application can query Dayforce to retrieve a list of projects. The consuming
application can also request details for a specific project by entering the project’s XRefCode in a
separate GET request.

RESTful Get Projects

This GET operation returns a list containing all of the projects configured by an organization. The
operation uses the following URL:

https://www.dayforcehcm.com/api/CompanyName/V1/Projects

Parameters
Consumers can retrieve projects data by using combinations of the following parameters:

shortName (string)

The project name.

longName (string)

The project description.

pageSize (integer)

The number of records returned per page in the paginated response.

projectClientXRefCode (string)

Reference code for the project client to be retrieved.

projectTypeXRefCode (string)

Reference code for the project type to be retrieved.

projectPhaseXRefCode (string)

Reference code for the project phase to be retrieved.

productGroupXRefCode (string)

Reference code for the product group to be retrieved.

Page 163 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
productModuleXRefCode (string)

Reference code for the product module to be retrieved.

creationOrgUnitXRefCode (string)

Reference code for the organization to be retrieved.

lastModifiedStartDate (string)

The start date used when searching for projects with updates in a specified time frame.

lastModifiedEndDate (string)

The end date used when searching for projects with updates in a specified time frame.

filterStartDateFrom (string)

Use to search for projects with a start date value greater than or equal to the specified value.

filterStartDateTo (string)

Use to search for projects with a start date value less than or equal to the specified value.

filterDueDateFrom (string)

Use to search for projects with a due date value greater than or equal to the specified value.

filterDueDateTo (string)

Use to search for projects with a due date value less than or equal to the specified value.

filterCompletedDateFrom (string)

Use to search for projects with a completed date value greater than or equal to the specified
value.

filterCompletedDateTo (string)

Use to search for projects with a completed date value less than or equal to the specified value.

certifiedPayrollProjectNumber (integer)

Use to search for projects with a certified payroll project number.

parentProjectXRefCode (string)

Reference code of the parent project to be retrieved.

isDeleted (boolean)

This filters the projects based on their deleted status (that is, whether it was deleted or not).

Page 164 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
ledgerCode (string)

Use to search for projects with the specified ledger code.

clockTransferCode (string)

Use to search for projects with the specified clock code.

accountNum (string)

Use to search for projects with the specified account number.

iFRSClassification (boolean)

Use to filter accounts that are IFRS standardized accounts.

filterProjectPriorityForm (integer)

Use to search for projects with a project priority value greater than or equal to the specified value.
When you use this parameter, you must also configure the filterProjectPriorityTo parameter.

filterProjectPriorityTo (integer)

Use to search for projects with a project priority value less than or equal to the specified value.
When you use this parameter, you must also configure the filterProjectPriorityFrom parameter.

filterBudgetHoursFrom (number)

Use to search for projects with a budget hours value greater than or equal to the specified value.
When you use this parameter, you must also configure the filterBudgetHoursTo parameter.

filterBudgetHoursTo (number)

Use to search for projects with a budget hours value less than or equal to the specified value.
When you use this parameter, you must also configure the filterBudgetHoursFrom parameter.

filterBudgetAmountFrom (number)

Use to search for projects with a budget amount value greater than or equal to the specified value.
When you use this parameter, you must also configure the filterBudgetAmountTo parameter.

filterBudgetAmountTo (number)

Use to search for projects with a budget amount value less than or equal to the specified value.
When you use this parameter, you must also configure the filterBudgetAmountFrom parameter.

filterPctCompleteFrom (number)

Use to search for projects with a percentage complete value greater than or equal to the specified
value. When you use this parameter, you must also configure the filterPctCompleteTo
parameter.

Page 165 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
filterPctCompleteTo (number)

Use to search for projects with a percentage complete value less than or equal to the specified
value. When you use this parameter, you must also configure the filterPctCompleteFrom
parameter.

Response
The response from this request contains data from the referenced project. Here is an example
response:
"ParentProjectXRefCode": "string",
"CreationOrgUnitXRefCode": "string",
"StartDate": "2021-11-15T21:54:24.353Z",
"DueDate": "2021-11-15T21:54:24.353Z",

RESTful Get Projects XRefCodes

This GET operation returns the details of a specific project based on the XRefCode you enter. The
operation uses the following URL:

https://www.dayforcehcm.com/api/CompanyName/V1/Projects/xRefCode

Parameters
Consumers can retrieve projects data by using combinations of the following parameters:

XRefCode (string)

The unique identifier (external reference code) of the project that will be retrieved. The value
provided must be an exact match, otherwise a bad request (400) error will be returned. This
setting is required.

Response
The response from this request will contain data from the referenced XRefCode. Here is an
example response:
{
"Data": {
"ProjectXRefCode": "string",
"ShortName": "string",
"ParentProjectXRefCode": "string",
"CreationOrgUnitXRefCodes": [

Page 166 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 "string"
],
"StartDate": "2022-02-24T00:51:10.464Z",
"DueDate": "2022-02-24T00:51:10.464Z",
"LongName": "string",
"ClockTransferCode": "string",
"ProjectPriority": 0,
"AccountNum": "string",
"LedgerCode": "string",
"IFRSClassification": true,
"CertifiedPayrollProjectNumber": "string",
"CompletedDate": "2022-02-24T00:51:10.464Z",
"PctComplete": 0,
"BudgetHours": 0,
"BudgetAmount": 0,
"ProjectClientXRefCode": "string",
"ProjectTypeXRefCode": "string",
"ProjectPhaseXRefCode": "string",
"ProductGroupXRefCode": "string",
"ProductModuleXRefCode": "string",
"Deleted": true,
"TaxLocationAddressXRefCode": "string",
"ChildProjectXRefCodes": [
"string"
],
"EmployeeXRefCodes": {
"IsAssignedAll": true,
"XrefCodes": [
"string"
]
},
"DeptJobXRefCodes": {
"IsAssignedAll": true,
"XrefCodes": [
"string"
]
},
"DepartmentXRefCodes": {
"IsAssignedAll": true,
"XrefCodes": [
"string"
]
},
"PayCodeXRefCodeChargeToHours": {
"IsAssignedAll": true,
"XrefCodes": [
"string"
]
},

Page 167 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 "PayCodeXRefCodeChargeToAmount": {
"IsAssignedAll": true,
"XrefCodes": [
"string"
]
},
"IsResidentAddressUsedForTaxation": true
},
"ProcessResults": [
{
"Code": "string",
"Context": "string",
"Level": "string",
"Message": "string"
}
]
}

Page 168 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
RESTful Add and Update Projects Data

The HTTP verbs POST and PATCH are used to process inserts and updates to projects
information. Insert and update capabilities support adding new project information for an
employee and updating project information for an existing employee.

The following topics contain more information about the POST and PATCH project endpoints:
l POST Projects Data (see page 169)
l PATCH Projects Data (see page 171)

POST Projects Data

Dayforce RESTful services use the POST verb to create an instance of the resource. In the case of
the Projects resource, POST refers to creating a new project.

Endpoint URL
The URL for POST Projects uses the following base URL:

https://www.dayforcehcm.com/api/CompanyName/V1/Projects

Important: This request writes data into Dayforce. When using this request, be sure that the
consuming application/requester is using the correct Dayforce instance (for example, Test or
Production). Watch out for inadvertently updating the wrong instance of Dayforce (for example,
inserting test data in a production instance).

Parameters
isValidateOnly (boolean)
l Used to specify that all of the validations need to be performed without committing any
changes.
l Use this parameter to control whether committing information to your instance of Dayforce
is your responsibility. See the Important note above.
l The URL syntax is:
https://www.dayforcehcm.com/api/CompanyName/V1/Projects?isValidateOnly=t
rue

Page 169 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Request Body
The request body contains the values that need to be inserted into the available data entities. The
example below shows all of the possible fields in the correct JSON format.
{
"ProjectXRefCode": "string",
"ShortName": "string",
"CreationOrgUnitXRefCodes": [
"string"
],
"ClockTransferCode": "string",
"ProjectPriority": 0,
"AccountNum": "string",
"IFRSClassification": true,
"LongName": "string",
"LedgerCode": "string",
"CertifiedPayrollProjectNumber": "string",
"ProjectClientXRefCode": "string",
"ProjectTypeXRefCode": "string",
"ProjectPhaseXRefCode": "string",
"ProductGroupXRefCode": "string",
"ProductModuleXRefCode": "string",
"StartDate": "2022-04-07T19:56:31.648Z",
"DueDate": "2022-04-07T19:56:31.648Z",
"BudgetHours": 0,
"BudgetAmount": 0,
"EmployeeAssignment": {
"IsAssignedAll": true,
"XrefCodes": [
"string"
]
},
"DeptJobAssignment": {
"IsAssignedAll": true,
"XrefCodes": [
"string"
]
},
"DepartmentAssignment": {
"IsAssignedAll": true,
"XrefCodes": [
"string"
]
},
"CompletedDate": "2022-04-07T19:56:31.648Z",
"PctComplete": 0,
"IsDeleted": true,
"PayCodeXRefCodeChargeToHours": {

Page 170 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 "IsAssignedAll": true,
"XrefCodes": [
"string"
]
},
"PayCodeXRefCodeChargeToAmount": {
"IsAssignedAll": true,
"XrefCodes": [
"string"
]
},
"ParentProjectXRefCode": "string",
"TaxLocationAddressXRefCode": "string",
"IsResidentAddressUsedForTaxation": true
}

Validation of Org Unit Level

Dayforce validates that any project you create using this operation is assigned to the proper org
unit. You cannot create a project that’s assigned to a department-level org unit. The application
validates that the org unit referenced in the request’s "CreationOrgUnitXRefCode" field is
not assigned as a department-level org unit in Org Setup > Organization. When the application
detects that a project is assigned to a department, an error message is displayed.

The "CreationOrgUnitXRefCode" field provides multiple org level support. That is, the field
supports multiple locations and doesn’t require that the locations are directly tied to each other as
org units. For example, you can include locations that are nested at different or indirect levels in
your organizational hierarchy.

Important: If you include org units that are nested deep in your organizational hierarchy (for
example, 16 levels) in this field, it might impact the performance of this operation.

Validation of IFRS Classification

Dayforce validates that any request containing the "IFRSClassification" field is configured
correctly. When your request contains this field, it must be set to either true or false.

Security
Adding a new project requires role access to the HCM Anywhere > Web Services > Patch/Post
Projects role feature in the Features tab of System Admin > Roles.

PATCH Projects Data

Dayforce RESTful services use the PATCH verb to update projects.

Page 171 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Overview
You can update projects data using the PATCH Projects endpoint. The operation uses the
following URL:

https://www.dayforcehcm.com/api/CompanyName/V1/Projects

Parameters
projectXRefCode (string)
l Reference code of the project from which data must be retrieved.
l The URL syntax is: https://www.day-
forcehcm.com/api/CompanyName/V1/Projects?projectxrefcode=[XRefCode]

isValidateOnly (boolean)
l Used to specify that all of the validations need to be performed without committing any
changes.
l Use this parameter to control whether committing information to your instance of Dayforce
is your responsibility.
l The URL syntax is: https://www.day-
forcehcm.com/api/CompanyName/V1/Projects?isValidateOnly=true

Request Body
The request body contains the data entities and elements that need to be processed within a
structure that can be interpreted by Dayforce web services. The example below shows all of the
possible fields in the correct JSON format.
{
"ProjectXRefCode": "string",
"ShortName": "string",
"CreationOrgUnitXRefCodes": [
"string"
],
"ClockTransferCode": "string",
"ProjectPriority": 0,
"AccountNum": "string",
"IFRSClassification": true,
"LongName": "string",
"LedgerCode": "string",
"CertifiedPayrollProjectNumber": "string",
"ProjectClientXRefCode": "string",
"ProjectTypeXRefCode": "string",
"ProjectPhaseXRefCode": "string",
"ProductGroupXRefCode": "string",

Page 172 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 "ProductModuleXRefCode": "string",
"StartDate": "2022-04-08T14:28:49.243Z",
"DueDate": "2022-04-08T14:28:49.243Z",
"BudgetHours": 0,
"BudgetAmount": 0,
"EmployeeAssignment": {
"IsAssignedAll": true,
"XrefCodes": [
"string"
]
},
"DeptJobAssignment": {
"IsAssignedAll": true,
"XrefCodes": [
"string"
]
},
"DepartmentAssignment": {
"IsAssignedAll": true,
"XrefCodes": [
"string"
]
},
"CompletedDate": "2022-04-08T14:28:49.244Z",
"PctComplete": 0,
"IsDeleted": true,
"PayCodeXRefCodeChargeToHours": {
"IsAssignedAll": true,
"XrefCodes": [
"string"
]
},
"PayCodeXRefCodeChargeToAmount": {
"IsAssignedAll": true,
"XrefCodes": [
"string"
]
},
"ParentProjectXRefCode": "string",
"TaxLocationAddressXRefCode": "string",
"IsResidentAddressUsedForTaxation": true
}

Validation of Org Unit Level

Dayforce validates that any project you update using this operation is assigned to the proper org
unit. You can’t update a project that’s assigned to a department-level org unit. The application
validates that the org unit referenced in the request’s "CreationOrgUnitXRefCode" field is

Page 173 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
not assigned as a department-level org unit in Org Setup > Organization. When the application
detects that a project is assigned to a department, an error message is shown.

The "CreationOrgUnitXRefCode" field provides multiple org level support. That is, the field
supports multiple locations and doesn’t require that the locations are directly tied to each other as
org units. For example, you can include locations that are nested at different or indirect levels in
your organizational hierarchy.

Important: If you include org units that are nested deep in your organizational hierarchy (for
example, 16 levels) in this field, it might impact the performance of this operation.

Validation of IFRS Classification

Dayforce validates that any request containing the "IFRSClassification" field is configured
correctly. When your request contains this field, it must be set to either true or false.

Validation of Parent Project

When updating a child project, this operation uses a project’s ID in the database to determine the
correct parent project. The "ParentProjectXRefCode" field is not used to identify a child
project’s parent project because several different parent projects can be given the same
XRefCode in the Projects feature.

Security
Updating the details for an existing project requires role access to the HCM Anywhere > Web
Services > Patch/Post Projects role feature in the Features tab of System Admin > Roles.

Page 174 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
REST Services for Retrieving
Documents

The following topics describe the foundational concepts and methods for retrieving documents
using RESTful Web Services:
l URL Endpoint (see page 175)
l Documents API Proxy Class (see page 175)
l Retrieve List of Documents Based on Employee (see page 176)
l Retrieve a Single Document (see page 177)

URL Endpoint
The base URL for the Document API is as follows, where you replace <clientName> with the
name of your organization:
https://www.dayforcehcm.com/api/<clientName>/v1/Documents

Documents API Proxy Class

This class is a proxy class provided to act as a façade on top of the REST layer. Using this class is
optional. Note that the examples in this topic provide the pure raw REST request and response
details, but the sample code uses the DocumentsApi class.

In your application, you’ll want to instantiate the DocumentsApi class using either the root URL
or the target redirect URL that will be embedded in a URI object. Here is code that demonstrates
instantiating the DocumentsApi class:

Page 175 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Retrieve List of Documents Based on
Employee
The following function will retrieve a list of information about each document associated with an
Employee’s XRefCode. The information contains metadata about each document. The content of
each document will not be available in this function, but the DocumentGUIDis. The
DocumentGUID is the unique identifier needed to retrieve the document in the Retrieve a Single
Document function.
GET https://www.dayforcehcm.com/api/<clientName>/v1/Documents/?EmployeeXRefCo
de=123

Body:
{
"DocumentGUID": "24f4f5d6-3b57-4220-a47c-a01abc4a16fb",
"DocumentName": "850qa2 Document count - before.jpg",
"DocumentType":
{
"ShortName": "Address",
"Description": "Address",
"XRefCode": "ADDRESS"
},
"FileName": "850qa2 Document count - before.jpg",
"UploadedDate": "2017-03-24T14:59:56.617",
"UploadedBy":
{
"LoginId": "CAdmin"
}
}

Page 176 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Sample Code: Retrieve List of Documents Based
on Employee
The following screenshot shows the sample code used to retrieve a list of documents:

Retrieve a Single Document

The following function will retrieve a single document based on a unique DocumentGUID. The
response contains two parts: the metadata and the content.

The metadata contains information about the name of the file, file type, and publishing date.

The content data is stored as a BLOB in the database and then converted as a base 64-byte array
when it's retrieved by the web services request. To make the contents usable by a reader, it must
be deserialized. An example of deserialization is available in the sample application code. The
document location is set as the root of the sample application as a default.
GET: https://www.dayforcehcm.com/api/<clientName>/v1/Documents/123

Body:
{
"DocumentGroup": "DocumentManagement",
"SourceReportUniqueId": "e2e34a25-169e-4784-996d-3d5c43cafe6f",
"PublishDateTime": "2017-04-11T11:59:18.727",
"Title": "Message Response Mockups.pdf",
"PageCount": 0,
"CultureId": 0,
"Contents": "JVBERi0xLjQKJafj8fEKMSAwIG9iago8PAovVHlwZSA…”
"FileName": "Message Response Mockups.pdf",
"SizeBytes": 141876
}

Sample Code: Retrieve and Save a Single

Document
The following figure shows the sample code used to retrieve and save a single document:

Page 177 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Sample Code - Saving Function for a Single
Document
The following figure shows the sample code for the saving function of the single document:

Page 178 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
REST Services for Retrieving Report
Metadata and Report Data

The following topics describe the foundational concepts and methods for retrieving report
definitions and report data using RESTful web services:
l URL Endpoint (see page 179)
l Report API Proxy Class (see page 179)
l Retrieve List of Report Metadata (see page 180)
l Retrieve Report Metadata for One Report (see page 181)
l Retrieve Data for One Report (see page 181)

URL Endpoint
The base URL for the ReportMetadata API is as follows, where you replace <clientName>
with the name of your organization:
https://www.dayforcehcm.com/api/<clientName>/v1/ReportMetadata

Report API Proxy Class

This class is a proxy class provided to act as a facade on top of the REST layer. Using this class is
optional. Note that the examples in this topic provide the pure raw REST request and response
details, but the sample code uses the ReportApi class.

In your application, you'll want to instantiate the ReportApi class using either the root URL or the
target redirect URL that will be embedded in a URI object. Here is the code that demonstrates
instantiating the ReportAPI class:

Page 179 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Retrieve List of Report Metadata
The following function will retrieve a list of report definitions for reports accessible via RESTful
web service. The information contains metadata about each report. The content of each report will
not be available in this function.
GET https://www.dayforcehcm.com/api/<clientName>/v1/ReportMetadata
{
"Data":[
{
"Name": "Pay Summary WS",
"Description": "Displays pay data for employees, such as how much
employees earned and the pay category associated with the record.",
"XRefCode": "PaySummaryWS",
"MaxRows": 20000
},
{
"Name": "PaySummaryData",
"Description": "",
"XRefCode": "PaySummaryData",
"MaxRows": 20000
}
]
}

Sample Code: Retrieve List of Report Metadata

Page 180 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
The following function will retrieve a list of report definitions for reports accessible via RESTful
web service. The information contains metadata about each report. The content of each report will
not be available in this function.

Retrieve Report Metadata for One Report

The following figure shows the sample code used to retrieve metadata for a single report:

Retrieve Data for One Report

The following figure shows the sample code used to retrieve data from a single report:

Response data would look like the following sample result:

Page 181 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
"Data": {
"XRefCode": "TestWS",
"Rows": [
{
"IsTotalItem": "0",
"OrgUnit_ShortName": "Bank 1 - Admin",
"EmployeeEmploymentStatus_BaseRateAverage": "16.770512"
},
{
"IsTotalItem": "0",
"OrgUnit_ShortName": "Bank 1 - Commercial Lines",
"EmployeeEmploymentStatus_BaseRateAverage": "9.625000"
},
{
"IsTotalItem": "0",
"OrgUnit_ShortName": "Bank 1 - Customer Service",
"EmployeeEmploymentStatus_BaseRateAverage": "8.364583"
},
{
"IsTotalItem": "0",
"OrgUnit_ShortName": "Bank 1 - Employee Benefits",
"EmployeeEmploymentStatus_BaseRateAverage": "8.316666"
}
{
"IsTotalItem": "0",
"OrgUnit_ShortName": "Hotel 1 - Food & Beverage",
"EmployeeEmploymentStatus_BaseRateAverage": "9.150000"
}
]
},
"Paging": {
"Next": ""
}
}

Page 182 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
REST Services for Updating an
Employee's I-9 Order Status

To make changes to an employee’s I-9 order status, an HTTP request can be made to Dayforce’s
web services using the HTTP verb PATCH.

The base URL for the Employees API is as follows, replacing <clientName> with your
organization’s name:
https://www.dayforcehcm.com/api/<clientName>/v1/I9Orders

Overview
To make changes to an employee's I-9 order status, an HTTP request can be made to Dayforce's
web services using the HTTP verb PATCH.

The base URL for the I9Orders API is as follows, replacing <clientname> with your organization's
name:
https://www.dayforcehcm.com/api/<ClientName>/V1/I9Orders

Parameters
Consumers can update a single employee’s I-9 order using the following parameters:

Request Body
The request body is defined with the following properties:
l I9OrderId (string): The id of the order to be updated.
l OrderStatusXRefCode: An XRefCode corresponding to an I-9 order status that Dayforce
supports. The following values are supported:
l SENT TO EMPLOYEE

l PENDING EMPLOYER

l COMPLETED

l NEW

l DECLINED BY EMPLOYEE

l PENDING EMPLOYEE

Page 183 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
i9OrderId (string)
l This parameter should be specified both as query parameter and as a parameter in the
request body. The query parameter and parameter in the request body need to match.
l The id of the order to be updated.
l The URL syntax is the following: https://www.day-
forcehcm.com/api/CompanyName/V1/I9Orders/exampleI9OrderId

IsValidateOnly (boolean)
l Used to specify that all of the validations need to be performed without committing any
changes
l Use this parameter to control whether committing information to your instance of Dayforce
is your responsibility.
l The URL syntax is the following: https://www.da-
for-
cehcm.-
com/ap-
i/CompanyName/V1/I9Orders/exampleI9OrderId?isValidateOnly=true

Response
This call returns an HTTP 200 response code with an empty response body when the call is
successful.

If the call is not successful, then the standard error response is returned. For example:
{
"requestId": "800000d9-0006-f800-b63f-84710c7967bb",
"processResults": [
{
"code": "I9_NO_ORDER_FOUND",
"level": "ERROR",
"message": "No I-9 order was found that matches the I-9 order id
of 'asfd'. isValidateOnly = False."
}
]
}

Page 184 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
REST Services for Retrieving Job
Posting Feeds

You can use the Get Job Feeds endpoint to retrieve a feed of job postings. This allows you to set
up the job feed with an external job site so that your postings can be shared there without a
recruiter having to post them manually.

The call URL is constructed by adding "JobFeeds" to the base URL. Optional parameters can be
added to the URL as required:
https://www.dayforcehcm.com/api/CompanyName/V1/JobFeeds

Query string parameters to filter job posting feeds

Parameter Description
The company name is the value of the company name override
from the client career site configuration page. If company name
companyName
override is not available then it's the value of the parent company
name.
The parent company name is the value configured for the
parentCompanyName
Company Name for Job Feeds client property.
The job board reference code. The value for this parameter
corresponds to the reference code configured in Recruiting Setup
internalJobBoardCode > Client Career Site Management.

Example: CANDIDATEPORTAL.
Because this is a boolean parameter, it can only be expressed as
true or false:
includeActivePostingOnly l If true, then inactive postings are excluded from the results.
l If false, then the lastUpdateTimeFrom and lastUp-
dateTimeTo parameters are required.

Page 185 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Query string parameters to filter job posting feeds
Parameter Description
The starting timestamp of the last updated job posting. This
parameter is required when the includeActivePostingOnly is set to
false.

The difference between the lastUpdateTimeFrom

lastUpdateTimeFrom
and lastUpdateTimeTo parameters cannot exceed one month.

Datetime value should be expressed as yyyy-mm-ddThh:mm:ss

where T is a separator used between the date and time. For
example, 2017-01-01T13:24:56.
The ending timestamp of the last updated job posting. This
parameter is required when the includeActivePostingOnly is set to
false.

The difference between the lastUpdateTimeFrom

lastUpdateTimeTo
and lastUpdateTimeTo parameters cannot exceed one month.

Datetime value should be expressed as yyyy-mm-ddThh:mm:ss

where T is a separator used between the date and time. For
example, 2017-01-01T13:24:56.
The starting timestamp of the job posting date.

datePostedFrom Datetime value should be expressed as yyyy-mm-ddThh:mm:ss

where T is a separator used between the date and time. For
example, 2017-01-01T13:24:56.
The starting timestamp of the job posting date.

datePostedTo Datetime value should be expressed as yyyy-mm-ddThh:mm:ss

where T is a separator used between the date and time. For
example, 2017-01-01T13:24:56.

The response from this request includes the information from the relevant job postings according
to the filters. Here is an example response:

The response is in JSON or XML format depending on the request header. If the request header
contains "Accept = application/xml" then the response format will be XML. Otherwise it
will be in JSON format. Below there is an example of a response in XML and in JSON.

Example XML Response

<ArrayOfJob xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Job>
<Title>
<![CDATA[Store 110 - Accessories Associate]]>

Page 186 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 </Title>
<Description>
<![CDATA[Retail Salesperson Job Purpose: Serves customers by
helping them select products.
Retail Salesperson Job Duties: - Welcomes customers by greeting them; offering
them assistance. - Directs customers by escorting them to racks and counters;
suggesting items. - Advises customers by providing information on products. -
Helps customer make selections by building customer confidence; offering
suggestions and opinions. - Documents sale by creating or updating customer
profile records. - Processes payments by totaling purchases; processing
checks, cash, and store or other credit cards. - Keeps clientele informed by
notifying them of preferred customer sales and future merchandise of potential
interest. - Contributes to team effort by accomplishing related results as
needed.]]>
</Description>
<ClientSiteName>
<![CDATA[Client Careers Site]]>
</ClientSiteName>
<ClientSiteXrefCode>
<![CDATA[CANDIDATEPORTAL]]>
</ClientSiteXrefCode>
<CompanyName>
<![CDATA[XYZ Co.]]>
</CompanyName>
<ParentCompanyName>
<![CDATA[XYZ Co.]]>
</ParentCompanyName>
<JobDetailsUrl>
<![CDATA[http://localhost:51009/en-US/DFLocal/Posting/View/17]]>
</JobDetailsUrl>
<ApplyUrl>
<![CDATA[https://prdemo.dayforcehcm.com/CandidatePortal/en-
US/prdemo2/JobPosting/Job?jobId=17]]>
</ApplyUrl>
<City>
<![CDATA[San Francisco]]>
</City>
<State>
<![CDATA[CA]]>
</State>
<Country>
<![CDATA[USA]]>
</Country>
<PostalCode>
<![CDATA[30009]]>
</PostalCode>
<Education>
<![CDATA[Master’s Degree]]>
</Education>

Page 187 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 <JobFunction>
<![CDATA[General and Operations Manager]]>
</JobFunction>
<EmploymentIndicator>
<![CDATA[Contractor]]>
</EmploymentIndicator>
<DatePosted>2014-06-13T00:00:00</DatePosted>
<LastUpdated>2014-06-13T17:06:44.16</LastUpdated>
<ReferenceNumber>17</ReferenceNumber>
<ParentRequisitionCode>3</ParentRequisitionCode>
<MinHiringRate xsi:nil="true" />
<MaxHiringRate xsi:nil="true" />
<HiringRate>10.30000</HiringRate>
<JobType>0</JobType>
<TravelPercentage>30</TravelPercentage>
<TravelRequired>1</TravelRequired>
<TelecommutePercentage>10</TelecommutePercentage>
</Job></ArrayOfJob>

Example JSON Response

[{
"Title": "Store 110 - Accessories Associate",
"Description": "Sample desc",
"ClientSiteName": "Client Careers Site",
"ClientSiteXrefCode": "CANDIDATEPORTAL",
"CompanyName": "XYZ Co.",
"ParentCompanyName": "XYZ Co.",
"JobDetailsUrl": "http://localhost:51009/en-
US/DFLocal/Posting/View/17",
"ApplyUrl": "https://prdemo.dayforcehcm.com/CandidatePortal/en-
US/prdemo2/JobPosting/Job?jobId=17",
"City": "San Francisco",
"State": "CA",
"Country": "USA",
"PostalCode": "30009",
"Education": "Master’s Degree",
"JobFunction": "General and Operations Manager",
"EmploymentIndicator": "Contractor",
"DatePosted": "2014-06-13T00:00:00",
"LastUpdated": "2014-06-13T17:06:44.16",
"ReferenceNumber": 17,
"ParentRequisitionId": 3,
"HiringRate": 10.3,
"JobType": 0,
"TravelPercentage": 30,
"TravelRequired": 1,
"TelecommutePercentage": 10
}]

Sample Code - Get Job Feeds

Page 188 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
The following figure shows the sample code used to retrieve a job feed:

Error Codes

The following error codes can be returned:

l JOBFEED_INVALID_CLIENT_PROPERTY: The Dayforce client property that controls
access to this endpoint is currently not enabled. Contact the Dayforce client's system admin-
istrator to inquire about enabling the client property.
l JOBFEED_QUERY_PARAMETER_NOT_FOUND: Values for the Last Update Time
From or Last Update Time To parameters were not found. The Last Update Time
From and Last Update Time To parameters are required when the Include Active
Postings Only parameter is set to the value of False.
l JOBFEED_INVALID_DATE_RANGE: An invalid Last Update time range was specified.
The range specified between the Last Update Time From and Last Update Time
To parameters must not be larger than 1 month.

Page 189 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Integrations with Candidate Assessment
Providers

Before you begin: Integrating with a third-party candidate assessment provider also requires
setup in Dayforce. See "Configure the Use of Assessments" in the Recruiting Guide. You also
need to provide the base URL for all calls out and the URL for the authentication tokens to the
integrator site to Ceridian HCM, Inc. so that the primary setup steps can be completed.

The topics listed below contain more information about the RESTful endpoints that need to be
used for integrations with third-party candidate assessment providers.

The following endpoints are used by assessment providers to connect with Dayforce:
l RESTful GET Assessment List (see page 190)
l RESTful POST Candidate Assessment Registration (see page 191)
l RESTful POST Candidate Assessment Status (see page 193)

The following endpoints are provided by Dayforce to receive candidate assessment results:
l RESTful POST Candidate Reports (see page 193)
l RESTful POST Candidate Scores (see page 194)

RESTful GET Assessment List

The GET Assessment List API needs to be implemented by the candidate assessment
provider so that Dayforce can retrieve the list of all active assessments configured for the client.
Dayforce updates the assessment list using the records returned in the response.

Assessments that aren't part of the response are considered deleted or inactive.

Below is an example of the JSON response body expected by Dayforce and its required
information:
{
"CreationDateTime": "2019-11-20T07:01:56.266189Z",
"Assessments": [
{
"ShortName": "C #",
"LongName": "C Sharp",
"ReferenceCode": "C#"
},
{
"ShortName": "SQL",

Page 190 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 "LongName": "SQL",
"ReferenceCode": "SQL"
}
],
"StatusInfo": {
"Code": "Success"
}
}

Response schema parameters

Parameters Description
CreationDateTime Date the details were sent/received
Assessments* List of assessments
ShortName* Name of the assessment
LongName Description of the assessment
ReferenceCode* Provider reference code
StatusInfo* Information about the request status
Code* Status of the request
Message Additional message about any errors

RESTful POST Candidate Assessment

Registration
The POST Candidate Assessment Registration request allows Dayforce to register
candidates for assessments. The assessment link is expected as part of the response to this
request. Dayforce sends the link to candidates for them to complete the assessment.

The following is a sample request that Dayforce sends to providers:

{
"CreationDateTime": "2019-11-20T07:34:38.4435297Z",
"Candidate": {
"FirstName": "FSample",
"LastName": "LSample",
"EmailAddress": "[email protected]",
"Language": "en-us",
"CandidateId": 1234,
"IsCandidateInternal": true,
"CandidateAssessmentGuid": "6015AA33-5E91-41DE-994A-0F4C7F8FED6F"
},
"JobReqInfo": {
"JobReqId": 123,
"JobReqName": "The job requisition name",

Page 191 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 "DepartmentName": "Department name",
"OrgInfo": {
"ShortName": "wo",
"Address": "123 address",
"Address2": "Address 2",
"StateCode": "state code",
"PostalCode": "12345",
"CountryCode": "USA",
"PhysicalLocation": true
}
},
"AssessmentReference": "C#",
"PushBackLinks": {
"Scores": "https://pushbackurl.com/scores",
"Reports": "https://pushbackurl.com/reports"
}
}

Response schema parameters

Parameters Description
CreationDateTime Date the details were sent/received
AssessmentURL* Candidate assessment URL
CandidateAssessmentGuid* Dayforce candidate assessment reference
ReceiptId Provider candidate assessment reference
StatusInfo* Information about the request status
Code* Status of the request
Message Additional message about any errors

The following is a sample response that Dayforce is expecting from the provider. Note that the
ReceiptId is the assessment provider’s unique identifier for the assessment request:
{
"CreationDateTime": "2019-11-20T10:12:00.9402311Z",
"AssessmentURL": "http://sample-assessment-url.com",
"CandidateAssessmentGuid": "6015AA33-5E91-41DE-994A-0F4C7F8FED6F",
"ReceiptId": "123",
"StatusInfo": {
"Code": "Success"
}
}

Page 192 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
RESTful POST Candidate Assessment
Status
The POST Candidate Assessment Status endpoint needs to be implemented by the
assessment provider so that Dayforce can retrieve candidate assessment statuses. The
assessment status, indicating whether the candidate has completed the assessment, is returned
as part of the response.

The following is a sample request that Dayforce sends to providers:

{
"CreationDateTime": "2019-11-20T10:23:31.733312Z",
"CandidateAssessmentGuid": "6015AA33-5E91-41DE-994A-0F4C7F8FED6F"
}

Response schema parameters

Parameters Description
CreationDateTime Date the details were sent/received
CandidateAssessmentGuid* Dayforce candidate assessment reference
Candidate assessment status: Not Started, Pending, In
AssessmentStatus*
Progress, Completed
StatusInfo* Information about the request status
Code* Status of the request
Message Additional message about any errors

The following is a sample response that Dayforce is expecting from the provider:
{
"CreationDateTime": "2019-11-20T10:26:49.0899826Z",
"CandidateAssessmentGuid": "6015AA33-5E91-41DE-994A-0F4C7F8FED6F",
"AssessmentStatus": "Completed",
"StatusInfo": {
"Code": "Success"
}
}

RESTful POST Candidate Reports

The POST Candidate Reports endpoint is used to post candidate assessment reports to
Dayforce when the candidate completes their assessment. Report links are expected in the
request body, from which the user can view the detailed reports. These links are available on
candidate profiles in Recruiting.

The following is a sample body that Dayforce is expecting from the provider:

Page 193 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
{
"CreationDateTime": "2019-11-20T12:03:54.6620461Z",
"CandidateAssessmentGuid": "6015AA33-5E91-41DE-994A-0F4C7F8FED6F",
"Reports": [
{
"ShortName": "sample report 1",
"ReportLink": "http://sample-report-url"
},
{
"ShortName": "sample report 2",
"ReportLink": "http://sample-report-url"
}
]
}

Response schema parameters

Parameters Description
CreationDateTime Date the details were sent/received
CandidateAssessmentGuid* Dayforce candidate assessment reference
Reports* List of candidate assessment reports
ShortName Report name
ReportLink* Report link
StatusInfo* Information about the request status
Code* Status of the request
Message Additional message about any errors

RESTful POST Candidate Scores

The POST Candidate Scores endpoint is used to post candidate assessment scores to
Dayforce when the candidate completes their assessment. The scores are displayed in candidate
profiles in Recruiting.

The following is a sample response that Dayforce is expecting from providers:

{
"CreationDateTime": "2019-11-20T11:12:52.8188554Z",
"CandidateAssessmentGuid": "6015AA33-5E91-41DE-994A-0F4C7F8FED6F",
"OverallScore": {
"Score": "90",
"ScoreType": "Percentile",
"PassFailed": false
},
"IsRecommended": true,
"RecommendationStatement": "This is a recommended statement",

Page 194 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 "DetailedScores": [
{
"ShortName": "C#",
"Score": "80",
"ScoreType": "Percentile",
"PassFailed": true
},
{
"ShortName": "SQL",
"Score": "30",
"ScoreType": "Percentile",
"PassFailed": false
}
]
"Reports": [
{
"ShortName": "sample report 1",
"ReportLink": "http://sample-report-url"
}
]
}

Response schema description

Parameters Description
CreationDateTime Date the details were sent/received
CandidateAssessmentGuid* Dayforce candidate assessment reference
OverallScore* Information about the candidate's overall assessment score
Score* Candidate assessment overall score
ScoreType The score type (for example, percentile)
PassFailed Has the candidate passed the assessment
IsRecommended Is the candidate recommended
RecommendationStatement Recommendation statement
DetailedScores List of details candidate assessment scores
ShortName* Name of the assessment
Score* Candidate score for the assessment
ScoreType The score type (for example, percentile)
PassFailed Has the candidate passed the assessment
Reports* List of candidate assessment reports
ShortName Report name
ReportLink* Report link

Page 195 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Response schema description
Parameters Description
StatusInfo* Information about the request status
Code* Status of the request
Message Additional message about any errors

Page 196 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Pagination of Response Data

In Dayforce Release 56, a paging mechanism was added so that some RESTful API endpoints
can return data in batches as pages. This was introduced to support large responses provided by
features like GET Reports and GET Employee Punches. This allows both server and client
to process each request with less data stored in memory and less data transmitted over the
network.

For these endpoints, the response is divided into pages. Each page contains a Paging record
with the link to the next page. The consuming application must check this Paging element to
determine if there is more data to retrieve. When there is more data, the Paging element contains
a Next property with the URI that points to the next page of data. You should use the URI to
retrieve the subsequent pages of data. The Next property in the Paging element for the last
page of data will have an empty string value. This is the indication to the client that this is the last
page of data.

The following is an example of the Paging element showing that there is another page of data to
retrieve:
{
"Data": {
... this content removed for brevity ...
},
"Paging": {
"Next":
"https://usconfigr56.dayforcehcm.com:443/Api/ddn/V1/Reports/Payroll_Earning_
Hours_
Detail?cursor=cqkkpzMM%252F2%252Fxkfm67LcyOdPhDj94GYLl2gLOeMPaIiVkx8K1r5iDc3B
qGkXo9qKU"
}
}

The following example shows the Paging element for the final page of data. The Next link is an
empty string:
{
"Data": {
... this content removed for brevity ...
},
"Paging": {
"Next": ""
}
}

Number of Records Per Page

Page 197 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Most APIs that paginate data return 1,000 records per page by default, but that is not a static
number of all APIs. You can specify the number of records you would like to receive per page by
specifying a pageSize query string parameter. Although setting the page size is not
recommended, it might be helpful in some scenarios, such as for testing purposes. If the
pageSize query parameter is not used (which is the recommended approach), then the server
uses a default value.

The following is an example that sets the page size to 2,500:

https://www.dayforcehcm.com/api/{clientName}/v1/Reports/
{reportXRefCode}?pageSize=2500

Next Page Link

The next page link is a complete URL that you can use to retrieve the next page of data without
modifying it. The URL contains the original query string parameters, plus an additional cursor
parameter and value. The server uses the cursor as a pointer within the original data so that it
understands what is the next set of data to return.

If there are no additional pages of data, the Next property will have a value of an empty string.

Page 198 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Data Authorization and Filtering

Data elements that are returned from Dayforce REST Services are limited and filtered based on
the field level and access authorizations associated with the default role of the user account that
was used to authenticate with. These authorizations are defined as part of the configuration of the
Dayforce application for web services use.

The user role must have access to the data for both the field level filtering and the access
authorizations. If either of these filters the data, the data will not be returned.

Note: The structure of the data will not change if data is filtered other than the unauthorized
properties will not be present on the response. Data is filtered by setting the data value to null or
the default value. There are two levels of filtering and authorization, described in the following
topics.

Field Level Filtering

To limit the number of fields returned, a white list of fields is configured using Dayforce to indicate
which fields can be returned.

The list is associated to specific client and user role, so different users having different roles can
receive different data elements.

The list of allowed fields is specified using the data contract class and property names so they’ll
match exactly the names used in the JSON response.

See the Dayforce Web Services Configuration Guide.

Access Authorizations
Each data element that is returned from Dayforce REST Services might have an access
authorization associated with it. The access authorization limits the data that can be returned.
Access authorizations are hard-coded on the data contract and aren't customizable. The access
authorizations used by Dayforce REST Services are the same as those used by the rest of the
Dayforce application.

For example, many properties of the Employee class are controlled by the Employee Personal
Information access authorization. If you add this access authorization on the default role of the
user that was used during authentication, you can see properties such as names and dates.

Page 199 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Check for Errors

All Dayforce REST APIs return an HTTP Status code of 200 if the request was successful. Other
possible error codes include 400 level error codes indicating an issue with the request itself, or
500 level codes indicating the server is not functioning properly.

In the case of a unsuccessful request, you should always check the body of the response to
determine if there is any additional information to help in resolving the error.

The following method is called from the above code samples to check for an error and display the
content of the response body:

Additionally, read ProcessResult Messages on page 58. The process results are messages that
will assist you in resolving issues with requests that result in 400 level HTTP status codes.

Page 200 of 200

Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.