September 23, 2024

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, Contacts API documentation or Organizations API documentation 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:

{
  "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.