REST Services for Updating Employee Information

The following topics describe the foundational concepts and methods for retrieving employee information using RESTful Web Services:

• URL Endpoint
• Request to Update an Employee
• Validation of Employee Data

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
         }
      ]
   }
}

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:

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:

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?isValidateOnly=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 isn’t 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 isn’t valid.