# API Reference Onomondo provides an HTTP RESTful Application Programming Interface (API) for 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. {% embed url="" %} {% embed url="" %} 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: ``` ## 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. ``` 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](https://www.epochconverter.com/timezones?q=1730239201)), meaning that in the current period 600 - 520 = 80 calls were already made. ## Response limits Each response can return a maximum of 1000 objects and the default limit can vary per endpoint. If more objects for a given endpoint is required then consult the pagination method of said endpoint. # SIMs ## Retrieve information for all SIMs > Returns detailed information for all registered SIMs.\ > \ > {% hint style="info" %} Minimum package requirement for SIM location, modem model, and modem manufacturer information: \Fleet\\ > \ > Minimum package requirement for SIM alert threshold information: \Pro\ {% endhint %}\ > Using parameters will focus the records returned in the response. ```json {"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/sims":{"get":{"summary":"Retrieve information for all SIMs","description":"Returns detailed information for all registered SIMs.\n\n{% hint style=\"info\" %} Minimum package requirement for SIM location, modem model, and modem manufacturer information: Fleet\n\nMinimum package requirement for SIM alert threshold information: Pro {% endhint %}\nUsing parameters will focus the records returned in the response.","parameters":[{"name":"next_page","in":"query","schema":{"type":"string"},"description":"Used for pagination of records."},{"name":"limit","in":"query","schema":{"type":"string"},"description":"The max number of records returned. Limit can be between 1 and 5000 records. Default is 1000 records."},{"name":"filter","in":"query","style":"deepObject","explode":true,"schema":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"description":"Filter SIMs based on various criteria. Can be provided as a single filter or multiple filters.\n\n**Single filter format**: `filter=key:value`\n\n**Multiple filters format**: `filter[]=key:value&filter[]=key2:value2`\n\nSupported filter types:\n\n**online** - Boolean filter for SIM online status\n- Format: `online:true` or `online:false`\n\n**activated** - Boolean filter for SIM activation status\n- Format: `activated:true` or `activated:false`\n\n**connector** - Filter by Connector name\n- Format: `connector:`\n\n**network_whitelist** - Filter by Network List name\n- Format: `network_whitelist:`\n"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}} ``` ## Retrieve information for a specific SIM > Returns detailed information for a specific SIM.\ > {% hint style="info" %} Minimum package requirement for SIM location, modem model, and modem manufacturer information: \Fleet\\ > \ > Minimum package requirement for SIM alert threshold information: \Pro\ {% endhint %}\ > 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. ```json {"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/sims/{sim_id}":{"get":{"summary":"Retrieve information for a specific SIM","description":"Returns detailed information for a specific SIM.\n{% hint style=\"info\" %} Minimum package requirement for SIM location, modem model, and modem manufacturer information: Fleet\n\nMinimum package requirement for SIM alert threshold information: Pro {% endhint %}\nBy 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](https://app.onomondo.com/sims).\nYou can also use the **ICCID value**, if that is available.\n\nNote that the `location` and `device_info` fields are optional, meaning that they are only present if the information is available.","parameters":[{"name":"sim_id","in":"path","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}} ``` ## Find SIMs > Retrieves a list of SIMs filtered by partial SIM ID, label, or exact ICCID match.\ > {% hint style="info" %} Minimum package requirement for SIM location, modem model, and modem manufacturer information: \Fleet\\ > \ > Minimum package requirement for SIM alert threshold information: \Pro\ {% endhint %} ```json {"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/sims/find":{"get":{"summary":"Find SIMs","description":"Retrieves a list of SIMs filtered by partial SIM ID, label, or exact ICCID match.\n{% hint style=\"info\" %} Minimum package requirement for SIM location, modem model, and modem manufacturer information: Fleet\n\nMinimum package requirement for SIM alert threshold information: Pro {% endhint %}","parameters":[{"name":"search","in":"query","schema":{"type":"string"},"description":"A partial SIM id or label, as well as a complete ICCID.","required":true},{"name":"limit","in":"query","schema":{"type":"string"},"description":"Without this parameter the default is 10. Limit can be between 1 and 5000 records."},{"name":"offset","in":"query","schema":{"type":"string"},"description":"The number of first records returned. Used for pagination of records, otherwise will default to 0."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}} ``` ## Update specific SIM > Updates configurable parameters for the specified SIM.\ > {% hint style="info" %} Minimum package requirement for updating SIM alert: \Pro\ {% endhint %}\ > This request takes a JSON body. Only the properties that are being updated need to be included. ```json {"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/sims/{sim_id}":{"patch":{"summary":"Update specific SIM","description":"Updates configurable parameters for the specified SIM.\n{% hint style=\"info\" %} Minimum package requirement for updating SIM alert: Pro {% endhint %}\nThis request takes a JSON body. Only the properties that are being updated need to be included.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","nullable":true,"description":"A string alias of the SIM, null if no alias to be assigned."},"network_whitelist":{"type":"string","nullable":true,"description":"Name of the Network List attached, null if no Network List should be attached."},"imei_lock":{"type":"string","nullable":true,"description":"String IMEI of device the SIM should be locked to (if presented in network signaling) or a null value."},"connector":{"type":"string","nullable":true,"description":"Name of Connector attached, set to null if no Connector should be attached."},"activated":{"type":"boolean","description":"Boolean to activate and deactivate the SIM."},"data_limit":{"type":"object","nullable":true,"description":"Object that can set hard data limits to the SIM. When the limit is reached the device will not be able to send data until the time indicated by the property `resets_at`. If webhook is set up, usage-alert events will be triggered at alert_threshold and when total limit is reached.","required":["total","type"],"properties":{"total":{"type":"integer","minimum":500000,"description":"Data limit in bytes (minimum 500KB)."},"type":{"type":"string","enum":["minute","hourly","daily","monthly"],"description":"Time period for the data limit reset."},"alert_threshold":{"type":"integer","minimum":500000,"description":"Warning amount in bytes. Must be less than total. Triggers usage-alert event when reached (minimum 500KB)."}}},"tags":{"type":"array","items":{"type":"string"},"description":"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."},"technologies":{"type":"object","description":"Object to control technology access. **Caution**: Ensure SIM is not connected to RAN when changing these settings.","properties":{"sms":{"type":"boolean","description":"Set to false to remove the ability to send SMS."},"2g_3g":{"type":"boolean","description":"Set to false to remove the ability to connect on 2G/3G."},"4g":{"type":"boolean","description":"Set to false to remove ability to connect to 4G."}}}}}}}},"parameters":[{"name":"Content-Type","in":"header","schema":{"type":"string"}},{"name":"sim_id","in":"path","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}} ``` ## Bulk SIM Update > Updates configuration parameters for multiple SIMs simultaneously.\ > \ > {% hint style="info" %} Minimum package requirement for updating SIM alert: \Pro\ {% endhint %}\ > \ > 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.\ > \ > {% hint style="warning" %} ICCID is not accepted but can be connected to a SIM ID by taking the first 9 of the last 10 numbers of the ICCID. Here is an ICCID example with the SIM ID in bold:\ > \ > 8945738730-\_\_000001934\_\_-2 {% endhint %} ```json {"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/sims/bulk":{"patch":{"summary":"Bulk SIM Update","description":"Updates configuration parameters for multiple SIMs simultaneously.\n\n{% hint style=\"info\" %} Minimum package requirement for updating SIM alert: Pro {% endhint %}\n\nThis 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.\n\n**LIMIT: 20 SIMs per call**\n\n`sims` is the only one field in the body, which consists of an array of SIM update objects.\n\nEach object needs to have the field `id`, which is the 9 character SIM ID.\n\n{% hint style=\"warning\" %} ICCID is not accepted but can be connected to a SIM ID by taking the first 9 of the last 10 numbers of the ICCID. Here is an ICCID example with the SIM ID in bold:\n\n8945738730-__000001934__-2 {% endhint %}","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["sims"],"properties":{"sims":{"type":"array","items":{"type":"object","required":["id"],"properties":{"id":{"type":"string","description":"The SIM ID."},"label":{"type":"string","nullable":true,"description":"A string alias of the SIM, null if no alias to be assigned."},"network_whitelist":{"type":"string","nullable":true,"description":"Name of the Network List attached, null if no Network List should be attached."},"imei_lock":{"type":"string","nullable":true,"description":"String IMEI of device the SIM should be locked to (if presented in network signaling) or a null value."},"connector":{"type":"string","nullable":true,"description":"Name of Connector attached, set to null if no Connector should be attached."},"activated":{"type":"boolean","description":"Boolean to activate and deactivate the SIM."},"data_limit":{"type":"object","nullable":true,"description":"Object that can set hard data limits to the SIM. When the limit is reached the device will not be able to send data until the time indicated by the property `resets_at`. If webhook is set up, usage-alert events will be triggered at alert_threshold and when total limit is reached.","required":["total","type"],"properties":{"total":{"type":"integer","minimum":500000,"description":"Data limit in bytes (minimum 500KB)."},"type":{"type":"string","enum":["minute","hourly","daily","monthly"],"description":"Time period for the data limit reset."},"alert_threshold":{"type":"integer","minimum":500000,"description":"Warning amount in bytes. Must be less than total. Triggers usage-alert event when reached (minimum 500KB)."}}},"tags":{"type":"array","items":{"type":"string"},"description":"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."},"technologies":{"type":"object","description":"Object to control technology access. **Caution**: Ensure SIM is not connected to RAN when changing these settings.","properties":{"sms":{"type":"boolean","description":"Set to false to remove the ability to send SMS."},"2g/3g":{"type":"boolean","description":"Set to false to remove the ability to connect on 2G/3G."},"4g":{"type":"boolean","description":"Set to false to remove ability to connect to 4G."}}}}}}}}}}},"parameters":[{"name":"Content-Type","in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"type":"string"}}}}}}}}} ``` ## Add Tag to list of Tags of a SIM > 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. ```json {"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/sims/{sim_id}/tags/{tag_id}":{"put":{"summary":"Add Tag to list of Tags of a SIM","description":"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.","requestBody":{"content":{}},"parameters":[{"name":"sim_id","in":"path","schema":{"type":"string"},"required":true},{"name":"tag_id","in":"path","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object"}}}}}}}}} ``` ## Remove Tag from list of Tags of a SIM > 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. ```json {"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/sims/{sim_id}/tags/{tag_id}":{"delete":{"summary":"Remove Tag from list of Tags of a SIM","description":"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.","parameters":[{"name":"sim_id","in":"path","schema":{"type":"string"},"required":true},{"name":"tag_id","in":"path","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object"}}}}}}}}} ``` # Network Lists ## Retrieve information about all Network Lists > Retrieves a list of all Network Lists connected to your organization.\ > \ > The response includes Network List objects containing the name, associated Tags,\ > and a list of network objects with \`mcc\` (Mobile Country Code) and \`mnc\` (Mobile Network Code) values. ```json {"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/network-whitelists":{"get":{"summary":"Retrieve information about all Network Lists","description":"Retrieves a list of all Network Lists connected to your organization.\n\nThe response includes Network List objects containing the name, associated Tags,\nand a list of network objects with `mcc` (Mobile Country Code) and `mnc` (Mobile Network Code) values.","responses":{"200":{"description":"OK","content":{"application/json":{}}}}}}}} ``` ## Retrieve a specific Network List > Retrieves a specific Network List by named that is connected to the account. ```json {"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/network-whitelists/{network_whitelist_name}":{"get":{"summary":"Retrieve a specific Network List","description":"Retrieves a specific Network List by named that is connected to the account.","parameters":[{"name":"network_whitelist_name","in":"path","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}} ``` ## Add Network List > Creates a new Network List connected to the account.\ > \ > Once the Network List is created, you can map SIMs to it by updating the desired SIMs.\ > \ > {% hint style="warning" %} Pricing of networks differ. Make sure you check pricing of networks in your ratecard or clarify with us at \\ to avoid incurring unexpected costs related to networks. {% endhint %} ```json {"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/network-whitelists":{"post":{"summary":"Add Network List","description":"Creates a new Network List connected to the account.\n\nOnce the Network List is created, you can map SIMs to it by updating the desired SIMs.\n\n{% hint style=\"warning\" %} Pricing of networks differ. Make sure you check pricing of networks in your ratecard or clarify with us at support@onomondo.com to avoid incurring unexpected costs related to networks. {% endhint %}","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"tags":{"type":"array","items":{"type":"string"},"description":"An array of Tag IDs to be associated with the Network List."},"networks":{"type":"array","items":{"type":"object"},"description":"An array of networks to be associated with a SIM."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}} ``` ## Update Network List > Modify a specific Network List.\ > {% hint style="warning" %} Pricing of networks differ. Make sure you check pricing of networks in your ratecard or clarify with us at \\ to avoid incurring unexpected costs related to networks. {% endhint %} ```json {"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/network-whitelists/{network_whitelist_name}":{"patch":{"summary":"Update Network List","description":"Modify a specific Network List.\n{% hint style=\"warning\" %} Pricing of networks differ. Make sure you check pricing of networks in your ratecard or clarify with us at support@onomondo.com to avoid incurring unexpected costs related to networks. {% endhint %}","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string"},"description":"An array of Tag IDs to be associated with the Network List. **Caution**: Include all Tags you want to keep plus any new ones, as this replaces the entire list of Tags."},"networks":{"type":"array","items":{"type":"object"},"description":"An array of networks to be associated with a SIM. **Caution**: Include all networks you want to keep plus any new ones, as this replaces the entire list of networks."}}}}}},"parameters":[{"name":"network_whitelist_name","in":"path","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}} ``` ## Delete Network List > Removes a specific Network List.\ > \ > Note that all mappings to said Network List will need to be removed prior to the removal of the Network List itself, otherwise a \`403\` status code will be encountered. ```json {"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/network-whitelists/{network_whitelist_name}":{"delete":{"summary":"Delete Network List","description":"Removes a specific Network List.\n\nNote that all mappings to said Network List will need to be removed prior to the removal of the Network List itself, otherwise a `403` status code will be encountered.","parameters":[{"name":"network_whitelist_name","in":"path","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"403":{"description":"Network List still mapped to some SIMs","content":{"application/json":{"schema":{"type":"object"}}}}}}}}} ``` # Connectors ## Retrieve information for all Connectors > Returns detailed information for all registered Connectors.\ > Note that sensitive data will not be returned but information around\ > when it was updated and if its set can be found in the \`meta\` object.\ > \ > {% hint style="info" %}\ > Minimum package requirement: \Enterprise\\ > {% endhint %} ```json {"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/connectors":{"get":{"summary":"Retrieve information for all Connectors","description":"Returns detailed information for all registered Connectors.\nNote that sensitive data will not be returned but information around\nwhen it was updated and if its set can be found in the `meta` object.\n\n{% hint style=\"info\" %}\nMinimum package requirement: Enterprise\n{% endhint %}","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}} ``` ## Add Connector > Creates a Connector. The \`object\` various depending on the \`type\`.\ > \`passthrough\` and \`tags\` are shared amongst all types though and\ > are the mechanisms to route parts of the traffic around the Connector\ > as well as grouping and access control.\ > \ > \[Read more about Connectors here]\( > \ > {% hint style="info" %}\ > Minimum package requirement: \Enterprise\\ > \ > Note: Some Connectors are not included in the documentation here as they are currently in a beta state.\ > Moreover, then some Connectors are easier to create in the web app, e.g. AWS IoT Core Connector.\ > {% endhint %} ```json {"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}},"schemas":{"SecretMeta":{"type":"object","properties":{"is_set":{"type":"boolean","description":"Whether the secret value is configured"},"last_updated_at":{"type":"string","format":"date-time","description":"When the secret was last updated"}},"required":["is_set","last_updated_at"]}}},"paths":{"/connectors":{"post":{"summary":"Add Connector","description":"Creates a Connector. The `object` various depending on the `type`.\n`passthrough` and `tags` are shared amongst all types though and\nare the mechanisms to route parts of the traffic around the Connector\nas well as grouping and access control.\n\n[Read more about Connectors here](https://help.onomondo.com/en/articles/213872-what-are-onomondo-connectors).\n\n{% hint style=\"info\" %}\nMinimum package requirement: Enterprise\n\nNote: Some Connectors are not included in the documentation here as they are currently in a beta state.\nMoreover, then some Connectors are easier to create in the web app, e.g. AWS IoT Core Connector.\n{% endhint %}","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"name":{"type":"string","pattern":"^[-_a-zA-Z0-9]{3,255}$","description":"A descriptive name for the connector (3-255 characters, alphanumeric, hyphens, and underscores only)"},"type":{"type":"string","enum":["https","tls","microsoft_azure_iot","aws_iot_core"],"description":"The type of Connector to create"},"tags":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Tags for grouping and access control (UUIDs)","nullable":true},"passthrough":{"type":"array","nullable":true,"items":{"oneOf":[{"type":"object","properties":{"protocol":{"type":"string","enum":["icmp"],"description":"The protocol for passthrough traffic"},"ip":{"type":"string","nullable":true,"description":"The IP address for passthrough traffic"}},"required":["protocol"]},{"type":"object","properties":{"protocol":{"type":"string","enum":["tcp","udp"],"description":"The protocol for passthrough traffic"},"ip":{"type":"string","nullable":true,"description":"The IP address for passthrough traffic"},"port":{"type":"integer","minimum":0,"maximum":65535,"nullable":true,"description":"The port for passthrough traffic"}},"required":["protocol"]}]},"description":"Rules for routing traffic around the connector"},"options":{"type":"object","description":"Connector-specific configuration options","oneOf":[{"title":"TLS Connector Options","properties":{"host":{"type":"string","description":"The target host IP address or hostname"},"port":{"type":"integer","minimum":1,"maximum":65535,"description":"The target port number"},"server_name":{"type":"string","description":"The server name for TLS SNI"},"key":{"type":"string","format":"password","description":"RSA private key in PEM format"},"ca":{"type":"string","format":"password","description":"Certificate Authority certificate in PEM format"},"cert":{"type":"string","format":"password","description":"Client certificate in PEM format"}},"required":["host","port","server_name","key","ca","cert"]},{"title":"HTTPS Connector Options","properties":{"host":{"type":"string","format":"uri","description":"The target HTTPS URL"},"shouldReturnBody":{"type":"boolean","description":"Whether to return the response body","default":false}},"required":["host"]},{"title":"AWS IoT Core Connector Options","properties":{"region":{"type":"string","description":"The AWS region for IoT Core"},"role":{"type":"string","description":"The AWS IAM role ARN for authentication"},"publishTopic":{"type":"string","description":"The MQTT topic to publish to"},"subscribeTopic":{"type":"string","description":"The MQTT topic to subscribe to"},"defaultProtocol":{"type":"string","enum":["tcp","udp"],"description":"The default protocol for connections"},"defaultPort":{"type":"integer","minimum":1,"maximum":65535,"description":"The default port for connections"}},"required":["region","role","publishTopic","subscribeTopic","defaultProtocol","defaultPort"]},{"title":"Microsoft Azure IoT Connector Options","properties":{"connectionString":{"type":"string","format":"password","description":"The Azure IoT Hub connection string"}},"required":["connectionString"]}]}}}}}},"responses":{"200":{"description":"Connector successfully created","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The Connector name"},"type":{"type":"string","enum":["tls","https","aws_iot_core","microsoft_azure_iot"],"description":"The Connector type"},"passthrough":{"type":"array","nullable":true,"items":{"oneOf":[{"type":"object","properties":{"protocol":{"type":"string","enum":["icmp"]},"ip":{"type":"string","nullable":true}}},{"type":"object","properties":{"protocol":{"type":"string","enum":["tcp","udp"]},"ip":{"type":"string","nullable":true},"port":{"type":"integer","minimum":0,"maximum":65535,"nullable":true}}}]},"description":"Passthrough rules for traffic routing"},"tags":{"type":"array","nullable":true,"items":{"type":"string","format":"uuid"},"description":"Tags for grouping and access control"},"options":{"type":"object","description":"Connector-specific configuration (sensitive values may be omitted)"},"meta":{"type":"object","description":"Metadata about sensitive fields (only present for connectors with secrets)","properties":{"ca":{"$ref":"#/components/schemas/SecretMeta"},"key":{"$ref":"#/components/schemas/SecretMeta"},"cert":{"$ref":"#/components/schemas/SecretMeta"},"connectionString":{"$ref":"#/components/schemas/SecretMeta"}}}}}}}}}}}}} ``` ## Update Connector > Use a PATCH request to update an Onomondo Connector in your account.\ > \ > \ > Update one of the settings of your Connector:\ > \- \`name\`: Change the name\ > \- \`type\`: Change the type of the Connector. For this to be successful, you will need to also update the \`options\` field with the new Connector type details.\ > \- \`passthrough\`: An array of objects to exclude being processed up by the connector. Each object requires at least a "protocol" (of either \`udp\`,\`tcp\`, or \`icmp\`).\ > \- \`tags\`: An array of Tag IDs to be associated with a Connector.\ > \- \`options\`: See the \`POST\` requests for each of the Connectors for fields required in the options field.\ > \ > {% hint style="info" %}\ > Minimum package requirement: \Enterprise\\ > {% endhint %} ```json {"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}},"schemas":{"SecretMeta":{"type":"object","properties":{"is_set":{"type":"boolean","description":"Whether the secret value is configured"},"last_updated_at":{"type":"string","format":"date-time","description":"When the secret was last updated"}},"required":["is_set","last_updated_at"]}}},"paths":{"/connectors/{connector_name}":{"patch":{"summary":"Update Connector","description":"Use a PATCH request to update an Onomondo Connector in your account.\n\n\nUpdate one of the settings of your Connector:\n- `name`: Change the name\n- `type`: Change the type of the Connector. For this to be successful, you will need to also update the `options` field with the new Connector type details.\n- `passthrough`: An array of objects to exclude being processed up by the connector. Each object requires at least a \"protocol\" (of either `udp`,`tcp`, or `icmp`).\n- `tags`: An array of Tag IDs to be associated with a Connector.\n- `options`: See the `POST` requests for each of the Connectors for fields required in the options field.\n\n{% hint style=\"info\" %}\nMinimum package requirement: Enterprise\n{% endhint %}","operationId":"updateConnector","tags":["Connectors"],"parameters":[{"name":"connector_name","in":"path","schema":{"type":"string"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["https","tls","microsoft_azure_iot","aws_iot_core"],"description":"The type of Connector (must update options field when changing type)"},"tags":{"type":"array","items":{"type":"string"},"description":"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."},"passthrough":{"type":"array","nullable":true,"items":{"oneOf":[{"type":"object","properties":{"protocol":{"type":"string","enum":["icmp"],"description":"The protocol for passthrough traffic"},"ip":{"type":"string","nullable":true,"description":"The IP address for passthrough traffic"}},"required":["protocol"]},{"type":"object","properties":{"protocol":{"type":"string","enum":["tcp","udp"],"description":"The protocol for passthrough traffic"},"ip":{"type":"string","nullable":true,"description":"The IP address for passthrough traffic"},"port":{"type":"integer","minimum":0,"maximum":65535,"nullable":true,"description":"The port for passthrough traffic"}},"required":["protocol"]}]},"description":"Rules for routing traffic around the connector"},"options":{"type":"object","description":"Connector-specific configuration options (see POST examples for each connector type)","oneOf":[{"title":"TLS Connector Options","properties":{"host":{"type":"string","description":"The target host IP address or hostname"},"port":{"type":"integer","minimum":1,"maximum":65535,"description":"The target port number"},"server_name":{"type":"string","description":"The server name for TLS SNI"},"key":{"type":"string","format":"password","description":"RSA private key in PEM format"},"ca":{"type":"string","format":"password","description":"Certificate Authority certificate in PEM format"},"cert":{"type":"string","format":"password","description":"Client certificate in PEM format"}}},{"title":"HTTPS Connector Options","properties":{"host":{"type":"string","format":"uri","description":"The target HTTPS URL"},"shouldReturnBody":{"type":"boolean","description":"Whether to return the response body"}}},{"title":"AWS IoT Core Connector Options","properties":{"region":{"type":"string","description":"The AWS region for IoT Core"},"role":{"type":"string","description":"The AWS IAM role ARN for authentication"},"publishTopic":{"type":"string","description":"The MQTT topic to publish to"},"subscribeTopic":{"type":"string","description":"The MQTT topic to subscribe to"},"defaultProtocol":{"type":"string","enum":["tcp","udp"],"description":"The default protocol for connections"},"defaultPort":{"type":"integer","minimum":1,"maximum":65535,"description":"The default port for connections"}}},{"title":"Microsoft Azure IoT Connector Options","properties":{"connectionString":{"type":"string","format":"password","description":"The Azure IoT Hub connection string"}}}]}}}}}},"responses":{"200":{"description":"Connector successfully updated","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The Connector name"},"type":{"type":"string","enum":["https","tls","microsoft_azure_iot","aws_iot_core"],"description":"The connector type"},"passthrough":{"type":"array","nullable":true,"items":{"oneOf":[{"type":"object","properties":{"protocol":{"type":"string","enum":["icmp"]},"ip":{"type":"string","nullable":true}}},{"type":"object","properties":{"protocol":{"type":"string","enum":["tcp","udp"]},"ip":{"type":"string","nullable":true},"port":{"type":"integer","minimum":0,"maximum":65535,"nullable":true}}}]},"description":"Passthrough rules for traffic routing"},"tags":{"type":"array","nullable":true,"items":{"type":"string","format":"uuid"},"description":"Tags for grouping and access control"},"options":{"type":"object","description":"Connector-specific configuration (sensitive values may be omitted)"},"meta":{"type":"object","description":"Metadata about sensitive fields (only present for connectors with secrets)","properties":{"ca":{"$ref":"#/components/schemas/SecretMeta"},"key":{"$ref":"#/components/schemas/SecretMeta"},"cert":{"$ref":"#/components/schemas/SecretMeta"},"connectionString":{"$ref":"#/components/schemas/SecretMeta"}}}}}}}}}}}}} ``` ## Remove Connector > Removes a specific Connector.\ > \ > \ > Note that all mappings to said Connector will need to be\ > removed prior to the removal of the Connector itself, otherwise\ > a \`403\` status code will be encountered.\ > \ > \ > {% hint style="info" %}\ > Minimum package requirement: \Enterprise\\ > {% endhint %} ```json {"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/connectors/{connector_name}":{"delete":{"summary":"Remove Connector","description":"Removes a specific Connector.\n\n\nNote that all mappings to said Connector will need to be\nremoved prior to the removal of the Connector itself, otherwise\na `403` status code will be encountered.\n\n\n{% hint style=\"info\" %}\nMinimum package requirement: Enterprise\n{% endhint %}","parameters":[{"name":"connector_name","in":"path","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"403":{"description":"Connector still mapped to some SIMs","content":{"application/json":{"schema":{"type":"object"}}}}}}}}} ``` # Usage ## Retrieve All Usage > Retrieves all usage associated to all SIMs which are connected to an account/organization.\ > \ > Using parameters will focus the records returned in the response. ```json {"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/usage":{"get":{"summary":"Retrieve All Usage","description":"Retrieves all usage associated to all SIMs which are connected to an account/organization.\n\nUsing parameters will focus the records returned in the response.","parameters":[{"name":"next_page","in":"query","schema":{"type":"string"},"description":"Used for pagination of records."},{"name":"limit","in":"query","schema":{"type":"string"},"description":"The max number of records returned. Limit can be between 1 and 1000 records. Default is 1000 records."},{"name":"offset","in":"query","description":"Number of records to skip (for pagination)","schema":{"type":"integer","minimum":0,"default":0}},{"name":"group","in":"query","schema":{"type":"string"},"description":"Used for grouping the records by hours or not"},{"name":"filter","in":"query","style":"deepObject","explode":true,"schema":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"required":true,"description":"Filter usage based on various criteria. Can be provided as a single filter or multiple filters.\n\n**Single filter format**: `filter=key:value`\n\n**Multiple filters format**: `filter[]=key:value&filter[]=key2:value2`\n\nSupported filter types:\n\n**time** - Filter usage by time\n- Format: `time:2020-01-30` or `time:2020-01` or `time:2020`\n\n**sim_id** - Filter usage by SIM id\n- Format: `sim_id:000000001`\n\n**country_code** - Filter usage by country code\n- Format: `country_code:dk`\n"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}} ``` ## Retrieve Usage of specific SIM > Retrieves usage associated to a specific SIM connected to an account/organization.\ > \ > Using parameters will focus the records returned in the response. ```json {"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/usage/{sim_id}":{"get":{"summary":"Retrieve Usage of specific SIM","description":"Retrieves usage associated to a specific SIM connected to an account/organization.\n\nUsing parameters will focus the records returned in the response.","parameters":[{"name":"sim_id","in":"path","schema":{"type":"string"},"required":true},{"name":"next_page","in":"query","schema":{"type":"string"},"description":"Used for pagination of records."},{"name":"limit","in":"query","schema":{"type":"string"},"description":"The max number of records returned. Limit can be between 1 and 1000 records. Default is 1000 records."},{"name":"offset","in":"query","description":"Number of records to skip (for pagination)","schema":{"type":"integer","minimum":0,"default":0}},{"name":"group","in":"query","schema":{"type":"string"},"description":"Used for grouping the records by hours or not"},{"name":"filter","in":"query","style":"deepObject","explode":true,"schema":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"description":"Filter usage based on various criteria. Can be provided as a single filter or multiple filters.\n\n**Single filter format**: `filter=key:value`\n\n**Multiple filters format**: `filter[]=key:value&filter[]=key2:value2`\n\nSupported filter types:\n\n**time** - Filter usage by time\n- Format: `time:2020-01-30` or `time:2020-01` or `time:2020`\n\n**country_code** - Filter usage by country code\n- Format: `country_code:dk`\n"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}} ``` ## Retrieve total usage by Tag > Retrieves all usage associated to all SIMs connected to an account/organization.\ > \ > Using parameters will focus the records returned in the response. ```json {"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/usage/tag-total/{tag_id}":{"get":{"summary":"Retrieve total usage by Tag","description":"Retrieves all usage associated to all SIMs connected to an account/organization.\n\nUsing parameters will focus the records returned in the response.","parameters":[{"name":"tag_id","in":"path","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}} ``` # Tags ## Retrieve Tags > Retrieves the name and ID of the all the Tags, which can be used to alter Tag assocations on the different resources (SIMs, Connectors and Network Lists).\ > \ > Tags allow you to group SIMs, users, Connectors and Network Lists into sub-groups within your organization to customize control and views.\ > \ > If you want more information about the feature, check out our article \[How do I set up Tags?]\( > \ > {% hint style="info" %} Currently, creating and updating Tags should be done in \the](https://app.onomondo.com/tags">the) Tags page in the web app\. {% endhint %} ```json {"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/tags/search/tags":{"get":{"summary":"Retrieve Tags","description":"Retrieves the name and ID of the all the Tags, which can be used to alter Tag assocations on the different resources (SIMs, Connectors and Network Lists).\n\nTags allow you to group SIMs, users, Connectors and Network Lists into sub-groups within your organization to customize control and views.\n\nIf you want more information about the feature, check out our article [How do I set up Tags?](https://help.onomondo.com/en/articles/151350-how-do-i-set-up-tags)\n\n{% hint style=\"info\" %} Currently, creating and updating Tags should be done in the Tags page in the web app. {% endhint %}","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}} ``` # Network Logs ## Retrieve Network Logs of a SIM > Retrieves the Network Logs for a specific SIM. Network Logs capture the complete connection lifecycle and help diagnose connectivity issues.\ > \ > The response contains various different Log Types (distinguished by the \`log\_type\` field). Each type holds different information and showcases the type of event that has occurred:\ > \- \`network-authentication\`: Initial connection attempt when device scans for and attempts to connect to a specific network. Records whether the SIM is allowed to connect based on Network List/Whitelist and IMEI settings.\ > \- Authentication \`log\_types\` also include SIM and network information. A successful authentication will have \`status\`/\`reason\` properties as \`null\` in the response.\ > \ > \- \`network-registration\`: Occurs after authentication when Onomondo and the given network sync to provide cellular technology connections. Has two phases:\ > \- Device registration to specific technology (\`is\_data\_attach: false\`), means that the device will be able to send and receive SMSs\ > \- Data session creation enabling data transmission (\`is\_data\_attach: true\`), means that the device will be able to send and receieve IP traffic\ > \ > \- \`network-deregistration\`: Logs disconnection between Onomondo and the used network. Normal brief occurrences are expected, but frequent deregistrations may indicate connectivity issues.\ > \ > For more information read \[How to use Network Logs]\(). ```json {"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/network-logs/{sim_id}":{"get":{"tags":["Network Logs"],"summary":"Retrieve Network Logs of a SIM","description":"Retrieves the Network Logs for a specific SIM. Network Logs capture the complete connection lifecycle and help diagnose connectivity issues.\n\nThe response contains various different Log Types (distinguished by the `log_type` field). Each type holds different information and showcases the type of event that has occurred:\n- `network-authentication`: Initial connection attempt when device scans for and attempts to connect to a specific network. Records whether the SIM is allowed to connect based on Network List/Whitelist and IMEI settings.\n - Authentication `log_types` also include SIM and network information. A successful authentication will have `status`/`reason` properties as `null` in the response.\n\n- `network-registration`: Occurs after authentication when Onomondo and the given network sync to provide cellular technology connections. Has two phases:\n - Device registration to specific technology (`is_data_attach: false`), means that the device will be able to send and receive SMSs\n - Data session creation enabling data transmission (`is_data_attach: true`), means that the device will be able to send and receieve IP traffic\n\n- `network-deregistration`: Logs disconnection between Onomondo and the used network. Normal brief occurrences are expected, but frequent deregistrations may indicate connectivity issues.\n\nFor more information read [How to use Network Logs](https://help.onomondo.com/en/articles/220554-how-to-use-network-logs).","parameters":[{"name":"sim_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"timestamp","in":"query","required":true,"description":"ISO 8601 timestamp in UTC format that sets the cursor for where records should start","schema":{"type":"string","format":"date-time","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z$"}},{"name":"order","in":"query","description":"Temporal sort order for the results","schema":{"type":"string","enum":["ASC","DESC"],"default":"DESC"}},{"name":"limit","in":"query","description":"Maximum number of records to return","schema":{"type":"integer","minimum":1,"maximum":1000,"default":1000}},{"name":"offset","in":"query","description":"Number of records to skip (for pagination)","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}} ``` # SMS ## Retrieve SMS usage for all SIMs > Retrieves all usage information for SMS messages sent to and from devices across all SIMs. The response includes delivery status, attempt counts, and other usage metrics to help track SMS communication with your devices.\ > {% hint style="info" %} The response does not contain the actual payload/content of the SMSs, in order to get this information you will have to set up a Webhook endpoint or use the web app, see \this](https://help.onomondo.com/en/articles/161795-where-can-i-see-sms-sent-by-my-device">this) article\ for more information. {% endhint %} ```json {"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/sms/usage/":{"get":{"summary":"Retrieve SMS usage for all SIMs","description":"Retrieves all usage information for SMS messages sent to and from devices across all SIMs. The response includes delivery status, attempt counts, and other usage metrics to help track SMS communication with your devices.\n{% hint style=\"info\" %} The response does not contain the actual payload/content of the SMSs, in order to get this information you will have to set up a Webhook endpoint or use the web app, see this article for more information. {% endhint %}","parameters":[{"name":"limit","in":"query","description":"Maximum number of SMS records to return","schema":{"type":"integer","minimum":1,"maximum":1000,"default":1000}},{"name":"offset","in":"query","description":"Number of records to skip (for pagination)","schema":{"type":"integer","minimum":0,"default":0}},{"name":"timestamp","in":"query","description":"Filter SMS records by ISO date (YYYY-MM-DD format)","schema":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"order","in":"query","description":"Temporal sort order for the results","schema":{"type":"string","enum":["ASC","DESC"],"default":"DESC"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique SMS record identifier"},"sim_id":{"type":"string","description":"SIM ID associated with the SMS"},"message":{"type":"string","description":"SMS content"},"direction":{"type":"string","enum":["inbound","outbound"],"description":"Whether SMS was sent to or from device"},"status":{"type":"string","enum":["delivered","failed","pending"],"description":"Delivery status"},"attempts":{"type":"integer","description":"Number of delivery attempts"},"timestamp":{"type":"string","format":"date-time","description":"When the SMS was processed"}}}},"pagination":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"}}}}}}}}}}}}} ``` ## Retrieve SMS usage for a specific SIM > Retrieve all usage information for SMS messages sent to and from a specific device using its SIM ID. The response includes delivery status, attempt counts, and other usage metrics to help track SMS communication with your devices.\ > {% hint style="info" %} The response does not contain the actual payload/content of the SMSs, in order to get this information you will have to set up a Webhook endpoint or use the web app, see \this](https://help.onomondo.com/en/articles/161795-where-can-i-see-sms-sent-by-my-device">this) article\ for more information. {% endhint %} ```json {"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/sms/usage/{sim_id}":{"get":{"summary":"Retrieve SMS usage for a specific SIM","description":"Retrieve all usage information for SMS messages sent to and from a specific device using its SIM ID. The response includes delivery status, attempt counts, and other usage metrics to help track SMS communication with your devices.\n{% hint style=\"info\" %} The response does not contain the actual payload/content of the SMSs, in order to get this information you will have to set up a Webhook endpoint or use the web app, see this article for more information. {% endhint %}","parameters":[{"name":"sim_id","in":"path","required":true,"description":"SIM ID","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum number of SMS records to return","schema":{"type":"integer","minimum":1,"maximum":1000,"default":1000}},{"name":"offset","in":"query","description":"Number of records to skip (for pagination)","schema":{"type":"integer","minimum":0,"default":0}},{"name":"timestamp","in":"query","description":"Filter SMS records by ISO date (YYYY-MM-DD format)","schema":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"order","in":"query","description":"Temporal sort order for the results","schema":{"type":"string","enum":["ASC","DESC"],"default":"DESC"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"time":{"type":"string","format":"date-time","description":"Timestamp when the SMS was processed"},"sim_id":{"type":"string","description":"SIM ID associated with the SMS"},"iccid":{"type":"string","description":"Integrated Circuit Card Identifier"},"direction":{"type":"string","enum":["incoming","outgoing"],"description":"Direction of the SMS"},"status":{"type":"string","enum":["success","failed","pending"],"description":"SMS delivery status"},"retries_left":{"type":"integer","description":"Number of retry attempts remaining"},"id":{"type":"string","format":"uuid","description":"Unique SMS record identifier"},"session_id":{"type":"string","format":"uuid","description":"Session identifier for the SMS transaction"},"network":{"type":"object","description":"Network information","properties":{"mcc":{"type":"string","description":"Mobile Country Code"},"mnc":{"type":"string","description":"Mobile Network Code"}},"required":["mcc","mnc"]}},"required":["time","sim_id","iccid","direction","status","retries_left","id","session_id","network"]}},"pagination":{"type":"object","properties":{"count":{"type":"integer","description":"Number of records in current response"},"limit":{"type":"integer","description":"Maximum number of records requested"},"offset":{"type":"integer","description":"Number of records skipped"},"total":{"type":"integer","description":"Total number of records available"}},"required":["count","limit","offset","total"]}},"required":["data","pagination"]}}}}}}}}} ``` ## Send SMS to a device > Send SMS messages to a device using its SIM ID. Supports both text and binary SMS with different encoding options.\ > \ > \*\*SMS Types:\*\*\ > \- \*\*Text SMS\*\*: Standard text messages (default)\ > \- \*\*Binary SMS\*\*: Raw binary data with hex or base64 encoding\ > \ > For more information on the difference read \[How to send SMS using the Onomondo web app]\( > {% hint style="info" %} The response does not contain the actual payload/content of the SMSs, in order to get this information you will have to set up a Webhook endpoint or use the web app, see \this](https://help.onomondo.com/en/articles/161795-where-can-i-see-sms-sent-by-my-device">this) article\ for more information. {% endhint %} ```json {"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/sms/{sim_id}":{"post":{"summary":"Send SMS to a device","description":"Send SMS messages to a device using its SIM ID. Supports both text and binary SMS with different encoding options.\n\n**SMS Types:**\n- **Text SMS**: Standard text messages (default)\n- **Binary SMS**: Raw binary data with hex or base64 encoding\n\nFor more information on the difference read [How to send SMS using the Onomondo web app](https://help.onomondo.com/en/articles/143654-how-do-i-send-sms-to-a-device-using-the-onomondo-platform).\n{% hint style=\"info\" %} The response does not contain the actual payload/content of the SMSs, in order to get this information you will have to set up a Webhook endpoint or use the web app, see this article for more information. {% endhint %}","parameters":[{"name":"sim_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["from","text"],"properties":{"from":{"oneOf":[{"type":"integer","minimum":0,"maximum":999999999999999,"description":"Numeric sender ID (up to 15 digits)"},{"type":"string","pattern":"^[a-zA-Z0-9]{1,10}$","description":"Alphanumeric sender ID (1-10 characters, letters and numbers only)"}],"description":"Sender identification - either numeric (up to 15 digits) or alphanumeric (up to 10 chars)"},"type":{"type":"string","enum":["text","binary"],"default":"text","description":"Type of SMS message"},"encoding":{"type":"string","enum":["hex","base64"],"description":"Encoding format for binary SMS (required when type is 'binary')"},"text":{"type":"string","description":"Message content. For text SMS, this is the actual message. For binary SMS, this is the encoded data (hex or base64)."}},"allOf":[{"if":{"properties":{"type":{"const":"binary"}}},"then":{"required":["encoding"],"properties":{"encoding":{"type":"string","enum":["hex","base64"]}}}}]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}}}}} ``` # Messages ## Send text to a device > Send text or raw data over UDP or TCP to a device with a specific SIM ID.\ > \ > If the protocol is UDP, the packet will be sent to the receiving port. If the protocol is TCP, a connection will be established with the device on that port and the data will be sent. If the device does not accept incoming connections on that port, the data will be discarded.\ > \ > Either \`text\` or \`data\` must be provided, but not both. Use \`text\` for string data and \`data\` for base64-encoded binary data that will be decoded and sent as raw bytes. ```json {"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/messages/{sim_id}":{"post":{"summary":"Send text to a device","description":"Send text or raw data over UDP or TCP to a device with a specific SIM ID.\n\nIf the protocol is UDP, the packet will be sent to the receiving port. If the protocol is TCP, a connection will be established with the device on that port and the data will be sent. If the device does not accept incoming connections on that port, the data will be discarded.\n\nEither `text` or `data` must be provided, but not both. Use `text` for string data and `data` for base64-encoded binary data that will be decoded and sent as raw bytes.","parameters":[{"name":"sim_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["protocol","port"],"properties":{"protocol":{"type":"string","enum":["udp","tcp"],"description":"The protocol to use for sending the message"},"port":{"type":"integer","minimum":1,"maximum":65535,"description":"The target port number"},"text":{"type":"string","description":"String data to send (mutually exclusive with data)"},"data":{"type":"string","format":"byte","description":"Base64-encoded binary data to send (mutually exclusive with text)"}},"oneOf":[{"required":["text"],"not":{"required":["data"]}},{"required":["data"],"not":{"required":["text"]}}]}}}},"responses":{"200":{"description":"Message sent successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}}}}}},"400":{"description":"Bad request, invalid parameters or device offline","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}}} ``` # Error Logs ## Retrieve Error Logs > Returns the latest errors that have occurred in interactions pertaining to Connectors, Webhooks, and Messages (\`message-to-devices\`). Use the \`types\[]\` parameter to specify which types of errors to include in the response. Multiple types can be specified to get errors from different sources.\ > {% hint style="info" %} Error Logs are stored with a retention limit per error type, meaning if a lot of errors are occurring you will only receive the latest ones. {% endhint %} ```json {"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/error-logs":{"get":{"summary":"Retrieve Error Logs","description":"Returns the latest errors that have occurred in interactions pertaining to Connectors, Webhooks, and Messages (`message-to-devices`). Use the `types[]` parameter to specify which types of errors to include in the response. Multiple types can be specified to get errors from different sources.\n{% hint style=\"info\" %} Error Logs are stored with a retention limit per error type, meaning if a lot of errors are occurring you will only receive the latest ones. {% endhint %}","parameters":[{"name":"types","in":"query","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","enum":["connectors","webhooks","messages-to-devices"]}},"description":"Filter error logs by type. Can specify multiple types using array syntax.\n**Available types:**\n- `connectors`: Errors related to Connectors\n- `webhooks`: Errors related to Webhooks\n- `messages-to-devices`: Errors related to Messages"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}} ``` # Webhooks ## Retrieve information about all Webhooks > Returns detailed information for all registered Webhooks.\ > {% hint style="info" %} Minimum package requirement: \Pro\ {% endhint %} ```json {"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/webhooks":{"get":{"summary":"Retrieve information about all Webhooks","description":"Returns detailed information for all registered Webhooks.\n{% hint style=\"info\" %} Minimum package requirement: Pro {% endhint %}","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}} ``` ## Retrieve information about a specific Webhook > Returns detailed information for a specific Webhook.\ > {% hint style="info" %} Minimum package requirement: \Pro\ {% endhint %} ```json {"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/webhooks/{webhook_id}":{"get":{"summary":"Retrieve information about a specific Webhook","description":"Returns detailed information for a specific Webhook.\n{% hint style=\"info\" %} Minimum package requirement: Pro {% endhint %}","parameters":[{"name":"webhook_id","in":"path","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}} ``` ## Add Webhook > Create a Webhook to receive events from your organization. Webhooks can be filtered as to what they receive by applying filtering using Tags and/or excluding event types.\ > {% hint style="info" %} Minimum package requirement: \Pro\ {% endhint %} ```json {"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/webhooks":{"post":{"summary":"Add Webhook","description":"Create a Webhook to receive events from your organization. Webhooks can be filtered as to what they receive by applying filtering using Tags and/or excluding event types.\n{% hint style=\"info\" %} Minimum package requirement: Pro {% endhint %}","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","active","label","tags","exclude_types"],"properties":{"url":{"type":"string","format":"uri","pattern":"^https://","description":"The HTTPS endpoint that will receive the events."},"active":{"type":"boolean","description":"When true, the endpoint will start receiving events."},"label":{"type":"string","nullable":true,"description":"Plain text name for the webhook. Must be unique if provided."},"tags":{"type":"array","items":{"type":"string"},"description":"Array of Tag IDs to filter events. Only SIMs with these Tags will trigger events. Empty array includes all Tags."},"exclude_types":{"type":"array","items":{"type":"string","enum":["usage","usage-sms","network-registration","network-deregistration","network-authentication","sms","location","cost-alert"]},"description":"Array of event types to exclude from this webhook. Empty array will send all event types."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}} ``` ## Update Webhook > Modify a specific Webhook.\ > {% hint style="info" %} Minimum package requirement: \Pro\ {% endhint %}\ > {% hint style="warning" %} When updating arrays, the whole array will be replaced. To keep existing \Tags\ or \exclude\_types\ you will need to include all properties in the array, not just the additional ones. {% endhint %} ```json {"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/webhooks/{webhook_id}":{"patch":{"summary":"Update Webhook","description":"Modify a specific Webhook.\n{% hint style=\"info\" %} Minimum package requirement: Pro {% endhint %}\n{% hint style=\"warning\" %} When updating arrays, the whole array will be replaced. To keep existing Tags or exclude_types you will need to include all properties in the array, not just the additional ones. {% endhint %}","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","active","label","tags","exclude_types"],"properties":{"url":{"type":"string","format":"uri","pattern":"^https://","description":"The HTTPS endpoint that will receive the events."},"active":{"type":"boolean","description":"When true, the endpoint will start receiving events."},"label":{"type":"string","nullable":true,"description":"Plain text name for the webhook. Must be unique if provided."},"tags":{"type":"array","items":{"type":"string"},"description":"Array of Tag IDs to filter events. Only SIMs with these Tags will trigger events. Empty array includes all Tags."},"exclude_types":{"type":"array","items":{"type":"string","enum":["usage","usage-sms","network-registration","network-deregistration","network-authentication","sms","location","cost-alert"]},"description":"Array of event types to exclude from this webhook. Empty array will send all event types."}}}}}},"parameters":[{"name":"webhook_id","in":"path","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}} ``` ## Remove Webhook > Removes a specific Webhook. If you think you will want to use it again you can always set the \`"active": false\` with the PATCH call instead. This will keep the Webhook but prevent it from sending any events to the endpoint.\ > {% hint style="info" %} Minimum package requirement: \Pro\ {% endhint %} ```json {"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/webhooks/{webhook_id}":{"delete":{"summary":"Remove Webhook","description":"Removes a specific Webhook. If you think you will want to use it again you can always set the `\"active\": false` with the PATCH call instead. This will keep the Webhook but prevent it from sending any events to the endpoint.\n{% hint style=\"info\" %} Minimum package requirement: Pro {% endhint %}","parameters":[{"name":"webhook_id","in":"path","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}} ``` # Webhooks Reference Lets you subscribe to certain events regarding SIMs and process the event notifications through an integration or app. Webhooks are a way of sending you events specific to your SIMs when something happens. We will deliver the events as HTTP POST calls. This enables you to act on things happening with you IoT fleet in near to real-time, such as knowing when/if a SIM changes its physical location, SIMs registering to networks, ingest all of your fleet's usage, or get notified when usage threshold (alerts) are reached. The current Webhooks that Onomondo supports can be seen in the following table.
Name (in the web app)Type indicated in POST callDescription
Data UsageusageIncludes information about the data usage of per SIM, i.e. how many bytes the SIM has sent over a specific network.
SMS Usageusage-smsUsage data around in- and outgoing SMSs.
Usage Alertsusage-alertOccurs when a SIM has reached a certain amount of data usage, e.g. the alert threshold (soft) or the usage limit (hard).
Cost Alertcost-alertOccurs when a SIM has reached a certain amount of cost, which is set by cost alert threshold.
Network Registrationnetwork-registrationInformation around when a device attaches to a network.
Network Deregistrationnetwork-deregistrationInformation around when a device detach from a network.
Network Authenticationnetwork-authenticationContains information around when a device has attempted to authenticate for a specific network, occurs both when a device successfully authenticates as well as when it is denied.
SMSsmsContains the text/payload of outgoing SMSs from a device perspective.
Location UpdatelocationInformation around the physical location of the cell that the device has attached to, wherein the cell is a subarea of the total area that a cell tower/base station covers.
## Back off timers and circuit breakers Your endpoint will need to respond with a status code of `200` in order for the request to be considered successfully delivered. If your endpoint does not respond with a status code `200` or doesn't reply within one second then the delivery will be considered unsuccessful. We will try to deliver an event 10 times. If the event is still not delivered successfully on the 11th attempt then the event is discarded. Any issues with delivering to your will be added to the [Error Logs](https://app.onomondo.com/error-log). The back off times are: ``` 1. attempt: Instant 2. attempt: 10 seconds 3. attempt: 30 seconds 4. attempt: 1 minute 10 seconds 5. attempt: 2 minutes 30 seconds 6. attempt: 5 minutes 10 seconds 7. attempt: 10 minutes 30 seconds 8. attempt: 21 minutes 10 seconds 9. attempt: 42 minutes 30 seconds 10. attempt: 1 hour 15 minutes 10 seconds 11. attempt: 2 hours 50 minutes 30 seconds ``` Moreover, then Onomondo uses a [circuit-breaker pattern](https://martinfowler.com/bliki/CircuitBreaker.html) with an error rate at 50% over a 10 second sliding window as well as a probe configured at every 10 seconds for any endpoint in the half-open state. The back off times still apply. This means that if you have an endpoint that is failing over a longer period of time then it is not guaranteed that 11 delivery attempts are made. ## Webhook Signature Verification All outgoing requests from Onomondo will include a cryptographic signature, HMAC, that allows you to verify the authenticity and integrity of the payload. The signature is provided in the `X-Onomondo-Signature-256` header and follows this format: ``` sha256=20d1121489c9eaa2454bd203cad63c90b8309042c2cab75b31812b5feb2c29f6 ``` To verify the signature on your end compute the HMAC-SHA256 of the request body using your secret, which can be found in Edit page for the specific Webhook in the web app. Then compare it with the hash provided in the header (after the `sha256=` prefix). If they match, you can be confident that the request originated from Onomondo and hasn't been tampered with. ## Usage related Webhooks ### Data usage Data usage, which is default webhook type (`"type": "usage"`), occurs per SIM approximately every 15 minutes and after a network deregistration. This provides the same information as using the `GET /usage` API call. Example: ```json { "type": "usage", "id": "d08592fd-823e-3d4d-af99-1509a7220fb4", "session_id": "0afcd0cd-3119-3b6b-a7c2-dc6a9fe1f414", "time": "2020-04-23T11:39:01.000Z", "sim_id": "000002273", "iccid": "89457387300000022734", "ipv4": "100.66.133.212", "imei": "3554014423671441" "bytes": 9484, "network": { "name": "TDC A/S", "country": "Denmark", "country_code": "DK", "mcc": "238", "mnc": "01" }, "sim_label": "iphone", } ``` ### SMS usage SMS usage events occur when ever someone: * Sends an SMS to a device (`"direction": "outgoing"`). * Either by using the API POST SMS to a device or from the SIM tab on the platform. * An SMS is sent from a device (`"direction": "incoming"`). * The information in the text from the device needs to be captured from the webhook event or by being in the specific SIMs detail page at the time (and viewed on the SMS Tab). This is the same as the API `GET /usage/sms` request or on the platform when looking at the SMS tab at a specific SIM. {% hint style="info" %} An SMS is received by the device when `"status": "success"` with regards to `GET /usage/sms`. If the SMS was not successfully delivered an error type will be displayed instead, such as `"status": "absentSubscriber"`. This could for instance occur in the scenario where a device is or goes goes offline before the SMS is delivered. {% endhint %} Example: ```json { "type": "usage-sms", "sim_label": "iphone", "id": "85eec601-45cb-471b-87ed-876bfa7b7833", "session_id": "310ca71b-7894-326b-bdcd-ad80e067a32b", "time": "2020-11-30T10:39:04.447Z", "sim_id": "000002273", "iccid": "89457387300000022734", "direction": "outgoing", "status": "success", "retries_left": 9, "network": { "name": "TDC A/S", "country": "Denmark", "country_code": "DK", "mcc": "238", "mnc": "01" } } ``` ### Usage Alerts Usage alerts, which is default Webhook type (`"type": "usage-alert"`), is sent based on the data limits set on a specific SIM. There are two types of events. #### **Alert threshold** When the usage of a SIM in a period reaches the SIM's specified usage threshold an event is sent. Included in the event object is the reason (`"reason": "alert-threshold"`). When a device reaches the threshold it will *not* be cut off from using more data but instead serves as a way for users to be warned about data consumption. Example: ```json { "type": "usage-alert", "reason": "alert-threshold", "time": "2021-12-01T10:08:36.530Z", "sim_id": "000000001", "iccid": "89457387300000000105", "ipv4": "100.96.0.1", "data_limit": { "used": 1101976, "total": 2000000, "type": "monthly", "period": "202112", "alert_threshold": 1000000, "resets_at": "2022-01-01T00:00:00.000Z" }, "sim_label": "foobar" } ``` #### **Data limit reached** When the usage of a SIM in a period reaches the SIM's specified data limit an event is sent. Until the limit period is reset the device will be able to connect to a network but not send any more data. Included in the event object is the reason (`"reason": "blocked"`). Note that the `used` field might be a little above or below the actual data usage which is due to differing sampling rates. Example: ```json { "type": "usage-alert", "reason": "blocked", "time": "2021-12-01T10:09:41.571Z", "sim_id": "000000001", "iccid": "89457387300000000105", "ipv4": "100.96.0.1", "data_limit": { "used": 1934264, "total": 2000000, "type": "monthly", "period": "202112", "alert_threshold": 1000000, "resets_at": "2022-01-01T00:00:00.000Z" }, "sim_label": "foobar" } ``` ### Cost Alert Cost alerts, which is default type (`“type”:”cost-alert”`), is sent based on the cost alert threshold set on an individual SIM. When the cost related to a SIM in a specific period reaches the specified cost alert threshold an event is sent, it will not be cut off from using more data, sending SMSs, attaching to networks, etc., but instead it serves as a warning. Example: ```json { "sim_id": "000002273", "period": "monthly", "threshold": 10, "total_cost": 10, "type": "cost-alert" } ``` ## Network Log related Webhooks All registration, deregistration, and authentication logs for all SIMs as per the API call to retreive Network Logs of a SIM. ### Network Registration A Network Registration occurs when a SIM attaches to or deattaches from our network through the local base station. Once the registration has occurred the device will be able to send/receive SMSs (with a GSM connection) and send/receive data (through a 2G/3G/4G data connection). Example a GSM Network Registration, i.e. a registration wherein the device can only receive and send SMSs: ```json { "id": "c73606fe-ebae-4f20-9d79-bd057f94f1dd", "time": "2020-04-23T11:38:39.688Z", "type": "network-registration", "sim_id": "000002273", "iccid": "89457387300000022734", "network_type": "GSM", "imei": null, "network": { "name": "Hi3G", "country": "Denmark", "country_code": "DK", "mcc": "238", "mnc": "06" }, "sim_label": "iphone" } ``` Example of a 3G Network Registration: ```json { "type": "network-registration" "id": "913ed25e-310f-3194-9102-fef88fa9478d", "session_id": "0afcd0cd-3119-3b6b-a7c2-dc6a9fe1f414", "time": "2024-04-04T08:56:48.462Z", "sim_id": "000002273", "iccid": "89457387300000022734", "imei": "3554014423671441", "network_type": "3G", "network": { "name": "Hi3G", "country": "Denmark", "country_code": "DK", "mcc": "238", "mnc": "06" }, "ipv4": "100.66.133.212", "sim_label": "iphone", } ``` ### Network Deregistration See the description of [Network Registration](https://fugolungo.gitbook.io/fugolungo-docs/Sw9EnGkWPJZdpbTYFR6Q/reference/webhooks#network-registration). Example: ```json { "type": "network-deregistration" "id": "055d86a5-798b-3129-bd52-7eb931ca1d0a", "session_id": "965e15f7-7e3d-3af0-8c70-d165e4fed793", "time": "2024-04-04T08:56:50.963Z", "sim_id": "000002273", "iccid": "89457387300000022734", "imei": "3554014423671441", "network_type": "3G", "network": { "name": "Telia", "country": "Denmark", "country_code": "DK", "mcc": "238", "mnc": "20" }, "ipv4": "100.66.133.212", "session_usage": { "upload": 2016, "download": 3298 }, "sim_label": "iphone", } ``` ### Network Authentication Before the device can attach to a base station, it needs to confirm with us, if it is allowed. When the device asks permission to attach to the base station, a network-authentication event occurs. When status and reason properties are `null`, then the SIM was authenticated and it is allowed to attach to our network. If an authentication is blocked, the information will be provided in these properties. Example of a successful authentication: ```json { "type": "network-authentication", "id": "b0f57875-d79d-4493-8b02-c82e85f862e6", "time": "2020-11-30T10:21:53.623Z", "sim_id": "000002273", "sim_label": "iphone", "iccid": "89457387300000022734", "imei": null, "status": null, "reason": null, "network_type": "2G/3G", "network": { "name": "TDC A/S", "country": "Denmark", "country_code": "DK", "mcc": "238", "mnc": "01" } } ``` Example of an authentication attempt that was denied: ```json { "type": "network-authentication", "id": "bd98099b-323d-46d8-b8a7-2376475ec9f9", "time": "2020-11-30T12:24:56.878Z", "sim_id": "000002273", "sim_label": "iphone", "iccid": "89457387300000022734", "imei": null, "status": "operatorDeterminedBarring", "reason": "network_whitelist", "network_type": "GSM", "network": { "name": "Hi3G", "country": "Denmark", "country_code": "DK", "mcc": "238", "mnc": "06" } } ``` ## SMS All SMSs from a device come through the Webhook as an event. The typical body of the `POST` request includes: * `"time"` sent. * ID of the SIM (both `"sim_id"` and `"iccid"`). * `"sim_label"`. * A destination the device has sent it `"to"`. * And the actual SMS (`"text"`) as well as the raw SMS without any decoding but encoded using Base64 (`"text_base64"`). Example: ```json { "type": "sms", "time": "2024-04-09T10:45:37.409Z", "sim_id": "000002273", "iccid": "89457387300000022734", "sim_label": "iphone", "to": 453388326, "text": "Hello World!", "text_base64": "SGVsbG8gV29ybGQh" } ``` ## Location Update Location events occur at the beginning and end of sessions, as well as if the location changes during a session. This is an approximate location, when possible it will also include the `"accuracy"` in meters radius. Some of the same information as using the GET ["Retrieve specific SIM information" API request](https://docs.onomondo.com/#aa33c442-cf55-4c83-960f-2fcb14b9849d) when a SIM is online. Not all sessions can we determine location. In these situations `accuracy`, `lat`, and `lng` values will be `null`. Example: ```json { "type": "location", "imei": "3518650966887220", "iccid": "89457387300002010000", "sim_id": "000201000", "location": { "cell_id": 31508, "location_area_code": 183, "accuracy": 2873, // in meters radius "lat": "56.702866", "lng": "14.6013649" }, "network": { "name": "TDC A/S", "country": "Denmark", "country_code": "DK", "mcc": "238", "mnc": "01" }, "network_type": "3G", "sim_label": "Motorola3_ValidSIM", "time": "2020-07-02T12:46:42.105Z", "ipv4": "100.96.0.117", "session_id": "965e15f7-7e3d-3af0-8c70-d165e4fed793" } ``` # IP Ranges Onomondo will send Webhooks and device traffic through a limited set of public IPs. For firewall configuration(s) we document the used subnets. All requests from Onomondo SIMs will come from the subnets listed below, likewise Webhooks will come from the subnets listed under "Webhook Subnets". If you use a firewall, you will need to allow these: **SIM Subnets** * `158.177.93.16/28` * `185.228.69.0/24` * `185.228.70.0/24` * `3.69.121.60/32` * `3.69.192.150/32` * `3.64.84.111/32` * `3.73.220.0/32` * `3.69.113.129/32` * `18.194.252.193/32` **Webhook Subnets** * `3.65.45.209/32` * `35.158.167.193/32` * `52.58.186.11/32` # OpenVPN You can connect to your devices from your computer or server using OpenVPN. When connecting to Onomondo through OpenVPN the client's IP will be that of the user, this IP and whether a given user has the correct access can be seen in the Users page. {% hint style="info" %} Your user needs to have VPN access which can be granted by owners or admins. {% endhint %} To connect you will need: 1. A user with VPN access 2. Having a password configured for said user, if you do not have a password configured you will not be able to connect Having these things in place you will be able connect using an OpenVPN client of your choice with the following configuration file and authenticating using your email and password. {% file src="/files/Div1ieui9AkIxlgosjFv" %} New to OpenVPN? Or simply want further instructions then see the following article. {% embed url="" %} ## Access control Restrictions are applied OpenVPN clients based on the user type and Tags. Owners and admins will have unrestricted access to all SIMs in your organization, whereas members' access will be determined by the Tags assigned to said member—both read and write access grants a member access to a given SIM, direction of traffic is not accounted for. For a quick reference as to how access control works regarding the OpenVPN realm then see the following table: | User type | Access to | | --------- | ------------------ | | Owner | Every SIM | | Admin | Every SIM | | Member | Determined by Tags | # Traffic Monitor CLI Capture all traffic between a device and the network, seen from the network's perspective. Output to a pcap file, or pipe to another tool that can read pcap files (like Wireshark). `onomondo-live` is the Traffic Monitor CLI tool that enables you to capture all traffic between a device and the network, seen from the network's perspective. [The source code can be found here](https://github.com/onomondo/onomondo-live). You can output the captured traffic to PCAP file or pipe it to another tool that can read PCAP files (like Wireshark). ## Installation You need to have NodeJS and `npm` installed on your system. Then run this command: ``` $ npm install onomondo-live --global ``` ## Usage You need to use the SIM ID of one or more of your SIMs, and an Onomondo API key. If you want to listen to multiple sims you can supply multiple `--sim` parameters, e.g. like this: `--sim=111111111 --sim=222222222`. **Write to file** ``` $ onomondo-live --key=onok_a1b2c3.f00ba5 --sim=012345678 --filename=output.pcap ``` **Write to standard output** ``` $ onomondo-live --key=onok_a1b2c3.f00ba5 --sim=012345678 - ``` **Pipe to Wireshark example** ``` $ onomondo-live --key=onok_a1b2c3.f00ba5 --sim=012345678 - | wireshark -k -i - ```