Batch

Using a single API call to update multiple users and groups


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

Use this for cases where you need to take actions on several groups or users at once. The action taken for each entity is 'create or update': If a user or group with that ID already exists, it will be updated with the provided data, otherwise it will be created.

If any of the changes produces an error, none of the changes will be applied, so you're always in a known state.

HTTP Request #

HTTP:
POST https://api.cord.com/v1/batch
POST https://api.cord.com/v1/batch
Copy

Request Body #

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


users
optional
BatchUpdateUser[]
List of user objects. Every object must include the id field. If the user already exists, all other fields are optional and only updated when present. If the user does not already exist, fields are required as described in the Create or update a user API.

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


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.

id
required
string | number

groups
optional
BatchUpdateGroup[]
List of group objects. Every object must include the id field. If the group already exists, all other fields are optional and only updated when present. If the group does not already exist, fields are required as described in the Create or update a group API.

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


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.

id
required
string | number

Deleting users

To remove a user across your application, Cord's data model includes a status field on the User object. If that value is set as deleted, the user will no longer be able to use Cord. This means they won't be able to load Cord components, be marked as present, view past conversations, etc.. The user will also disappear from any facepiles they were previously shown in. However, any messages they've sent will still exist. This applies across all groups that the user was a member of.

Setting the status field to active reverses this change, causing the user to reappear where they had previously been present and allowing the user to login and use Cord again.

You may want to remove a user from a particular Group rather than removing them from across the application. For more information on this, see the Groups API.

Example Request #

cURL:
curl "https://api.cord.com/v1/batch" -X POST -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Content-Type: application/json" -d '{
  "groups": [
    {
      "id": "10",
      "name": "Planet Express",
      "members": ["4", "42"]
    }
  ],
  "users": [
    {
      "id": "4",
      "name": "Hubert Farnsworth",
      "email": "hubert@planetexpress.nny"
    },
    {
      "id": "42",
      "name": "Leela Turanga",
      "email": "leela@planetexpress.nny"
    }
  ]
}'
curl "https://api.cord.com/v1/batch" -X POST -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Content-Type: application/json" -d '{
  "groups": [
    {
      "id": "10",
      "name": "Planet Express",
      "members": ["4", "42"]
    }
  ],
  "users": [
    {
      "id": "4",
      "name": "Hubert Farnsworth",
      "email": "hubert@planetexpress.nny"
    },
    {
      "id": "42",
      "name": "Leela Turanga",
      "email": "leela@planetexpress.nny"
    }
  ]
}'
Copy

Ask Cordy