Documentation Powered by ReDoc

PING Customer API documentation (1.0.13)

Download OpenAPI specification:Download

Purpose of this documentation

This documentation describes the API for the PING customer portal. It describes the list and details of all available operations.

Examples

For all operations request and response examples are provided to aid with API usage.

Authentication

PING API utilizes OAuth2 authentication scheme for granting access to the API based on the access tokens issued.

All requests to the API must be authenticated using bearer token authentication by passing the valid access token as part of Authorization HTTP header as presented below:

Authorization: Bearer

An example of a valid authenticated request would look like in the following example:

GET /1.0/events/ HTTP/1.1
Host: api.pingasset.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGci(...)

Each token is associated with an user in the API and all actions performed via API using such a token are attributed to that user.

You can obtain an access token to use with PING API using the requests described in detail in this section.

Client credentials grant

Client credentials grant type is the simplest of OAuth2 grants. It is suitable for machine-to-machine authentication where client ID and secret can be kept secure.

With this grant client is directly issued tokens by the token endpoint described in Obtaining an access token endpoint documentation.

To obtain access token with client credentials grant you are required to pass only a valid client ID and secret in the request.

In this OAuth2 flow refresh token is not issued. When the access token validity period ends a new token must be explicitly requested.

Authorization code grant

With authorization code grant the client using the application must first redirect the user to the login server in which the user will have to explicitly log in using his/hers credentials. As a result, after successful authentication and approval of the client authorization request, an authorization code will be handed back in the query string of the redirect response. This code can be exchanged for access and refresh tokens using the returned authorization code itself as well as the client id and confidential client secret.

This flow should be used for use cases in which an explicit user login and client application authorization is required to gain access, but client secret can be kept secure allowing the refresh token to be safely issued and used.

To execute the flow you must use two endpoints consecutively. Please refer to Authorizing a client and Obtaining an access token endpoints documentation below.

Authorizing a client

This request initiates the client authorization flow for the authorization code OAuth2 grant to gain access to the API. To initiate the flow this endpoint must be passed a valid client ID for the application with optional redirect URL to which the user will be redirected back after completing the flow (by accepting or denying the request). After initiating the authorization process users will be shown a PING branded log-in screen in which they will have to provide valid login credentials. Upon logging in they will be asked to authorize access to their account by the application requesting that permission (the one matching client ID passed to the request). Users must explicitly agree for the application to use their account access to use the API. If redirect URL will not be explicitly provided when initiating the authorization flow, in all cases redirection will happen to the first URL configured in the application that is being used to authorize the client.

Successful authorization

When user agrees for the app to access their account, it will be redirected back to the redirect URL (or the default URL, see above). In the returning query string code and optionally state (if passed by the initiating client) will be returned. The code should be used to exchange it for the access token that can then be used to access the API.

Unsuccessful authorization and errors

When user does not agree for the app to access their account or other misconfiguration errors happen, user will be redirected back to the redirect URL (or the default URL, see above). In the returning query string error will be passed containing the error message. In case of malicious redirect URL supplied not matching any of the configured URLs, user will not be redirected back at all.

query Parameters
response_type
required
string
Value:"code"
Example: "code"

Response type for the authorization endpoint. With PING API and authorization code flow the only accepted value is code.

client_id
required
string
Example: "A9mHRmDxliS5XzuXVZgRR0KgTGHKEBcWzEENArvI"

Client identifier of the application for which the token request is issued.

redirect_uri
string
Example: "https://example.org"

The URL to which the user will be redirected after completing the authorization flow, both in case of success and error. This parameter is optional, but if not send the user will be redirected to the first URL defined as allowed in the application. It must match one the allowed URLs defined within the application, otherwise the authorization flow will end with error.

state
string
Example: "kgrW0h8iavBtYxZW4Hsw2xxge020hj"

A state token. This parameter is not required but its usage is highly recommended. When passed, the same value will be returned by the authorization endpoint alongside the authorization code. Match between these values can be used to validate against malicious authorization responses.

There is no required format for this parameter. It will be returned intact.

Responses

302

Redirect through the authorization flow. Ends in redirect to the redirect URI with code returned on success.

get /auth/authorize/
https://api.pingasset.com//auth/authorize/

Obtaining an access token

This endpoint returns a new access token valid for a given period of time in exchange for a set of authentication credentials, depending on the chosen OAuth 2 flow.

Client credentials grant

To obtain access token with client credentials grant you must pass a valid client ID and secret in the request. In return the access token will be returned that can be used to access the API.

In this OAuth2 flow refresh token is not issued. When the access token validity period ends a new token must be explicitly requested.

Authorization code grant

To obtain access token with authorization code grant you must pass a valid client ID and secret in the request, as well as the received code, the same redirect URL as provided with authorizatoin flow and state if it was used in the process. In return the access token will be returned that can be used to access the API.

In this OAuth2 flow refresh token is issued and can be used to issue further access tokens when the token validity expires.

Request Body schema: application/json
client_id
required
string (Client ID)

Client identifier of the application for which the token request is issued.

Used with client_credentials and authorization_code grant type.

client_secret
required
string (Client secret)

Client secret of the application for which the token request is issued.

Used with client_credentials and authorization_code grant type.

grant_type
required
string (Grant type)
Enum:"client_credentials" "authorization_code"

Chosen authentication flow for the given application.

Used with client_credentials and authorization_code grant type.

redirect_uri
string (Redirect URI)

Redirect URI for the authorization flow. It must match the redirect URI previously provided to the authorization endpoint.

Used with authorization_code grant type.

code
string (Authorization code)

Authorization code being exchanged for the token. It was previously returned by the authorization endpoint in the query string.

Used with authorization_code grant type.

Responses

200

Access token response.

400

Invalid request parameters and validation errors.

post /auth/token/
https://api.pingasset.com//auth/token/

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "client_id": "A9mHRmDxliS5XzuXVZgRR0KgTGHKEBcWzEENArvI",
  • "client_secret": "nXi5oZ8om6d4wjYEg7hoWPrwO8uzR7ErOQMW3zd86ydsu1MJ1ZDYp53bKJVhpgrEzhEJumjmDp39bSAC2ir6Nl1YfOEHBekexybtpxqUnp8yNoQMp5BymNuTelNoGD0L",
  • "grant_type": "client_credentials",
  • "redirect_uri": "https://example.org",
  • "code": "3LpM0dscS27mmaKtdbc4aBNhFExk0E"
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI(...)",
  • "expires_in": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI(...)",
  • "token_type": "Bearer",
  • "scope": "read write"
}

User Accounts

This section describes API endpoints related to user accounts.

User details

This operation returns the details for currently authenticated user and the customer the user belongs to.

Responses

200

Authenticated user details

get /1.0/customers/accounts/me/
https://api.pingasset.com//1.0/customers/accounts/me/

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "id": 1,
  • "username": "jon.doe@example.org",
  • "first_name": "Jon",
  • "last_name": "Doe",
  • "customer":
    {
    },
  • "created_at": "2019-07-13T18:09:35Z",
  • "modified_at": "2019-07-13T18:09:35Z"
}

Change password

This operation allows to change password for currently authenticated user.

Request Body schema: application/json
old_password
required
string (Old password)

Old password subject to change.

password
required
string (New password)

New password to be assigned to the user account.

password_confirmation
required
string (New password confirmation)

New password confirmation, must contain the same value as password.

Responses

204

The password has been successfully changed.

400

Invalid request parameters and validation errors.

post /1.0/customers/accounts/password/change/
https://api.pingasset.com//1.0/customers/accounts/password/change/

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "old_password": "foo",
  • "password": "bar",
  • "password_confirmation": "bar"
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "field_name":
    [
    ],
  • "non_field_errors":
    [
    ]
}

OAuth2 Applications

All PING customer users can create and manage OAuth2 applications scoped to the user, effectively allowing users to enable API access for additional applications acting on their behalf.

PING API supports two OAuth2 authorization flows. For information on how to acquire a valid token to authenticate against the API with one of the created applications please refer to Authentication section.

Client credentials grant

Client credentials grant type is the simplest of OAuth2 grants. It is suitable for machine-to-machine authentication where client ID and secret can be kept secure.

With PING API all tokens issued for client credentials grant type application give access to the same resources as the user owning the application, and all actions taken are attributed to that user.

To access the API using the client credentials grant application it is necessary to first obtain an access token with limited time to live value, meaning the token expires after a period of time.

To retrieve the token only client ID and secret are needed.

Authorization code grant

With authorization code grant the client using the application must first redirect the user to the login server in which the user will have to explicitly log in using his/hers credentials. As a result an authorization code will be given, which can be exchanged for access and refresh tokens using the authorization code itself as well as the client id and confidential client secret.

This flow should be used for use cases in which an explicit user login is required to gain access, but client secret can be kept secure allowing the refresh token to be safely issued and used.

API endpoints

Below API endpoints allowing listing and management of user's OAuth2 applications are described in detail.

List of OAuth2 applications

This operation returns the list of OAuth2 applications created by the logged in user.

query Parameters
page
integer
Example: 3

A page number within the paginated result set.

Responses

200

List of OAuth 2 applications matching the filtering criteria.

get /1.0/applications/
https://api.pingasset.com//1.0/applications/

Response samples

application/json
Copy
 Expand all Collapse all
{}

Create OAuth2 application

This operation creates a new OAuth2 application for the logged in customer.

The created application can be used for API access using generated pair of client identifier and confidential client secret and one of the allowed OAuth2 flows.

All created applications can be deleted effectively revoking access through their credentials.

Request Body schema: application/json
name
required
string (Name)

Name for the application

authorization_grant_type
required
string (Type of the authorization grant)
Enum:"authorization-code" "implicit" "client-credentials"

Authorization grant type for the OAuth2 flow that will be used with this application. Allowed values are the following:

  • authorization-code - authorization code flow
  • client-credentials - client credentials flow
redirect_uris
string (Redirect URIs allowed)

Comma separated list of redirect URIs allowed in OAuth2 flows requiring redirect validations, which are:

  • authorization-code - authorization code flow

Responses

201

Application has been created successfully. Returns newly created application in response.

400

Invalid request parameters and validation errors.

post /1.0/applications/
https://api.pingasset.com//1.0/applications/

Request samples

application/json
Copy
 Expand all Collapse all
{}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "id": 1,
  • "name": "Backup event retriever",
  • "client_id": "tVjLAng6wRI4oAE1AAFVtqeB0oLZ65WstjIV32MU",
  • "client_secret": "9u3La89Ai4SRkKfJZqhak8W6fVVD437ZnhHmySN4jKonVHHA9YGGtizsJfdqjs0gPOd8sfzy49jNbUDWTu7hqQYDKi39sy4cfz6vDGvtqwKr5Q4lgsRilgNdRyPNQLKy",
  • "authorization_grant_type": "authorization-code",
  • "redirect_uris": "https://myapiapp.localhost/",
  • "created_at": "2019-07-13T18:09:35Z",
  • "modified_at": "2019-07-13T18:09:35Z"
}

OAuth2 application details

This operation returns detailed information of a single application identified by its ID, granted the application is owned by the logged in user.

path Parameters
id
required
integer

A unique integer value identifying this application.

Responses

200
404

The application was either not found, or the logged-in account is not allowed to access it.

get /1.0/applications/{id}/
https://api.pingasset.com//1.0/applications/{id}/

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "id": 1,
  • "name": "Backup event retriever",
  • "client_id": "tVjLAng6wRI4oAE1AAFVtqeB0oLZ65WstjIV32MU",
  • "client_secret": "9u3La89Ai4SRkKfJZqhak8W6fVVD437ZnhHmySN4jKonVHHA9YGGtizsJfdqjs0gPOd8sfzy49jNbUDWTu7hqQYDKi39sy4cfz6vDGvtqwKr5Q4lgsRilgNdRyPNQLKy",
  • "authorization_grant_type": "authorization-code",
  • "redirect_uris": "https://myapiapp.localhost/",
  • "created_at": "2019-07-13T18:09:35Z",
  • "modified_at": "2019-07-13T18:09:35Z"
}

Update OAuth2 application

This operation updates an application identified by its ID. Fields that can be changed include:

  • Name
  • Grant type
  • Redirect URIs
path Parameters
id
required
integer

A unique integer value identifying this application.

Request Body schema: application/json
name
required
string (Name)

Name for the application

authorization_grant_type
required
string (Type of the authorization grant)
Enum:"authorization-code" "implicit" "client-credentials"

Authorization grant type for the OAuth2 flow that will be used with this application. Allowed values are the following:

  • authorization-code - authorization code flow
  • client-credentials - client credentials flow
redirect_uris
string (Redirect URIs allowed)

Comma separated list of redirect URIs allowed in OAuth2 flows requiring redirect validations, which are:

  • authorization-code - authorization code flow

Responses

200
400

Invalid request parameters and validation errors.

404

The application was either not found, or the logged-in account is not allowed to access it.

put /1.0/applications/{id}/
https://api.pingasset.com//1.0/applications/{id}/

Request samples

application/json
Copy
 Expand all Collapse all
{}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "id": 1,
  • "name": "Backup event retriever",
  • "client_id": "tVjLAng6wRI4oAE1AAFVtqeB0oLZ65WstjIV32MU",
  • "client_secret": "9u3La89Ai4SRkKfJZqhak8W6fVVD437ZnhHmySN4jKonVHHA9YGGtizsJfdqjs0gPOd8sfzy49jNbUDWTu7hqQYDKi39sy4cfz6vDGvtqwKr5Q4lgsRilgNdRyPNQLKy",
  • "authorization_grant_type": "authorization-code",
  • "redirect_uris": "https://myapiapp.localhost/",
  • "created_at": "2019-07-13T18:09:35Z",
  • "modified_at": "2019-07-13T18:09:35Z"
}

Partial update OAuth2 application

This operation partially updates an application identified by its ID. Fields that can be changed include:

  • Name
  • Grant type
  • Redirect URIs

Not provided fields will not be changed. With partial updates not all fields are required.

path Parameters
id
required
integer

A unique integer value identifying this application.

Request Body schema: application/json
name
required
string (Name)

Name for the application

authorization_grant_type
required
string (Type of the authorization grant)
Enum:"authorization-code" "implicit" "client-credentials"

Authorization grant type for the OAuth2 flow that will be used with this application. Allowed values are the following:

  • authorization-code - authorization code flow
  • client-credentials - client credentials flow
redirect_uris
string (Redirect URIs allowed)

Comma separated list of redirect URIs allowed in OAuth2 flows requiring redirect validations, which are:

  • authorization-code - authorization code flow

Responses

200
400

Invalid request parameters and validation errors.

404

The application was either not found, or the logged-in account is not allowed to access it.

patch /1.0/applications/{id}/
https://api.pingasset.com//1.0/applications/{id}/

Request samples

application/json
Copy
 Expand all Collapse all
{}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "id": 1,
  • "name": "Backup event retriever",
  • "client_id": "tVjLAng6wRI4oAE1AAFVtqeB0oLZ65WstjIV32MU",
  • "client_secret": "9u3La89Ai4SRkKfJZqhak8W6fVVD437ZnhHmySN4jKonVHHA9YGGtizsJfdqjs0gPOd8sfzy49jNbUDWTu7hqQYDKi39sy4cfz6vDGvtqwKr5Q4lgsRilgNdRyPNQLKy",
  • "authorization_grant_type": "authorization-code",
  • "redirect_uris": "https://myapiapp.localhost/",
  • "created_at": "2019-07-13T18:09:35Z",
  • "modified_at": "2019-07-13T18:09:35Z"
}

Delete OAuth2 application

This operation deletes an application identified by its ID.

path Parameters
id
required
integer

A unique integer value identifying this application.

Responses

204

The application has been successfully deleted.

404

The application was either not found, or the logged-in account is not allowed to access it.

delete /1.0/applications/{id}/
https://api.pingasset.com//1.0/applications/{id}/

Configurations

This section contains operations related to device configurations.

Configurations can be used to override certain device parameters such as how often the device reports, temperature logging intervals or shock threshold values.

Configurations are applied to devices through device groups. When a device group is assigned a custom configuration, it applies to all devices within that group.

The configurations are managed in draft and published states and only draft configurations may be edited. On the other hand, only published and hence read only configurations may be assigned to device groups.

Please refer to Device Groups section regarding assignemnt of a custom configuration to the group.

List configurations

This operation returns the list of configurations owned by the customer account the logged in user belongs to.

This request always results in a response containing zero or more configurations matching the filtering criteria.

When no configurations are found, results array will be empty.

Filtering

Configurations may be queried against a set of filtering criteria, allowing for fine-grained control on what results will be returned.

All filtering is done based on query-string parameters described below.

Multiple filters can be used at the same time, resulting in AND-ing them.

Ordering

Configurations may be ordered by a certain field by passing the field name to the ordering query-string parameter, e.g. ordering=name. For ordering in reverse (descending) order, prepend a minus sign to the field name, e.g. ordering=-name.

Fields on which ordering is allowed are listed below.

query Parameters
ordering
string
Example: "name,-created_at"

Field (or fields) to order by. To use multiple fields, separate them with commas. To order in reverse order, prepend field name with a minus sign.

Orderable fields:

  • name
  • created_at
  • modified_at
search
string
Example: "Sample name"

A search term allowing full text search by configuration name.

name
string
Example: "Sample name"

Allows filtering by comma-separated names to filter by.

page
integer
Example: 3

A page number within the paginated result set.

Responses

200

List of configurations matching the filtering criteria.

get /1.0/configurations/customer/
https://api.pingasset.com//1.0/configurations/customer/

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "count": 15,
  • "next": "https://api.pingasset.com/1.0/configurations/customer/?page=2",
  • "num_pages": 0,
  • "previous": "https://api.pingasset.com/1.0/configurations/customer/?page=1",
  • "results":
    [
    ]
}

Create configuration

This operation creates a new configuration for the customer account the logged in user belongs to.

Request Body schema: application/json
name
string (Name)

Name of the configuration

description
string (Description)

Description of the configuration

settings
object (Configuration settings)

Responses

201

Configuration has been created successfully. Returns newly created configuration in response.

400

Invalid request parameters and validation errors.

post /1.0/configurations/customer/
https://api.pingasset.com//1.0/configurations/customer/

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "name": "Custom Configuration",
  • "description": "Custom configuration extending reporting frequency",
  • "settings":
    {
    }
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "id": 1,
  • "name": "Custom Configuration",
  • "description": "Custom configuration extending reporting frequency",
  • "checksum": "a7cd6c22",
  • "settings":
    {
    },
  • "created_at": "2019-07-13T18:09:35Z",
  • "modified_at": "2019-07-13T18:09:35Z",
  • "state": "draft",
  • "customer":
    {
    }
}

Configuration details

This operation returns detailed information of a configuration identified by its ID.

In order to request the configuration details the logged-in user must belong to the customer who owns the configuration.

path Parameters
id
required
integer

A unique integer value identifying this configuration.

Responses

200
404

The configuration was either not found, or the logged-in account is not allowed to access it.

get /1.0/configurations/customer/{id}/
https://api.pingasset.com//1.0/configurations/customer/{id}/

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "id": 1,
  • "name": "Custom Configuration",
  • "description": "Custom configuration extending reporting frequency",
  • "checksum": "a7cd6c22",
  • "settings":
    {
    },
  • "created_at": "2019-07-13T18:09:35Z",
  • "modified_at": "2019-07-13T18:09:35Z",
  • "state": "draft",
  • "customer":
    {
    }
}

Update configuration

This operation updates an configuration identified by its ID.

path Parameters
id
required
integer

A unique integer value identifying this configuration.

Request Body schema: application/json
name
string (Name)

Name of the configuration

description
string (Description)

Description of the configuration

settings
object (Configuration settings)

Responses

200
400

Invalid request parameters and validation errors.

404

The configuration was either not found, or the logged-in account is not allowed to access it.

put /1.0/configurations/customer/{id}/
https://api.pingasset.com//1.0/configurations/customer/{id}/

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "name": "Custom Configuration",
  • "description": "Custom configuration extending reporting frequency",
  • "settings":
    {
    }
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "id": 1,
  • "name": "Custom Configuration",
  • "description": "Custom configuration extending reporting frequency",
  • "checksum": "a7cd6c22",
  • "settings":
    {
    },
  • "created_at": "2019-07-13T18:09:35Z",
  • "modified_at": "2019-07-13T18:09:35Z",
  • "state": "draft",
  • "customer":
    {
    }
}

Partial update configuration

This operation updates an configuration identified by its ID.

When a subset of values is provided for PATCH request, other values will remain unchanged.

path Parameters
id
required
integer

A unique integer value identifying this configuration.

Request Body schema: application/json
name
string (Name)

Name of the configuration

description
string (Description)

Description of the configuration

settings
object (Configuration settings)

Responses

200
400

Invalid request parameters and validation errors.

404

The configuration was either not found, or the logged-in account is not allowed to access it.

patch /1.0/configurations/customer/{id}/
https://api.pingasset.com//1.0/configurations/customer/{id}/

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "name": "Custom Configuration",
  • "description": "Custom configuration extending reporting frequency",
  • "settings":
    {
    }
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "id": 1,
  • "name": "Custom Configuration",
  • "description": "Custom configuration extending reporting frequency",
  • "checksum": "a7cd6c22",
  • "settings":
    {
    },
  • "created_at": "2019-07-13T18:09:35Z",
  • "modified_at": "2019-07-13T18:09:35Z",
  • "state": "draft",
  • "customer":
    {
    }
}

Delete configuration

This operation deletes configuration identified by its ID.

path Parameters
id
required
integer

A unique integer value identifying this configuration.

Responses

204

The configuration has been successfully deleted.

404

The configuration was either not found, or the logged-in account is not allowed to access it.

delete /1.0/configurations/customer/{id}/
https://api.pingasset.com//1.0/configurations/customer/{id}/

Publish configuration

This operation publishes configuration identified by its ID. This action cannot be undone and published configuration is no longer subject to modification. Only published configurations can be assigned to device groups.

path Parameters
id
required
integer

A unique integer value identifying this configuration.

Responses

200

The configuration has been successfully published.

404

The configuration was either not found, or the logged-in account is not allowed to access it.

post /1.0/configurations/customer/{id}/publish/
https://api.pingasset.com//1.0/configurations/customer/{id}/publish/

Devices

This sections contains operations listing and retrieving device details for devices owned by the customer of the logged in user.

Querying and filtering devices is described in detail in the following API operations.

List devices

This operation returns the list of all devices owned by the customer the logged in user belongs to. This request always results in a response containing zero or more devices. When no devices are found, results array will be empty.

Filtering

Devices may be queried against a set of filtering criteria, allowing for fine-grained control on what results will be returned. All filtering is done based on query-string parameters described below. Multiple filters can be used at the same time, resulting in AND-ing them.

Example filter queries

Fetch list of devices with last known location with 5km of Time Square
GET /1.0/devices/devices/?latitude=40.758970&longitude=-73.984479&radius__lte=5000
Fetch list of devices with last known location farther away than 10km of Time Square
GET /1.0/devices/devices/?latitude=40.758970&longitude=-73.984479&radius__gte=10000
Fetch list of devices with last known location within geo group with ID=7 boundary
GET /1.0/devices/devices/?geogroup_inside=7
Fetch list of devices with last known location outside geo group with ID=7 boundary
GET /1.0/devices/devices/?geogroup_outside=7
Fetch list of devices with last known location farther than 1000 meters of geo group with ID=7 boundary
GET /1.0/devices/devices/?geogroup_inside=7&geogroup_distance=1000

Ordering

Devices may be ordered by a certain field by passing the field name to the ordering query-string parameter, e.g. ordering=name. For ordering in reverse (descending) order, prepend a minus sign to the field name, e.g. ordering=-name. Fields on which ordering is allowed are listed below.

query Parameters
ordering
string
Example: "-last_event_timestamp,-imei"

Field (or fields) to order by. To use multiple fields, separate them with commas. To order in reverse order, prepend field name with a minus sign.

Orderable fields:

  • imei
  • mac
  • last_event_timestamp
  • last_event_created_at
  • created_at
  • modified_at
page
integer
Example: 3

A page number within the paginated result set.

search
string
Example: "990000862471854"

A search term to filter devices against. This is a generic filter allowing to search through devices with a simple single query.

Fields included in search lookup

  • IMEI numer
  • MAC number
imei
string
Example: "990000862471854"

An IMEI number of the device.

mac
string
Example: "00:A0:C9:14:C8:29"

A MAC number of the device network interface.

fault
boolean

Filters faulty (true) or healthy (false) devices.

customer_group_id
integer
Example: 1

Filters devices which are assigned to the customer group with given ID.

radius__lte
integer
Example: 130

Distance in meters to the given geographical point. Must be used in conjunction with latitude and longitude parameters, otherwise takes no effect. When applied, events within radius specified will be found.

radius__gte
integer
Example: