Cord LogoDocs
Sign inStart now

Groups

REST API /
Ask the Community

All available operations for manipulating groups and their information

Check out our integration guide to understand how user syncing fits in your backend workflow

Create or update a group #

This endpoint creates or updates a group:

  • if the group does not exist in the Cord backend (based on its ID), it will be created; some fields are required.
  • if the group exists, it will be updated: all fields are optional, only the fields provided will be updated; if the request is updating the members list, the list is treated as exhaustive: all member user IDs must be included, previous members who are not in the list will be removed.

HTTP Request #

HTTP:
PUT https://api.cord.com/v1/groups/<ID>
cURL:
curl https://api.cord.com/v1/groups/<ID> \
-X PUT \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
CLI:
# you can install @cord-sdk/cli for a simpler experience

# create
cord group create <ID>
# update
cord group update <ID>
PUT https://api.cord.com/v1/groups/<ID>
Copy

For more information about IDs, check out our Identifiers concept breakdown.

Request Body #

Listed below are the fields of the request body to be added as part of the HTTP PUT request.

name
optional
string
Group name. Required when creating an group.
status
optional
"active" | "deleted"
Whether this group is active or deleted. Attempting to log into a deleted group will fail.
metadata
optional
EntityMetadata
Arbitrary key-value pairs that can be used to store additional information.
members
optional
ID[]
List of partner-specific IDs of the users who are members of this group. This will replace the existing members.

Example Request #

cURL:
curl "https://api.cord.com/v1/groups/456" \
-X PUT \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
  "name": "Planet Express",
  "members": ["4", "42"]
}'
CLI:
# you can install @cord-sdk/cli for a simpler experience
cord group create 456
--name="Planet Express"
--members='["4", "42"]'
            
curl "https://api.cord.com/v1/groups/456" \
-X PUT \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
  "name": "Planet Express",
  "members": ["4", "42"]
}'
Copy

If creation was successful, the response will be:

JSON:
{
  "success": true,
  "message": "✅ You successfully created group 456"
}
{
  "success": true,
  "message": "✅ You successfully created group 456"
}
Copy

If update was successful, the response will be:

JSON:
{
  "success": true,
  "message": "✅ You successfully updated group 456"
}
{
  "success": true,
  "message": "✅ You successfully updated group 456"
}
Copy

Update group members #

Use this endpoint to add and/or remove members from a group.

Requests to add a user that is already a member of that group, or remove a user that is not a member, will have no effect (but will not return an error).

Note: It is an error to add and remove the same user in a single request.

HTTP Request #

HTTP:
POST https://api.cord.com/v1/groups/<ID>/members
cURL:
curl https://api.cord.com/v1/groups/<ID>/members \
-X POST \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
CLI:
# you can install @cord-sdk/cli for a simpler experience
# add
cord group add-member <GROUP_ID> 
# remove
cord group remove-member <GROUP_ID>

POST https://api.cord.com/v1/groups/<ID>/members
Copy

Request Body #

Listed below are the fields of the request body to be added as part of the HTTP POST request.

add
optional
ID[]
The IDs of users to add to this group.
remove
optional
ID[]
The IDs of users to remove from this group.

Example Request #

cURL:
curl "https://api.cord.com/v1/groups/456/members" \
  -X POST \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "add": ["4", "66"],
    "remove": ["42"]
  }'
CLI:
# you can install @cord-sdk/cli for a simpler experience
cord group add-member 456 --user=4
cord group add-member 456 --user=66
cord group remove-member 456 --user=42
            
curl "https://api.cord.com/v1/groups/456/members" \
  -X POST \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "add": ["4", "66"],
    "remove": ["42"]
  }'
Copy

If successful, the response will be:

JSON:
{
  "success": true,
  "message": "✅ You successfully updated group members"
}
{
  "success": true,
  "message": "✅ You successfully updated group members"
}
Copy

List groups #

Use this endpoint to list all groups that you have created within your Cord project.

HTTP Request #

HTTP:
GET https://api.cord.com/v1/groups
cURL:
curl https://api.cord.com/v1/groups \
-H 'Authorization: Bearer <ACCESS_TOKEN>'
CLI:
# you can install @cord-sdk/cli for a simpler experience
cord group ls
GET https://api.cord.com/v1/groups
Copy

Request Body #

This endpoint does not require a request body.

Response #

The response is an object containing the information about the groups:

name
string
Group name. Required when creating an group.
id
string | number
ID of the group
status
"active" | "deleted"
Whether this group is active or deleted. Attempting to log into a deleted group will fail.
metadata
EntityMetadata
Arbitrary key-value pairs that can be used to store additional information.
connectedToSlack
boolean
If the group has connected to a Slack workspace

Example Request #

cURL:
curl "https://api.cord.com/v1/groups" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
CLI:
# you can install @cord-sdk/cli for a simpler experience
cord group ls
curl "https://api.cord.com/v1/groups" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
Copy

If successful, the response will be:

JSON:
[
  {
    "id": "10",
    "name": "Planet Express"
  }
]
[
  {
    "id": "10",
    "name": "Planet Express"
  }
]
Copy

List group members #

Use this endpoint to list all members from a group.

HTTP Request #

HTTP:
GET https://api.cord.com/v1/groups/<ID>/members
cURL:
curl https://api.cord.com/v1/groups/<ID>/members \
-X GET \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
GET https://api.cord.com/v1/groups/<ID>/members
Copy

Request Body #

This endpoint does not require a request body.

Request Parameters #

The endpoint supports the following query request parameters:

limit
optional
number
Number of group members to return. The default limit is set to 1000.
token
optional
string
Pagination token. This is returned in the pagination object of a previous response.

Response #

The response is an object containing the information about the groups members:

users
ServerListGroupMember[]

This is an array of objects, each of which has the following fields:

Show property details

pagination
PaginationDetails

This is an object with the following fields:

Show property details

Example Request #

cURL:
curl "https://api.cord.com/v1/groups/456/members" \
  -X GET \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \

curl "https://api.cord.com/v1/groups/456/members" \
  -X GET \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
Copy

If successful, the response will be:

JSON:
{
  "users": [
    {
      "id": "3001",
      "name": "Philip J Fry",
      "email": "delivery@planetexpress.nny",
    },
    {
      "id": "123",
      "name": "Leela Turanga",
      "email": "capt@planetexpress.nny"
    }
  ],
  "pagination": {
    "token": "eTJhbGciOiJIUzI1NiIsInR5cCI63kpXVC09=",
    "total": 5
  }
}
{
  "users": [
    {
      "id": "3001",
      "name": "Philip J Fry",
      "email": "delivery@planetexpress.nny",
    },
    {
      "id": "123",
      "name": "Leela Turanga",
      "email": "capt@planetexpress.nny"
    }
  ],
  "pagination": {
    "token": "eTJhbGciOiJIUzI1NiIsInR5cCI63kpXVC09=",
    "total": 5
  }
}
Copy

Get group details #

HTTP Request #

HTTP:
GET https://api.cord.com/v1/groups/<ID>
cURL:
curl https://api.cord.com/v1/groups/<ID> \
-H 'Authorization: Bearer <ACCESS_TOKEN>'
CLI:
# you can install @cord-sdk/cli for a simpler experience
cord group get <ID>
GET https://api.cord.com/v1/groups/<ID>
Copy

For more information about IDs, check out our Identifiers concept breakdown.

Request Body #

This endpoint does not require a request body.

Response #

The response is a JSON Object with the following fields:

id
string | number
ID of the group
name
string
Group name. Required when creating an group.
status
"active" | "deleted"
Whether this group is active or deleted. Attempting to log into a deleted group will fail.
members
ID[]
List of partner-specific IDs of the users who are members of this group
connectedToSlack
boolean
If the group has connected to a Slack workspace
metadata
EntityMetadata
Arbitrary key-value pairs that can be used to store additional information.

Example Request #

cURL:
curl "https://api.cord.com/v1/groups" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
CLI:
# you can install @cord-sdk/cli for a simpler experience
cord group get <ID>
curl "https://api.cord.com/v1/groups" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
Copy

If the request is successful and the group exists, the response payload will be of the form:

JSON:
{
  "id": "10",
  "name": "Planet Express",
  "members": ["4", "42"],
  "connectedToSlack": false
}
{
  "id": "10",
  "name": "Planet Express",
  "members": ["4", "42"],
  "connectedToSlack": false
}
Copy

Delete a group #

This endpoint will permanently delete a group and associated data. This operation will delete all threads and message associated with the group. Please only use this endpoint if you are okay with that. Users will not be deleted because users can be in multiple groups. However, deleting the group also removes all users from the group.

HTTP Request #

HTTP:
DELETE https://api.cord.com/v1/groups/<ID>
cURL:
curl https://api.cord.com/v1/groups/<ID> \
-X DELETE \
-H 'Authorization: Bearer <ACCESS_TOKEN>'
CLI:
# you can install @cord-sdk/cli for a simpler experience
cord group delete <ID>
DELETE https://api.cord.com/v1/groups/<ID>
Copy

For more information about IDs, check out our Identifiers concept breakdown.

Request Body #

This endpoint does not require a request body.

Example Request #

cURL:
curl -X DELETE "https://api.cord.com/v1/groups/456" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
CLI:
# you can install @cord-sdk/cli for a simpler experience
cord group delete <ID>
curl -X DELETE "https://api.cord.com/v1/groups/456" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
Copy

If the request is successful and the group is now deleted, the response payload will be of the form:

JSON:
{
  "success": true,
  "message": "✅ You successfully deleted group 456"
}
{
  "success": true,
  "message": "✅ You successfully deleted group 456"
}
Copy

Not finding the answer you need? Ask our Developer Community

Ask Cordy