Cord LogoDocs
Sign inStart now

Users

REST API /

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 #

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.

Example Request #

curl "https://api.cord.com/v1/users/123" \
-X PUT \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
  "name": "Bender Bending Rodriguez",
  "profilePictureURL": "https://cord.com/favicon-32x32.png"
}'
Copy

If successful, the response will be:

{
  "success": true
}
Copy

List users #

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

HTTP Request #

GET https://api.cord.com/v1/users?limit=25
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.
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
Arbitrary key-value pairs of data associated with the 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 "https://api.cord.com/v1/users" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
Copy

If successful, the response will be:

[
  users: [
    {
      "id": "3001",
      "name": "Philip J Fry",
      "email": "delivery@planetexpress.nny",
    },
    {
      "id": "123",
      "name": "Bender Bending Rodriguez",
      "email": "bending@planetexpress.nny"
    }
  ],
  pagination: {
    token: "eTJhbGciOiJIUzI1NiIsInR5cCI63kpXVC09=",
    total: 200,
    remaining: 175
  }
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 #

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:

organizations
(string | number)[]
List of organizations the user is a member of.
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 "https://api.cord.com/v1/users/3001" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
Copy

If successful, the response will be:

{
  "id": "3001",
  "name": "Philip J Fry",
  "email": "delivery@planetexpress.nny",
  "organizations": ["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 #

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 "https://api.cord.com/v1/users/h349f0s-kjsf20-sdk0e3" \
  -X DELETE 
  -H "Authorization: Bearer <ACCESS_TOKEN>"
  -d '{
    "permanently_delete": true
  }'
Copy

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

{
  "success": true,
  "message": "User deleted.",
  "userID": "h349f0s-kjsf20-sdk0e3",
}
Copy

Ask Cordy