REST Services for Retrieving Employee Information

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

• URL Endpoint
• Employee API Proxy Class
• Use Specific Criteria to Retrieve Employee XRefCodes
• Retrieve Details for Individual Employees

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.

The following sample code demonstrates instantiating the EmployeesApi class:

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:

ContextDate

EmployeeNumber

EmployeeXRefCode

EmploymentStatusXRefCode

FilterHireEndDate

FilterHireStartDate

FilterTerminationEndDate

FilterTerminationStartDate

OrgUnitXRefCode

FilterUpdatedEndDate

FilterUpdatedStartDate

filterUpdatedEntities

filterUpdatedEntities=EmploymentStatuses,WorkAssignments,Addresses,Contacts

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

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.

After 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

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

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 isn’t 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

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.

Note: Collections such as Addresses or WorkAssignments aren't standard collections. They are classes which have two properties, a DateInsertBehavior property and an Items 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:

• Addresses: Retrieve employee address information.
• AuthorizationAssignments: Retrieve employee access authorization information from the Work > Authorization Assignments screen in People.
• CANFederalTaxes: Retrieve Canadian federal taxes information.
• CANStateTaxes: Retrieve Canadian state taxes information.
• CANTaxStatuses: Retrieve Canadian provincial tax filing status information, such as single or married.
• ClockDeviceGroups: Retrieve clock device group assignments.
• CompensationSummary: Retrieve historical employee compensation changes.
• Contacts: Retrieve employee contact information.
• Courses: Retrieve employee course assignments.
• DirectDeposits: Retrieve employee direct deposit information.
• DocumentManagementSecurityGroups: Retrieve employee document security groups.
• EIRates: Retrieve employee legal entity and premium rate information.
• EmergencyContacts: Retrieve employee emergency contact information.
• EmployeeManagers: Retrieve employee manager assignments.
• EmployeePronouns: Retrieve employee pronouns.
• EmployeeProperties: Retrieve employee property information.
• EmployeePayAdjustCodeGroups: Retrieve employee pay adjustment groups information.
• EmployeeWorkAssignmentManagers: Retrieve employee direct manager assignments.
• EmploymentAgreements: Retrieve employee employment agreement information.
• EmploymentStatuses: Retrieve employment status information.
• EmploymentTypes: Retrieve employee employment types, such as contractor, pensioner, or employee.
• Ethnicities: Retrieve employee ethnicity information.
• GLSplit: Retrieve GL split data from the Payroll > GL Splits screen of People.
• HealthWellnessDetails: Retrieve employee health and wellness information.
• HighlyCompensatedEmployees: Retrieve the highly compensated employee indicator.
• HRIncidents: Retrieve employee HR incident details.
• LaborDefaults: Retrieve employee labor default details.
• Locations: Retrieve employee location and authority assignments.
• MaritalStatuses: Retrieve employee marital status information.
• OnboardingPolicies: Retrieve employee onboarding policy assignments.
• OrgUnitInfos: Retrieve employee organization assignment information.
• PayGradeRates: Retrieve employee pay grade rates related to their position rate policies.
• PerformanceRatings: Retrieve employee performance rating information.
• Roles: Retrieve employee role assignment details.
• Skills: Retrieve employee skill information.
• SSOAccounts: Retrieve employee SSO account assignments.
• TrainingPrograms: Retrieve information about employee training program assignments.
• UnionMemberships: Retrieve employee union membership information.
• UserPayAdjustCodeGroups: Retrieve users' pay adjustment code groups.
• USFederalTaxes: Retrieve employee US federal tax information.
• USStateTaxes: Retrieve employee US state tax information.
• USTaxStatuses: Retrieve US tax status information, such as state filing status single or married.
• WorkAssignments: Retrieve employee work assignment details.
• WorkContracts: Retrieve employee work contract and associated work pattern information.

Most of the subordinate endpoints listed above support the ContextDate, ContextDateRangeFrom, and ContextDateRangeTo parameters. See REST Services for Retrieving Employee Information.

• Courses
• DirectDeposits
• DocumentManagementSecurityGroups
• EmployeePayAdjustCodeGroups
• HRIncidents
• OrgUnitInfos
• PerformanceRatings
• TrainingPrograms
• UserPayAdjustCodeGroups