REST Service for Adding Employee Raw Clock Entries

The following topics describe the foundational concepts and methods for adding employee raw clock entries using RESTful Web Services:

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",
  "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	Required	Description
EmployeeBadge	STRING	TRUE	The badge number of the employee.
RawPunchTime	STRING	TRUE	The datetime, with UTC offset, of when the clock entry occurred.
PunchType	STRING	TRUE	The type of clock entry. See the Clock Entry Type section below for a list of allowed values.
PunchDevice	STRING	TRUE	The MAC address of the clock. It must be a clock where the device type is API.
SupervisorBadge	STRING	FALSE	The badge number of the supervisor clocking in on behalf of the employee.
LocationXRefCode	STRING	FALSE	The reference code for the organization.
LocationClockTransferCode	STRING	FALSE	The clock code for the organization.
PositionXRefCode	STRING	FALSE	The reference code for the position.
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.
TypeXRefCode	STRING	FALSE	The reference code for the labor metric type.
TypeClockTransferCode	STRING	FALSE	The clock code for the labor metric code.
CodeXRefCode	STRING	FALSE	The reference code for the labor metric code.
CodeClockTransferCode	STRING	FALSE	The clock code for the labor metric code.
MealWaiver	STRING	FALSE	Specifies which meal, if any, is being waived (0 = None, 1 = First Meal, 2 = Second Meal).
BreakAttestation	BOOLEAN	FALSE	Specifies whether the employee worked through his/her break.

Punch Type Field

Valid clock entry 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.
Transfer	Can be used for any type of transfer and for multiple transfers (for example, docket, project, or combined). This clock entry type is recommended for all transfers.
Docket_Transfer	Used to transfer dockets and, optionally, quantity.
Quantity	Used to change docket quantity without transferring dockets.
Project _Transfer	Used to transfer projects.
Combined_Transfer	Used for a location and position transfer.
Meal_Subsidy	The end of the employee's shift with a meal waiver. To be used when submitted MealWaiver.
Labor_Metrics_Transfer	Used for labor metric 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 clock entry
PunchType	Level	Message
Punch_In	Info	FIRST_NAME LAST_NAME(BADGE_NUMBER) Clocked in at TIME AM/PM
Break_Out	Info	FIRST_NAME LAST_NAME(BADGE_NUMBER) Clocked out for break at TIME AM/PM
Break_In	Info	FIRST_NAME LAST_NAME(BADGE_NUMBER) Clocked in from break at TIME AM/PM
Meal_Out	Info	FIRST_NAME LAST_NAME(BADGE_NUMBER) Clocked out for meal at TIME AM/PM
Meal_In	Info	FIRST_NAME LAST_NAME(BADGE_NUMBER) Clocked in from meal at TIME AM/PM
Punch_Out	Info	FIRST_NAME LAST_NAME(BADGE_NUMBER) Clocked out at TIME AM/PM

Error Responses

There are two types of errors that can be returned:

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).
An HTTP 200 response is returned when the record can be processed but there is a problem (for example, clock entry order validation error caused by submitting two clock ins).

HTTP 400 Responses

HTTP 400 response reasons
Level	Code	Description
Error	WFM_PUNCH_FIELD_REQUIRED_EMPLOYEE_BADGE	Employee badge is required.
Error	WFM_PUNCH_FIELD_REQUIRED_PUNCH_TYPE	Clock Entry Type is required.
Error	WFM_PUNCH_FIELD_REQUIRED_PUNCH_DEVICE	Clock Entry Device is required.
Error	WFM_PUNCH_FIELD_REQUIRED_PUNCH_TIME	Raw clock entry time is required.
Error	WFM_PUNCH_FIELD_INVALID_PUNCH_TYPE	Clock Entry Type is invalid.
Error	WFM_PUNCH_FIELDS_ONE_ONLY_REQUIRED _CLOCK_CODE_XREF_CODE	Invalid specification of transfer code. Transfer must specify either XRef Code/Reference Code or Clock Code, but not both.
Error	WFM_PUNCH_FIELD_INVALID_PUNCH_DEVICE	Clock Entry Device is invalid. Device Type must be API.
Error	WFM_PUNCH_FIELD_INVALID_PUNCH_TIME	Format of raw clock entry time is invalid.

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 clock entry time is invalid
Error	Clock Entry Type is invalid
Error	Clock Entry 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>
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>