Dayforce HCM (Preview)

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 API URL for your Dayforce environment, including the client namespace.
  • This is the base URL used to call the Dayforce API for your tenant, for example:
    https://{environmentHost}/{basePath}/api/{clientNamespace}
  • The exact format depends on your Dayforce environment configuration. Contact your Dayforce administrator if you are unsure of the URL.

---

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 using the API URL provided at connection creation time, 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

   • API URL – The base API URL for your Dayforce tenant, including the client namespace. This is the URL the connector will use to route requests to your Dayforce environment. Do not include a trailing slash.

     • Example: https://{environmentHost}/{basePath}/api/{clientNamespace}

     Important: Some Dayforce environments use a universal URL (for example, https://dayforcehcm.com/api/{clientNamespace}) that automatically redirects to an environment-specific URL (for example, https://us252-services.dayforcehcm.com/api/{clientNamespace}). When configuring the connector, always use the final, resolved URL rather than the universal URL. You can determine the final URL by navigating to the Swagger documentation page for your environment (for example, https://dayforcehcm.com/api/{clientNamespace}/swagger/index.html) and noting the URL your browser is redirected to.

   • Username – The Dayforce API username.

   • Password – The Dayforce API password.

3. Use these values when creating a connector connection

   • In the Power Platform connection dialog:
     • Enter the API URL for your Dayforce environment.
     • Enter the username and password for the Dayforce API user.
   • The connector uses the API URL to route requests to the correct Dayforce tenant and the credentials to authenticate the call.

If you are unsure of your API URL 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:
   • API URL – The base API URL for your Dayforce tenant (including the client namespace). Do not include a trailing slash.
   • Username – Dayforce API user name.
   • Password – Dayforce API user password.
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 connector requires a valid Dayforce API URL (provided at connection creation time). If the URL does not match your actual Dayforce environment configuration, calls will fail with connection or routing errors. Do not include a trailing slash in the API URL.

• 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 "API URL" field used for?
The API URL is the base URL for your Dayforce tenant, including the client namespace. The connector uses it to route all API requests to the correct Dayforce environment. The URL should not include a trailing slash.
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 API URL and credentials.
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

This connector uses a non-shareable connection model. When you share a Power App or Copilot Studio agent that uses this connector, only the connector definition is shared — each user must create their own Dayforce connection with their own credentials on first use. Connections cannot be shared in a way that allows one user's Dayforce permissions to be reused by another. All authentication types are configured as Not shareable, so connection sharing is blocked at the platform level and every user is always required to establish their own Dayforce connection.

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

Definitions

ProcessResult

Employee

PersonContactCollection

PersonAddressCollection

PersonContact

PersonAddress

Country

ContactInformationType

State

ContactInformationTypeGroup

Payload_Employee