Overview of Groups Object

The Group object is used to represent any subset of employees, such as Department, Paygroup, Division, Team, Business Unit, Location, or any additional type of company hierarchy.

• If your customer has multiple types of groupings (for example Division, Cost Center, and Department), then all those groups will be created and you will be able to distinguish each by the type field.

• If an employee is in multiple Groups (fore example Finance Department in the West Coast Division), then Merge will create an ID for both of those Groups.

How to leverage /group/types

The /group/types endpoint returns a list of distinct group type values from the Groups common model. You can use this to identify the possible Group types for a Linked Account to then use in downstream processes like filtering.

How to identify the right Group to display in your product

To ensure you’re surfacing the correct Group type (e.g., Team, Department, Cost Center) for a customer, follow these steps:

1. Fetch available Group types: Use the List Group Types endpoint to see which group types exist for the connected HRIS provider

   1. GET https://api.merge.dev/api/hris/v1/groups/types

      1. You can also set show_enum_origins=type to surface the original values from the third party.

   2. GET https://api.merge.dev/api/hris/v1/groups/

2. Ask the customer which Group type they want to use

   1. During onboarding, prompt the customer to choose which Group type should power the label they care about (e.g., Team / Department / Cost Center). This prompt is often in typically in a post-connection settings screen.

   2. Best practice is to show:

      1. The list of available group types

      2. A few example group names for each type (pulled from the Groups list endpoint) so the customer can confidently select the right type.

3. Only surface Groups that match the selected type

   1. After the customer selects a Group type, filter your displayed Groups to only those whose type matches the customer’s selection.

How to leverage show_enum_origins for specific Integrations

There are some providers that are very configurable, where there’s no true way to normalize what Cost Center / Group maps to a specific Department, Team, Cost Center, etc. For example, one customer may use Cost Center 1 to map to Departments, and another customer may use Cost Center 3.

This occurs for UKG Pro, UKG Ready, Paylocity, and Proliant.

How to find the correct Group to surface in your product:

1. When pulling from out GET/Groups endpoint, you will apply the show_enum_origins parameter on “type”.

   • https://api.merge.dev/api/hris/v1/groups?show_enum_origins=type

2. During the onboarding process, build a way to ask the end-user what Cost Center they’d like to be leveraged for Team / Department / Cost Center, etc.

3. Once you gather this information, you will only surface Groups with a type that matches the customer input

   • For UKG Ready → It’s done by Index 0, 1, 2, 3, 4, 5, 6, 7, 8

   • For UKG Pro → It’s done by Type and/or Org Level

   • For Paylocity → It’s done by Cost Center 1, 2, 3, 4, 5

If you have any questions, please reach out to us at [email protected]!