# September 23, 2024 

** The September 23, 2024 Karbon API release adds the ability set or update the complete Client Team record for Client Groups, Contacts and Organizations. It also triggers a Contact webhook notification when the Client Team is updated. **
---

## Create or Update Client Team roles

### POST/PUT Client Groups, POST/PUT Contacts and POST/PUT Organizations
Endpoints:
* `https://api.karbonhq.com/v3/ClientGroups`
* `https://api.karbonhq.com/v3/Contacts`
* `https://api.karbonhq.com/v3/Organizations`

When creating or updating a Client Group, Contact or Organization, it is now possible to optionally set or update the Client Team assigned.

This is done by providing `ClientTeam` property in the request, which is an array containing a record for:
* each User assigned to the ClientOwner, ClientManager, UserDefinedRoles, and/or
* Users and Teams assigned to the Client Team without a specific role

Refer to the [ClientGroups API documentation](https://karbonhq.github.io/karbon-api-reference/#get-/v3/ClientGroups), [Contacts API documentation](https://karbonhq.github.io/karbon-api-reference/#get-/v3/Contacts) or [Organizations API documentation](https://karbonhq.github.io/karbon-api-reference/#get-/v3/Organizations) for a full request and response payloads from these endpoints.

### Example use case
You want to create a new Client Group, it will have:
* a `Contact` and an `Organization` as `Members`,
* a Client Team comprised of a `ClientOwner` and one of the `UserDefinedRole` properties

You'll need:
* To enable at least one of the User Defined Roles by assigning it a name under Karbon Settings > Contact Settings > Client Team
* The `OrganizationKey` for the Organization you want to add to the Client Group
* The `ContactKey` for the Contact you want to add to the Client Group
* The `UserId` for each of the roles you want to assign to the client team members.
* You have requested access to the `Users` endpoint to retrieve each `UserId` you wish to assign to the Client Team

Make a POST request to the `ClientGroups` endpoint `https://api.karbonhq.com/v3/ClientGroups` with a request payload that includes the Client Group `Members` and `ClientTeam` properties.
The `MemberKey` for each assigned Client Team role will be set to a `UserId` for a member of your firm. You can retrieve a list of these Ids from the `Users` endpoint.

For example:

```JSON
{
  "FullName": "Silvers Family",
  "ContactType": "Client",
  "UserDefinedIdentifier": "SILVERS",
  "RestrictionLevel": "Public",
  "EntityDescription": {
    "Text": "Silvers Family tax and accounting clients"
  },
  "Members": [
    {
      "ContactKey": "34yxkY51knn7"
    }, {
      "OrganizationKey": "4ncPZ7q96SGc"
    }
  ],
  "ClientTeam": [
    {
      "MemberKey": "JTphCpQqQYg",
      "MemberType": "User",
      "RoleType": "ClientOwner"
    },
    {
      "MemberKey": "nRML2ngs7WJ",
      "MemberType": "User",
      "RoleType": "UserDefinedRole1"
    }
  ]
}
```

If successful, this will return an HTTP status code of `201 Created` with a response that includes the `ClientGroupKey` of the newly created Client Group.
You can then use the GET `ClientGroup` endpoint with the query parameter `$expand=ClientTeam` to verify the `ClientTeam` was correctly assigned, e.g. `https://api.karbonhq.com/v3/ClientGroups/NwFFZqd3jM3?$expand=ClientTeam`

### Notes
* Teams can never be assigned to a specific role (e.g. ClientManager), but can be assigned to the ClientTeam - i.e. the `RoleType` property will be always be `null`
* Whilst the ClientTeam array can include a MemberType of `Team`, it is not yet possible to request information about a Team and it's members via the API
* The `ClientTeam` property duplicates and overrides the existing ClientManager and ClientOwner properties on client records
* It is possible to assign Users with a pending registration status to a Client Team role. 
* It is **not** possible to assign an archived Users to a Client Team role.

## Contact Webhook notifcations and Client Teams

Any change to the Client Team will trigger a `Contact` webhook notification with the `ActionType` property set to `Updated`.