Groups

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
(string | number)[]
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
(string | number)[]
The IDs of users to add to this group.

remove
optional
(string | number)[]
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 application.

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:


name
string | null
Full user name

id
string | number
Provided ID for the user

createdTimestamp
Date | null
Creation timestamp

email
string | null

shortName
string | null
Short user name. In most cases, this will be preferred over name when set.

status
"active" | "deleted"

profilePictureURL
string | null
This must be a valid URL, which means it needs to follow the usual URL formatting and encoding rules. For example, any space character will need to be encoded as %20. We recommend using your programming language's standard URL encoding function, such as encodeURI in Javascript.

metadata
EntityMetadata
Arbitrary key-value pairs that can be used to store additional information.

pagination
PaginationDetails

This is an object with the following fields:


token
string | null
The token to use to get the next page of results. If empty, there are no more results.

total
number
Total number of results. Might be bigger than the number of results returned on the query. Useful to display a "total" counter.

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
(string | number)[]
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

Ask Cordy