Questions

Overview

Questions make up the parts of survey or form components. They are contained within surveys through survey chats.

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 Questions

Returns all questions within the company.

GET /questions

Endpoint URL

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

Headers

Header	Description	Required	Values
Admin	Authorizes the use of some options.	Depends on the query parameters.	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
limit	Limits the amount of questions 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 questions within the company.	boolean	Optional
ids OR _id	Returns questions with the IDs indicated in the array.	ObjectId<COTQuestion>[ ]	Optional
modified	Returns questions with the indicated modification date in the `modifiedAt` field.	ISODate	Optional	YYYY-MM-DDTHH:mm:ss.SSSZ
modified_gt	Returns questions modified after the indicated date and time.	ISODate	Optional	YYYY-MM-DDTHH:mm:ss.SSSZ
modified_gte	Returns questions with a value in the `modifiedAt` field equal to or greater than the indicated date and time.	ISODate	Optional	YYYY-MM-DDTHH:mm:ss.SSSZ
modified_lt	Returns questions modified before the indicated date and time.	ISODate	Optional	YYYY-MM-DDTHH:mm:ss.SSSZ
modified_lte	Returns questions with a value in the `modifiedAt` field equal to or less than the indicated date and time.	ISODate	Optional	YYYY-MM-DDTHH:mm:ss.SSSZ
created	Returns questions with the indicated creation date in the `createdAt` field.	ISODate	Optional	YYYY-MM-DDTHH:mm:ss.SSSZ
created_gt	Returns questions created after the indicated date and time.	ISODate	Optional	YYYY-MM-DDTHH:mm:ss.SSSZ
created_gte	Returns questions with a value in the `createdAt` field equal to or greater than the indicated date and time.	ISODate	Optional	YYYY-MM-DDTHH:mm:ss.SSSZ
created_lt	Returns questions created before the indicated date and time.	ISODate	Optional	YYYY-MM-DDTHH:mm:ss.SSSZ
created_lte	Returns questions with a value in the `createdAt` field equal to or less than the indicated date and time.	ISODate	Optional	YYYY-MM-DDTHH:mm:ss.SSSZ
isActive	Returns questions according to their `isActive` status.	string	Optional	Options are: `all`, `true`, `false` Requires the "Admin" header.
debug	Adds the `debug` field with error notifications.	string	Optional	Option: `true`

Request Samples

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

This default request gets all the questions in the company.

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

This request gets the questions modified on or after the indicated date and time.

curl --location --request GET 'https://www.cotalker.com/api/v2/questions?modified_gte=2020-11-24T14:59:40.366Z' \
--header 'Authorization: Bearer $ACCESS_TOKEN'

This example gets all the questions in the company.

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

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

async function getQuestions(): Promise<QuestionGetCollection | undefined> {
    const response = await api.getV2Questions();
    return response.data?.data;
}

getQuestions().then(questions => console.log(questions)).catch(e=>console.log(e))

Response Sample

Responses follow the COTQuestion data model.

Get a Question by Id

Returns the question indicated by the Id.

GET /questions/{id}

Endpoint URL

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

Path Parameters

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

Headers

Header	Description	Required	Values
Admin	Authorizes the use of some options.	Depends on the query parameters.	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`
isActive	Returns the question if it coincides with the selected `isActive` status.	string	Optional	Options are: `all`, `true`, `false`. Requires the "Admin" header to funcion properly.

Request Sample

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

Response Sample

The response follows the COTQuestion data model.

Create a New Question

Creates a new question.

POST /questions

Endpoint URL

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

Headers

Header	Description	Required	Values
Admin	Grants administrative access to create a new survey chat.	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 COTQuestion data model. Unrequired fields that are not submitted are either filled in automatically or left blank.

Element	Description	Type	Required	Notes
contentType	Indicates COTQuestionContentType, i.e. survey component type	string	Required	List of question content types
display	Displayed question title or field label	string[ ]	Required	Its contents depend on the `contentType` and whether the data model corresponds to the title section of the question.

Request Sample

Survey chat created with the minimum required fields:

curl --location --request POST 'https://www.cotalker.com/api/v2/questions' \
--header 'Admin: true' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "display": [
        "Input 4"
    ],
    "contentType": "application/vnd.cotalker.survey+text"
}'

Response Sample

Go to COTQuestion for a complete description of the response.

{
    "command": {
        "commands": [],
        "resetIdentifiers": [],
        "values": []
    },
    "display": [
        "Input 4"
    ],
    "code": [],
    "isActive": true,
    "isSystemModel": false,
    "_id": "61a65dfd61adbedb7d7511c3",
    "contentType": "application/vnd.cotalker.survey+text",
    "company": "6136968b580aaf2b0e49d844",
    "identifier": "1638291417215hoo28",
    "modifiedAt": "2021-11-30T16:56:57.219Z",
    "textAlign": "left",
    "__v": 0
}

Update a Question

Updates or edits an existing question.

PATCH /questions/{id}

Endpoint URL

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

Path Parameters

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

Headers

Header	Description	Required	Values
Admin	Grants administrative access to modify a question.	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 COTQuestion data model.

Request Sample

This sample sets up conditional display questions inserting a command object:

curl --location --request PATCH 'https://www.cotalker.com/api/v2/questions/61a66fdc9e7c38b758a0b93d?debug=true' \
--header 'Admin: true' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "command": {
        "commands": [],
        "resetIdentifiers": [],
        "isCommanded": "item_list",
        "values": [
            {
                "_id": "615af821b0ca3100073e4f1a",
                "op": "eq",
                "target": "op_1"
            }
        ]
    }
}'

Response Sample

Go to COTQuestion for a complete description of the response.

{
    "command": {
        "commands": [],
        "resetIdentifiers": [],
        "values": [
            {
                "_id": "615af821b0ca3100073e4f1a",
                "op": "eq",
                "target": "op_1"
            }
        ],
        "isCommanded": "item_list"
    },
    "display": [
        "Input 1"
    ],
    "code": [],
    "isActive": true,
    "isSystemModel": false,
    "_id": "61a66fdc9e7c38b758a0b93d",
    "contentType": "application/vnd.cotalker.survey+text",
    "company": "6136968b580aaf2b0e49d844",
    "identifier": "1638287705330orcsk",
    "modifiedAt": "2021-11-30T18:21:24.335Z",
    "textAlign": "left",
    "__v": 0,
    "isReadOnly": false
}

QR Code & NFC function

Gather information for your surveys through QR code scan and NFC by adding the corresponding values in the question's code field.

note

Only functional on mobile devices.
Configurable only through API requests.

POST /questions

Endpoint URL

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

Headers

Header	Description	Required	Values
Admin	Grants administrative access to create a new question.	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

Field	Description	Type	Required	Notes
code	Code depends on the content type. Below is the code for scanning QR & NFC in surveys.	string[ ]	Required	Objects within the array must be written in string format.
code[index].scan		object	Required
code[index].scan.enabled	`true` activates the feature.	boolean	Required
code[index].scan.source	Indicates the input source.	string[ ]	Required	Valid options: `qr` and/or `nfc`.
code[index].scan.force	`true` allows only QR Code or NFC input. `false` permits manual text input, also.	boolean	Required
contentType	Indicates how the system should interpret the data.	string	Required	Must be set to: `application/vnd.cotalker.survey+textinput`
identifier	Unique identification name	string	Required	Maximum 60 characters; only lowercase letters, numbers, and underscore allowed; must be unique.

Request Sample

curl --location --request POST 'https://www.cotalker.com/api/v2/questions?debug=true' \
--header 'Admin: true' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "code": [
        "{\"scan\":{\"enabled\":true,\"source\":[\"qr\",\"nfc\"],\"force\":true}}"
    ],
    "display": [
        "input 3"
    ],
    "identifier": "qr_nfc_input",
    "contentType": "application/vnd.cotalker.survey+textinput"
}'

Response Sample

Go to COTQuestion for a complete description of the response.

{
    "_id": "61a78c177f130200079de9d3",
    "command": {
        "commands": [],
        "resetIdentifiers": [],
        "values": []
    },
    "display": [
        "input 3"
    ],
    "code": [
        "{\"scan\":{\"enabled\":true,\"source\":[\"qr\",\"nfc\"],\"force\":true}}"
    ],
    "isActive": true,
    "isSystemModel": false,
    "identifier": "qr_test",
    "contentType": "application/vnd.cotalker.survey+textinput",
    "company": "6136968b580aaf2b0e49d844",
    "modifiedAt": "2021-12-01T14:52:07.636Z",
    "__v": 0
}

Overview​

Get Questions​

Endpoint URL​

Headers​

Query Parameters​

Request Samples​

Response Sample​

Get a Question by Id​

Endpoint URL​

Path Parameters​

Headers​

Query Parameters​

Request Sample​

Response Sample​

Create a New Question​

Endpoint URL​

Headers​

Query Parameters​

Request Body​

Request Sample​

Response Sample​

Update a Question​

Endpoint URL​

Path Parameters​

Headers​

Query Parameters​

Request Body​

Request Sample​

Response Sample​

QR Code & NFC function​

Endpoint URL​

Headers​

Query Parameters​

Request Body​

Request Sample​

Response Sample​

Overview

Get Questions

Endpoint URL

Headers

Query Parameters

Request Samples

Response Sample

Get a Question by Id

Endpoint URL

Path Parameters

Headers

Query Parameters

Request Sample

Response Sample

Create a New Question

Endpoint URL

Headers

Query Parameters

Request Body

Request Sample

Response Sample

Update a Question

Endpoint URL

Path Parameters

Headers

Query Parameters

Request Body

Request Sample

Response Sample

QR Code & NFC function

Endpoint URL

Headers

Query Parameters

Request Body

Request Sample

Response Sample