Skip to main content

API Conventions

Coolr Group has a lot of APIs for various use cases/ data integration endpoints. However, for convention we implement some standard patterns for majority of our APIs.

If you are not using Coolr's surrogate API, you may not be sure whether the record you are trying to update is a new record or old record. In such a case, you can call just the update API with your external code.

In List, Load and Export APIs, you will also get additional attributes back based on the system. We are continuously enhancing our documentation to list these additional attributes. For example:

  • Asset: It also returns latest telemetry data as well as stock information.

Add​

Required parameters​

  • id (Number, required): 0
  • action (String, required): save
Note
  • You can use the unique Code or ExternalCode parameter with appropriate parameter name for the specific master APIs. For example, instead of passing id: 1 to delete a location with id 1, you can use LocationCode: "demo" or ExternalLocationCode: "ext-demo"
  • You only need to pass the properties that need to be modified

Load​

Required parameters​

  • id (Number, required):
  • action (String, required): load
Note
  • You can use the unique Code or ExternalCode parameter with appropriate parameter name for the specific master APIs. For example, instead of passing id: 1 to delete a location with id 1, you can use LocationCode: "demo" or ExternalLocationCode: "ext-demo"

Update​

Required parameters​

  • id (Number, required)
  • action (String, required): save
Note
  • You can use the unique Code or ExternalCode parameter with appropriate parameter name for the specific master APIs. For example, instead of passing id: 1 to delete a location with id 1, you can use LocationCode: "demo" or ExternalLocationCode: "ext-demo"
  • You only need to pass the properties that need to be modified

Delete​

Required parameters​

  • id (Number, required)
  • action (String, required): delete
Note
  • You can use the unique Code or ExternalCode parameter with appropriate parameter name for the specific master APIs. For example, instead of passing id: 1 to delete a location with id 1, you can use LocationCode: "demo" or ExternalLocationCode: "ext-demo"
  • Coolr Group uses soft-delete instead of hard-delete. So, a record can also be restored if deleted accidentally
  • You can also pass IsDeleted=true in the Update API to mark a record deleted

Export​

Note
  • Export API can also use Sorting and Filtering parameters
  • Export API can extract up-to 50,000 records at once. For more records, you must using filtering.

Export API has a few key parameters:

Required parameters​

  • action (String, required): export
  • format (String, optional, default csv)
    • csv
    • xlsx
    • pdf
    • xml

List​

Note
  • List API can also use Sorting and Filtering parameters
  • Due to page size limit, it is recommended to use Export API if you need to go to more than 5000 records.

List API has a few key parameters:

Required parameters​

  • action (String, required): list
  • asArray (Number, optional, default 1): To reduce the list of the list, the APIs return the column names in mappings array and keys are not repeated. If you wish the return the list in key-value format, use asArray: 1

Paging​

  • start (Number, optional): 0 based index for starting record
  • limit (Number, optional, default 50): number of records to fetch/ page size

Sorting​

  • sort (String, optional): Name of the property to sort by
  • dir (String, optional, default asc): Direction of sort:
    • asc (default): Ascending
    • desc: Descending

Filtering​

APIs support a complex array of filtering options to limit the data retrieved. These filters can be constructed as an array. Please consult with a Coolr Group technical resource for a demo on how to easily create filters.

Simple filtering​

In simple filtering scenario, you can have a number of filter parameters in sequence. Example:

filter[0][field]=AlertAt
filter[0][data][type]=date
filter[0][data][comparison]=gt
filter[0][data][value]=04/26/2020
filter[1][field]=IsActive
filter[1][data][type]=bool
filter[1][data][comparison]=eq
filter[1][data][value]=true

Each filter has 4 properties:

  1. field - name of the field
  2. type - date/ bool/ string/ number
  3. comparison
  • eq: equals
  • lt: less than
  • lte: less than or equals
  • gt: greater than
  • gte: greater than or equals
  • neq: not equals
  • starts: starts with

Logical Operator based filtering​

The general filter parameter is:

  • filter (String, optional): String encoded JSON

Example:

filter={"fieldName":"CreatedOn","operatorId":"DATE_GREATER","convert":false,"values":["2017-10-07%2020:00:17"]}

Another example with combination of multiple filters:

filter: {"left":{"fieldName":"CreatedOn","operatorId":"DATE_GREATER_OR_EQUAL","convert":false,"values":["2018-11-01 00:00:00"]},"logicalOperator":"AND","right":{"fieldName":"CreatedOn","operatorId":"DATE_LESS_OR_EQUAL","convert":false,"values":["2018-11-22 00:00:00"]}}

Operators supported are:

  • Number
    • NUMBER_EQUAL
    • NUMBER_NOT_EQUAL
    • NUMBER_GREATER
    • NUMBER_GREATER_OR_EQUAL
    • NUMBER_LESS
    • NUMBER_LESS_OR_EQUAL
    • NUMBER_RANGE
    • NUMBER_NOT_RANGE
    • NUMBER_IN_LIST
    • NUMBER_NOT_IN_LIST
  • Boolean
    • BOOL_EQUAL
  • String
    • STRING_EQUAL
    • STRING_DIFFERENT
    • STRING_NOT_EQUAL
    • STRING_CONTAINS
    • STRING_DOESNT_CONTAIN
    • STRING_STARTS_WITH
    • STRING_ENDS_WITH
    • STRING_LIST
    • STRING_NOT_IN_LIST
  • Date
    • DATE_EQUAL
    • DATE_NOT_EQUAL
    • DATE_GREATER
    • DATE_GREATER_OR_EQUAL
    • DATE_LESS
    • DATE_LESS_OR_EQUAL
    • DATE_RANGE
    • DATE_PERIOD
    • DATE_ISNULL
    • DATE_IS_NOT_NULL

Multi-tenancy​

In case you have access to multiple tenants, you can use the following additional parameter:

  • clientId (Number, optional): ClientId of the tenant you wish the pull data for. If not specified, you'll get data across the tenants you have access for