Customer API reference

General considerations

This document describes the Ondilo Customer API. It is intended to help on building your own app for query information and interact with your ICO data.

URL prefix

All requests except explicitly mentioned shall be performed on the same URL prefix : https://interop.ondilo.com/api/customer/v1

Headers

Ondilo Customer API uses UTF-8 as the response encoding and supports HTTP-level compression. Requests should have the following headers:

Authorization: Bearer {{access_token}}
Accept: application/json
Accept-Charset: utf-8
Accept-Encoding : gzip-deflate
Content-type: application/json

Authentication

The Ondilo Customer API requires the user to be authenticated by providing an access token in the header of any request.
The access token shall be retrieved by using the Ondilo authentication service.

HTTP status codes

The Ondilo Customer API uses the following set of HTTP response status codes:

Status Description
200 The request was successful, no error was encountered.
400 There is a problem with some data sent in the request. An error response body shall clarify the issue.
401 The access token sent in the header is invalid. You should call the refresh token endpoint of the Ondilo authentication service.
404 You are trying to reach a page that doesn't exist.
500 An error in the Ondilo Customer API application logic has been detected. An error response body shall clarify the issue.
503 The Ondilo Customer API is not currently available. You should try again later.

Response body format

The Ondilo Customer API provides response bodies as JSON objects. Format of the objects depend of the endpoint called.

{
    // The data contained here depends on the endpoint,
    // but it is either an object or an array
}

Quotas

We remind that ICO takes measures every hour.

In order to avoid excessive load of our servers, the requests to the Ondilo Customer API are limited to the following per user quotas :

  • 5 requests per second
  • 30 requests per hour

User data

The Ondilo Customer API provides several endpoints allowing your application to retrieve some user oriented information, that includes user information and user units.

User information

The user information endpoint shall be used to retrieve information about the user, including email, name and identifier.

Request

Method GET
URL {{url_prefix}}/user/info
Headers Authorization: Bearer {{access_token}}
Accept: application/json
Accept-Charset: utf-8
Accept-Encoding: gzip, deflate

Example

GET /api/customer/v1/user/info HTTP/1.1
Authorization: Bearer 4fc86e46a11abbb3914b90af3e21f2858f3376f5
Accept: application/json
Accept-Charset: utf-8
Accept-Encoding: gzip, deflate

Response

Requests to the user information endpoint will generate the following JSON response:

{
    "lastname": "Doe",
    "firstname": "John",
    "email": "john@doe.org"
}

User units

The user units endpoint shall be used to retrieve all the units set by the user. Notice that those units are used when requesting for measures when data is displayed in the mobile app.

Request

Method GET
URL {{url_prefix}}/user/units
Headers Authorization: Bearer {{access_token}}
Accept: application/json
Accept-Charset: utf-8
Accept-Encoding: gzip, deflate

Example

GET /api/customer/v1/user/units HTTP/1.1
Authorization: Bearer 4fc86e46a11abbb3914b90af3e21f2858f3376f5
Accept: application/json
Accept-Charset: utf-8
Accept-Encoding: gzip, deflate

Response

Requests to the user units endpoint will generate the following JSON response:

{
    "conductivity": "MICRO_SIEMENS_PER_CENTI_METER",
    "hardness": "FRENCH_DEGREE",
    "orp": "MILLI_VOLT",
    "pressure": "HECTO_PASCAL",
    "salt": "GRAM_PER_LITER",
    "speed": "METER_PER_SECOND",
    "temperature": "CELSIUS",
    "volume": "CUBIC_METER"
}

Pool/spa data

The Ondilo Customer API provides several endpoints allowing your application to retrieve some pool/spa oriented information, that includes getting the list of user's pools/spas, the device attached to a pool/spa, the configuration of a pool/spa, and the list of users with whom the pool/spa is shared.

List of pools/spas

The list of pools/spas endpoint shall be used to retrieve the list of the pools/spas owned by the user or shared with him.
The returned information includes the identifier of the pool/spa, needed further to requesting pool/spa data, the name of the pool/spa, its type, volume, type of disinfection (chlorine, bromine or salt) with information on the use of UV sanitizer or ozonator, its address and the date of last modification.

Request

Method GET
URL {{url_prefix}}/pools
Headers Authorization: Bearer {{access_token}}
Accept: application/json
Accept-Charset: utf-8
Accept-Encoding: gzip, deflate

Example

GET /api/customer/v1/pools HTTP/1.1
Authorization: Bearer 4fc86e46a11abbb3914b90af3e21f2858f3376f5
Accept: application/json
Accept-Charset: utf-8
Accept-Encoding: gzip, deflate

Response

Requests to the pools/spas list endpoint will generate the following JSON response:

[
    {
        "id": 234,
        "name": "John's Pool",
        "type": "outdoor_inground_pool",
        "volume": 15,
        "disinfection": {
            "primary": "chlorine",
            "secondary": {
                "uv_sanitizer": true,
                "ozonator": false
            }
        },
        "address": {
            "street": "162 Avenue Robert Schuman",
            "zipcode": "13760",
            "city": "Saint-Cannat",
            "country": "France",
            "latitude": 43.612282,
            "longitude": 5.3179397
        },
        "updated_at": "2019-11-27T23:00:21+0000"
    },
    {
        ...
    }
]
Please note that volume is expressed in cubic meters (m3)

Pool/spa device

The pool/spa device endpoint shall be used to retrieve information about the device attached to a pool/spa.
The returned information includes the universal unique identifier (UUID) of the device, its serial number and firmware version.

Request

Method GET
URL {{url_prefix}}/pools/{{pool_id}}/device
Headers Authorization: Bearer {{access_token}}
Accept: application/json
Accept-Charset: utf-8
Accept-Encoding: gzip, deflate

Example

GET /api/customer/v1/pools/234/device HTTP/1.1
Authorization: Bearer 4fc86e46a11abbb3914b90af3e21f2858f3376f5
Accept: application/json
Accept-Charset: utf-8
Accept-Encoding: gzip, deflate

Response

Requests to the pool/spa device endpoint will generate the following JSON response:

{
    "uuid": "1234567890ABCDEF",
    "serial_number": "SN00001",
    "sw_version": "1.5.1-stable"
}

Pool/spa configuration

The pool/spa configuration endpoint shall be used to retrieve information about the pool/spa settings set by the user.
The returned information includes the ranges of temperature, pH, ORP, salt and TDS, as well as the preferred maintenance weekday and the phone number of the pool guy (Service Company).
The maintenance day is a weekday expressed as a 0 to 6 value, 0 meaning Monday and 6 Sunday.

Request

Method GET
URL {{url_prefix}}/pools/{{pool_id}}/configuration
Headers Authorization: Bearer {{access_token}}
Accept: application/json
Accept-Charset: utf-8
Accept-Encoding: gzip, deflate

Example

GET /api/customer/v1/pools/234/configuration HTTP/1.1
Authorization: Bearer 4fc86e46a11abbb3914b90af3e21f2858f3376f5
Accept: application/json
Accept-Charset: utf-8
Accept-Encoding: gzip, deflate

Response

Requests to the pool/spa configuration endpoint will generate the following JSON response:

{
    "temperature_low": 10,
    "temperature_high": 30,
    "ph_low": 7.6,
    "ph_high": 8.5,
    "orp_low": 400,
    "orp_high": 900,
    "salt_low": 3000,
    "salt_high": 5000,
    "tds_low": 250,
    "tds_high": 2000,
    "pool_guy_number": "0123456789",
    "maintenance_day": 2
}
Please note that values are expressed in the following units:
  • Temperature: Celsius degrees (°C)
  • ORP: millivolts (mV)
  • Salt: milligrams per liter (mg/L)
  • TDS: parts per million (ppm)

Pool/spa shares

The pool/spa shares endpoint shall be used to retrieve the list of users with whom the pool/spa is shared.
The returned information includes the first name, last name and email of the user and the date of the share.

Request

Method GET
URL {{url_prefix}}/pools/{{pool_id}}/shares
Headers Authorization: Bearer {{access_token}}
Accept: application/json
Accept-Charset: utf-8
Accept-Encoding: gzip, deflate

Example

GET /api/customer/v1/pools/234/shares HTTP/1.1
Authorization: Bearer 4fc86e46a11abbb3914b90af3e21f2858f3376f5
Accept: application/json
Accept-Charset: utf-8
Accept-Encoding: gzip, deflate

Response

Requests to the pool/spa shares endpoint will generate the following JSON response:

[
    {
        "lastname": "Doe",
        "firstname": "Jane",
        "email": "jane@doe.org",
        "shared_since": "2019-12-06T11:29:36+0000"
    },
    {
        ...
    }
]

Measures

The Ondilo Customer API provides several endpoints allowing your application to retrieve measures, that includes getting the last measure(s) and a set of measures of a specific type.

Last measure(s)

The last measure endpoint shall be used to retrieve the last measure(s) taken by the device in the pool/spa.
The returned information includes the type of data, measured value, date and time of the measure, a flag indicating the validity of the measure and the reason why the measure might be invalid.

Request

Method GET
URL {{url_prefix}}/pools/{{pool_id}}/lastmeasures
Headers Authorization: Bearer {{access_token}}
Accept: application/json
Accept-Charset: utf-8
Accept-Encoding: gzip, deflate
Content-Type: application/x-www-form-urlencoded

Parameters

types Specify the types of measures that should be returned. This parameter might be repeated, and array form shall be used.
Allowed values are:
  • temperature
  • ph
  • orp
  • salt (for salt pools/spas)
  • tds (for non-salt pools/spas)
  • battery
  • rssi

Example

GET /api/customer/v1/pools/123/lastmeasures?types[]=temperature&types[]=orp HTTP/1.1
Authorization: Bearer 4fc86e46a11abbb3914b90af3e21f2858f3376f5
Accept: application/json
Accept-Charset: utf-8
Accept-Encoding: gzip, deflate
Content-Type: application/x-www-form-urlencoded

Response

Requests to the last measure endpoint will generate the following JSON response:

[
    {
        "data_type": "temperature",
        "value": 12.5,
        "value_time": "2020-03-23T16:08:51+0000",
        "is_valid": true,
        "exclusion_reason": null
    },
    {
        "data_type": "orp",
        "value": 523,
        "value_time": "2020-03-23T16:08:51+0000",
        "is_valid": true,
        "exclusion_reason": null
    }
]
Please note that values are expressed in the following units:
  • Temperature: Celsius degrees (°C)
  • ORP: millivolts (mV)
  • Salt: milligrams per liter (mg/L)
  • TDS: parts per million (ppm)
  • Battery and RSSI: percent (%)

Set of measures

The set of measures endpoint shall be used to retrieve a set of measures of a specific type.
The number of measures returned depends on the chosen period, from last 24 hours, last week or last month. The returned information has the same format as the last measure(s) endpoint.

Request

Method GET
URL {{url_prefix}}/pools/{{pool_id}}/measures
Headers Authorization: Bearer {{access_token}}
Accept: application/json
Accept-Charset: utf-8
Accept-Encoding: gzip, deflate
Content-Type: application/x-www-form-urlencoded

Parameters

type Specify the type of measure that should be returned. Unlike the last measure(s) endpoint, this parameter must be specified only once.
Allowed values are identical to the ones specified for the last measure(s) endpoint.
period Specify the period over which the measures have to be retrieved.
Allowed values are:
  • day: for the last 24 hours
  • week: for the last 7 days
  • month: for the last 30 days

Example

GET /api/customer/v1/pools/123/measures?type=temperature&period=day HTTP/1.1
Authorization: Bearer 4fc86e46a11abbb3914b90af3e21f2858f3376f5
Accept: application/json
Accept-Charset: utf-8
Accept-Encoding: gzip, deflate
Content-Type: application/x-www-form-urlencoded

Response

Requests to the set of measures endpoint will generate the following JSON response:

[
    {
        "data_type": "temperature",
        "value": 12.5,
        "value_time": "2020-03-22T16:08:51+0000",
        "is_valid": true,
        "exclusion_reason": null
    },
    {
        "data_type": "temperature",
        "value": 12.6,
        "value_time": "2020-03-22T17:09:13+0000",
        "is_valid": true,
        "exclusion_reason": null
    },
    {
        ...
    }
]
Please note that values are expressed in the following units:
  • Temperature: Celsius degrees (°C)
  • ORP: millivolts (mV)
  • Salt: milligrams per liter (mg/L)
  • TDS: parts per million (ppm)
  • Battery and RSSI: percent (%)

Recommendations

The Ondilo Customer API provides several endpoints allowing your application to retrieve the list of active recommendations and to validate them.

List active recommendations

The list active recommendations endpoint shall be used to retrieve the recommendations that are currently ongoing and haven't been validated yet.
The returned information includes the identifier of the recommendation, needed to validate it, its title and message, the creation and update date, the status and the deadline of the recommendation.

Request

Method GET
URL {{url_prefix}}/pools/{{pool_id}}/recommendations
Headers Authorization: Bearer {{access_token}}
Accept: application/json
Accept-Charset: utf-8
Accept-Encoding: gzip, deflate

Example

GET /api/customer/v1/pools/123/recommendations HTTP/1.1
Authorization: Bearer 4fc86e46a11abbb3914b90af3e21f2858f3376f5
Accept: application/json
Accept-Charset: utf-8
Accept-Encoding: gzip, deflate

Response

Requests to the list active recommendations endpoint will generate the following JSON response:

[
    {
        "id": 10251,
        "title": "Clean your filter",
        "message": "I recommend you to regularly clean your filter in order to evacuate the impurities retained and ensure its efficiency.",
        "created_at": "2020-03-25T04:09:59+0000",
        "updated_at": "2020-03-25T04:09:59+0000",
        "status": "waiting",
        "deadline": "2020-03-26T00:00:00+0000"
    },
    {
        ...
    }
]

Validate recommendation

The validate recommendation endpoint shall be used to validate an active recommendation. Validating an active recommendation tells the system that the user has done what is recommended.
The endpoints returns "Done" if the recommendation has been successfully validated, an error message otherwise.

Request

Method PUT
URL {{url_prefix}}/pools/{{pool_id}}/recommendations/{{recommendation_id}}
Headers Authorization: Bearer {{access_token}}
Accept: application/json
Accept-Charset: utf-8
Accept-Encoding: gzip, deflate

Example

PUT /api/customer/v1/pools/123/recommendations/10251 HTTP/1.1
Authorization: Bearer 4fc86e46a11abbb3914b90af3e21f2858f3376f5
Accept: application/json
Accept-Charset: utf-8
Accept-Encoding: gzip, deflate

Response

Requests to the validate recommendation endpoint will return the following response:

"Done"