Overview
Merge will no longer support the Teams common model after June 30th, 2024. After this date, we will not add any improvements or support any bug fixes related to Teams.
We strongly recommend using the Group common model going forward, as it has the same capabilities as Teams and is more comprehensive. This help center article outlines the changes your organization should be aware of as part of the transition.
Why Groups?
Historically, Merge mapped the Teams Common Model to represent an Employee's subdivision in a company, usually a department. Each employee was grouped into one specific Team. Over time, it became clear that this mapping traded simplicity (an opinionated stance on what an employee’s “team” would be) for flexibility (situations where users need more control over how we define that).
The Groups Common Model is meant to be that more flexible, comprehensive model. Different API providers represent an Employee's Team, Department, or Business Unit in varying ways. Groups will have all of the same capabilities as Teams going forward.
Changes
New Field
To ease this transition, we have added a new field to our Group common model, named is_commonly_used_as_team.This field signifies whether a Group typically represents a team within third-party platforms, based on Merge's analysis. For the full is_commonly_used_as_team field definition and a deeper explanation of how Merge defines a team, refer to our HRIS Group docs here.
For Group objects where is_commonly_used_as_team is set to true, these will correspond to what was previously represented as a Team object, provided that the Team model was supported for that particular HRIS integration prior to the upcoming deprecation. For a historical list of supported integrations, refer to the Field Support by Integration section of our Team docs here.
New Teams Filter
To facilitate the querying of team-like Group objects, use the GET /groups endpoint with the new is_commonly_used_as_team query parameter:
GET https://api.merge.dev/api/hris/v1/groups?is_commonly_used_as_team=true
Note that this way of filtering for teams should replace the historical use of our GET /teams endpoint.
Shown below is a sample API response in JSON format, which also shows the updated Group object schema:
{
"next": "cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw",
"previous": "cj1sZXdwd2VycWVtY29zZnNkc2NzUWxNMEUxTXk0ME16UXpNallsTWtJ",
"results": [
{
"id": "134e0111-0f67-44f6-98f0-597000290bb3",
"remote_id": "800293",
"created_at": "2021-09-15T00:00:00Z",
"modified_at": "2021-10-16T00:00:00Z",
"parent_group": "2ef51b11-2c4e-4b02-8d1d-50592d9e96ef",
"name": "COST_CENTER_US",
"is_commonly_used_as_team": true,
"type": "COST_CENTER",
"remote_was_deleted": false,
"field_mappings": {
"organization_defined_targets": {
"custom_key": "custom_value"
},
"linked_account_defined_targets": {
"custom_key": "custom_value"
}
},
"remote_data": [
{
"path": "/group",
"data": [
"Varies by platform"
]
}
]
}
]
}
Note that, in the above example, this Group has the is_commonly_used_as_team field set to true, even though the type field on the object does not take on the value TEAM. This simply means that COST_CENTER is commonly represented as a team in this third-party HRIS system.
Integration Specific Nuances
Charthop
Historically, Merge created Team objects for Charthop’s departments. In order to maintain accuracy and one-to-one correspondence with the deprecated Teams model, groups with type TEAM and DEPARTMENT will have is_commonly_used_as_team set to true.
Workday
Historically, Merge created Team objects for Workday’s job families. In order to maintain one-to-one correspondence with the deprecated Teams model, groups with type Job Family will have is_commonly_used_as_team set to true.