NAV Navbar
shell python
  • Introduction
  • Authentication
  • SIMs
  • Connectors
  • Usages
  • 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",
            "connector": "",
            "activated": true,
            "usage": 1234
        },
        {
            "id": "123456790",
            "alias": "my_second_sim",
            "connector": "",
            "activated": true,
            "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/sim/123456789"
    
    headers = { 'Authorization': "YOUR-API-KEY" }
    
    response = requests.request("GET", url, headers=headers)
    
    print(response.text)
    
    curl --request GET \
      --url https://api.onomondo.com/sim/123456789 \
      --header 'Authorization: YOUR-API-KEY'
    

    The above command returns JSON structured like this:

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

    This endpoint retrieves a specific SIM.

    HTTP Request

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

    URL Parameters

    Parameter Description
    ID The ID of the SIM to retrieve

    Update a Specific SIM

    import requests
    
    url = "https://api.onomondo.com/sim/123456789"
    
    payload = '{ "alias": "new_alias", "activated": false }'
    headers = {
        'Authorization': "YOUR-API-KEY",
        'Content-Type': "application/json",
        }
    
    response = requests.request("PUT", url, data=payload, headers=headers)
    
    print(response.text)
    
    curl --request PUT \
      --url https://api.onomondo.com/sim/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

    PUT https://api.onomondo.com/sim/<ID>

    URL Parameters

    Parameter Description
    ID The ID of the SIM to update

    Query Parameters

    Parameter Description
    alias TODO, write something meaningful
    connector TODO, write something meaningful
    activated TODO, write something meaningful

    Delete a Specific SIM

    import requests
    
    url = "https://api.onomondo.com/sim/123456789"
    
    headers = { 'Authorization': "YOUR-API-KEY" }
    
    response = requests.request("DELETE", url, headers=headers)
    
    print(response.text)
    
    curl --request DELETE \
      --url https://api.onomondo.com/sim/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/sim/<ID>

    URL Parameters

    Parameter Description
    ID The ID of the SIM to delete

    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_ibm_watson_iot_connector",
            "type": "ibm_watson_iot",
            "config": {
                "org": "...",
                "type": "...-gateway",
                "id": "...",
                "domain": "internetofthings.ibmcloud.com",
                "auth-method": "token",
                "auth-token": "..."
            },
            "event": "status",
            "mapped_to": ["123456789", "987654321"]
        },
        {
            "name": "my_microsoft_azure_iot_connector",
            "type": "microsoft_azure_iot",
            "connectionString": "HostName=Onomondo.azure-devices.net;DeviceId=MyTestDevice;SharedAccessKey=...",
            "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/connector/my_ibm_watson_iot_connector"
    
    headers = { 'Authorization': "YOUR-API-KEY" }
    
    response = requests.request("GET", url, headers=headers)
    
    print(response.text)
    
    curl --request GET \
      --url https://api.onomondo.com/connector/my_ibm_watson_iot_connector \
      --header 'Authorization: YOUR-API-KEY'
    

    The above command returns JSON structured like this:

    {
        "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",
        "mapped_to": ["123456789", "987654321"]
    }
    

    This endpoint retrieves a specific Connector.

    HTTP Request

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

    URL Parameters

    Parameter Description
    NAME The name of the Connector to retrieve

    Create a Specific Connector

    import requests
    
    url = "https://api.onomondo.com/connector/my_ibm_watson_iot_connector"
    
    payload = '{ "type": "ibm_watson_iot", "config": { "org" : "...", "type" : "...", "id" : "...", "domain": "internetofthings.ibmcloud.com", "auth-method" : "token", "auth-token" : "..." }, "event": "status" }'
    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/connector/my_ibm_watson_iot_connector \
      --header 'Authorization: YOUR-API-KEY' \
      --header 'Content-Type: application/json' \
      --data '{ "type": "ibm_watson_iot", "config": { "org" : "...", "type" : "...", "id" : "...", "domain": "internetofthings.ibmcloud.com", "auth-method" : "token", "auth-token" : "..." }, "event": "status" }'
    

    The above command returns JSON structured like this:

    {
        "message": "OK"
    }
    

    This endpoint creates a specific Connector.

    HTTP Request

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

    URL Parameters

    Parameter Description
    NAME The name of the Connector to create

    Query Parameters

    TODO, parameters depends on connector type, write something meaningful

    Update a Specific Connector

    import requests
    
    url = "https://api.onomondo.com/connector/my_ibm_watson_iot_connector"
    
    payload = '{ "type": "ibm_watson_iot", "config": { "org" : "...", "type" : "...", "id" : "...", "domain": "internetofthings.ibmcloud.com", "auth-method" : "token", "auth-token" : "..." }, "event": "status" }'
    headers = {
        'Authorization': "YOUR-API-KEY",
        'Content-Type': "application/json"
        }
    
    response = requests.request("PUT", url, data=payload, headers=headers)
    
    print(response.text)
    
    curl --request PUT \
      --url https://127.0.0.1:8443/connector/my_ibm_watson_iot_connector \
      --header 'Authorization: YOUR-API-KEY' \
      --header 'Content-Type: application/json' \
      --data '{ "type": "ibm_watson_iot", "config": { "org" : "...", "type" : "...", "id" : "...", "domain": "internetofthings.ibmcloud.com", "auth-method" : "token", "auth-token" : "..." }, "event": "status" }'
    

    The above command returns JSON structured like this:

    {
        "message": "OK"
    }
    

    This endpoint updates a specific Connector.

    HTTP Request

    PUT https://api.onomondo.com/connector/<NAME>

    URL Parameters

    Parameter Description
    NAME The name of the Connector to update

    Query Parameters

    TODO, parameters depends on connector type, write something meaningful

    Delete a Specific Connector

    import requests
    
    url = "https://api.onomondo.com/connector/my_ibm_watson_iot_connector"
    
    headers = { 'Authorization': "YOUR-API-KEY" }
    
    response = requests.request("DELETE", url, headers=headers)
    
    print(response.text)
    
    curl --request DELETE \
      --url https://api.onomondo.com/connector/my_ibm_watson_iot_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/connector/<NAME>

    URL Parameters

    Parameter Description
    NAME The name of the Connector to delete

    Usages

    Get All Usages

    import requests
    
    url = "https://api.onomondo.com/usages"
    
    headers = { 'Authorization': "YOUR-API-KEY" }
    
    response = requests.request("GET", url, headers=headers)
    
    print(response.text)
    
    curl --request GET \
      --url https://api.onomondo.com/usages \
      --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 usages on all your SIMs.

    HTTP Request

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

    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:

    {
        "time": "2018-01-01 01:23:45",
        "bill_id": "1234567890123",
        "sim_id": "123456789",
        "country_code": "dk",
        "usage": 0
    }
    

    This webhook shows usage of your SIMs.

    Parameters

    Parameter Description
    time TODO, write something meaningful
    bill_id TODO, write something meaningful
    sim_id TODO, write something meaningful
    country_code TODO, write something meaningful
    usage TODO, write something meaningful

    Network Registration

    The usage webhook returns JSON structured like this:

    {
        "time": "2018-01-01 01:23:45",
        "sim_id": "123456789",
        "country_code": "dk",
        "imei": "1234567890123456"
    }
    

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

    Parameters

    Parameter Description
    time TODO, write something meaningful
    sim_id TODO, write something meaningful
    country_code TODO, write something meaningful
    imei TODO, write something meaningful

    Network Deregistration

    The usage webhook returns JSON structured like this:

    {
        "time": "2018-01-01 01:23:45",
        "sim_id": "123456789",
        "country_code": "dk",
        "imei": "1234567890123456"
    }
    

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

    Parameters

    Parameter Description
    time TODO, write something meaningful
    sim_id TODO, write something meaningful
    country_code TODO, write something meaningful
    imei TODO, write something meaningful