API

Onomondo provides an HTTP RESTful Application Programming Interface (API) to fore easy programmatic management of the different features.

The API is a HTTP RESTful API based around resource oriented URLs. It uses standard HTTP verbs and returns JSON on all requests where a data response is expected.

The API is served over TLS (HTTPS) to ensure data privacy, unencrypted HTTP is not supported—or rather will result in a redirect to HTTPS.

Authorization

To use the API an API key is needed. API keys can be generated in the platform and are coupled to the organization under which it is created. It is possible to have API keys with more or less access. This can be done so through Tags.

Once you have generated your API key, you need to add it into the header of all HTTP requests made. We utilize the Authorization header for this purpose, e.g.:

Authorization: <YOUR_API_KEY>

Rate limiting

Every minute a user can send 600 API calls to our server, averaging to one every 0.1 seconds. You can monitor the API limits in the response headers.

• x-ratelimit-limit is a number that informs you of the maximum amount of calls that can be made per period in total.

• x-ratelimit-remaining is a number that informs you of how many calls you have left in the current period.

• x-ratelimit-reset is an epoch/Unix timestamp informing you of when the period will be reset, i.e. at this point in time x-ratelimit-remaining will be reset.

For instance then you might see something like the following

x-ratelimit-limit: 600
x-ratelimit-remaining: 520
x-ratelimit-reset: 1730239201

Which would indicate that at this point in time you have 520 calls left in the given period and that they will be reset at 1730239201 (Tuesday, October 29, 2024 11:00:01 PM GMT+01:00), meaning that in the current period 600 - 520 = 80 calls were already made.

Filter SIMs

get

Retrieve a list of SIMs based on one Filtering criteria:

Minimum tier requirement for SIM location, modem model, and modem manufacturer information: Fleet

Minimum tier requirement for SIM alert threshold information: Pro

Only one filter can be used at a time and can be:

 activated

A boolean to filter if sims are activated or not activated.

 connector

The string name of the connector attached SIMs

 network_whitelist

name-of-whitelist

Authorizations

apikeyAuth

Query parameters

limitstringOptional

The max number of records returned. Limit can be between 1 and 1000 records. Default is 1000 records.

Example: {{limit}}

filterstringOptionalExample: {{filter_option}}

Responses

200

OK

application/json

Responseobject

get

HTTPcURLJavaScriptPython

GET /sims HTTP/1.1
Host: {{host}}
Authorization: apikey YOUR_SECRET_TOKEN
Accept: */*

200

OK

{
  "count": 1,
  "limit": 20,
  "offset": 0,
  "total": 1,
  "sims": [
    {
      "id": "000002418",
      "iccid": "89457387300000024185",
      "label": null,
      "network_whitelist": "Americas",
      "imei_lock": null,
      "connector": null,
      "activated": false,
      "ipv4": "100.66.131.197",
      "online": false,
      "online_at": null,
      "last_came_online_at": "2021-11-01T12:13:39.627Z",
      "network": {
        "name": null,
        "country": null,
        "country_code": null,
        "mcc": null,
        "mnc": null
      },
      "usage": 0,
      "tags": [
        {
          "name": "Supplier",
          "id": "a5023f47-1db8-425e-b664-dc0b8921f644",
          "can_write": false,
          "color": "#5ba571"
        },
        {
          "name": "Steens Products",
          "id": "4c21c1ce-0e3d-445f-8b3a-9d918a9acd89",
          "can_write": false,
          "color": "#441212"
        }
      ]
    }
  ]
}