Using the Dayforce DPI

What is the Dayforce Payroll Interface?

The Dayforce Payroll Interface (DPI) is a collection of standard interfaces provided through Dayforce designed to enable Payroll applications to integrate with Dayforce and accurately process local payroll.

DPI enables global payroll processing for employees that reside in countries and locations where Dayforce does not offer payroll natively, as well as accepting the results of that local payroll process back to Dayforce

Payroll Partners are to leverage the standard interfaces to facilitate a faster onboarding of new countries the partner could service, reduce software upgrade and maintenance costs as changes occur, as well as enabling a high-quality customer experience through increased payroll accuracy and timelines that the standard interfaces and improved data quality provides. 

Getting Started and Responsibility of the Payroll Partner

You’ll need the following to start using the Dayforce Payroll Interface:

  • An understanding of the data structures in the Dayforce Payroll Interface listed above.
  • A middleware application that can:
    • Receive and process the interfaces that send data from Dayforce to the Payroll Partner
    • Generate and transmit back the interfaces that send data from the Payroll Partner to Dayforce.
  • A way to upload and download files using SFTP (if required)
  • Access to a Dayforce environment with test data tailored to the country or countries you’re working with

Important: You’ll need to be comfortable creating a middleware application. This document points you to code samples that might help you get started, but it does not provide guidance on how to write code to work with APIs or the Dayforce Payroll Interface. Your middleware might be something you have developed, or it might be a commercial IPaaS or ETL solution.

Interfaces

Dayforce to Payroll Partner

Interface Description Available As
Employee Data A dataset focused on employee HR data and recurring payroll earnings and deductions. JSON
Payroll Quick Entries A dataset containing one-time or variable earnings and deductions. JSON
Time and Attendance Data A dataset containing gross pay, pay adjustments, and timesheet summaries. JSON

Payroll Partner to Dayforce

Interface Description Available As
Global Pay Run Data A dataset containing the results of the pay run. XML, CSV
Pay Slips A dataset containing employee pay slip information which enables employees to view their own pay slips inside of Dayforce. JSON


The integrations between Dayforce and the Payroll Partner will follow a ‘push’ model.  Meaning, Dayforce, after all time, pay and HR data edits have been completed, will push the data along the interfaces to the Payroll Partner.   The model exists in the reverse as well.  After payroll has been calculated and all the necessary tasks completed in the Payroll Partner system, the Payroll Partner will push the data along the interfaces back to Dayforce. 


DPI - Employee Data

This section will provide specifics on the Dayforce Payroll Interface for Employee Data.  This interface can be sent to REST API endpoints (JSON.)

At a high level, this interface describes the Dayforce Employee Object.  The output of this interface is a collection of Employee objects configured per customer to be sent to the Payroll Provider.

The Employee Object contains two key data types:  Core Employee Data and Additional Properties.

Core Employee Data

These data fields and collections are natively available in Dayforce as part of the core Employee Data model. Data fields reside directly on the Employee object.  An employee is considered to have one of these data fields.  An example of this would be First Name or Birth Date.
 

--Sample expressed as JSON. Notice how this employee has one reference code, first name, and birth date.
{
  "Employee": [
    {
      "EmployeeXrefCode": "1003",
      "EmployeeNumber": "1003",
      "FirstName": "EF1008",
      "MiddleName": "EM1008",
      "LastName": "EL1008",
      "BirthDate": "1970-10-18",
      "HireDate": "1990-10-18",
      "TerminationDate": null,
…

Data collections are attached to the Employee object.  An employee could have zero or many of these entities.  An example of this would be Work Assignments or Addresses.

--Sample expressed as JSON.  Notice how this employee has multiple work assignments.
{
  "Employee": [
    {
      "EmployeeXrefCode": "1003",
      "EmployeeNumber": "1003",
      "FirstName": "EF1008",
      …
      …
      "WorkAssignments": {
        "WorkAssignment": [
          {
            "EffectiveStart": "1990-10-18",
            "EffectiveEnd": null,
            "JobStatusReason": null,
            "Job": "JOB1",
            "Department": "DEPARTMENT",
            "Location": "LOCATION1",
            "Position": "DEPARTMENT_JOB1",
            "IsPrimary": true
          },
          {
            "EffectiveStart": "1990-10-18",
            "EffectiveEnd": null,
            "JobStatusReason": null,
            "Job": "JOB2",
            "Department": "DEPARTMENT",
            "Location": "LOCATION1",
            "Position": "DEPARTMENT_JOB2",
            "IsPrimary": false
          }
        ]
      },

Additional Properties

This section contains the extended data fields and collections created to support country specific compliant HR and Payroll.  These data fields and collections are extensions on Dayforce’s Core Employee Data Model.

Important:  This section is where Payroll Partners can expect to find all fields required to provide compliant local payroll.  As part of the Dayforce Payroll Partner certification process, the Payroll Partner will work with the Dayforce team to ensure the required country specific fields are added to Dayforce as well as adding the fields to this section of the interface.

An employee can have both data fields and collections defined in the Additional Properties area, depending on the requirements of the country and payroll provider. 

For the full specification, see the companion detailed specifications.

Effective Dating in Dayforce

It is important to understand that Dayforce maintains the employee record as a date-effective stack. This means, for example, if you want to ask Dayforce for an employee’s marital status, you need to specify when.  If you ask for that information as of 3 years ago, Dayforce could say the employee was single, but if you ask for it as-of today, it might tell you the employee is married.

This applies to other data as well, such as salary changes. It is important to understand that Dayforce is aware of both when a change is effective and when the change was made. Imagine a change to an employee’s salary that is made today. That change could be effective three weeks in the past, two months in the future, or today. This means that Dayforce can tell you about retroactive changes (those that affect previously closed pay periods) and future-dated changes (those that aren’t yet effective) in addition to those effective today. If your systems don’t manage data in the same way that Dayforce does, you need to adjust the date effectiveness parameters available in the Interface.

Therefore, in the DPI – Employee Data interface, all entities identified as arrays in the specification could potentially contain multiple date effective records.

If the payroll system can support date effective records, the interface can be configured to return the full employee history, the full record within the current pay period, or all current and future records.

If the payroll system cannot sort through a collection of date effective records, the interface can be configured to send the most current record, the most future record, and in some cases the ‘primary’ record (see Work Assignments).

Changes Only

The DPI – Employee Data interface can be configured to only send the employees that have changed since the last execution of the interface.  This, coupled with a small schedule frequency, ensures the amount of data flowing through the interface remains small. 

While only the changed employees will be sent, the full payload of each employee will be transmitted (subject to the effective dated parameters already mentioned).


DPI - Time and Attendance Data

This section will provide specifics on the Dayforce Payroll Interface for Time and Attendance Data.  This interface can be sent to REST API endpoints (JSON.).

The time and attendance dataset is inclusive of all zero to gross time calculations, including any manual pay adjustments and time away from work (vacation, sick, etc..) requests.

The interface provides granular gross time detail per time-segment in an easy to consume flat data model.

Example: if an employee starts a shift at 9:00am, takes 1 hour of lunch starting at 12:00pm, takes a 15 minute break at 2:00pm, then finishes work at 5:00pm, the gross time details could look like this.

Employee XrefCode Pay
Date		 Business Date Time
Start		 Time End Pay Code Pay Category Hours Rate Amount
12345 Jan 31 2023 Jan 20 2023 9:00 am 12:00 pm WRK REG 3.00 10.00 30.00
12345 Jan 31 2023 Jan 20 2023 12:00 pm 1:00 pm MEAL UNPAID 1.00 0.00 0.00
12345 Jan 31 2023 Jan 20 2023 1:00 pm 2:00 pm WRK REG 1.00 10.00 10.00
12345 Jan 31 2023 Jan 20 2023 2:00 pm 2:15 pm BRK UNPAID 0.25 0.00 0.00
12345 Jan 31 2023 Jan 20 2023 2:15 pm 5:00 pm WRK REG 2.45 10.00 24.50
  
--Sample expressed as JSON.  
{
    "EmployeeXRefCode": "1003",
    "PositionXRefCode": "DEPARTMENT_JOB1",
    "DepartmentXRefCode": "DEPARTMENT",
    "JobXRefCode": "JOB1",
    "PayCodeXRefCode": "WRK",
    "PayCategoryXRefCode": "Reg",
    "LocationXRefCode": "LOCATION1",
    "ProjectXRefCode": null,
    "DocketXRefCode": null,
    "PayDate": "2023-05-26",
    "BusinessDate": "2023-05-26",
    "TimeStart": "2023-05-26 09:00:00",
    "TimeEnd": "2023-05-26 17:00:00",
    "NetHours": 8.00,
    "MinuteDuration": 480.00,
    "Rate": 2.00,
    "PayAmount": 16.00,
    "IsRetro": false
  }
For the full specification, see the companion detailed specifications.

Retroactive Changes

Any changes to an employee’s time in a period that has already been paid is called a “retro”.  Retro changes can be identified by the IsRetro field equaling true. 


DPI - Payroll Quick Entries

This section will provide specifics on the Dayforce Payroll Interface for Payroll Quick Entry data.  This interface can be sent to REST API endpoints (JSON.).

The payroll quick entry dataset is inclusive of manual entries performed by the payroll administrator.  These are typically done as part of the regular payroll cycle before it is processed, or as separate off-cycle pay runs. 

The interface provides granular payroll quick entries in an easy to consume flat data model.
 

--​Sample expressed as JSON.  
{
    "EntryType": "PAYROLL_QE",
    "PayGroupXRefCode": "PAYGROUP_01",
    "Currency": "USD",
    "PeriodStart": "2023-05-26",
    "PeriodEnd": "2023-06-08",
    "PPN": "12-00",
    "PayDate": "2023-06-16",
    "EmployeeXRefCode": "1003",
    "Replace": false,
    "CodeType": "Earning",
    "CodeXRefCode": "REGULAR",
    "Hours": 10.00,
    "Rate": 2.00,
    "Amount": 20.00,
    …
}

For the full specification, see the companion detailed specifications.


DPI - Global Pay Run Import (GPRI)

This section will provide specifics on the Dayforce Payroll Interface for Global Pay Run Import (GPRI).  This interface needs to be sent to Dayforce as an XML or CSV file.

The GPRI interface contains transactional pay run details for the employee, as calculated by the Payroll Partner.  After a payroll is successfully processed by the Payroll Partner, the Global Dayforce Payroll solution requires the Payroll Partner to send back to Dayforce the pay run details so the customer can have centralized access to all pay run data in support of auditing and reporting requirements.

--Sample expressed as XML.  
<GlobalPayRunImport>
    <PayRunImport> 
        <PayDate>2013-04-26</PayDate> 
        <PayPeriod>01</PayPeriod> 
        <IsOffCycle>0</IsOffCycle> 
        <NoOverride>0</NoOverride> 
        <CommitDate>2013-04-20</CommitDate> 
        <PayGroupXrefCode>PGStores</PayGroupXrefCode> 
        <PayPeriodStart>2013-04-01</PayPeriodStart> 
        <PayPeriodEnd>2013-05-01</PayPeriodEnd> 
        <EmployeeXrefCode>100124</EmployeeXrefCode> 
        <LegalEntityXrefCode>PGLE</LegalEntityXrefCode> 
        <ItemType>Earning</ItemType> 
        <ItemCode>Regular</ItemCode> 
        <ItemAmount>2083.33</ItemAmount>
        <Units>0</Units> 
        <Rate>0</Rate> 
        <ContributeToNetPay>1</ContributeToNetPay> 
        <IsPreTax>0</IsPreTax> 
        <IsEmployerDeduction>0</IsEmployerDeduction> 
        <IsEmployerTax>0</IsEmployerTax> 
    </PayRunImport>
    <PayRunImport> 
        <PayDate>2013-04-26</PayDate> 
        <PayPeriod>1</PayPeriod> 
        <IsOffCycle>0</IsOffCycle> 
        <NoOverride>0</NoOverride> 
        <CommitDate>2013-04-20</CommitDate> 
        <PayGroupXrefCode>PGStores</PayGroupXrefCode> 
        <PayPeriodStart>2013-04-01</PayPeriodStart> 
        <PayPeriodEnd>2013-05-01</PayPeriodEnd> 
        <EmployeeXrefCode>100131</EmployeeXrefCode> 
        <LegalEntityXrefCode>PGLE</LegalEntityXrefCode> 
        <ItemType>Deduction</ItemType> 
        <ItemCode>EE Pension</ItemCode> 
        <ItemAmount>6.4</ItemAmount> 
        <Units>0</Units> 
        <Rate>0</Rate> 
        <ContributeToNetPay>0</ContributeToNetPay> 
        <IsPreTax>1</IsPreTax> 
        <IsEmployerDeduction>0</IsEmployerDeduction> 
        <IsEmployerTax>0</IsEmployerTax> 
    </PayRunImport> 
    …
</GlobalPayRunImport>

For the full specification, see the companion detailed specifications.


DPI - Pay Slips

This section will provide specifics on the Dayforce Payroll Interface for Pay Slip data.  Pay Slips can be uploaded to Dayforce’s Document Management datastore via a POST to the /{clientNamespace}/V1/Document/Upload API.

Sending pay slips back to Dayforce enables global employees access to their pay slips inside the Dayforce Self Service or Mobile app.

For the full specification, see the companion detailed specifications.

 

For the full specification, see the companion detailed specifications.