Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

SIMs

Retrieve information for all SIMs

get

Returns detailed information for all registered SIMs.

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

Minimum package requirement for SIM alert threshold information: Pro

Using parameters will focus the records returned in the response.

Authorizations
AuthorizationstringRequired
Query parameters
next_pagestringOptional

Used for pagination of records.

Example: MDAyNDY0OTk5
limitstringOptional

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

Example: 10
filterone ofOptional

Filter SIMs based on various criteria. Can be provided as a single filter or multiple filters.

Single filter format: filter=key:value

Multiple filters format: filter[]=key:value&filter[]=key2:value2

Supported filter types:

online - Boolean filter for SIM online status

  • Format: online:true or online:false

activated - Boolean filter for SIM activation status

  • Format: activated:true or activated:false

connector - Filter by Connector name

  • Format: connector:<connector-name>

network_whitelist - Filter by Network List name

  • Format: network_whitelist:<whitelist-name>
Example: filter[]=online:true&filter[]=connector:foobar
stringOptional
or
string[]Optional
Responses
200

OK

application/json
objectOptional
get/sims
GET /sims HTTP/1.1
Host: api.onomondo.com
Authorization: YOUR_API_KEY
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
      },
      "technologies": {
        "sms": true,
        "2g_3g": true,
        "4g": true
      },
      "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"
        }
      ]
    }
  ]
}

Retrieve information for a specific SIM

get

Returns detailed information for a specific SIM.

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

Minimum package requirement for SIM alert threshold information: Pro

By default, we suggest to use the SIM ID that can be found on the SIM card itself or from SIMs page in the web app. You can also use the ICCID value, if that is available.

Note that the location and device_info fields are optional, meaning that they are only present if the information is available.

Authorizations
AuthorizationstringRequired
Path parameters
sim_idstringRequiredExample: 000000001
Responses
200

OK

application/json
objectOptional
get/sims/{sim_id}
GET /sims/{sim_id} HTTP/1.1
Host: api.onomondo.com
Authorization: YOUR_API_KEY
Accept: */*
200

OK

{
  "id": "{{sim_id}}",
  "msisdn": "882360011968393",
  "iccid": "89457387300002791013",
  "label": "Bene-getting-started-device",
  "network_whitelist": "bene-excellent-testing-whitelist",
  "imei_lock": null,
  "imei": "861340049971524",
  "imsi": "234500027179101",
  "connector": "getting-started",
  "activated": true,
  "ipv4": "100.68.153.152",
  "online_at": "2021-11-01T12:13:39.627Z",
  "last_came_online_at": "2021-11-01T12:13:39.627Z",
  "network": {
    "name": "Telia",
    "country": "Denmark",
    "country_code": "DK",
    "mcc": "238",
    "mnc": "20"
  },
  "usage": 97606,
  "tags": [
    {
      "name": "ConnectivityCheck Success",
      "id": "8ebab849-af20-43ae-b59a-13e70e2a9932",
      "can_write": false,
      "color": null
    }
  ],
  "online": true,
  "data_limit": {
    "used": 248,
    "total": 10000000,
    "type": "hourly",
    "period": "2021110112",
    "alert_threshold": null,
    "resets_at": "2021-11-01T13:00:00.000Z"
  },
  "location": {
    "lat": 55.6821716,
    "lng": 12.5824411,
    "cell_id": 41963030,
    "location_area_code": null,
    "accuracy": 568
  },
  "device_info": {
    "model": "SARA-R410M",
    "manufacturer": "u-blox"
  }
}

Find SIMs

get

Retrieves a list of SIMs filtered by partial SIM ID, label, or exact ICCID match.

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

Minimum package requirement for SIM alert threshold information: Pro

Authorizations
AuthorizationstringRequired
Query parameters
searchstringRequired

A partial SIM id or label, as well as a complete ICCID.

Example: ?search=foobar
limitstringOptional

Without this parameter the default is 10. Limit can be between 1 and 5000 records.

Example: 10
offsetstringOptional

The number of first records returned. Used for pagination of records, otherwise will default to 0.

Example: 20
Responses
200

OK

application/json
objectOptional
get/sims/find
GET /sims/find?search=text HTTP/1.1
Host: api.onomondo.com
Authorization: YOUR_API_KEY
Accept: */*
200

OK

[
  {
    "id": "000002273",
    "iccid": "89457387300000022734",
    "label": "iphone",
    "network_whitelist": "DK-UK-Only",
    "imei_lock": null,
    "connector": null,
    "activated": true,
    "online_at": "2020-09-30T05:52:21.953Z",
    "last_came_online_at": "2020-09-30T05:52:21.953Z",
    "network": {
      "name": "Telia",
      "country": "Denmark",
      "country_code": "DK",
      "mcc": "238",
      "mnc": "20"
    },
    "ipv4": "100.64.237.173",
    "usage": 568222249,
    "tags": [
      {
        "name": "Product A",
        "id": "aef0c9c8-f6d5-4e93-a330-1f59d5093d92",
        "can_write": false,
        "color": "#5b8fa5"
      }
    ],
    "location": {
      "lat": null,
      "lng": null,
      "cell_id": 39457,
      "location_area_code": 632,
      "accuracy": null
    }
  },
  {
    "id": "000002417",
    "iccid": "89457387300000024177",
    "label": "test-device",
    "network_whitelist": "nordics-only",
    "imei_lock": null,
    "connector": null,
    "activated": true,
    "online_at": null,
    "last_came_online_at": "2020-09-30T05:52:21.953Z",
    "network": {
      "name": null,
      "country": null,
      "country_code": null,
      "mcc": null,
      "mnc": null
    },
    "ipv4": "100.66.131.195",
    "usage": 0,
    "tags": [
      {
        "name": "Steens Products",
        "id": "4c21c1ce-0e3d-445f-8b3a-9d918a9acd89",
        "can_write": false,
        "color": "#441212"
      }
    ]
  },
  {
    "id": "000002418",
    "iccid": "89457387300000024185",
    "label": null,
    "network_whitelist": "Americas",
    "imei_lock": null,
    "connector": null,
    "activated": false,
    "online_at": null,
    "last_came_online_at": "2020-09-30T05:52:21.953Z",
    "network": {
      "name": null,
      "country": null,
      "country_code": null,
      "mcc": null,
      "mnc": null
    },
    "ipv4": "100.66.131.197",
    "usage": 0,
    "tags": [
      {
        "name": "Steens Products",
        "id": "4c21c1ce-0e3d-445f-8b3a-9d918a9acd89",
        "can_write": false,
        "color": "#441212"
      },
      {
        "name": "Supplier",
        "id": "a5023f47-1db8-425e-b664-dc0b8921f644",
        "can_write": false,
        "color": "#5ba571"
      }
    ]
  }
]

Update specific SIM

patch

Updates configurable parameters for the specified SIM.

Minimum package requirement for updating SIM alert: Pro

This request takes a JSON body. Only the properties that are being updated need to be included.

Authorizations
AuthorizationstringRequired
Path parameters
sim_idstringRequiredExample: 000000001
Header parameters
Content-TypestringOptionalExample: application/json
Body
labelstring · nullableOptional

A string alias of the SIM, null if no alias to be assigned.

Example: My IoT Device
network_whiteliststring · nullableOptional

Name of the Network List attached, null if no Network List should be attached.

Example: production-whitelist
imei_lockstring · nullableOptional

String IMEI of device the SIM should be locked to (if presented in network signaling) or a null value.

Example: 123456789012345
connectorstring · nullableOptional

Name of Connector attached, set to null if no Connector should be attached.

Example: my-connector
activatedbooleanOptional

Boolean to activate and deactivate the SIM.

Example: true
tagsstring[]Optional

An array of Tag IDs to be associated with a SIM. Tag IDs require string format and can be obtained using GET /tags endpoint. Caution: Include all Tags you want to keep plus any new ones, as this replaces the entire list of Tags.

Example: ["tag-id-1","tag-id-2"]
Responses
200

OK

application/json
objectOptional
patch/sims/{sim_id}
PATCH /sims/{sim_id} HTTP/1.1
Host: api.onomondo.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 48

{
  "label": "Updated Device Name",
  "activated": true
}
200

OK

{
  "id": "000279101",
  "msisdn": "882360011968393",
  "iccid": "89457387300002791013",
  "label": "test-device",
  "network_whitelist": "bene-excellent-testing-whitelist",
  "imei_lock": null,
  "imei": "861340049971524",
  "imsi": "234500027179101",
  "connector": "getting-started",
  "activated": true,
  "ipv4": "100.68.153.152",
  "online_at": null,
  "network": {
    "name": "Telia",
    "country": "Denmark",
    "country_code": "DK",
    "mcc": "238",
    "mnc": "20"
  },
  "usage": 97854,
  "tags": [
    {
      "name": "getting-started product",
      "id": "4c21c1ce-0e3d-445f-8b3a-9d918a9acd89",
      "can_write": false,
      "color": "#AB7D63"
    },
    {
      "name": "Developer",
      "id": "a5023f47-1db8-425e-b664-dc0b8921f644",
      "can_write": true,
      "color": "#5ba571"
    }
  ],
  "data_limit": {
    "used": 744,
    "total": 10000000,
    "type": "hourly",
    "period": "2021110112",
    "alert_threshold": null,
    "resets_at": "2021-11-01T13:00:00.000Z"
  },
  "location": {
    "lat": 55.6821716,
    "lng": 12.5824411,
    "cell_id": 41963030,
    "location_area_code": null,
    "accuracy": 568
  }
}

Bulk SIM Update

patch

Updates configuration parameters for multiple SIMs simultaneously.

Minimum package requirement for updating SIM alert: Pro

This request takes a JSON body. Only the properties that are being updated needs to be included. All properties that can be updated by a single SIM update can be added to the bulk call.

LIMIT: 20 SIMs per call

sims is the only one field in the body, which consists of an array of SIM update objects.

Each object needs to have the field id, which is the 9 character SIM ID.

Authorizations
AuthorizationstringRequired
Header parameters
Content-TypestringOptionalExample: application/json
Body
Responses
200

OK

text/plain
stringOptional
patch/sims/bulk
PATCH /sims/bulk HTTP/1.1
Host: api.onomondo.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 313

{
  "sims": [
    {
      "id": "000001934",
      "connector": "https-connector",
      "data_limit": {
        "total": 50000000,
        "type": "monthly",
        "alert_threshold": 25000000
      }
    },
    {
      "id": "000279139",
      "label": "jasons-device",
      "data_limit": {
        "total": 1000000,
        "type": "hourly",
        "alert_threshold": 750000
      }
    },
    {
      "id": "000210799",
      "network_whitelist": "{{network_whitelist}}"
    }
  ]
}
200

OK

{"id":"000001934","success":true}
{"id":"000279139","success":true}
{"id":"000210799","success":true}

Bulk Apply SIM Operations

patch

Applies one or more operations to a set of SIMs in a single request. The SIMs are selected by ID, by filter, by search, or by any combination of the three.

Minimum package requirement for updating data limit: Pro

Selecting the SIMs

  • simIds — an explicit array of 9 character SIM IDs.

  • filter — the SIMs matching the filters, same filter keys as GET /sims.

  • search — query parameter, a partial SIM ID or label, or a complete ICCID.

All three are combined. When simIds is sent, every requested SIM ID must also match filter/search and be accessible with the API key, otherwise the whole request is rejected with a 403. When simIds is left out, the operations are applied to every SIM matching filter/search, so sending neither simIds nor filter nor search updates the whole fleet.

Operations

Each entry in ops is one change: path is the property, op is how to apply it, value is the new value.

path

op

value

/label

set

String, max 255 characters, or null.

/connector

set

Name of an existing Connector (^[-_a-zA-Z0-9]{3,255}$), or null to detach.

/network_whitelist

set

Name of an existing Network List (^[-_a-zA-Z0-9]{3,255}$), or null to detach.

/tags

set, add, remove

Array of Tag IDs (UUID). set replaces the whole list, add/remove change part of it. All Tag IDs must exist in the organization.

/technologies

set, add, remove

Array of sms, 2g_3g, 4g. set enables exactly the listed technologies and disables the rest, add/remove only touch the listed ones.

/data_limit

set

Object, see below, or null.

/cost_alert

set

Object, see below, or null.

A path must not appear twice with conflicting operations: combining set with add/remove on /tags or /technologies in the same request is rejected with a 422.

Errors are returned as {"error": "<reason>"}, with a details object on validation errors.

/data_limit

  • total — bytes, minimum 500000. Must be sent together with type.

  • type — minute, hourly, daily, monthly

  • alert_threshold — bytes, minimum 500000, triggers the usage-alert webhook event when reached. Requires the webhooks feature.

  • null, or total: null, resets the SIMs to the default data limit of the organization's package instead of leaving them without a limit.

/cost_alert

  • threshold — positive number, the cost that triggers the alert.

  • period — daily or monthly, required when threshold is set.

  • null, or threshold: null, removes the cost alert.

Filters

filter takes a single key:value string or an array of them. Values of the same key are combined with OR, different keys with AND, e.g. ["connector:foo", "connector:bar", "activated:true"] selects activated SIMs on either Connector.

Filter key
Value

sim_id

One or more 9 character SIM IDs, comma separated.

iccid

One or more ICCIDs, comma separated.

imsi

One or more IMSIs, comma separated.

ipv4

One or more IPv4 addresses, comma separated.

label

One or more exact labels, comma separated.

tags

Tag name, or none for SIMs without Tags.

tag_types

is_read or is_write.

connector

Connector name, or none for SIMs without a Connector.

network_whitelist

Network List name, or none for SIMs without a Network List.

technologies

sms, 2g_3g or 4g, matches SIMs with that technology enabled.

online

true or false.

activated

true or false.

last_came_online_at

ISO timestamp, matches SIMs last online at or after it.

mcc

3 digit MCC, or none for SIMs without a current network.

country_code

2 letter uppercase country code, or none.

network_name

Network name, or none.

is_softsim

true or false.

type

physical, softsim, uicc_card, uicc_chip, uicc_softsim, euicc_card, euicc_chip or euicc_smdpp.

A comma separated filter value can hold at most 5000 entries.

Limits

Any number of operations can be sent in one request, each is applied to every selected SIM. API keys restricted through Tags can select at most 5000 SIMs per call, cannot change Tags in bulk, and can only update SIMs they have write access to.

Authorizations
AuthorizationstringRequired
Query parameters
searchstringOptional

Narrows the selection to SIMs matching a partial SIM ID or label, or a complete ICCID.

Example: ?search=foobar
Header parameters
Content-TypestringOptionalExample: application/json
Body
simIdsstring[]Optional

The SIM IDs to update. Leave out to update every SIM matching filter and search.

Example: ["000001934","000279139"]
filterone ofOptional

Selects the SIMs to update, using the same filter keys as GET /sims. Also verifies access when simIds is sent.

Example: ["activated:true","connector:foobar"]
stringOptional
or
string[]Optional
Responses
200

OK

application/json
objectOptional
patch/sims/bulk-apply
PATCH /sims/bulk-apply HTTP/1.1
Host: api.onomondo.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 334

{
  "simIds": [
    "000001934",
    "000279139"
  ],
  "ops": [
    {
      "path": "/label",
      "op": "set",
      "value": "jasons-device"
    },
    {
      "path": "/tags",
      "op": "add",
      "value": [
        "4c21c1ce-0e3d-445f-8b3a-9d918a9acd89"
      ]
    },
    {
      "path": "/technologies",
      "op": "remove",
      "value": [
        "sms"
      ]
    },
    {
      "path": "/data_limit",
      "op": "set",
      "value": {
        "total": 50000000,
        "type": "monthly",
        "alert_threshold": 25000000
      }
    }
  ]
}
{
  "message": "ok"
}

Add Tag to list of Tags of a SIM

put

Adds the Tag with the Tag ID to the given SIM. Will throw a 400 error if the Tag already is associated with the SIM.

Authorizations
AuthorizationstringRequired
Path parameters
sim_idstringRequiredExample: 000000001
tag_idstringRequiredExample: 7b6c2c22-dab6-482d-af43-0d673c6717fd
Body
Responses
200

OK

application/json
objectOptional
put/sims/{sim_id}/tags/{tag_id}
PUT /sims/{sim_id}/tags/{tag_id} HTTP/1.1
Host: api.onomondo.com
Authorization: YOUR_API_KEY
Accept: */*
{
  "message": "ok"
}

Remove Tag from list of Tags of a SIM

delete

Removes the Tag with Tag ID from the given SIM. Will throw a 400 error if the Tag is not currently associated with the SIM.

Authorizations
AuthorizationstringRequired
Path parameters
sim_idstringRequiredExample: 000000001
tag_idstringRequiredExample: 7b6c2c22-dab6-482d-af43-0d673c6717fd
Responses
200

OK

application/json
objectOptional
delete/sims/{sim_id}/tags/{tag_id}
DELETE /sims/{sim_id}/tags/{tag_id} HTTP/1.1
Host: api.onomondo.com
Authorization: YOUR_API_KEY
Accept: */*
{
  "message": "ok"
}

Last updated