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 Clock Entries, and Employee Raw Clock Entry 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
xRefCode (required)	The unique identifier (external reference code) of the employee to be retrieved. The value provided must be the exact match for an employee; otherwise, a bad request (400) error will be returned.
filterAvailabilityStartDate (required)	Inclusive period start date to determine which employee availability data to retrieve. Example: 2017-01-01T00:00:00.
filterAvailabilityEndDate (required)	Inclusive period end date to determine which employee availability 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"
        },
        {
            "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:

Sample code for Retrieve Availability Data.

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

Query string parameters to filter schedules
Parameter	Description
xRefCode (required)	The unique identifier (external reference code) of the employee to be retrieved. The value provided must be the exact match for an employee; otherwise, a bad request (400) error will be returned.
filterScheduleStartDate (required)	Inclusive period start aligned to the employee business day start date to determine which employee schedule data to retrieve. Example: 2017-01-01T00:00:00.
filterScheduleEndDate (required)	Inclusive period end aligned to the employee business day start to determine which employee availability data to retrieve. Example: 2017-01-01T00:00:00.
isPosted	A flag to determine whether to display posted schedules. By default it searches for published schedules.
expand	This parameter accepts a comma-separated list of top-level entities that contain the data elements needed for downstream processing. When this parameter isn’t 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",
            "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

Sample code for Retrieve Schedule Data.

Expanding for more Schedule Details

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
xRefCode (required)	The unique identifier (external reference code) of the employee to be retrieved. The value provided must be the exact match for an employee; otherwise, a bad request (400) error will be returned.
filterTAFWStartDate (required)	Inclusive period start date to determine which employee time away from work data to retrieve. Example: 2017-01-01T13:24:56.
filterTAFWEndDate (required)	Inclusive period end date to determine which employee time away from work data to retrieve. Example: 2017-01-01T13:24:56.
status (required)	A case-sensitive field containing status for time away from work values. Examples: [APPROVED, PENDING, CANCELED, DENIED, 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	
        }
    ]
}

Sample Code – Retrieve Time Away Data

Sample code for Retrieve Time Away Data.

Retrieve Employee Clock Entries Data

The following function will retrieve a list of employee clock entry data for all employees within the specified date range via RESTful web service.

GET https://www.dayforcehcm.com/api/<clientName>/v1/EmployeePunches?filterTransactionTimeEndUtc=2019-01-21&filterTransactionTimeStartUtc=2019-01-01&EmployeeXRefCode=30896

Sample code for Retrieve Employee Punch Data.

 {
    "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
}

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.

Retrieve Employee Raw Clock Entries Data

The following function will retrieve a list of employee raw clock entry data for all employees within the specified date range via RESTful web service:

GET https://www.dayforcehcm.com/api/<clientName>/v1/EmployeeRawPunches?filterTransactionTimeEndUtc=2019-01-21&filterTransactionTimeStartUtc=2019-01-01

Query string parameters to filter raw clock entry requests
Parameter	Description
FilterTransactionStartTimeUTC (required)	The start time of the period for which to retrieve raw clock entry records. Example: `2017-01-01T13:24:56`.
FilterTransactionEndTimeUTC (required)	The end time of the period for which to retrieve raw clock entry records. Example: `2017-01-01T13:24:56`.
EmployeeXRefCode	Reference code associated with the employee whose raw clock entry data is to be retrieved.
EmployeeBadge	The badge number for the employee whose raw clock entry data is to be retrieved.
PunchState	Reference code for the state of the clock entry. Accepted values: ALL REJECTED PROCESSED
PunchTypes	The type of clock entries to be retrieved. Accepted values: ANY NONE PUNCH_IN BREAK_OUT BREAK_IN MEAL_OUT MEAL_IN PUNCH_OUT JOB_TRANSFER DECLARE_TIPS DIRECTIONLESS SHIFT_OVERRIDE LOCATION_TRANSFER DOCKET PROJECT RELAY_CONTROL QUANTITY COMBINED_TRANSFER MEAL_SUBSIDY TRANSFER LABOR_METRICS_TRANSFER

Response

The response from this request will contain data from employees' raw clock entries. 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",
        "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.

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?filterTransactionTimeEndUtc=2020-01-21&filterTransactionTimeStartUtc=2020-01-01

Query string parameters to filter pay summary requests
Parameter	Description
filterTransactionStartTimeUTC (required)	The start time of the period for which to retrieve pay summary records. Example: `2017-01-01T13:24:56`.
filterTransactionEndTimeUTC (required)	The end time of the period for which to retrieve pay summary records. Example: `2017-01-01T13:24:56`.
employeeXRefCode	Reference code associated with the employee whose pay summary data is to be retrieved.
locationXRefCode	Reference code for the location of the pay summary to be 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",
			"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?filterTransactionTimeEndUtc=2020-01-21&filterTransactionTimeStartUtc=2020-01-01

Query string parameters to filter pay adjustment requests
Parameter	Description
filterPayAdjustmentStartDate (required)	The start time of the period for which to retrieve employee pay adjustment data. Example: `2017-01-01T13:24:56`.
filterPayAdjustmentEndDate (required)	The end time of the period for which to retrieve employee pay adjustment data. Example: `2017-01-01T13:24:56`.
filterLastModifiedStartDateUTC	Inclusive start date (in UTC format) of the filter period for which pay adjustments were modified.
filterLastModifiedEndDateUTC	Inclusive end date (in UTC format) of the filter period for which pay adjustments were modified.
orgUnitXRefCode	A case-sensitive field that identifies a unique organization.
employeeXRefCode	A case-sensitive field that identifies a unique employee.
payAdjustmentCodeXRefCode	A case-sensitive field that identifies a unique pay adjustment code.
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.
referenceDate	Inclusive period reference date in UTC to determine which employee pay adjustment data to retrieve. Example: 2017-01-01T00:00:00.
managerAuthorized	A flag to determine if a pay adjustment is manager authorized.
employeeAuthorized	A flag to determine if a pay adjustment is employee authorized.
employeePayAdjustXRefCode	A case-sensitive field that identifies a unique employee pay adjustment.
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:

Copy

{
  "Data": [
    {
      "EmployeePayAdjustXRefCode": "string",
      "AdjustPeriodStartDate": "2024-10-15T19:30:55.581Z",
      "AdjustPeriodEndDate": "2024-10-15T19:30:55.581Z",
      "EmployeeXRefCode": "string",
      "DepartmentXRefCode": "string",
      "JobXRefCode": "string",
      "PayAdjustmentCodeXRefCode": "string",
      "PayCategoryXRefCode": "string",
      "PayDate": "2024-10-15T19:30:55.581Z",
      "OrgUnitXRefCode": "string",
      "IsPremium": true,
      "IsDeleted": true,
      "TimeStart": "2024-10-15T19:30:55.581Z",
      "TimeEnd": "2024-10-15T19:30:55.581Z",
      "Hours": 0,
      "Rate": 0,
      "Amount": 0,
      "ReferenceDate": "2024-10-15T19:30:55.581Z",
      "ProjectXRefCode": "string",
      "DocketXRefCode": "string",
      "PieceQuantity": 0,
      "EmployeeComment": "string",
      "ManagerComment": "string",
      "EmployeeAuthorized": true,
      "ManagerAuthorized": true,
      "LaborMetrics": [
        {
          "LaborMetricsTypeXRefCode": "string",
          "LaborMetricsCodeXRefCode": "string"
        }
      ],
      "LastModifiedTimestampUtc": "2024-10-15T19:30:55.581Z"
    }
  ],
  "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.

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?filterTransactionTimeEndUtc=2020-01-21&filterTransactionTimeStartUtc=2020-01-01

Query string parameters to filter employee schedule requests
Parameter	Description
OrgUnitXRefCode (required)	Filter by organization XRefCode.
FilterTransactionStartTimeUTC (required)	The start time of the period for which to retrieve employee schedule records. Example: `2017-01-01T13:24:56`.
FilterTransactionEndTimeUTC (required)	The end time of the period for which to retrieve employee schedule records. Example: `2017-01-01T13:24:56`.
EmployeeXRefCode	Reference code associated with the employee whose schedule data is to be retrieved.
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.
Expand	This parameter accepts a comma-separated list of top-level entities that contain the data elements needed for downstream processing. When this parameter isn’t used, only data elements from the master record will be included. See the Dayforce Web Services Introduction Guide. This parameter 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",
			    "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.

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?filterTransactionTimeEndUtc=2020-01-21&filterTransactionTimeStartUtc=2020-01-01

Query string parameters to filter payroll tax requests
Parameter	Description
XRefCode (required)	The unique identifier (external reference code) of the employee whose data will be retrieved. The value provided must be the exact match for an employee or a bad 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"
		     }
		    ]