Users

All available operations for manipulating users and their information


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

Create or update a user #

This endpoint creates or updates a user:

  • if the user does not exist in the Cord backend (based on its ID), it will be created; some fields are required.
  • if the user exists, it will be updated; all fields are optional, only the fields provided will be updated.

HTTP Request #

HTTP:
PUT https://api.cord.com/v1/users/<ID>
cURL:
curl https://api.cord.com/v1/users/<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 user create <ID>
# update
cord user update <ID>
PUT https://api.cord.com/v1/users/<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 | null
Full user name

email
optional
string | null
Email address

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

status
optional
"active" | "deleted"

profilePictureURL
optional
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
optional
EntityMetadata
Arbitrary key-value pairs that can be used to store additional information.

addGroups
optional
string[]
A list of group IDs this user should be made a member of. It is an error to specify a group that doesn't exist or one that is also being removed in the same call. It is not an error to add a user to a group they're already a member of.

removeGroups
optional
string[]
A list of group IDs this user should stop being a member of. It is an error to specify a group that doesn't exist or one that is also being added in the same call. It is not an error to remove a user from a group they are not a member of.

Example Request #

cURL:
curl "https://api.cord.com/v1/users/123" \
-X PUT \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
  "name": "Leela Turanga",
  "profilePictureURL": "https://cord.com/favicon-32x32.png"
}'
CLI:
# you can install @cord-sdk/cli for a simpler experience
cord user create 123 
--name="Leela Turanga"
--profile-picture-url=https://cord.com/favicon-32x32.png
              
curl "https://api.cord.com/v1/users/123" \
-X PUT \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
  "name": "Leela Turanga",
  "profilePictureURL": "https://cord.com/favicon-32x32.png"
}'
Copy

If creation was successful, the response will be:

JSON:
{
  "success": true,
  "message": "✅ You successfully created user 123"
}
{
  "success": true,
  "message": "✅ You successfully created user 123"
}
Copy

If update was successful, the response will be:

JSON:
{
  "success": true,
  "message": "✅ You successfully updated user 123"
}
{
  "success": true,
  "message": "✅ You successfully updated user 123"
}
Copy

List users #

This endpoint lists all users created in the context of your application.

HTTP Request #

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

Request Body #

This REST endpoint has no request body.

Request Parameters #

The endpoint supports the following query request parameters:


limit
optional
number
Number of users 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.

filter
optional
Pick<FilterParameters, "metadata">
This is a JSON object with one optional entry. Users will be matched against the filter specified. This is a partial match, which means any keys other than the ones you specify are ignored when checking for a match. Please note that because this is a query parameter in a REST API, this JSON object must be URI encoded before being sent.

This is an object with the following fields:


metadata
optional
EntityMetadata
Return only objects containing these metadata keys and values. (Metadata is arbitrary key-value pairs of data that you can associate with an object.)

Response #

The response is a JSON object with the following fields:


users
ServerListUser[]

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


email
string | null

name
string | null
Full user name

id
string | number
Provided ID for the user

createdTimestamp
Date | null
Creation timestamp

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/users?limit=25" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
CLI:
# you can install @cord-sdk/cli for a simpler experience
cord user ls --limit=25
curl "https://api.cord.com/v1/users?limit=25" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
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: 200,
  }
}
{
  users: [
    {
      "id": "3001",
      "name": "Philip J Fry",
      "email": "delivery@planetexpress.nny",
    },
    {
      "id": "123",
      "name": "Leela Turanga",
      "email": "capt@planetexpress.nny"
    }
  ],
  pagination: {
    token: "eTJhbGciOiJIUzI1NiIsInR5cCI63kpXVC09=",
    total: 200,
  }
}
Copy

Get user details #

This endpoint fetches the information about a user that has been stored in Cord's backend. The data you retrieve here contains the same values that would be displayed in Cord's UI components when that user loads your application.

HTTP Request #

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

Request Body #

This REST endpoint has no request body.

Response #

The response is a JSON Object with the following fields:


groups
(string | number)[]
List of groups the user is a member of.

groupIDsWithLinkedSlackProfile
string[]
A list containing all the groups the user has explicity linked their Slack profile to. This list excludes groups connected to a Slack workspace where the user has not linked their Slack profile.

email
string | null

name
string | null
Full user name

id
string | number
Provided ID for the user

createdTimestamp
Date | null
Creation timestamp

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.

Example Request #

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

If successful, the response will be:

JSON:
{
  "id": "3001",
  "name": "Philip J Fry",
  "email": "delivery@planetexpress.nny",
  "groups": ["org1", "org2"]
}
{
  "id": "3001",
  "name": "Philip J Fry",
  "email": "delivery@planetexpress.nny",
  "groups": ["org1", "org2"]
}
Copy

Delete a user #

This endpoint will permanently delete a user and all associated data.

This operation will delete all threads and messages associated with the user. Please only use this endpoint if you are okay with that.

HTTP Request #

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

Request Body #

The request body contains only one field:


permanently_delete
required
boolean
The user will be deleted only if this value is true.

Example Request #

cURL:
curl "https://api.cord.com/v1/users/123" \
  -X DELETE \ 
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  --json '{ "permanently_delete": true }'
CLI:
# you can install @cord-sdk/cli for a simpler experience
cord user delete 123 
--permanently-delete=true
              
curl "https://api.cord.com/v1/users/123" \
  -X DELETE \ 
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  --json '{ "permanently_delete": true }'
Copy

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

JSON:
{
  "success": true,
  "message": "User deleted.",
  "userID": "123",
  // failedDeletionIDs is a list of any files we were unable
  // to delete that the user created.
  // Please reach out to us if it is crucial they be deleted.
  "failedDeletionIDs": [],
}
{
  "success": true,
  "message": "User deleted.",
  "userID": "123",
  // failedDeletionIDs is a list of any files we were unable
  // to delete that the user created.
  // Please reach out to us if it is crucial they be deleted.
  "failedDeletionIDs": [],
}
Copy

Ask Cordy