Overview

The Dayforce connector enables your AI Colleagues to integrate with your organization's Dayforce HCM platform using the REST API connector, facilitating automated HR workflows, employee data management, and workforce operations.

Dayforce is a comprehensive human capital management (HCM) cloud platform by Ceridian that covers the entire employee lifecycle including HR, payroll, benefits, talent management, workforce management, and time & attendance. The REST API connector allows Leena AI to automate HR workflows, manage employee data, and interact with Dayforce seamlessly.

API Details

Leena AI integrates with Dayforce via REST APIs using the REST API connector.

Documentation link: https://developers.dayforce.com

Setup

The Dayforce integration uses the REST API connector and supports two authentication methods: Basic Authentication and OAuth 2.0 Token-based Authentication. Choose the method that best fits your organization's security requirements.

Prerequisites

Before setting up the Dayforce connector via REST API, ensure you have:

• A Dayforce Developer Network account (create one at developers.dayforce.com)
• Access to your Dayforce HCM environment
• API credentials (Username and Password for Basic Auth, or Client ID and Client Secret for OAuth 2.0)
• Your organization's Client Namespace and Client Host URL
• Access to your Leena AI workspace with connector management permissions

Get credentials

Here is how to obtain Dayforce API credentials:

1. Create a Dayforce Developer Network Account:
   1. Navigate to https://developers.dayforce.com
   2. Click on "Sign Up" to create a new developer account
   3. Complete the registration process and verify your email
2. Access API Credentials:
   1. Log in to the Dayforce Developer Network
   2. Navigate to API Explorer > Employee > GET Employees
   3. Here you can find the basic authentication credentials (username and password) for the sample environment
   4. For production environments, contact your Dayforce administrator to obtain:
      • Username: A service account username (recommended for API access)
      • Password: The corresponding password
      • Client ID: OAuth 2.0 application client ID (for token-based auth)
      • Client Secret: OAuth 2.0 application client secret (for token-based auth)
3. Identify Your Client Namespace and Host:
   1. Client Host: Your Dayforce instance URL (e.g., usconfigr58.dayforcehcm.com for sample environment)
   2. Client Namespace: The API path component (e.g., ddn for sample environment)
   3. Token Endpoint: For OAuth 2.0, the token URL follows the format: https://{identity_host}/connect/token (e.g., https://dfidtst.np.dayforcehcm.com/connect/token for test environments)
   4. For production, these details are typically provided in your Dayforce welcome email or by your HR/IT administrator

Add connection - Option 1: Basic Authentication

Basic Authentication is the simplest method to connect to Dayforce. It uses username and password credentials encoded in the request header.

Here is how to add a connection on Leena AI using Basic Auth:

1. Log in to your Leena AI workspace
2. Navigate to Settings > Integrations
3. Search for "REST API" and select it from the list to add a new connector
4. Start configuring the connector:
   1. Auth Type: Select "Basic Auth" from the dropdown
   2. Username: Enter your Dayforce API username (e.g., DFWSTest for sample environment)
   3. Password: Enter your Dayforce API password
5. Save the connection configuration

Add connection - Option 2: OAuth 2.0 Authentication

OAuth 2.0 provides enhanced security through token-based authentication. Dayforce supports OAuth 2.0 to ensure secure access to data and protect against unauthorized access. This method is recommended for production environments.

Here is how to add a connection on Leena AI using OAuth 2.0:

1. Log in to your Leena AI workspace
2. Navigate to Settings > Integrations
3. Search for "REST API" and select it from the list to add a new connector
4. Start configuring the connector:
   1. Auth Type: Select "OAuth 2.0" from the dropdown
   2. Client ID: Enter your Dayforce OAuth application Client ID
   3. Client Secret: Enter your Dayforce OAuth application Client Secret
   4. Token URL: Enter your Dayforce token endpoint URL (e.g., https://dfidtst.np.dayforcehcm.com/connect/token)
   5. Grant Type: Select "Client Credentials"
   6. Scope: Enter required scopes as specified by your Dayforce administrator (if applicable)
5. Save the connection configuration

Base URL Configuration

When configuring actions, use the following Base URL format:

https://{client_host}/Api/{client_namespace}/V1

For the sample environment:

https://usconfigr58.dayforcehcm.com/Api/ddn/V1

Note: Dayforce API endpoints may redirect traffic. The REST API connector handles these redirects automatically while preserving authentication headers.

Actions

The following actions can be configured using the REST API connector for Dayforce:

Get Employees

Retrieves a list of employees from Dayforce. The Agent can leverage this action to fetch employee records based on various filter criteria.

Input Parameters

Here are the input parameters required to set up this action:

Action Configuration

Optional Query Parameters

Here is a sample configuration:

{
  "url": "https://usconfigr58.dayforcehcm.com/Api/ddn/V1/Employees",
  "httpMethod": "GET",
  "responseType": "JSON",
  "headers": [],
  "params": [
    {
      "key": "filterHireStartDate",
      "value": "2024-01-01"
    }
  ]
}

Response

The action returns a list of employees with basic information including XRefCode (unique employee identifier), employee number, and status.

Get Employee Details

Retrieves detailed information about a specific employee using their XRefCode.

Input Parameters

Here are the input parameters required to set up this action:

Action Configuration

Mandatory Path Parameters

Here is a sample configuration:

{
  "url": "https://usconfigr58.dayforcehcm.com/Api/ddn/V1/Employees/42199",
  "httpMethod": "GET",
  "responseType": "JSON",
  "headers": [],
  "params": []
}

Response

Returns comprehensive employee details including personal information, employment status, and organizational data.

Get Employee Address

Retrieves address information for a specific employee.

Input Parameters

Here are the input parameters required to set up this action:

Action Configuration

Mandatory Path Parameters

Here is a sample configuration:

{
  "url": "https://usconfigr58.dayforcehcm.com/Api/ddn/V1/Employees/42199/Addresses",
  "httpMethod": "GET",
  "responseType": "JSON",
  "headers": [],
  "params": []
}

Response

Returns the employee's address information including street address, city, state, postal code, and country.

Update Employee Address

Updates address information for a specific employee.

Input Parameters

Here are the input parameters required to set up this action:

Action Configuration

Mandatory Path Parameters

Here is a sample JSON input:

{
  "url": "https://usconfigr58.dayforcehcm.com/Api/ddn/V1/Employees/42199/Addresses",
  "httpMethod": "PATCH",
  "responseType": "JSON",
  "headers": [
    {
      "key": "Content-Type",
      "value": "application/json"
    }
  ],
  "params": [],
  "body": {
    "Address1": "123 Main Street",
    "City": "Minneapolis",
    "State": "MN",
    "PostalCode": "55401",
    "Country": "USA"
  }
}

Response

Returns confirmation of the address update with HTTP status code 200 on success.

Get Employee Contacts

Retrieves contact information for a specific employee.

Input Parameters

Here are the input parameters required to set up this action:

Action Configuration

Mandatory Path Parameters

Here is a sample configuration:

{
  "url": "https://usconfigr58.dayforcehcm.com/Api/ddn/V1/Employees/42199/Contacts",
  "httpMethod": "GET",
  "responseType": "JSON",
  "headers": [],
  "params": []
}

Response

Returns the employee's contact information including phone numbers, email addresses, and emergency contacts.

Update Employee Contacts

Updates contact information for a specific employee.

Input Parameters

Here are the input parameters required to set up this action:

Action Configuration

Mandatory Path Parameters

Here is a sample JSON input:

{
  "url": "https://usconfigr58.dayforcehcm.com/Api/ddn/V1/Employees/42199/Contacts",
  "httpMethod": "PATCH",
  "responseType": "JSON",
  "headers": [
    {
      "key": "Content-Type",
      "value": "application/json"
    }
  ],
  "params": [],
  "body": {
    "ContactNumber": "555-123-4567",
    "ContactType": "Mobile",
    "EffectiveStart": "2025-01-01"
  }
}

Response

Returns confirmation of the contact update with HTTP status code 200 on success.

Get Work Assignments

Retrieves work assignment information for a specific employee.

Input Parameters

Here are the input parameters required to set up this action:

Action Configuration

Mandatory Path Parameters

Here is a sample configuration:

{
  "url": "https://usconfigr58.dayforcehcm.com/Api/ddn/V1/Employees/42199/WorkAssignments",
  "httpMethod": "GET",
  "responseType": "JSON",
  "headers": [],
  "params": []
}

Response

Returns the employee's work assignment details including job title, department, location, and manager information.

Get Employment Status

Retrieves employment status information for a specific employee.

Input Parameters

Here are the input parameters required to set up this action:

Action Configuration

Mandatory Path Parameters

Here is a sample configuration:

{
  "url": "https://usconfigr58.dayforcehcm.com/Api/ddn/V1/Employees/42199/EmploymentStatuses",
  "httpMethod": "GET",
  "responseType": "JSON",
  "headers": [],
  "params": []
}

Response

Returns the employee's employment status history including active/inactive status, hire date, and termination details if applicable.

Get Compensation Summary

Retrieves compensation summary for a specific employee.

Input Parameters

Here are the input parameters required to set up this action:

Action Configuration

Mandatory Path Parameters

Here is a sample configuration:

{
  "url": "https://usconfigr58.dayforcehcm.com/Api/ddn/V1/Employees/42199/CompensationSummary",
  "httpMethod": "GET",
  "responseType": "JSON",
  "headers": [],
  "params": []
}

Response

Returns the employee's compensation details including base pay, pay rate, and pay frequency.

Get Time Off Requests

Retrieves time off requests for a specific employee.

Input Parameters

Here are the input parameters required to set up this action:

Action Configuration

Mandatory Path Parameters

Here is a sample configuration:

{
  "url": "https://usconfigr58.dayforcehcm.com/Api/ddn/V1/Employees/42199/TimeOffRequests",
  "httpMethod": "GET",
  "responseType": "JSON",
  "headers": [],
  "params": []
}

Response

Returns a list of time off requests with details including request date, status, leave type, and duration.

Create Time Off Request

Creates a new time off request for an employee.

Input Parameters

Here are the input parameters required to set up this action:

Action Configuration

Mandatory Path Parameters

Here is a sample JSON input:

{
  "url": "https://usconfigr58.dayforcehcm.com/Api/ddn/V1/Employees/42199/TimeOffRequests",
  "httpMethod": "POST",
  "responseType": "JSON",
  "headers": [
    {
      "key": "Content-Type",
      "value": "application/json"
    }
  ],
  "params": [],
  "body": {
    "TimeOffPolicyXRefCode": "VACATION",
    "StartDate": "2025-02-01",
    "EndDate": "2025-02-05",
    "FullDayRequest": true,
    "Comment": "Annual vacation"
  }
}

Response

Returns confirmation of the time off request creation with the new request ID and status.

Get Time Off Balance

Retrieves time off balance for a specific employee.

Input Parameters

Here are the input parameters required to set up this action:

Action Configuration

Mandatory Path Parameters

Here is a sample configuration:

{
  "url": "https://usconfigr58.dayforcehcm.com/Api/ddn/V1/Employees/42199/TimeOffBalances",
  "httpMethod": "GET",
  "responseType": "JSON",
  "headers": [],
  "params": []
}

Response

Returns the employee's time off balances by leave type including accrued, used, and remaining balances.

Get Employee Schedules

Retrieves schedule information for a specific employee.

Input Parameters

Here are the input parameters required to set up this action:

Action Configuration

Mandatory Path Parameters

Optional Query Parameters

Here is a sample configuration:

{
  "url": "https://usconfigr58.dayforcehcm.com/Api/ddn/V1/Employees/42199/Schedules",
  "httpMethod": "GET",
  "responseType": "JSON",
  "headers": [],
  "params": [
    {
      "key": "filterStartDate",
      "value": "2025-01-01"
    },
    {
      "key": "filterEndDate",
      "value": "2025-01-31"
    }
  ]
}

Response

Returns the employee's schedule information including shift times, positions, and locations.

Create Employee Schedule

Creates a new schedule entry for an employee.

Input Parameters

Here are the input parameters required to set up this action:

Action Configuration

Mandatory Path Parameters

Optional Query Parameters

Here is a sample JSON input:

{
  "url": "https://usconfigr58.dayforcehcm.com/Api/ddn/V1/Employees/42199/Schedules",
  "httpMethod": "POST",
  "responseType": "JSON",
  "headers": [
    {
      "key": "Content-Type",
      "value": "application/json"
    }
  ],
  "params": [],
  "body": {
    "StartTime": "2025-02-01T09:00:00",
    "EndTime": "2025-02-01T17:00:00",
    "Position": "Developer"
  }
}

Response

Returns confirmation of the schedule creation with the ScheduleId and success status.

Get Employee Punches

Retrieves time punch records for a specific employee.

Input Parameters

Here are the input parameters required to set up this action:

Action Configuration

Mandatory Path Parameters

Here is a sample configuration:

{
  "url": "https://usconfigr58.dayforcehcm.com/Api/ddn/V1/Employees/42199/Punches",
  "httpMethod": "GET",
  "responseType": "JSON",
  "headers": [],
  "params": []
}

Response

Returns the employee's time punch records including clock-in/out times and locations.

Create Employee Punch

Creates a new time punch for an employee.

Input Parameters

Here are the input parameters required to set up this action:

Action Configuration

Here is a sample JSON input:

{
  "url": "https://usconfigr58.dayforcehcm.com/Api/ddn/V1/EmployeePunches",
  "httpMethod": "POST",
  "responseType": "JSON",
  "headers": [
    {
      "key": "Content-Type",
      "value": "application/json"
    }
  ],
  "params": [],
  "body": {
    "EmployeeXRefCode": "42199",
    "PunchTime": "2025-01-15T09:00:00",
    "PunchType": "ClockIn"
  }
}

Response

Returns confirmation of the punch creation with the punch ID and status.

Get Employee Documents

Retrieves a list of documents associated with an employee.

Input Parameters

Here are the input parameters required to set up this action:

Action Configuration

Mandatory Path Parameters

Here is a sample configuration:

{
  "url": "https://usconfigr58.dayforcehcm.com/Api/ddn/V1/Employees/42199/Documents",
  "httpMethod": "GET",
  "responseType": "JSON",
  "headers": [],
  "params": []
}

Response

Returns metadata for each document including DocumentGUID, document name, type, upload date, and document group.

Fetch Document

Retrieves detailed information and content of a specific document.

Input Parameters

Here are the input parameters required to set up this action:

Action Configuration

Mandatory Path Parameters

Here is a sample configuration:

{
  "url": "https://usconfigr58.dayforcehcm.com/Api/ddn/V1/Documents/abc123-def456-ghi789",
  "httpMethod": "GET",
  "responseType": "JSON",
  "headers": [],
  "params": []
}

Response

Returns detailed document information including metadata, publish date, and document contents in base64 format.

Get Employee Benefits

Retrieves benefits information for a specific employee.

Input Parameters

Here are the input parameters required to set up this action:

Action Configuration

Mandatory Path Parameters

Here is a sample configuration:

{
  "url": "https://usconfigr58.dayforcehcm.com/Api/ddn/V1/Employees/42199/Benefits",
  "httpMethod": "GET",
  "responseType": "JSON",
  "headers": [],
  "params": []
}

Response

Returns the employee's benefits enrollment information including plan types, coverage levels, and effective dates.

Get Performance Reviews

Retrieves performance review information for a specific employee.

Input Parameters

Here are the input parameters required to set up this action:

Action Configuration

Mandatory Path Parameters

Here is a sample configuration:

{
  "url": "https://usconfigr58.dayforcehcm.com/Api/ddn/V1/Employees/42199/PerformanceReviews",
  "httpMethod": "GET",
  "responseType": "JSON",
  "headers": [],
  "params": []
}

Response

Returns the employee's performance review history including review dates, ratings, and comments.

Best Practices

Security Recommendations

• For Basic Auth:
  • Use a dedicated service account for API access rather than personal credentials
  • Rotate API credentials periodically
  • Store credentials securely and never expose them in client-side code
• For OAuth 2.0:
  • Use OAuth 2.0 for production environments as it provides enhanced security through token-based authentication
  • Keep Client ID and Client Secret secure and avoid exposing them in public repositories
  • Monitor token expiration and implement proper token refresh mechanisms
  • Use the minimum required scopes for your integration
• General:
  • Use HTTPS for all API communications (enforced by Dayforce)
  • Implement proper error handling for failed authentication attempts
  • Dayforce uses AES 256 encryption to ensure connection credentials are safe

XRefCode Usage

The XRefCode is a unique identifier for employees in Dayforce. Always use the XRefCode when targeting specific employee records. XRefCodes can be retrieved from the Get Employees endpoint.

Rate Limiting

Be mindful of API rate limits when making bulk requests. Implement appropriate retry logic with exponential backoff for rate-limited responses.

Sample vs Production Environment

• Sample Environment: Uses usconfigr58.dayforcehcm.com with namespace ddn
• Production Environment: Your organization-specific host and namespace

Note that POST and PATCH requests to the sample environment will return HTTP 200 but will not actually modify the shared database.

Choosing Authentication Method