NAV Navbar
shell python
  • Introduction
  • Authentication
  • SIMs
  • Network Whitelists
  • Connectors
  • Usage
  • Webhooks
  • Introduction

    Welcome to the Onomondo API.

    You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

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

    The API is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.

    The webhooks is our way of sending you information specific to your SIMs. The webhook endpoints has 15 seconds to accept the event. If a success HTTP status code has not been returned within these 15 seconds, the event will be discarded.

    Authentication

    To authorize, use this code:

    import requests
    
    url = "https://api.onomondo.com"
    
    headers = { 'Authorization': "YOUR-API-KEY" }
    
    response = requests.request("GET", url, headers=headers)
    
    print(response.text)
    
    curl --request GET \
      --url https://api.onomondo.com \
      --header 'Authorization: YOUR-API-KEY'
    

    Make sure to replace YOUR-API-KEY with your API key.

    Onomondo uses API keys to allow access to the API.

    Onomondo expects for the API key to be included in all API requests to the server in a header that looks like the following:

    Authorization: YOUR-API-KEY

    SIMs

    Get All SIMs

    import requests
    
    url = "https://api.onomondo.com/sims"
    
    headers = { 'Authorization': "YOUR-API-KEY" }
    
    response = requests.request("GET", url, headers=headers)
    
    print(response.text)
    
    curl --request GET \
      --url https://api.onomondo.com/sims \
      --header 'Authorization: YOUR-API-KEY'
    

    The above command returns JSON structured like this:

    [
        {
            "id": "123456789",
            "alias": "my_first_sim",
            "network_whitelist": "",
            "imei_lock": "",
            "monthly_limit": "",
            "connector": "",
            "activated": true,
            "ip": "1.2.3.4",
            "usage": 1234
        },
        {
            "id": "123456790",
            "alias": "my_second_sim",
            "network_whitelist": "my_allowed_networks",
            "imei_lock": 1234567890123456,
            "monthly_limit": 76546048,
            "connector": "my_tls_connector",
            "activated": true,
            "ip": "",
            "usage": 0
        }
    ]
    

    This endpoint retrieves all SIMs.

    HTTP Request

    GET https://api.onomondo.com/sims

    Get a Specific SIM

    import requests
    
    url = "https://api.onomondo.com/sims/123456789"
    
    headers = { 'Authorization': "YOUR-API-KEY" }
    
    response = requests.request("GET", url, headers=headers)
    
    print(response.text)
    
    curl --request GET \
      --url https://api.onomondo.com/sims/123456789 \
      --header 'Authorization: YOUR-API-KEY'
    

    The above command returns JSON structured like this:

    {
        "id": "123456789",
        "alias": "my_first_sim",
        "network_whitelist": "",
        "imei_lock": "",
        "monthly_limit": "",
        "connector": "",
        "activated": true,
        "ip": "1.2.3.4",
        "usage": 4321,
        "online": true
    }
    

    This endpoint retrieves a specific SIM.

    HTTP Request

    GET https://api.onomondo.com/sims/<ID>

    URL Parameters

    Parameter Description
    ID The ID of the SIM to retrieve

    Update a Specific SIM

    import requests
    
    url = "https://api.onomondo.com/sims/123456789"
    
    payload = '{ "alias": "new_alias", "activated": false }'
    headers = {
        'Authorization': "YOUR-API-KEY",
        'Content-Type': "application/json",
        }
    
    response = requests.request("PATCH", url, data=payload, headers=headers)
    
    print(response.text)
    
    curl --request PATCH \
      --url https://api.onomondo.com/sims/123456789 \
      --header 'Authorization: YOUR-API-KEY' \
      --header 'Content-Type: application/json' \
      --data '{ "alias": "new_alias", "activated": false }'
    

    The above command returns JSON structured like this:

    {
        "message": "OK"
    }
    

    This endpoint updates a specific SIM.

    HTTP Request

    PATCH https://api.onomondo.com/sims/<ID>

    URL Parameters

    Parameter Description
    ID The ID of the SIM to update

    Query Parameters

    Parameter Description
    alias Alias of the SIM
    network_whitelist Name of the Network Whitelist attached, blank if no Network Whitelist should be attached
    imei_lock IMEI of device the SIM should be locked too (if presented in network signaling)
    monthly_limit Monthly limit of bytes allowed to be used by the SIM
    connector Name of Connector attached, blank if no Connector should be attached
    activated Boolean to activate and deactivate the SIM

    Delete a Specific SIM

    import requests
    
    url = "https://api.onomondo.com/sims/123456789"
    
    headers = { 'Authorization': "YOUR-API-KEY" }
    
    response = requests.request("DELETE", url, headers=headers)
    
    print(response.text)
    
    curl --request DELETE \
      --url https://api.onomondo.com/sims/123456789 \
      --header 'Authorization: YOUR-API-KEY'
    

    The above command returns JSON structured like this:

    {
        "message": "OK"
    }
    

    This endpoint deletes a specific SIM.

    HTTP Request

    DELETE https://api.onomondo.com/sims/<ID>

    URL Parameters

    Parameter Description
    ID The ID of the SIM to delete

    Network Whitelists

    ToDo

    Connectors

    Get All Connectors

    import requests
    
    url = "https://api.onomondo.com/connectors"
    
    headers = { 'Authorization': "YOUR-API-KEY" }
    
    response = requests.request("GET", url, headers=headers)
    
    print(response.text)
    
    curl --request GET \
      --url https://api.onomondo.com/connectors \
      --header 'Authorization: YOUR-API-KEY'
    

    The above command returns JSON structured like this:

    [
        {
            "name": "my_tls_connector",
            "type": "tls",
            "host": "87.65.43.21",
            "port": 443,
            "key": "-----BEGIN RSA PRIVATE KEY-----...-----END RSA PRIVATE KEY-----",
            "cert": "-----BEGIN RSA PRIVATE KEY-----...-----END RSA PRIVATE KEY-----",
            "ca": "-----BEGIN RSA PRIVATE KEY-----...-----END RSA PRIVATE KEY-----",
            "passthrough": [{ "protocol": "udp", "ip": "8.8.8.8", "port": 53 }, { "protocol": "tcp", "ip": "1.2.3.4", "port": 22 }],
            "mapped_to": [{ "id": "123456789", "alias": "my_first_sim"}, { "id": "987654321", "alias": ""}]
        },
        {
            "name": "my_ibm_watson_iot_connector",
            "type": "ibm_watson_iot",
            "config": {
                "org": "...",
                "type": "...-gateway",
                "id": "...",
                "domain": "internetofthings.ibmcloud.com",
                "auth-method": "token",
                "auth-token": "..."
            },
            "event": "status",
            "passthrough": "",
            "mapped_to": []
        },
        {
            "name": "my_microsoft_azure_iot_connector",
            "type": "microsoft_azure_iot",
            "connectionString": "HostName=Onomondo.azure-devices.net;DeviceId=MyTestDevice;SharedAccessKey=...",
            "passthrough": "",
            "mapped_to": []
        }
    ]
    

    This endpoint retrieves all Connectors.

    HTTP Request

    GET https://api.onomondo.com/connectors

    Get a Specific Connector

    import requests
    
    url = "https://api.onomondo.com/connectors/my_tls_connector"
    
    headers = { 'Authorization': "YOUR-API-KEY" }
    
    response = requests.request("GET", url, headers=headers)
    
    print(response.text)
    
    curl --request GET \
      --url https://api.onomondo.com/connectors/my_tls_connector \
      --header 'Authorization: YOUR-API-KEY'
    

    The above command returns JSON structured like this:

    {
        "name": "my_tls_connector",
        "type": "tls",
        "host": "87.65.43.21",
        "port": 443,
        "key": "-----BEGIN RSA PRIVATE KEY-----...-----END RSA PRIVATE KEY-----",
        "cert": "-----BEGIN RSA PRIVATE KEY-----...-----END RSA PRIVATE KEY-----",
        "ca": "-----BEGIN RSA PRIVATE KEY-----...-----END RSA PRIVATE KEY-----",
        "passthrough": [{ "protocol": "udp", "ip": "8.8.8.8", "port": 53 }, { "protocol": "tcp", "ip": "1.2.3.4", "port": 22 }],
        "mapped_to": [{ "id": "123456789", "alias": "my_first_sim"}, { "id": "987654321", "alias": ""}]
    }
    

    This endpoint retrieves a specific Connector.

    HTTP Request

    GET https://api.onomondo.com/connectors/<NAME>

    URL Parameters

    Parameter Description
    NAME The name of the Connector to retrieve

    Create a Specific Connector

    import requests
    
    url = "https://api.onomondo.com/connectors/my_tls_connector"
    
    payload = '{ "type": "tls", "host": "87.65.43.21", "port": 443, "key": "-----BEGIN RSA PRIVATE KEY-----...-----END RSA PRIVATE KEY-----", "cert": "-----BEGIN RSA PRIVATE KEY-----...-----END RSA PRIVATE KEY-----", "ca": "-----BEGIN RSA PRIVATE KEY-----...-----END RSA PRIVATE KEY-----", "passthrough": [{ "protocol": "udp", "ip": "8.8.8.8", "port": 53 }, { "protocol": "tcp", "ip": "1.2.3.4", "port": 22 }] }'
    headers = {
        'Authorization': "YOUR-API-KEY",
        'Content-Type': "application/json"
        }
    
    response = requests.request("POST", url, data=payload, headers=headers)
    
    print(response.text)
    
    curl --request POST \
      --url https://127.0.0.1:8443/connectors/my_tls_connector \
      --header 'Authorization: YOUR-API-KEY' \
      --header 'Content-Type: application/json' \
      --data '{ "type": "tls", "host": "87.65.43.21", "port": 443, "key": "-----BEGIN RSA PRIVATE KEY-----...-----END RSA PRIVATE KEY-----", "cert": "-----BEGIN RSA PRIVATE KEY-----...-----END RSA PRIVATE KEY-----", "ca": "-----BEGIN RSA PRIVATE KEY-----...-----END RSA PRIVATE KEY-----", "passthrough": [{ "protocol": "udp", "ip": "8.8.8.8", "port": 53 }, { "protocol": "tcp", "ip": "1.2.3.4", "port": 22 }] }'
    

    The above command returns JSON structured like this:

    {
        "message": "OK"
    }
    

    This endpoint creates a specific Connector.

    HTTP Request

    POST https://api.onomondo.com/connectors/<NAME>

    URL Parameters

    Parameter Description
    NAME The name of the Connector to create

    Query Parameters

    Parameters depends on Connector type. TODO - write explanation for each Connector type.

    Update a Specific Connector

    import requests
    
    url = "https://api.onomondo.com/connectors/my_tls_connector"
    
    payload = '{ "host": "12.34.56.78" }'
    headers = {
        'Authorization': "YOUR-API-KEY",
        'Content-Type': "application/json"
        }
    
    response = requests.request("PATCH", url, data=payload, headers=headers)
    
    print(response.text)
    
    curl --request PATCH \
      --url https://127.0.0.1:8443/connectors/my_tls_connector \
      --header 'Authorization: YOUR-API-KEY' \
      --header 'Content-Type: application/json' \
      --data '{ "host": "12.34.56.78" }'
    

    The above command returns JSON structured like this:

    {
        "message": "OK"
    }
    

    This endpoint updates a specific Connector.

    HTTP Request

    PATCH https://api.onomondo.com/connectors/<NAME>

    URL Parameters

    Parameter Description
    NAME The name of the Connector to update

    Query Parameters

    Parameters depends on Connector type. TODO - write explanation for each Connector type.

    Delete a Specific Connector

    import requests
    
    url = "https://api.onomondo.com/connectors/my_tls_connector"
    
    headers = { 'Authorization': "YOUR-API-KEY" }
    
    response = requests.request("DELETE", url, headers=headers)
    
    print(response.text)
    
    curl --request DELETE \
      --url https://api.onomondo.com/connectors/my_tls_connector \
      --header 'Authorization: YOUR-API-KEY'
    

    The above command returns JSON structured like this:

    {
        "message": "OK"
    }
    

    This endpoint deletes a specific Connector.

    HTTP Request

    DELETE https://api.onomondo.com/connectors/<NAME>

    URL Parameters

    Parameter Description
    NAME The name of the Connector to delete

    Usage

    Get All Usage

    import requests
    
    url = "https://api.onomondo.com/usage"
    
    headers = { 'Authorization': "YOUR-API-KEY" }
    
    response = requests.request("GET", url, headers=headers)
    
    print(response.text)
    
    curl --request GET \
      --url https://api.onomondo.com/usage \
      --header 'Authorization: YOUR-API-KEY'
    

    The above command returns JSON structured like this:

    [
        {
            "time_from": "2018-01-01 01:00:00",
            "time_to": "2018-01-01 02:00:00",
            "sim_id": "123456789",
            "country_code": "DK",
            "usage": 1234
        },
        {
            "time_from": "2018-01-01 01:00:00",
            "time_to": "2018-01-01 02:00:00",
            "sim_id": "987654321",
            "country_code": "DK",
            "usage": 4321
        }
    ]
    

    This endpoint retrieves all usage on all your SIMs.

    HTTP Request

    GET https://api.onomondo.com/usage

    Get usage on a Specific SIM

    import requests
    
    url = "https://api.onomondo.com/usage/123456789"
    
    headers = { 'Authorization': "YOUR-API-KEY" }
    
    response = requests.request("GET", url, headers=headers)
    
    print(response.text)
    
    curl --request GET \
      --url https://api.onomondo.com/usage/123456789 \
      --header 'Authorization: YOUR-API-KEY'
    

    The above command returns JSON structured like this:

    [
        {
            "time_from": "2018-01-01 01:00:00",
            "time_to": "2018-01-01 02:00:00",
            "sim_id": "123456789",
            "country_code": "DK",
            "usage": 1234
        },
        {
            "time_from": "2018-01-01 02:00:00",
            "time_to": "2018-01-01 03:00:00",
            "sim_id": "123456789",
            "country_code": "DK",
            "usage": 4321
        }
    ]
    

    This endpoint retrieves usage on a specific SIM.

    HTTP Request

    GET https://api.onomondo.com/usage/<ID>

    URL Parameters

    Parameter Description
    ID The ID of the SIM to retrieve usage on

    Webhooks

    Usage

    The usage webhook returns JSON structured like this:

    {
        "type": "usage",
        "time": "2018-01-01 01:23:45",
        "bill_id": "1234567890123",
        "sim_id": "123456789",
        "country_code": "dk",
        "ip": "1.2.3.4",
        "imei": 1234567890123456,
        "usage": 0
    }
    

    This webhook shows usage of your SIMs.

    Parameters

    Parameter Description
    type Type of webhook
    time Time of usage event
    bill_id Unique ID of usage event
    sim_id SIM ID
    country_code Country Code for usage event
    ip IPv4 of SIM
    imei IMEI of device, if presented in network signaling
    usage Usage in bytes

    Network Registration

    The usage webhook returns JSON structured like this:

    {
        "type": "network-registration",
        "time": "2018-01-01 01:23:45",
        "sim_id": "123456789",
        "country_code": "dk",
        "ip": "1.2.3.4",
        "imei": 1234567890123456
    }
    

    This webhook shows you when a SIM is registrered on a network.

    Parameters

    Parameter Description
    type Type of webhook
    time Time of usage event
    sim_id SIM ID
    country_code Country Code for usage event
    ip IPv4 of SIM
    imei IMEI of device, if presented in network signaling

    Network Deregistration

    The usage webhook returns JSON structured like this:

    {
        "type": "network-deregistration",
        "time": "2018-01-01 01:23:45",
        "sim_id": "123456789",
        "country_code": "dk",
        "ip": "1.2.3.4",
        "imei": 1234567890123456
    }
    

    This webhook shows you when a SIM is deregistered from a network.

    Parameters

    Parameter Description
    type Type of webhook
    time Time of usage event
    sim_id SIM ID
    country_code Country Code for usage event
    ip IPv4 of SIM
    imei IMEI of device, if presented in network signaling