Ceridian Dayforce User Management API Guide

Auth method: OAuth 2.0 (client credentials grant)

Setup steps

1. Log in to Dayforce as an administrator and navigate to System Admin > API Clients.
2. Create a new API Client, specifying the client name and allowed scopes.
3. Note the generated Client ID and Client Secret.
4. Request an access token via POST to https://{companyId}.dayforcehcm.com/connect/token with grant_type=client_credentials, client_id, and client_secret.
5. Include the returned Bearer token in the Authorization header for all subsequent API requests.

Required scopes

List employees

• Method: GET
• URL: https://{companyId}.dayforcehcm.com/Api/{companyId}/V1/Employees
• Watch out for: Returns a summary list; use the individual GET endpoint to retrieve full employee details.

Request example

GET /Api/ACME/V1/Employees?pageSize=200&skip=0
Authorization: Bearer {token}

Response example

{
  "Data": [
    {"XRefCode": "EMP001", "DisplayName": "Jane Doe", "EmploymentStatus": {"XRefCode": "ACTIVE"}}
  ],
  "Paging": {"Next": "..."}
}

Get employee by XRefCode

• Method: GET
• URL: https://{companyId}.dayforcehcm.com/Api/{companyId}/V1/Employees/{xrefCode}
• Watch out for: Use the expand query parameter to include sub-objects (e.g., Contacts, Addresses). Without it, nested data is omitted.

Request example

GET /Api/ACME/V1/Employees/EMP001?expand=Contacts,Addresses,EmploymentStatuses
Authorization: Bearer {token}

Response example

{
  "Data": {
    "XRefCode": "EMP001",
    "FirstName": "Jane",
    "LastName": "Doe",
    "Contacts": {"Items": [{"ContactInformationType": {"XRefCode": "BusinessEmail"}, "ContactNumber": "jane@acme.com"}]}
  }
}

Create employee

• Method: POST
• URL: https://{companyId}.dayforcehcm.com/Api/{companyId}/V1/Employees
• Watch out for: XRefCode must be unique. Many fields require valid XRefCode lookups (e.g., Department, Position) pre-populated in Dayforce.

Request example

POST /Api/ACME/V1/Employees
Authorization: Bearer {token}
Content-Type: application/json
{
  "XRefCode": "EMP099",
  "FirstName": "John",
  "LastName": "Smith",
  "HireDate": "2024-03-01"
}

Response example

{
  "Data": {
    "XRefCode": "EMP099",
    "ProcessResults": []
  }
}

Update employee

• Method: PATCH
• URL: https://{companyId}.dayforcehcm.com/Api/{companyId}/V1/Employees/{xrefCode}
• Watch out for: Partial updates are supported but some sub-objects (e.g., EmploymentStatuses) require full replacement of the collection.

Request example

PATCH /Api/ACME/V1/Employees/EMP099
Authorization: Bearer {token}
Content-Type: application/json
{
  "LastName": "Smith-Jones"
}

Response example

{
  "Data": {
    "XRefCode": "EMP099",
    "ProcessResults": []
  }
}

Terminate employee

• Method: POST
• URL: https://{companyId}.dayforcehcm.com/Api/{companyId}/V1/Employees/{xrefCode}/Terminations
• Watch out for: TerminationReason XRefCode must match a value configured in the Dayforce tenant. Termination does not delete the record.

Request example

POST /Api/ACME/V1/Employees/EMP099/Terminations
Authorization: Bearer {token}
Content-Type: application/json
{
  "TerminationDate": "2024-06-30",
  "TerminationReason": {"XRefCode": "RESIGNATION"}
}

Response example

{
  "Data": {
    "XRefCode": "EMP099",
    "ProcessResults": []
  }
}

Get employee contacts (email/phone)

• Method: GET
• URL: https://{companyId}.dayforcehcm.com/Api/{companyId}/V1/Employees/{xrefCode}/Contacts
• Watch out for: IsForSystemCommunications must be true on the primary email for Dayforce system notifications to route correctly.

Request example

GET /Api/ACME/V1/Employees/EMP001/Contacts
Authorization: Bearer {token}

Response example

{
  "Data": {
    "Items": [
      {"ContactInformationType": {"XRefCode": "BusinessEmail"}, "ContactNumber": "jane@acme.com", "IsForSystemCommunications": true}
    ]
  }
}

List org units (departments/locations)

• Method: GET
• URL: https://{companyId}.dayforcehcm.com/Api/{companyId}/V1/OrgUnits
• Watch out for: XRefCodes from this endpoint are required when assigning employees to departments or locations.

Request example

GET /Api/ACME/V1/OrgUnits?pageSize=200
Authorization: Bearer {token}

Response example

{
  "Data": [
    {"XRefCode": "DEPT_ENG", "ShortName": "Engineering", "OrgUnitType": {"XRefCode": "Department"}}
  ]
}

Get employee roles/security access

• Method: GET
• URL: https://{companyId}.dayforcehcm.com/Api/{companyId}/V1/Employees/{xrefCode}/UserPayAdjCodeGroups
• Watch out for: Role/security group assignment in Dayforce is complex; full role management may require UI configuration or Integration Hub workflows.

Request example

GET /Api/ACME/V1/Employees/EMP001/UserPayAdjCodeGroups
Authorization: Bearer {token}

Response example

{
  "Data": {
    "Items": [
      {"PayAdjCodeGroup": {"XRefCode": "MANAGER_GROUP"}}
    ]
  }
}

• Rate limits: Dayforce does not publicly document specific rate limit thresholds. Limits are enforced at the tenant level and may vary by contract.
• Rate-limit headers: Unknown
• Retry-After header: Unknown
• Rate-limit notes: Dayforce recommends batching requests and avoiding high-frequency polling. Contact Dayforce support for tenant-specific limits.
• Pagination method: offset
• Default page size: 200
• Max page size: 200
• Pagination pointer: pageSize / skip

• Webhooks available: No
• Webhook notes: Dayforce does not offer a native outbound webhook system for real-time event notifications as of the latest available documentation.
• Alternative event strategy: Use Dayforce Integration Hub (scheduled exports/imports) or poll the REST API on a schedule to detect changes. Some partners use Dayforce's Document Export feature for bulk data sync.

• SCIM available: No
• SCIM version: Not documented
• Plan required: Enterprise
• Endpoint: Not documented

Limitations:

• Dayforce does not natively expose a SCIM 2.0 endpoint.
• IdP integrations (Okta, Entra ID, OneLogin) use SSO (SAML/OIDC) for authentication but rely on Dayforce's proprietary REST API or Integration Hub for provisioning.
• Third-party middleware (e.g., Okta Workflows, MuleSoft) is commonly used to bridge SCIM to Dayforce REST API.

Onboarding: POST to /Employees after pre-fetching valid XRefCodes for Department, Position, Location, EmploymentStatus, and PayGroup from their respective lookup endpoints. All reference fields require XRefCodes pre-configured in the tenant; invalid values return 400 errors with minimal diagnostic detail.

Follow with a POST to /Employees/{xrefCode}/Contacts to set the business email with IsForSystemCommunications: true.

Profile sync: Poll GET /Employees using filterUpdatedStartDate (where supported) or maintain a local snapshot for change detection-Dayforce has no native delta or changelog endpoint. PATCH top-level fields directly; nested sub-objects (Contacts, Addresses) require their own dedicated sub-resource endpoints and in some cases full collection replacement rather than partial update.

Offboarding: POST to /Employees/{xrefCode}/Terminations with a valid TerminationReason XRefCode. Dayforce uses a soft-delete model; the record persists with a status change. Critically, Dayforce termination and IdP deprovisioning are fully decoupled-SSO sessions in Okta or Entra must be revoked separately, or a terminated employee retains downstream access.

Onboard a new employee

1. Authenticate via POST to /connect/token to obtain a Bearer token.
2. Retrieve valid XRefCodes for Department, Position, Location, EmploymentStatus, and PayGroup via their respective lookup endpoints.
3. POST to /Employees with required fields: XRefCode, FirstName, LastName, HireDate, EmploymentStatus, and desired optional fields.
4. POST to /Employees/{xrefCode}/Contacts to add the employee's business email with IsForSystemCommunications: true.
5. Optionally set LoginId or SSOIdentifier on the employee record to enable Dayforce login or SSO.

Watch out for: All reference XRefCodes must exist in the tenant before the POST. Pre-fetch lookup tables at the start of the workflow to avoid 400 errors mid-process.

Sync employee profile updates from an HR system

1. Poll GET /Employees with a filterUpdatedStartDate query parameter (if supported) or maintain a local snapshot for change detection.
2. For each changed employee, PATCH /Employees/{xrefCode} with only the modified top-level fields.
3. For nested sub-objects (e.g., Contacts, Addresses), use the dedicated sub-resource endpoints (e.g., PATCH /Employees/{xrefCode}/Contacts).
4. Log ProcessResults from each response to detect partial failures.

Watch out for: Dayforce does not provide a native delta/changelog endpoint. Polling frequency should be balanced against undocumented rate limits.

Offboard (terminate) an employee

1. Authenticate and obtain a Bearer token.
2. POST to /Employees/{xrefCode}/Terminations with TerminationDate and a valid TerminationReason XRefCode.
3. Verify the employee's EmploymentStatus changes to the terminated state via GET /Employees/{xrefCode}.
4. Revoke SSO access in the IdP (Okta/Entra) separately, as Dayforce termination does not automatically deprovision IdP sessions.

Watch out for: Dayforce termination and IdP deprovisioning are decoupled. Without a SCIM integration or custom middleware, IdP access must be revoked manually or via a separate automation.

The expand parameter trap is the most common source of silent data loss: without ?expand=Contacts,Addresses,... on GET requests, nested sub-objects are omitted from responses entirely with no error or warning. Developers who skip this parameter build syncs that appear to work but propagate incomplete records.

Rate limits are undocumented at the tenant level. Dayforce recommends batching and avoiding high-frequency polling, but provides no rate-limit headers or retry-after signals to guide backoff logic. Exceeding limits produces opaque failures rather than 429 responses with actionable metadata.

Bulk operations are not supported via REST. Large employee imports must go through Integration Hub file-based workflows, not the API-a constraint that surfaces late in integration builds and forces architectural rework.

Additionally, API versioning is path-based (/V1/); always verify the active version against the developer portal, as Dayforce may release new versions without deprecating old ones on a predictable schedule.