Users

Overview

A user represents a person or bot that can perform actions within a company and execute client-side actions such as participating in tasks, entering channels, answering surveys, and sending messages.

The users endpoint can be used to search for users, retrieve information, or group them by filtering their data. All this allows using user information for further automations.

additional resources

These are just some of the most basic API requests. For a complete list of endpoints, consult our API documentation on Swagger.

Get Users

Returns data from all users in the company.

GET /users

Endpoint URL

https://www.cotalker.com/api/v2/users

Headers

Header	Description	Required	Values
Authorization	Sends your access token to make an API request. Click here to see how to obtain an access token.	Required	Bearer $ACCESS_TOKEN

Query Parameters

Parameter	Description	Type	Required	Notes
search	Returns users that match the keywords in the `users.search` array.	string	Optional
limit	Limits the amount of users returned in the response.	number	Optional	By default, the limit is set to 10.
page	Makes the response display data from the indicated page number.	number	Optional	Best used in combination with the "limit" parameter.
count	Adds the `counter` field with the total amount of users.	boolean	Optional
orderBy	Orders the users by ascendeing or descending order according to the `users.modifiedAt` field.	string	Optional	Options: `asc`, `desc`
sortBy	For the user endpoint, the response is sorted only by its default, i.e., the `users.modifiedAt` field.	string	Optional
isActive	Returns users according to their users.isActive status.	string	Optional	Options are: `all`, `true`, `false`
email	Returns users with the emails contained in the array.	string[ ]	Optional
bot	Returns users with the indicated COTBot ObjectIds in their `users.bot` field.	ObjectId<COTBot>[ ]	Optional
id	Returns users with the indicated ObjectIds in their `users._id` field.	ObjectId<COTUser>[ ]	Optional
relatedUser	Returns users related to the indicated user according the `users.companies.hierarchy` field.	ObjectId<COTUser>	Optional
property	Returns users associated with the indicated property: `users.properties`.	ObjectId<COTProperty>	Optional
accessRole	Returns users with the indicated access role: `users.accessRoles`.	ObjectID<COTAccessRole>	Optional
job	Returns users associated with the indicated job title: `users.job`.	ObjectId<COTJobTitle>	Optional
modified	Returns users with the indicated modification date: `users.modifiedAt`	ISODate	Optional	YYYY-MM-DDTHH:mm:ss.SSSZ
modified_gt	Returns users modified after the indicated date and time.	ISODate	Optional	YYYY-MM-DDTHH:mm:ss.SSSZ
modified_gte	Returns users with a `users.modifiedAt` equal to or greater than the indicated date and time.	ISODate	Optional	YYYY-MM-DDTHH:mm:ss.SSSZ
created	Returns users with the indicated creation date: `users.createdAt`	ISODate	Optional	YYYY-MM-DDTHH:mm:ss.SSSZ
created_gt	Returns users created after the indicated date and time.	ISODate	Optional	YYYY-MM-DDTHH:mm:ss.SSSZ
created_gte	Returns users with a `users.createdAt` equal to or greater than the indicated date and time.	ISODate	Optional	YYYY-MM-DDTHH:mm:ss.SSSZ
created_lt	Returns users created before the indicated date and time.	ISODate	Optional	YYYY-MM-DDTHH:mm:ss.SSSZ
created_lte	Returns users with a `users.createdAt` equal to or less than the indicated date and time.	ISODate	Optional	YYYY-MM-DDTHH:mm:ss.SSSZ
debug	Adds the `debug` field with error notifications.	string	Optional	Option: `true`

Request Samples

cURL (default)
cURL (query)
Typescript (query)

This default request gets all the user data in the company.

curl --location --request GET 'https://www.cotalker.com/api/v2/users' \
--header 'Authorization: Bearer $ACCESS_TOKEN' 

This example uses the email query parameter to get matching users.

curl --location --request GET 'https://www.cotalker.com/api/v2/users?email=nick%40wuxi.com&email=yanxiang%40wuxi.com' \
--header 'Authorization: Bearer $ACCESS_TOKEN' 

This example uses the email query parameter to get matching users.

// $ACCESS_TOKEN stored in .env file.

import { Configuration, UserGetCollectionUsers, V2UsersApi } from "@cotalker/cotalker-api";

const api = new V2UsersApi(new Configuration({
    basePath: 'https://www.cotalker.com/api',
    accessToken: process.env.ACCESS_TOKEN,
    apiKey: 'true',
}));

async function getUsersByEmail(): Promise<UserGetCollectionUsers[] | undefined> {
    const response = await api.getV2Users({ email: ["nick@wuxi.com", "yanxiang@wuxi.com"] });  //query parameters used here
    return response.data?.data?.users;
}

getUsersByEmail().then(users => console.log(users)).catch(e=>console.log(e))

Response Sample

Responses follow the COTUser data model.

Get Current User

Returns the current user data.

GET /users/me

Endpoint URL

https://www.cotalker.com/api/v2/users/me

Headers

Header	Description	Required	Values
Authorization	Sends your access token to make an API request. Click here to see how to obtain an access token.	Required	Bearer $ACCESS_TOKEN

Request Sample

cURL
Typescript

curl --location --request GET 'https://www.cotalker.com/api/v2/users/me' \
--header 'Authorization: Bearer $ACCESS_TOKEN'

import { Configuration, COTUser, V2UsersApi } from "@cotalker/cotalker-api";

const api = new V2UsersApi(new Configuration({
    basePath: 'https://www.cotalker.com/api',
    accessToken: process.env.ACCESS_TOKEN,
}));


async function getMe(): Promise<COTUser | undefined> {
    const response = await api.getV2UsersMe();
    return response.data?.data;
}

getMe().then(user => console.log(user)).catch(e=>console.log(e))

Response Sample

Response follows the COTUser data model.

Get User by Id

Returns the user indicated by the Id.

GET /users/{id}

Endpoint URL

https://www.cotalker.com/api/v2/users/{id}

Path Parameters

Parameter	Description	Type	Required	Notes
id	The ObjectId of the user that is to be returned.	ObjectId<COTUser>	Required

Headers

Header	Description	Required	Values
Authorization	Sends your access token to make an API request. Click here to see how to obtain an access token.	Required	Bearer $ACCESS_TOKEN

Query Parameters

Parameter	Description	Type	Required	Notes
debug	Adds the `debug` field with error notifications.	string	Optional	Option: `true`

Request Sample

curl --location --request GET 'https://www.cotalker.com/api/v2/users/6194f0345923b62967d7ba46' \
--header 'Authorization: Bearer $ACCESS_TOKEN' 

Response Sample

Response follows the COTUser data model.

Create a New User

Creates a new user in the company following the COTUser data model.

POST /users

Endpoint URL

https://www.cotalker.com/api/v2/users

Headers

Header	Description	Required	Values
Authorization	Sends your access token to make an API request. Click here to see how to obtain an access token.	Required	Bearer $ACCESS_TOKEN
Admin	Grants administrative access to create a user.	Required	true
Content-Type	Sets the body's format.	Required	application/json

Query Parameters

Parameter	Description	Type	Required	Notes
notifyEmail	Sends an email notification to the newly created user. Only works when no password has been set.	string	Optional	Option: `true`
debug	Adds the `debug` field with error notifications.	string	Optional	Option: `true`

Request Body

Only required fields are listed below. For a complete schema description, please go to the COTUser data model. Unrequired fields that are not submitted are either filled in automatically or left blank.

Element	Description	Type	Required	Notes
accessRoles	The access roles the user has been designated.	ObjectID<COTAccessRole>[ ]	Required
email	The user's email.	string	Required	The email cannot be changed.
name	User's full name.	object
name.displayName	Displayed name on channel.	string	Required
name.names	The user's first and second names.	string	Required
name.lastName	The user's surname.	string	Required
name.secondLastName	The user's second surname.	string	Required

Request Sample

User created with minimum fields required:

curl --location --request POST 'https://www.cotalker.com/api/v2/users?debug=true' \
--header 'Admin: true' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": {
        "displayName": "Ma Tianbo",
        "names": "Tianbo",
        "lastName": "Ma",
        "secondLastName": ""
    },
    "email": "apple@jingmen.com",
    "accessRoles": [
        "619538262eebe7f03bde3db0",
        "6195382e7fde7e397f8b1f88",
        "61953833306b4481a5f5a34b"
    ]
}'

Response Sample

Go to COTUser for a complete description of the response.

{
    "_id": "61953bf9bdc3558a4966e54d",  // automatically generated ObjectId
    "name": {
        "displayName": "",
        "names": "Tianbo",
        "lastName": "Ma",
        "secondLastName": ""
    },
    "properties": [],
    "accessRoles": [  // ObjectId<COTAccessRole>[ ]
        "619538262eebe7f03bde3db0",
        "6195382e7fde7e397f8b1f88",
        "61953833306b4481a5f5a34b"
    ],
    "isActive": true,
    "termsConditions": false,
    "search": [  // automatically generated keywords
        "tianbo",
        "ma",
        "apple",
        "jingmen",
        "com",
        "applejingmencom"
    ],
    "isOnline": false,
    "email": "apple@jingmen.com",
    "companies": [
        {
            "hierarchy": {
                "boss": [],
                "peers": [],
                "subordinate": []
            },
            "_id": "61953bd8a1dd11a1943c28be",  // automatically generated ObjectId
            "companyId": "61953bd2155295659c76859c"  // ObjectId<COTCompany>
        }
    ],
    "lastRequestDate": "2021-11-17T15:34:42.171Z",
    "createdAt": "2021-11-17T15:34:42.171Z",
    "modifiedAt": "2021-11-17T15:34:42.206Z",
    "extensions": {}
}

Update a User

Adds, updates, or edits an existing user's information.

PATCH /users/{id}

Endpoint URL

https://www.cotalker.com/api/v2/users/{id}

Path Parameters

Parameter	Description	Type	Required	Notes
id	The ObjectId of the user that is to be modified.	ObjectId<COTUser>	Required

Headers

Header	Description	Required	Values
Authorization	Sends your access token to make an API request. Click here to see how to obtain an access token.	Required	Bearer $ACCESS_TOKEN
Admin	Grants administrative access to modify a user.	Required	true
Content-Type	Sets the body's format.	Required	application/json

Query Parameters

Parameter	Description	Type	Required	Notes
debug	Adds the `debug` field with error notifications.	string	Optional	Option: `true`

Request Body

Only the fields that are being updated or added are required to be put into the body. For a complete schema description, please go to the COTUser data model.

Request Sample

Updating a user's phone number:

curl --location --request PATCH 'https://www.cotalker.com/api/v2/users/61953bf9bdc3558a4966e54d' \
--header 'Admin: true' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "phone": "8675309"
}'

Response Sample

Go to COTUser for a complete description of the response.

{
    "_id": "61953bf9bdc3558a4966e54d",  // automatically generated ObjectId
    "name": {
        "displayName": "",
        "names": "Tianbo",
        "lastName": "Ma",
        "secondLastName": ""
    },
    "properties": [],
    "accessRoles": [  // ObjectId<COTAccessRole>[ ]
        "619538262eebe7f03bde3db0",
        "6195382e7fde7e397f8b1f88",
        "61953833306b4481a5f5a34b"
    ],
    "isActive": true,
    "termsConditions": false,
    "search": [  // automatically generated keywords
        "tianbo",
        "ma",
        "apple",
        "jingmen",
        "com",
        "applejingmencom"
    ],
    "isOnline": false,
    "email": "apple@jingmen.com",
    "companies": [
        {
            "hierarchy": {
                "boss": [],
                "peers": [],
                "subordinate": []
            },
            "_id": "61953bd8a1dd11a1943c28be",  // automatically generated ObjectId
            "companyId": "61953bd2155295659c76859c"  // ObjectId<COTCompany>
        }
    ],
    "lastRequestDate": "2021-11-17T15:34:42.171Z",
    "createdAt": "2021-11-17T15:34:42.171Z",
    "modifiedAt": "2021-11-17T15:34:42.206Z",
    "phone": "8675309",
    "extensions": {}
}

Overview​

Get Users​

Endpoint URL​

Headers​

Query Parameters​

Request Samples​

Response Sample​

Get Current User​

Endpoint URL​

Headers​

Request Sample​

Response Sample​

Get User by Id​

Endpoint URL​

Path Parameters​

Headers​

Query Parameters​

Request Sample​

Response Sample​

Create a New User​

Endpoint URL​

Headers​

Query Parameters​

Request Body​

Request Sample​

Response Sample​

Update a User​

Endpoint URL​

Path Parameters​

Headers​

Query Parameters​

Request Body​

Request Sample​

Response Sample​

Overview

Get Users

Endpoint URL

Headers

Query Parameters

Request Samples

Response Sample

Get Current User

Endpoint URL

Headers

Request Sample

Response Sample

Get User by Id

Endpoint URL

Path Parameters

Headers

Query Parameters

Request Sample

Response Sample

Create a New User

Endpoint URL

Headers

Query Parameters

Request Body

Request Sample

Response Sample

Update a User

Endpoint URL

Path Parameters

Headers

Query Parameters

Request Body

Request Sample

Response Sample