Cord LogoDocs
Sign inStart now

Groups

REST API /

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.
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 successful, the response will be:

JSON:
{
"success": true
}
{
"success": true
}
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:
[
  {
    "id": "3001",
    "name": "Philip J Fry",
    "email": "delivery@planetexpress.nny",
    "first_name": "Philip",
    "last_name": "Fry"
  },
  {
    "id": "123",
    "name": "Leela Turanga",
    "email": "capt@planetexpress.nny"
  }
]
[
  {
    "id": "3001",
    "name": "Philip J Fry",
    "email": "delivery@planetexpress.nny",
    "first_name": "Philip",
    "last_name": "Fry"
  },
  {
    "id": "123",
    "name": "Leela Turanga",
    "email": "capt@planetexpress.nny"
  }
]
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.
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

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

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/<id>" \
  -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/<id>" \
  -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,
}
{
  "success": true,
}
Copy

Ask Cordy