Home

September 3, 2024

Return the Client Team roles for a Client or Client Group

GET Client Groups, GET Contacts and GET Organizations

Endpoints:

  • https://api.karbonhq.com/v3/ClientGroups
  • https://api.karbonhq.com/v3/Contacts
  • https://api.karbonhq.com/v3/Organizations

When retrieving the details for a single Client Group, Contact or Organization it is now possible to request the Client Team details in the response using $expand=ClientTeam.

This will add a ClientTeam property to the response, which is an array containing a record for:

  • each User assigned to the ClientOwner, ClientManager, UserDefinedRoles, 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 example of the response from these endpoints.

Example use case

You want to check which users are assigned to the Client Team for an Organization, but not assigned a specific role.

You’ll need:

  • The OrganizationKey for an Organization you want to retrieve the Client Team for
  • To have requested and been granted access to the Users API endpoints

Make a request to the Organizations endpoint, adding the query string parameter $expand=ClientTeam e.g. https://api.karbonhq.com/v3/Organizations/23Z6Td1ggZSl?$expand=ClientTeam.

Inspect the ClientTeam array returned in the response, filtering for any items where RoleType is null (this means that there is no specific role set) and MemberType is User.

To retrieve information about a User in the list, make a call to the Users API, using the MemberKey as the UserId. For example: https://api.karbonhq.com/v3/Users/nRML2ngs7WJ

Notes

  • Teams will 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 does duplicate the existing ClientManager and ClienOwner properties on client records
  • The ability to update the client team will come in a future API release