September 23, 2024

Create or Update Client Team roles

POST/PUT Client Groups, POST/PUT Contacts and POST/PUT Organizations

Endpoints:

• JSONCopyCopied!

  https://api.karbonhq.com/v3/ClientGroups
• JSONCopyCopied!

  https://api.karbonhq.com/v3/Contacts
• JSONCopyCopied!

  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

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
  JSONCopyCopied!

  Contact
  and an
  JSONCopyCopied!

  Organization
  as
  JSONCopyCopied!

  Members
  ,
• a Client Team comprised of a
  JSONCopyCopied!

  ClientOwner
  and one of the
  JSONCopyCopied!

  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
  JSONCopyCopied!

  OrganizationKey
  for the Organization you want to add to the Client Group
• The
  JSONCopyCopied!

  ContactKey
  for the Contact you want to add to the Client Group
• The
  JSONCopyCopied!

  UserId
  for each of the roles you want to assign to the client team members.
• You have requested access to the
  JSONCopyCopied!

  Users
  endpoint to retrieve each
  JSONCopyCopied!

  UserId
  you wish to assign to the Client Team

Make a POST request to the

endpoint with a request payload that includes the Client Group and properties. The for each assigned Client Team role will be set to a for a member of your firm. You can retrieve a list of these Ids from the endpoint.

For example:

JSONCopyCopied!
{
  "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

with a response that includes the of the newly created Client Group. You can then use the GET endpoint with the query parameter to verify the was correctly assigned, e.g.

Notes

• Teams can never be assigned to a specific role (e.g. ClientManager), but can be assigned to the ClientTeam - i.e. the
  JSONCopyCopied!

  RoleType
  property will be always be
  JSONCopyCopied!

  null
• Whilst the ClientTeam array can include a MemberType of
  JSONCopyCopied!

  Team
  , it is not yet possible to request information about a Team and it's members via the API
• The
  JSONCopyCopied!

  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

webhook notification with the property set to .