Groups

A group is a named set of users in your account, such as “Customer success” or “Finance.” Wherever Carom accepts a group, every member receives what the group receives: a task assigned to a group is visible to all its members, and a group added to a space gives all its members access to it. Use this resource to manage groups and their members.

Every user in the account can see every group. Creating, changing, and deleting a group requires an account admin; other keys get 403 permission_denied.

#The group object

Returned by every group endpoint, always with its members.

Attributes

idstring · uuid

Unique identifier for the group.
namestring
descriptionstring · nullable
usersarray of users · nullable

The group’s members.

The group object

{
  "id": "ecfda68b-7364-46c5-8e20-cffc98e6f291",
  "name": "Customer success",
  "description": "Account managers for property-management customers.",
  "users": [
    {
      "id": "9c41d2e8-3f6a-4b7c-8d1e-5a2f7b9c0d3e",
      "first_name": "Dana",
      "last_name": "Whitfield",
      "email_address": "dana@harborline.example",
      "status": "active",
      …
    },
    {
      "id": "44c3f6da-393b-4664-9bfa-3c14e76b8cb8",
      "first_name": "Marcus",
      "last_name": "Oyelaran",
      "email_address": "marcus@harborline.example",
      "status": "active",
      …
    }
  ]
}

get/groups Read key

#List groups

Returns every group in your account in one response, each with its members; the list isn’t paginated. It takes no parameters.

Returns

collectionobject
Show 2 child attributesHide child attributes
- recordsarray of groups
- total_resultsinteger
  
  The number of groups returned.

get/groups

curl https://api.carom.io/groups \
  -H "Authorization: Bearer $CAROM_API_KEY"

Response200

{
  "collection": {
    "total_results": 2,
    "records": [
      {
        "id": "ecfda68b-7364-46c5-8e20-cffc98e6f291",
        "name": "Customer success",
        "description": "Account managers for property-management customers.",
        "users": […]
      },
      {
        "id": "6dd53ebb-eb27-4724-80dd-c172b7d75a49",
        "name": "Finance",
        "description": null,
        "users": […]
      }
    ]
  }
}

post/groups Write key

#Create a group

Creates a group and, when you send user_ids, adds those users to it. Requires an account admin.

Headers

Idempotency-Keystring

A key you choose, 1 to 255 printable ASCII characters, that makes the request safe to retry. When your key’s user repeats a request to this endpoint with the same key within 24 hours of a successful one, Carom returns the first response again instead of creating a second group. The request body isn’t compared, so use a new key for each new group. A failed request doesn’t use up its key.

Request body application/json

groupobjectrequired
Show 3 child attributesHide child attributes
- namestringrequired
- descriptionstring
- user_idsarray of strings · uuid
  
  The users to add. Ids of users outside your account are ignored; users in the response shows who was added.

Returns

The new group object with its members, wrapped in group, with status 201.

Errors

400invalid_requestA field failed validation, for example a missing name or a user id that isn’t a UUID, or the Idempotency-Key header is malformed.
403permission_deniedYour key’s user isn’t an account admin.
409idempotency_key_in_useA request with the same Idempotency-Key is still in progress. Retry shortly.

post/groups

curl https://api.carom.io/groups \
  -H "Authorization: Bearer $CAROM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2b7e4c19-6a3d-4f85-b0c2-9e1d5a7f3c64" \
  -d '{
    "group": {
      "name": "Customer success",
      "description": "Account managers for property-management customers.",
      "user_ids": [
        "9c41d2e8-3f6a-4b7c-8d1e-5a2f7b9c0d3e",
        "44c3f6da-393b-4664-9bfa-3c14e76b8cb8"
      ]
    }
  }'

Response201

{
  "group": {
    "id": "ecfda68b-7364-46c5-8e20-cffc98e6f291",
    "name": "Customer success",
    "description": "Account managers for property-management customers.",
    "users": [
      {
        "id": "9c41d2e8-3f6a-4b7c-8d1e-5a2f7b9c0d3e",
        "first_name": "Dana",
        …
      },
      {
        "id": "44c3f6da-393b-4664-9bfa-3c14e76b8cb8",
        "first_name": "Marcus",
        …
      }
    ]
  }
}

get/groups/{id} Read key

#Retrieve a group

Returns a single group with its members.

Path parameters

idstring · uuidrequired

The group’s id.

Returns

The group object, wrapped in group.

Errors

404record_not_foundNo group with that id exists in your account.

get/groups/{id}

curl https://api.carom.io/groups/ecfda68b-7364-46c5-8e20-cffc98e6f291 \
  -H "Authorization: Bearer $CAROM_API_KEY"

Response200

{
  "group": {
    "id": "ecfda68b-7364-46c5-8e20-cffc98e6f291",
    "name": "Customer success",
    "description": "Account managers for property-management customers.",
    "users": [
      {
        "id": "9c41d2e8-3f6a-4b7c-8d1e-5a2f7b9c0d3e",
        "first_name": "Dana",
        …
      },
      …
    ]
  }
}

patch/groups/{id} Write key

#Update a group

Changes the fields you send and leaves the rest alone. When you send user_ids, it replaces the group’s membership: users not in the list are removed and new ones are added. Requires an account admin.

Send null for description to clear it. Omit user_ids, or send null, to leave membership unchanged.

Path parameters

idstring · uuidrequired

Request body application/json

groupobjectrequired

Any of the attributes accepted by Create a group. user_ids is the complete new member list.

Returns

The updated group object, wrapped in group.

Errors

400invalid_requestA field failed validation, for example an empty name.
403permission_deniedYour key’s user isn’t an account admin.
404record_not_foundNo group with that id exists in your account.

patch/groups/{id}

curl -X PATCH https://api.carom.io/groups/ecfda68b-7364-46c5-8e20-cffc98e6f291 \
  -H "Authorization: Bearer $CAROM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "group": {
      "user_ids": [
        "9c41d2e8-3f6a-4b7c-8d1e-5a2f7b9c0d3e",
        "44c3f6da-393b-4664-9bfa-3c14e76b8cb8",
        "ea5f6800-b2b7-4df4-a5e9-3a4ed2d84961"
      ]
    }
  }'

Response200

{
  "group": {
    "id": "ecfda68b-7364-46c5-8e20-cffc98e6f291",
    "name": "Customer success",
    "users": [
      { "id": "9c41d2e8-3f6a-4b7c-8d1e-5a2f7b9c0d3e", "first_name": "Dana", … },
      { "id": "44c3f6da-393b-4664-9bfa-3c14e76b8cb8", "first_name": "Marcus", … },
      { "id": "ea5f6800-b2b7-4df4-a5e9-3a4ed2d84961", "first_name": "Elena", … }
    ],
    …
  }
}

delete/groups/{id} Write key

#Delete a group

Deletes the group and removes it from the assigned_group_ids of every task it was assigned to. Members lose access to spaces, pipelines, mailboxes, and shared records that they had only through the group. The users themselves are not otherwise affected. Requires an account admin. Deletion is permanent.

Path parameters

idstring · uuidrequired

Returns

An empty response with status 204.

Errors

403permission_deniedYour key’s user isn’t an account admin.
404record_not_foundNo group with that id exists in your account.

delete/groups/{id}

curl -X DELETE https://api.carom.io/groups/6dd53ebb-eb27-4724-80dd-c172b7d75a49 \
  -H "Authorization: Bearer $CAROM_API_KEY"

Response204

No content