Surveys

Overview

A survey is a way of gathering information from users through workflows, channels, bots, or even public surveys outside the Cotalker environment.

The /surveys API request works with survey data models (COTSurvey), which consolidate other data models: COTSurveyChat, COTQuestion, COTAnswer.

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 Surveys

Returns all surveys within the company.

GET /surveys

Endpoint URL

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

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
limit	Limits the amount of surveys 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 surveys within the company.	boolean	Optional
answer	Returns the ObjectId of the survey associated with the indicated answer.	string[ ]	Optional	Answers are identified by the ObjectId in their uuid field.
select	Surveys are returned showing only the indicated fields.	string[ ]	Optional	For example, GET /surveys?select=code, returns surveys displaying only the code field.
isActive	Returns surveys according to their isActive status.	string	Optional	Options are: all, true, false
search	Returns surveys with field values that begin with the search query.	string	Optional
debug	Adds the debug field with error notifications.	string	Optional	Option: true

Request Samples

cURL (default)

This default request gets all the surveys in the company.

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

cURL (query)

This request gets the survey related to the indicated answer.

curl --location --request GET 'https://www.cotalker.com/api/v2/surveys?answer=61a4f900cafd3b3a5cfd8cc3' \
--header 'Authorization: Bearer $ACCESS_TOKEN'

Typescript (default)

This example gets all the surveys in the company.

// $ACCESS_TOKEN stored in .env file.
import { SurveyGetCollection, Configuration, V2SurveysApi} from "@cotalker/cotalker-api";

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

async function getSurveys(): Promise<SurveyGetCollection | undefined> {
    const response = await api.getV2Surveys();
    return response.data?.data;
}

getSurveys().then(surveys => console.log(surveys)).catch(e=>console.log(e))

Response Sample

Responses follow the COTSurvey data model.

---

Get a Survey by Id

Returns the survey indicated by the Id.

GET /surveys/{id}

Endpoint URL

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

Path Parameters

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

Headers

Header	Description	Required	Values
Admin	Grants access to request the endpoint.	Required	true
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
populate	Returns the survey with the chat field which contains all the survey's survey chats, i.e., all of the the survey's components.	boolean	Optional

Request Sample

curl --location --request GET 'https://www.cotalker.com/api/v2/surveys/61a500049cf5178a9a6c1abe' \
--header 'Admin: true' \
--header 'Authorization: Bearer $ACCESS_TOKEN'

Response Sample

The response follows the COTSurvey data model.

---

Create a New Survey

Creates a new survey within the company.

POST /surveys

Endpoint URL

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

Headers

Header	Description	Required	Values
Admin	Grants administrative access to create a new survey.	Required	true
Authorization	Sends your access token to make an API request. Click here to see how to obtain an access token.	Required	Bearer $ACCESS_TOKEN
Content-Type	Indicates 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 required fields are listed below. For a complete schema description, please go to the COTSurvey data model. Unrequired fields that are not submitted are either filled in automatically or left blank.

Element	Description	Type	Required	Notes
code	The survey's unique identification name	string	Required	Maximum 60 characters; only lowercase letters, numbers, and underscore allowed; must be unique.
name	The survey's displayed name in the administrative panel	string	Required
version	Indicates the survey version and determines what fields should be used; 1 uses fields prior to January 2019; 2 uses fields created after January 2019	number	Required	Fields prior to January 2019: permissions, group, groupPermissions. Fields created after January 2019: permissionsV2, groupPermissionsV2, onlySubSurvey.

Request Sample

Survey created with the minimum required fields:

curl --location --request POST 'https://www.cotalker.com/api/v2/surveys' \
--header 'Admin: true' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Work Order",
    "code": "work_order_survey",
    "version": 1
}'

Response Sample

Go to COTSurvey for a complete description of the response.

{
    "permissions": [],
    "permissionsV2": [],
    "groupPermissionsV2": [],
    "onlySubSurvey": false,
    "propertiesChannel": [],
    "propertiesLimit": [],
    "isActive": true,
    "isSystemModel": false,
    "version": 1,
    "_id": "61a50f928843af3e1332c67f",
    "name": "Work Order",
    "code": "work_order_survey",
    "company": "6136968b580aaf2b0e49d844",
    "createdAt": "2021-11-29T16:58:27.044Z",
    "responders": [],
    "modifiedAt": "2021-11-29T16:58:27.045Z",
    "__v": 0
}

---

Update a Survey

Updates or edits an existing survey.

PATCH /surveys/{id}

Endpoint URL

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

Path Parameters

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

Headers

Header	Description	Required	Values
Admin	Grants administrative access to modify a survey.	Required	true
Authorization	Sends your access token to make an API request. Click here to see how to obtain an access token.	Required	Bearer $ACCESS_TOKEN
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 COTSurvey data model.

Request Sample

This sample adds an access role objectId to the permissions field:

curl --location --request PATCH 'https://www.cotalker.com/api/v2/surveys/61a50f928843af3e1332c67f' \
--header 'Admin: true' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "permissions": "61a51e04e98c389d90eea21d"
}'

Response Sample

Go to COTSurvey for a complete description of the response.

{
    "permissions": [
        "61a51e04e98c389d90eea21d"
    ],
    "permissionsV2": [],
    "groupPermissionsV2": [],
    "onlySubSurvey": false,
    "propertiesChannel": [],
    "propertiesLimit": [],
    "isActive": true,
    "isSystemModel": false,
    "version": 1,
    "_id": "61a50f928843af3e1332c67f",
    "name": "Work Order",
    "code": "work_order_survey",
    "company": "6136968b580aaf2b0e49d844",
    "createdAt": "2021-11-29T16:58:27.044Z",
    "responders": [],
    "modifiedAt": "2021-11-29T18:38:15.394Z",
    "__v": 2
}

---