SIMs
Returns detailed information for all registered SIMs.
Using parameters will focus the records returned in the response.
Used for pagination of records.
MDAyNDY0OTk5The max number of records returned. Limit can be between 1 and 5000 records. Default is 1000 records.
10Filter 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:trueoronline:false
activated - Boolean filter for SIM activation status
- Format:
activated:trueoractivated:false
connector - Filter by Connector name
- Format:
connector:<connector-name>
network_whitelist - Filter by Network List name
- Format:
network_whitelist:<whitelist-name>
filter[]=online:true&filter[]=connector:foobarOK
GET /sims HTTP/1.1
Host: api.onomondo.com
Authorization: YOUR_API_KEY
Accept: */*
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"
}
]
}
]
}Returns detailed information for a specific SIM.
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.
000000001OK
GET /sims/{sim_id} HTTP/1.1
Host: api.onomondo.com
Authorization: YOUR_API_KEY
Accept: */*
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"
}
}Retrieves a list of SIMs filtered by partial SIM ID, label, or exact ICCID match.
A partial SIM id or label, as well as a complete ICCID.
?search=foobarWithout this parameter the default is 10. Limit can be between 1 and 5000 records.
10The number of first records returned. Used for pagination of records, otherwise will default to 0.
20OK
GET /sims/find?search=text HTTP/1.1
Host: api.onomondo.com
Authorization: YOUR_API_KEY
Accept: */*
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"
}
]
}
]Updates configurable parameters for the specified SIM.
This request takes a JSON body. Only the properties that are being updated need to be included.
000000001application/jsonA string alias of the SIM, null if no alias to be assigned.
My IoT DeviceName of the Network List attached, null if no Network List should be attached.
production-whitelistString IMEI of device the SIM should be locked to (if presented in network signaling) or a null value.
123456789012345Name of Connector attached, set to null if no Connector should be attached.
my-connectorBoolean to activate and deactivate the SIM.
trueAn 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.
["tag-id-1","tag-id-2"]OK
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
}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
}
}Updates configuration parameters for multiple SIMs simultaneously.
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.
application/jsonOK
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}}"
}
]
}OK
{"id":"000001934","success":true}
{"id":"000279139","success":true}
{"id":"000210799","success":true}
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.
Selecting the SIMs
simIds— an explicit array of 9 character SIM IDs.filter— the SIMs matching the filters, same filter keys asGET /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, minimum500000. Must be sent together withtype.type—minute,hourly,daily,monthlyalert_threshold— bytes, minimum500000, triggers theusage-alertwebhook event when reached. Requires the webhooks feature.null, ortotal: 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—dailyormonthly, required whenthresholdis set.null, orthreshold: 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.
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.
Narrows the selection to SIMs matching a partial SIM ID or label, or a complete ICCID.
?search=foobarapplication/jsonThe SIM IDs to update. Leave out to update every SIM matching filter and search.
["000001934","000279139"]Selects the SIMs to update, using the same filter keys as GET /sims. Also verifies access when simIds is sent.
["activated:true","connector:foobar"]OK
Invalid body: unknown path, an operation not allowed on the given path, a value of the wrong type, or a property the organization's package does not include.
One or more requested SIMs or Tags are not accessible with the API key or do not exist, or the API key is restricted through Tags and tried to change Tags in bulk.
The requested Connector or Network List does not exist.
set was combined with add/remove on /tags or /technologies (invalid_tags_request, invalid_technologies_request), or more than 5000 SIMs were requested with an API key restricted through Tags.
The update did not finish in time. Retry with fewer SIMs or fewer operations per call.
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"
}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.
0000000017b6c2c22-dab6-482d-af43-0d673c6717fdOK
Bad Request
PUT /sims/{sim_id}/tags/{tag_id} HTTP/1.1
Host: api.onomondo.com
Authorization: YOUR_API_KEY
Accept: */*
{
"message": "ok"
}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.
0000000017b6c2c22-dab6-482d-af43-0d673c6717fdOK
Bad Request
DELETE /sims/{sim_id}/tags/{tag_id} HTTP/1.1
Host: api.onomondo.com
Authorization: YOUR_API_KEY
Accept: */*
{
"message": "ok"
}Last updated