Properties (Elements)

Overview

Properties (also known as _elements) are like the rows of a database table, but much more. Properties are contained within property types (collections).

They are used to establish a relationship or define something. That's why you can use properties sometimes as a resource and others as an asset. For example, you can send a specific text to all the users that have the "Special Message" property. Since each user is simply a collection or property type, you can add properties to them.

Additionally, workflows use properties to define their states.

As you can see, the versatility of properties is quite significant.

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 Properties

Returns all properties within the company.

GET /properties

Endpoint URL

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

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 properties with field values that match the query.	string	Optional
limit	Limits the amount of properties 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 properties within the company.	boolean	Optional
orderBy	Orders the properties by ascendeing or descending order according to their `modifiedAt` field.	string	Optional	Options: `asc`, `desc`
sortBy	Sorts properties in the response according to the last time they were modified.	string	Optional	Option: `modifiedAt`.
ids	Returns properties with the IDs indicated in the array.	ObjectId<COTProperty>[ ]	Optional
parent	Returns properties that have the properties indicated in the array as their parents.	ObjectId<COTProperties>[ ]	Optional
propertyTypes	Returns all the properties that belong to the indicated property type. The property type is identified by its `code`.	string[ ]	Optional	`code` is found in the COTProperyType data model.
codes	Returns properties that have the `name.code` fields indicated in the array.	string[ ]	Optional	`name.code` is found in the COTPropery data model.
isActive	Returns properties according to their `isActive` status.	string	Optional	Options are: `all`, `true`, `false`
owner	Gets properties that are associated to a user or task as an additional field. The query is done through the `owner` field in the COTProperty data model.	object	Optional	Sample: 'GET /properties?owner[$ref]=users &owner[$id]=61a77fc936d18897da3e8fa5'
modified	Returns properties with the indicated modification date in the `modifiedAt` field.	ISODate	Optional	YYYY-MM-DDTHH:mm:ss.SSSZ
modified_gt	Returns properties modified after the indicated date and time.	ISODate	Optional	YYYY-MM-DDTHH:mm:ss.SSSZ
modified_gte	Returns properties 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 properties modified before the indicated date and time.	ISODate	Optional	YYYY-MM-DDTHH:mm:ss.SSSZ
modified_lte	Returns properties 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 properties with the indicated creation date in the `createdAt` field.	ISODate	Optional	YYYY-MM-DDTHH:mm:ss.SSSZ
created_gt	Returns properties created after the indicated date and time.	ISODate	Optional	YYYY-MM-DDTHH:mm:ss.SSSZ
created_gte	Returns properties 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 properties created before the indicated date and time.	ISODate	Optional	YYYY-MM-DDTHH:mm:ss.SSSZ
created_lte	Returns properties 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
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 properties in the company.

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

This request gets properties by their code names.

curl --location --request GET 'https://www.cotalker.com/api/v2/properties?codes=ny_00&codes=stgo_00' \
--header 'Authorization: Bearer $ACCESS_TOKEN

This example gets all the properties in the company.

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

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

async function getProperties(): Promise<PropertyGetCollection | undefined> {
    const response = await api.getV2Properties();
    return response.data?.data;
}

getProperties().then(properties => console.log(properties)).catch(e=>console.log(e))

Response Sample

Responses follow the COTProperty data model.

Get a Property by Id

Returns the property indicated by the Id.

GET /properties/{id}

Endpoint URL

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

Path Parameters

Parameter	Description	Type	Required	Notes
id	The ObjectId of the property that is to be returned.	ObjectId<COTProperty>	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`

Request Sample

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

Response Sample

The response follows the COTProperty data model.

Create a New Property

Creates a new property within a collection.

POST /properties

Endpoint URL

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

Headers

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

Element	Description	Type	Required	Notes
name	Name settings.	object	Required
name.code	The property's identification code.	string	Required	Maximum 60 characters; only lowercase letters, numbers, and underscores allowed; must be unique.
name.display	The property's displayed name.	string	Required
propertyType	The `code` of the COTPropertyType associated with the property.	string	Required

Request Sample

Property created with the minimum required fields:

curl --location --request POST 'https://www.cotalker.com/api/v2/properties' \
--header 'Admin: true' \
--header 'Authorization: $ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "propertyType": "warehouse_supplies_00",
    "name": {
        "code": "paper_letter",
        "display": "letter paper 8.5x11"
    }
}'

Response Sample

Go to COTProperty for a complete description of the response.

{
    "_id": "61a4bbf40035762d5549c781",
    "subproperty": [],
    "isActive": true,
    "propertyType": "warehouse_supplies_00",
    "name": {
        "code": "paper_letter",
        "display": "letter paper 8.5x11"
    },
    "company": "6136968b580aaf2b0e49d844",
    "createdAt": "2021-11-29T11:34:12.992Z",
    "modifiedAt": "2021-11-29T11:34:13.010Z"
}

Update a Property

Updates or edits an existing property's data.

PATCH /properties/{id}

Endpoint URL

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

Path Parameters

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

Headers

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

Request Sample

This sample adds a values to additional fields:

curl --location --request PATCH 'https://www.cotalker.com/api/v2/properties/61a4bbf40035762d5549c781?debug=true' \
--header 'Admin: true' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "schemaInstance": {
        "description_1": "white",
        "description_2": "plain",
        "quantity": "100 reams"
    }
}'

Response Sample

Go to COTProperty for a complete description of the response.

{
    "_id": "61a4bbf40035762d5549c781",
    "subproperty": [],
    "isActive": true,
    "propertyType": "warehouse_supplies_00",
    "name": {
        "code": "paper_letter",
        "display": "letter paper 8.5x11"
    },
    "company": "6136968b580aaf2b0e49d844",
    "createdAt": "2021-11-29T11:34:12.992Z",
    "modifiedAt": "2021-11-29T12:45:48.923Z",
    "schemaInstance": {
        "description_1": "white",
        "description_2": "plain",
        "quantity": "100 reams"
    }
}

Overview​

Get Properties​

Endpoint URL​

Headers​

Query Parameters​

Request Samples​

Response Sample​

Get a Property by Id​

Endpoint URL​

Path Parameters​

Headers​

Query Parameters​

Request Sample​

Response Sample​

Create a New Property​

Endpoint URL​

Headers​

Query Parameters​

Request Body​

Request Sample​

Response Sample​

Update a Property​

Endpoint URL​

Path Parameters​

Headers​

Query Parameters​

Request Body​

Request Sample​

Response Sample​

Overview

Get Properties

Endpoint URL

Headers

Query Parameters

Request Samples

Response Sample

Get a Property by Id

Endpoint URL

Path Parameters

Headers

Query Parameters

Request Sample

Response Sample

Create a New Property

Endpoint URL

Headers

Query Parameters

Request Body

Request Sample

Response Sample

Update a Property

Endpoint URL

Path Parameters

Headers

Query Parameters

Request Body

Request Sample

Response Sample