Dayforce HCM (Preview)

Connects to the Dayforce HCM API to retrieve employee personal information (contacts, addresses, names) by employee reference code. Intended for HR administrators and low-code developers. Requires a Dayforce tenant, API credentials (Basic Auth) and appropriate permissions. Read-only; invalid reference codes return errors.

This connector is available in the following products and regions:

Service	Class	Regions
Copilot Studio	Premium	All Power Automate regions except the following:      -   US Government (GCC)      -   US Government (GCC High)      -   China Cloud operated by 21Vianet      -   US Department of Defense (DoD)
Logic Apps	Standard	All Logic Apps regions except the following:      -   Azure Government regions      -   Azure China regions      -   US Department of Defense (DoD)
Power Apps	Premium	All Power Apps regions except the following:      -   US Government (GCC)      -   US Government (GCC High)      -   China Cloud operated by 21Vianet      -   US Department of Defense (DoD)
Power Automate	Premium	All Power Automate regions except the following:      -   US Government (GCC)      -   US Government (GCC High)      -   China Cloud operated by 21Vianet      -   US Department of Defense (DoD)

Contact
Name	Dayforce Support
URL	https://www.dayforce.com/resources/help-center#support-for-employers
Email	MicrosoftPartnership@dayforce.com

Connector Metadata
Publisher	Dayforce AI
Website	https://www.dayforce.com/
Privacy policy	https://www.dayforce.com/privacy
Categories	AI;Human Resources

Dayforce HCM

Dayforce HCM is a human capital management platform.
This connector exposes a Dayforce API operation that lets you retrieve an employee’s personal information (name, addresses, and contact details) by their external reference code (XRefCode). You can use this data as a tool in Copilot Studio AI agents, as well as in other Power Platform scenarios.

Publisher: Dayforce

---

Prerequisites

To use this connector, you need:

• A Microsoft Power Platform environment (for example, to use the connector in Copilot Studio).
• An active Dayforce HCM environment (QA, UAT, or Production).
• A Dayforce API user (service account) with permission to read employee personal information.
• The client namespace for your Dayforce environment.
  • This value appears as the namespace segment in your Dayforce API URLs, for example:
    https://{environmentHost}/{clientNamespace}/V1/...

---

Supported Operations

The connector currently exposes the following operation.

Get Employee Personal Info

Operation ID: Get_Employee_Personal_Info
Method: GET

Retrieves a filtered, simplified view of personal information for a single employee based on their XRefCode.

Request

• Path parameter
  • xRefCode (string, required)
    The external reference code of the employee to be retrieved. The value must exactly match an existing employee’s XRefCode; otherwise, the service returns a 400 Bad Request.

Internally, the connector routes the call to the Dayforce Employees endpoint for your client namespace and expands relevant personal information, which is then transformed by the connector’s script into a streamlined JSON object.

Response

On success (HTTP 200), the connector does not return the full Dayforce employee payload.
Instead, it returns a transformed object with this structure:

{
  "firstName": "string",
  "lastName": "string",
  "addresses": [
    {
      "address1": "string",
      "address2": "string",
      "address3": "string",
      "city": "string",
      "postalCode": "string",
      "country": "string",
      "state": "string",
      "contactInformationType": "string"
    }
  ],
  "contacts": [
    {
      "personContactId": 0,
      "contactInformationType": "string",
      "electronicAddress": "string",
      "contactNumber": "string",
      "country": "string",
      "effectiveStart": "2024-01-01T00:00:00Z"
    }
  ]
}

More specifically:

• Top-level fields

  • firstName – Employee’s first name.
  • lastName – Employee’s last name.
  • addresses – A list of filtered address entries.
  • contacts – A list of filtered contact entries.

• Address object (addresses[])

  • address1 – Primary address line.
  • address2 – Secondary address line.
  • address3 – Additional address line.
  • city – City name.
  • postalCode – Postal or ZIP code.
  • country – Country name (mapped from the Dayforce Country name).
  • state – State or province name (mapped from the Dayforce State name).
  • contactInformationType – Short name describing the type of address (for example, “Home”, “Mailing”), based on the Dayforce contact information type.

• Contact object (contacts[])

  • personContactId – Internal numeric identifier for the contact record.
  • contactInformationType – Short name describing the type of contact (for example, “Mobile”, “Home Phone”, “Work Email”).
  • electronicAddress – For “online profile” style contacts (such as email or other electronic addresses).
  • contactNumber – For phone-style contacts (for example, mobile or landline numbers).
  • country – Country value associated with the contact (where applicable).
  • effectiveStart – Effective start date of this contact information (if available).

Note: The connector’s script intentionally filters the raw Dayforce payload.
Only the fields shown above are exposed to callers of this operation.

On error, the API returns:

• 400 Bad Request – For malformed requests or invalid xRefCode.
• 500 Internal Server Error – For unexpected server-side failures.

Error responses include diagnostic information from the underlying Dayforce API.

---

Obtaining Credentials

This connector uses Basic authentication to connect to the Dayforce API.

To obtain the required credentials:

1. Create or identify an API user in Dayforce

   • Work with your Dayforce administrator or implementation team.
   • Ensure the API user has read access to employee personal information for your environment.

2. Gather the following values

   • Username – The Dayforce API username.
   • Password – The Dayforce API password.
   • Client Namespace – The namespace value used in your Dayforce API URLs.
     • This is often a short identifier for your organization or environment, for example the segment that appears in URLs like:
       https://{environmentHost}/{clientNamespace}/V1/Employees/....

3. Use these values when creating a connector connection

   • In the Power Platform connection dialog:
     • Enter the username and password for the Dayforce API user.
     • Enter your Dayforce client namespace in the “Client Namespace” field.
   • The connector uses these values to route requests to the correct Dayforce tenant and authenticate the call.

If you are unsure of your client namespace or API user details, contact Dayforce support or your internal Dayforce administrator.

---

Getting Started

The recommended way to test and use this connector is to add it as a tool in a Copilot Studio AI agent.

1. Create a connection

Before using the connector in Copilot Studio, ensure a connection exists:

1. In the Power Platform admin or maker experience, go to Data > Connections.
2. Select + New connection.
3. Search for your Dayforce HCM connector (this connector).
4. When prompted, provide:
   • Username – Dayforce API user name.
   • Password – Dayforce API user password.
   • Client Namespace – Your Dayforce client namespace.
5. Save the connection.

2. Create an AI agent in Copilot Studio and add the connector as a tool

1. Open Copilot Studio.
2. Create a new AI agent (or open an existing agent where you want to use Dayforce data).
3. Go to the Tools/Plugins (or Connectors) section of the agent.
4. Add your Dayforce HCM connector as a tool.
5. Ensure the connector uses the connection you created earlier.

3. Call the connector from the AI agent

1. In your AI agent authoring experience:
   • Create or edit a topic, action, or plugin call where you want the agent to retrieve employee information.
2. Configure a tool call that uses the Get Employee Personal Info operation:
   • Map user input (for example, “employee code”) to the xRefCode parameter.
3. Use the returned fields:
   • firstName and lastName can be used in the AI agent’s responses (for example, “Here is the address and contact information for John Smith.”).
   • Use addresses and contacts in the agent logic to display or reason over the employee’s address and contact details.

This setup lets your AI agent safely call the Dayforce HCM connector as a tool, retrieve only the filtered fields, and incorporate those results into responses or decision-making.

---

Known Issues and Limitations

• Single-employee lookup only
  The operation retrieves data for one employee at a time, based on the XRefCode. Bulk queries or searches by other attributes (such as name or email) are not supported by this connector definition.

• Exact XRefCode match required
  The xRefCode parameter must match an existing employee’s external reference code exactly. If the value is invalid or does not exist, the service returns a 400 Bad Request response.

• Read-only operations
  This version of the connector is read-only. It does not support creating, updating, or deleting employee information.

• Environment-specific configuration
  The API definition and routing policy expect a valid Dayforce environment and client namespace. If these do not match your actual Dayforce environment configuration, calls will fail with connection or routing errors.

• Filtered payload
  The underlying Dayforce API returns many more fields than are exposed here. The connector’s script intentionally filters and reshapes this data into firstName, lastName, addresses[], and contacts[] only.

• Data visibility depends on Dayforce configuration
  The fields and values returned for an employee depend on how your Dayforce environment is configured (roles, security, and which data elements are enabled or populated).

---

Frequently Asked Questions

Q1: What is the “Client Namespace” field used for?
The client namespace identifies your Dayforce tenant within the Dayforce API URL. The connector uses it to route requests to the correct customer namespace, for example:
https://{environmentHost}/{clientNamespace}/V1/Employees/{xRefCode}
If you don’t know this value, contact your Dayforce administrator or implementation team.

Q2: What happens if I provide an invalid xRefCode?
If the xRefCode does not match an existing employee, the service returns a 400 Bad Request response. The underlying Dayforce API error is surfaced through the connector.

Q3: Can I retrieve multiple employees in one call?
Not with this connector definition. The current operation retrieves a single employee’s personal information per call, based on the provided xRefCode.

---

Deployment Instructions (CLI – paconn)

You can deploy this connector as a custom connector using the Power Platform Connectors CLI (paconn).

1. Prepare connector artifacts

Ensure you have the following files in a local folder (for example, ./dayforce-hcm-connector):

• apiDefinition.swagger.json
• apiProperties.json
• script.csx

These should match the structure expected by the Power Platform custom connector framework.

2. Install and configure the CLI

1. Install the Power Platform Connectors CLI (paconn) if you have not already done so.
2. Sign in to your target environment/tenant using paconn according to Microsoft’s documentation (for example, using paconn login).

3. Create the connector

Run a command similar to:

paconn create   --api-def apiDefinition.swagger.json   --api-prop apiProperties.json --icon icon.png   --script script.csx

• Make sure you run this command in the folder containing the connector files, or provide full paths to each file.
• After creation, the connector will appear as a custom connector in your target environment.

4. Update the connector (if needed)

If you later make changes to apiDefinition.swagger.json, apiProperties.json, or script.csx, you can update the existing connector with:

paconn update   --api-def apiDefinition.swagger.json   --api-prop apiProperties.json   --script script.csx   --connector-id <your-connector-id>

Replace <your-connector-id> with the ID of the connector that was created.

5. Create a connection and use it in Copilot Studio

Once the connector is deployed:

1. Go to Data > Connections and create a new connection for the Dayforce HCM connector using your Dayforce credentials and client namespace.
2. In Copilot Studio, add this connector as a tool to your AI agent, and call the Get Employee Personal Info operation as described in the Getting Started section.

6. Security and connection sharing

We intend for this connector to follow a non-shareable connection model: when a Power App or Copilot Studio agent using this connector is shared, only the connector definition is shared and each individual user must explicitly create their own Dayforce connection with their own credentials on first use. The connector must not allow sharing of connections in a way that would let one user’s Dayforce permissions be reused by another (i.e., no scenario where an app or agent runs under the app owner’s or connection owner’s Dayforce identity). As part of certification, please ensure that all authentication types for this connector are configured as Not shareable, so that connection sharing is blocked at the platform level and every user is always required to establish their own Dayforce connection.

Include this disclaimer: This is not shareable connection. If the power app is shared with another user, another user will be prompted to create new connection explicitly.

Once certified and published by Microsoft, the Dayforce HCM connector will be available as a certified connector, and you will typically only need to create a connection (no CLI deployment required for end users).

Creating a connection

The connector supports the following authentication types:

Default	Parameters for creating connection.	All regions	Not shareable

Default

Applicable: All regions

Parameters for creating connection.

This is not shareable connection. If the power app is shared with another user, another user will be prompted to create new connection explicitly.

Name	Type	Description	Required
username	securestring	The username for this api	True
password	securestring	The password for this api	True
Authentication Type	string	Authentication type to connect to your API	True
Client Namespace	string	client namespace	True

Throttling Limits

Name	Calls	Renewal Period
API calls per connection	100	60 seconds

Actions

Get Employee Personal Info

This operation retrieves data related to an employee and his/her personal (e.g. Name, Addresses and Contacts) information by XRef Code

Get Employee Personal Info

Operation ID:

Get_Employee_Personal_Info

This operation retrieves data related to an employee and his/her personal (e.g. Name, Addresses and Contacts) information by XRef Code

Parameters

Name	Key	Required	Type	Description
Employee Reference Code	xRefCode	True	string	The unique identifier (external reference code) of the employee to be retrieved. The value provided must be the exact match for an employee; otherwise, a bad request (400) error will be returned.

Returns

Body

Payload_Employee

Definitions

ProcessResult

Name	Path	Type	Description
Code	Code	string
Context	Context	string
Level	Level	string
Message	Message	string

Employee

Name	Path	Type	Description
EmployeeId	EmployeeId	integer
Contacts	Contacts	PersonContactCollection
Addresses	Addresses	PersonAddressCollection
GlobalPersonId	GlobalPersonId	string
XRefCode	XRefCode	string
NewXRefCode	NewXRefCode	string
CommonName	CommonName	string
DisplayName	DisplayName	string
FirstName	FirstName	string
LastName	LastName	string
Initials	Initials	string
MaidenName	MaidenName	string
MiddleName	MiddleName	string
Title	Title	string
LastModifiedTimestamp	LastModifiedTimestamp	date-time

PersonContactCollection

Name	Path	Type	Description
Items	Items	array of PersonContact

PersonAddressCollection

Name	Path	Type	Description
Items	Items	array of PersonAddress

PersonContact

Name	Path	Type	Description
PersonContactId	PersonContactId	integer
ContactInformationType	ContactInformationType	ContactInformationType
ContactNumber	ContactNumber	string
Country	Country	Country
EffectiveEnd	EffectiveEnd	date-time
EffectiveStart	EffectiveStart	date-time
ElectronicAddress	ElectronicAddress	string
Extension	Extension	string
IsForSystemCommunications	IsForSystemCommunications	boolean
IsPreferredContactMethod	IsPreferredContactMethod	boolean
IsUnlistedNumber	IsUnlistedNumber	boolean
FormattedNumber	FormattedNumber	string
IsVerified	IsVerified	boolean
IsRejected	IsRejected	boolean
ShowRejectedWarning	ShowRejectedWarning	boolean
NumberOfVerificationRequests	NumberOfVerificationRequests	integer
LastModifiedTimestamp	LastModifiedTimestamp	date-time

PersonAddress

Name	Path	Type	Description
PersonAddressId	PersonAddressId	integer
Address1	Address1	string
Address2	Address2	string
Address3	Address3	string
Address4	Address4	string
Address5	Address5	string
Address6	Address6	string
City	City	string
PostalCode	PostalCode	string
Country	Country	Country
State	State	State
ContactInformationType	ContactInformationType	ContactInformationType
IsPayrollMailing	IsPayrollMailing	boolean
DisplayOnTaxForm	DisplayOnTaxForm	boolean
DisplayOnEarningStatement	DisplayOnEarningStatement	boolean
EffectiveStart	EffectiveStart	date-time
EffectiveEnd	EffectiveEnd	date-time
County	County	string
LastModifiedTimestamp	LastModifiedTimestamp	date-time

Country

Name	Path	Type	Description
Name	Name	string
XRefCode	XRefCode	string
ShortName	ShortName	string
LongName	LongName	string
LastModifiedTimestamp	LastModifiedTimestamp	date-time

ContactInformationType

Name	Path	Type	Description
ContactInformationTypeGroup	ContactInformationTypeGroup	ContactInformationTypeGroup
XRefCode	XRefCode	string
ShortName	ShortName	string
LongName	LongName	string
LastModifiedTimestamp	LastModifiedTimestamp	date-time

State

Name	Path	Type	Description
Name	Name	string
XRefCode	XRefCode	string
ShortName	ShortName	string
LongName	LongName	string
LastModifiedTimestamp	LastModifiedTimestamp	date-time

ContactInformationTypeGroup

Name	Path	Type	Description
XRefCode	XRefCode	string
ShortName	ShortName	string
LongName	LongName	string
LastModifiedTimestamp	LastModifiedTimestamp	date-time

Payload_Employee

Name	Path	Type	Description
Data	Data	Employee
ProcessResults	ProcessResults	array of ProcessResult