Skip to main content

API Conventions

CoolR APIs use common patterns for creating, retrieving, updating, and deleting records. Check each endpoint's reference for supported parameters and additional response fields. For example, asset responses can include telemetry and stock information.

Record identifiers​

Where supported, master-data APIs accept a unique code or external code instead of the internal record ID. Use the parameter name documented for the entity. For example, a location can be identified by id: 1, LocationCode: "demo", or ExternalLocationCode: "ext-demo".

If you do not know whether a record already exists, supported update APIs can use its external code to create or update it. When updating, pass only the properties you want to change.

Add​

Required parameters​

  • id (Number, required): 0
  • action (String, required): save

Load​

Required parameters​

  • id (Number, required):
  • action (String, required): load

Update​

Required parameters​

  • id (Number, required)
  • action (String, required): save

Delete​

Required parameters​

  • id (Number, required)
  • action (String, required): delete
Note
  • 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 use 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): Set to 1 to reduce response size by returning column names in a mappings array instead of repeating keys. Omit this parameter or set it to 0 to return the list in key-value format.

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​

Pass filter parameters in sequence. For 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 four properties:

PropertyMeaning
fieldField name
typedate, bool, string, or number
comparisonComparison operator (listed below)
valueValue to compare against

Supported comparison operators:

  • eq: equals
  • lt: less than
  • lte: less than or equal to
  • gt: greater than
  • gte: greater than or equal to
  • neq: not equal to
  • starts: starts with

Logical operator 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 to retrieve data for. If omitted, results include all tenants you can access