UROS Connect platform API

Overview

The UROS Connect platform API provides means for customers to programmatically access information about devices and their data usage. Please don’t abuse or otherwise use API excessively - if you’re unsure about your usage patterns, please confirm it from via email from developers@REMOVEuros.com.

The API follows REST-style pattern for accessing information from UROS Connect platform using HTTP-protocol over SSL-tunnel from API-endpoint hosted at URL https://api.uros-connect.com.

Each chapter in the Endpoints chapter lists the exact path of the endpoint, purpose of the endpoint, accepted parameter structure and returned parameter structure. The list of parameters contains a character O in case it is an optional variable. For input parameters it means the parameter can be omitted, and usually the default functionality is explained. For return structures an optional parameter usually means the part of the structure is meaningless if missing.

Access control

When accessing data via any of the documented API endpoints, request is authenticated with customer’s email address as username and system generated API-token as password. Credentials are passed to the API endpoint via following HTTP-headers included in each authenticated API request.

X-UROS-Username - Email address for the customer’s account (e.g. john@some.net)
X-UROS-API-Token - Generated API token for customer (e.g. 1293i123123sedr)

You can create your developer API token from UROS Connect portal, after signing in with your personal username and password.

Take note of your API token; it’s unique to your account and should be kept private.

Common responses

The API follows common REST/HTTP guidelines for response codes. Following table explains the codes used by the API, and their explicit meaning within the context.

Code	Description
200 OK	The operation invoked by the client application completed successfully
201 Created	A POST or PUT operation was succesful. Data was added or modified, and there is no data to return
202 Accepted	Client application invoked an asynchronous request. The results will be available later in the url identified by the location header
400 Bad Request	Returned when client application sent the request with incorrect syntax (e.g. mandatory parameter is missing or some of the parameter values do not conform to the format introduced in this specification)
401 Unauthorized	Returned when client application is requesting a resource without valid authorisation. Application should retry the operation with valid API credentials
403 Forbidden	Returned when account is locked or expired or the given credentials don’t permit access to this feature
404 Not Found	Client application attempted to access a non-existent resource, for instance a device or a SIM card, or the given resource does not belong to the provided credentials’ context
429 Too Many Requests	Server refuses to fulfil the request due the client application sending too many request for a given time period. Application should retry the operation after the number of allowed requests falls back to allowed bounds. Client application must follow a rate limit of 5 requests per 30s time period
500 Internal Server Error	Server isn’t able to fulfil the request due the unexpected (error) condition
503 Service Unavailable	Server is currently unable to handle request due the temporary overloading or maintenance of the server. This condition implies temporary condition which will be rectified after some delay. If response has ‘Retry-After’ header, the client should wait specified amount before retrying operation. If no Retry-After is given, response should be treated in same way as response 500 is handled

API endpoints

List of API endpoints
`GET https://api.uros-connect.com/account/clients`
`GET https://api.uros-connect.com/account/clients/%sn%`
`PUT https://api.uros-connect.com/account/clients/%sn%`
`GET https://api.uros-connect.com/account/clients/%sn%/sims`
`GET https://api.uros-connect.com/account/clients/%sn%/consumption`
`GET https://api.uros-connect.com/account/clients/all/consumption`
`GET https://api.uros-connect.com/account/sims`
`GET https://api.uros-connect.com/account/sims/summary`
`GET https://api.uros-connect.com/account/sims/%iccid%`
`GET https://api.uros-connect.com/account/sims/%iccid%/country/%country%`
`PUT https://api.uros-connect.com/account/sims/%iccid%/country/%country%`
`GET https://api.uros-connect.com/account/sims/%iccid%/country/%country%/quota`
`PUT https://api.uros-connect.com/account/sims/%iccid%/country/%country%/quota`
`GET https://api.uros-connect.com/account/events`

List clients associated to account

Lists all the devices currently associated with the account. For each device the serial number, label (if available), activation date and current software version are returned.

In case listing a significant number of devices, the API provides a limit and offset query parameters for incremental query.

Request URL

GET https://api.uros-connect.com/account/clients

Query Parameters

Parameter	Flags	Description
max	O	Maximum number of results returned. If not provided, 1000 by default.
offset	O	Starting index of devices. This enables querying incrementally. 0 by default.

Sample response

[
    {
        "sn": "f2f2a126e60996a69f1aa49abe1d50b78b4a93e7",
        "clientSerial": "9267283718",
        "activationDate": "2020-02-12T15:38:11+00:00"
    },
    {
        "sn": "c81aa3e6d324314a8588a519caf046b7ac4ede74",
        "clientSerial": "9267293412",
        "label": "John",
        "activationDate": "2020-02-20T07:15:00+00:00"
    }
]

Field details

Field	Flags	Description
sn		Serial code of associated device. For a physical device, this is the factory built-in serial number. For a virtual device (software client) the serial code is randomly generated
label	O	Device label, free form tag used for identification
clientSerial	O	Client-provided serial number representing the device where the client is running
sw	O	Reported software version of associated device (only applicable for physical devices manufactured by UROS)
activationDate		Time of activation, ISO8601 -format

Examples

curl -Gs 'https://api.uros-connect.com/account/clients' \
    -H 'X-UROS-Username: john.doe@example.com' \
    -H 'X-UROS-API-Token: 12345678901234567890123456789012' \
    --compressed

Get configuration of a client

Read configuration of the device (identified by the device serial code in the request url). In addition of the basic data of the device the response lists the ICCID of the simcard, the ISO 3166-1 alpha-2 country code, the type, the status and the UTC offset of the destination currently associated with the device.

The configuration includes destinations, which is a list of countries where the client is configured to function, in addition to how the country is implemented, and its status. This part of the response is very large, so it can be opted out from the response by setting a query flag.

Request URL

GET https://api.uros-connect.com/account/clients/%sn%
GET https://api.uros-connect.com/account/clients/%sn%?destinations=false

Query Parameters

Parameter	Flags	Description
destinations	O	If set false, destinations are not included in response. By default true.

Sample response

{
    "sn": "f2f2a126e60996a69f1aa49abe1d50b78b4a93e7",
    "clientSerial": "9267283718",
    "label": "Test device 2",
    "activationDate": "2020-02-12T12:34:56+00:00",
    "destinations": [
        {
            "iccid": "8935806111212584189",
            "country": "FI",
            "timezone": "+02:00",
            "type": "PREPAID",
            "status": "ACTIVE"
        },
        {
            "iccid": "8934123412341234123",
            "country": "SE",
            "timezone": "+01:00",
            "type": "PERSONAL",
            "status": "ACTIVE"
        },
        {
            "iccid": "8935123412341234123",
            "country": "DK",
            "timezone": "+01:00",
            "type": "PERSONAL",
            "status": "ACTIVE",
            "quota": {
                "enabled": true,
                "fairUseLimit": "980MB",
                "hardLimit": "1GB"
            }
        }
    ]
}

Field details

Field	Flags	Description
sn		Serial code of associated device. For a physical device, this is the factory built-in serial number. For a virtual device (software client) the serial code is randomly generated
label	O	Device label, free form tag used for identification
clientSerial	O	Client-provided serial number representing the device where the client is running
sw	O	Reported software version of associated device (only applicable for physical devices manufactured by UROS)
activationDate		Time of activation, ISO8601 -format
state	O	State of the device (if applicable), one of `ACTIVE`, `SUSPENDED`
destinations	O	list of destinations/countries enabled for the device. This field is not present opted out by the query parameter.
country		ISO 3166-1 alpha-2 country-code of associated country
iccid		ICCID of SIM assigned for given country
type		Type of SIM, `PERSONAL` for user owned personal SIMs attached to device, `PREPAID` for destination SIMs provided by Uros
timezone		Timezone offset for given country
status	O	enumeration for the status of destination country (`ACTIVE`, `INACTIVE`, `BLOCKED`)
quota	O	object indicating allowed usage limits for daily data transfer for this destination country (KB, MB or GB). Only included if limits have been defined
quota.enabled		Boolean value indicating whether configured daily data transfer limit is enabled or disabled
quota.fairUseLimit	O	Fair-use limit for daily data transfer of destination country (KB, MB or GB). Device will throttle data transfer speed for this destination country until end of the current day after the limit has been reached
quota.hardLimit	O	Hard-use limit for daily data transfer of destination country (KB, MB or GB). Device will prevent data transfer for this destination country until end of the current day after the limit has been reached

Examples

Display details for client with serial code ‘f2f2a126e60996a69f1aa49abe1d50b78b4a93e7’

curl -Gs 'https://api.uros-connect.com/account/clients/f2f2a126e60996a69f1aa49abe1d50b78b4a93e7?destinations=false' \
    -H 'X-UROS-Username: john.doe@example.com' \
    -H 'X-UROS-API-Token: 12345678901234567890123456789012' \
    --compressed

Modify configuration of a client

Modifies device configuration (identified by the device serial number in the request url).

The API returns 404 if the device can not be found by serial number, 400 if the data can not be accepted, and 200 on success.

Not all device types necessarily support setting all property types. Error 400 will be returned if the device does not support the property.

Request URL

PUT https://api.uros-connect.com/account/clients/%sn%

Sample request:

{
    "label": "George"
}

Field details

Field	Flags	Description
label	O	Device label, free form tag used for identification
clientSerial	O	Client-provided serial number representing the device where the client is running
state	O	Client state, one of `ACTIVE` and `SUSPENDED`. This parameter is only applicable to a limited set of devices.

Examples

Change user-defined label for a device

curl -X PUT 'https://api.uros-connect.com/account/clients/f2f2a126e60996a69f1aa49abe1d50b78b4a93e7' \
    -H 'X-UROS-Username: john.doe@example.com' \
    -H 'X-UROS-API-Token: 12345678901234567890123456789012' \
    -H 'Content-Type: application/json' \
    -d '{ "label": "John Doe" }' \
    ---compressed

Get SIM Cards of a client

Lists SIM Cards that are attached to given client

Request URL

GET https://api.uros-connect.com/account/clients/%sn%/sims

Sample response:

[
    {
        "iccid": "8935806111212584189",
        "eid": "17487392848378189487281738274837"
    },
    {
        "iccid": "4835806111212512345",
        "eid": "17487392848378189487281738274837"
    }
]

Field details

Field	Flags	Description
iccid		ICCID of this SIM card of SIM profile. Not present if this object is an empty ESIM card
eid		Either the EID of an empty ESIM card, or the EID where this profile is loaded (if iccid is present in this object)

Examples

Retrieve sim cards attached to device ‘DM123412343’

curl -Gs 'https://api.uros-connect.com/account/clients/DM123412343/sims' \
    -H 'X-UROS-Username: john.doe@example.com' \
    -H 'X-UROS-API-Token: 12345678901234567890123456789012' \
    --compressed

Get data consumption of a client

Hourly data consumption for a single client for given date per active destination. Consumption is returned in user-defined timezone if the client request contains a timezone parameter. Destinations which do not have any recorded data consumption for the given day are not included in the response.

Request URL

GET https://api.uros-connect.com/account/clients/%sn%/consumption

Query Parameters

Parameter	Flags	Description
date		Requested date in date+offset (`yyyy-MM-dd'T'ZZ`) -format. For example 21th of December 2012 in Finnish winter time would be `2012-12-21T+03:00`. See ISO8601 specification for details. Note that `+` sign needs to be encoded to `%2B`, see Percent-encoding )
timezone	O	user-defined timezone for response data, defaults to timezone of request date -parameter. If specified, representation of result dates is converted into specified timezone

Sample response:

{
    "sn": "c81aa3e6d324314a8588a519caf046b7ac4ede74",
    "label": "John",
    "destinations": [
        {
            "country": "FI",
            "iccid": "8935806111212584189",
            "data": [
                {
                    "date": "2020-02-22T01+11:00",
                    "consumption": 432
                }
            ]
        },
        {
            "country": "SE",
            "iccid": "4835806111212512345",
            "data": [
                {
                    "date": "2020-02-22T01+11:00",
                    "consumption": 132
                },
                {
                    "date": "2020-02-22T02+11:00",
                    "consumption": 42
                }
            ]
        }
    ]
}

Field details

Field	Flags	Description
sn		Serial code of associated device. For a physical device, this is the factory built-in serial number. For a virtual device (software client) the serial code is randomly generated
label	O	Device label, free form tag used for identification
clientSerial	O	Client-provided serial number representing the device where the client is running
destinations		list of destinations where consumption has occurred in given time period
destinations.country		Country-code in ISO 3166-1 alpha-2 -format
destinations.iccid		ICCID of SIM card in question
destinations.data		daily consumption as list of date-consumption pairs
destinations.data.date		Timestamp of record in date+hour+offset (`yyyy-MM-dd'T'HHZZ`) ISO8601 -format
destinations.data.consumption		data consumption during presented hour in kilobytes (1 kilobyte = 1024 bytes)

Examples

Retrieve data consumption for device ‘DM123412343’ on February 12th, 2020 (on timezone +03) and return all results on UTC

curl -Gs 'https://api.uros-connect.com/account/clients/DM123412343/consumption?date=2020-02-12T%2B03:00&timezone=%2B00:00' \
    -H 'X-UROS-Username: john.doe@example.com' \
    -H 'X-UROS-API-Token: 12345678901234567890123456789012' \
    --compressed

Summarize data consumption over several clients

Data consumption overview for a set of devices for a given time period. Consumption reported as total sum for each day using per destination timezone offset. The “start” and “end” parameters are mandatory. The API endpoint allows access to 180 days old usage data with maximum period between “start” and “end” dates in a single request being 60 days. The “device” parameter can be included in the request multiple times to define the subset of devices (serial numbers) for which the data consumption overview report is generated. If the “device” parameter is omitted, the report is generated over all the devices associated with the account during the requested period (this may take some time if the account is associated with large number of devices).

Note! This API endpoint is asynchronous. The first time a request is received from a client a 202 Accepted response is returned (with a location header). The client is expected to retry the request using the url returned in the location header until it gets a 200 OK response with the payload described below in the body of the response. The client should not poll the location url in a busy-loop, but implement a short wait between subsequent requests.

Request URL

GET https://api.uros-connect.com/account/clients/all/consumption

Query Parameters

Parameter	Flags	Description
start		Start date in date+offset (`yyyy-MM-dd'T'ZZ`) ISO8601-format
end		End date in date+offset (`yyyy-MM-dd'T'ZZ`) ISO8601-format
device	O	client serial code as string. A single request can contain more than one device-parameters. If omitted, calculates consumption for all clients.
timezone	O	timezone to convert dates to. UTC by default

Sample response:

[
    {
        "sn": "c81aa3e6d324314a8588a519caf046b7ac4ede74",
        "label": "John",
        "destinations": [
            {
                "country": "FI",
                "iccid": "8935806111212576518",
                "data": [
                    {
                        "date": "2020-02-22T+02:00",
                        "consumption": 432
                    }
                ]
            }
        ]
    },
    {
        "sn": "2577c907babacf8267760c52cadbc428c528111e",
        "destinations": [
            {
                "country": "FI",
                "iccid": "8935806111212584189",
                "data": [
                    {
                        "date": "2020-02-22T+02:00",
                        "consumption": 150
                    }
                ]
            },
            {
                "country": "SE",
                "iccid": "4835806111212512345",
                "data": [
                    {
                        "date": "2020-02-13T+02:00",
                        "consumption": 132
                    },
                    {
                        "date": "2020-02-14T+02:00",
                        "consumption": 42
                    }
                ]
            }
        ]
    }
]

Field details

Field	Flags	Description
sn		Serial code of associated device. For a physical device, this is the factory built-in serial number. For a virtual device (software client) the serial code is randomly generated
label	O	Device label, free form tag used for identification
clientSerial	O	Client-provided serial number representing the device where the client is running
destinations		statistics of active destinations/countries of device
destinations.country		Countrycode in ISO 3166-1 alpha-2 -format
destinations.iccid		ICCID of SIM card in question
destinations.data		daily consumption as list of date-consumption pairs
destinations.data.date		Date of record in date+offset (`yyyy-MM-dd'T'ZZ`) ISO8601 -format
destinations.data.consumption		data consumption during presented day in kilobytes (1 kilobyte = 1024 bytes)

Examples

Get consumption overview for given 3 devices for the past (UTC) week

curl -Gs 'https://api.uros-connect.com/account/clients/all/consumption?start=2014-01-03T%2B00:00&end=2014-01-09T%2B00:00&device=CD8187653411&device=CD8187653412&device=CD8187653404'
    -H 'X-UROS-Username: john.doe@example.com' \
    -H 'X-UROS-API-Token: 12345678901234567890123456789012' \
    --compressed

Get consumption overview for all devices for January 2014 (UTC), convert days to +03:00 days in results.

curl -Gs 'https://api.uros-connect.com/account/clients/all/consumption?start=2014-01-01T%2B00:00&end=2014-01-31T%2B00:00&timezone=%2B03:00'
    -H 'X-UROS-Username: john.doe@example.com' \
    -H 'X-UROS-API-Token: 12345678901234567890123456789012' \
    --compressed

Get list of SIM-cards

List SIM-cards attached to the account, available in the account, or ordered. Incremental listing is provided in case the number if cards is very large.

Request URL

GET https://api.uros-connect.com/account/sims?scope=ordered

Query parameters

Parameter	Flags	Description
scope		One of `inuse`, `available` or `ordered`. See explanations below.
max	O	Maximum number of results returned. If not provided, 1000 by default.
offset	O	Starting index of devices. This enables querying incrementally. 0 by default.

Scope	Explanation
inuse	Lists SIM cards that are attached to a device and currently in use
available	Lists SIM cards that are pre-configured and made available, ready for use
ordered	Lists SIM cards that are ordered, but need to be enabled before using

Sample response

[
    {
        "iccid": "8935806111212584189",
        "eid": "17487392848378189487281738274913",
        "sn": "f2f2a126e60996a69f1aa49abe1d50b78b4a93e7"
    },
    {
        "iccid": "4835806111212512345",
        "eid": "17487392848378189487281738274837",
        "sn": "c81aa3e6d324314a8588a519caf046b7ac4ede74"
    }
]

Field details

Field	Flags	Description
iccid		ICCID of the SIM card or SIM profile being listed
eid	O	if the card or profile is attached to an ESIM, the corresponding EID
sn	O	if the card or profile is attached to a client, the client’s serial code

Get summary of SIM-cards

Query overview of all SIM-cards grouped by type and size. If account or any of its device don’t have SIM-cards, a response of 204 No Content is returned.

Request URL

GET https://api.uros-connect.com/account/sims/summary

Query parameters

Parameter	Flags	Description
type	O	type of SIM, `PERSONAL` for user owned personal SIMs, `PREPAID` for destination SIMs provided by UROS
size	O	enumeration for the size of the SIM (`MINI`, `MICRO`)
destinations	O	comma-separated list of ISO 3166-1 alpha-2 country codes that must be supported by the SIM-card

Sample response

[
    {
        "type": "PERSONAL",
        "size": "MICRO",
        "amount": {
            "inuse": 56,
            "available": 123
        }
    },
    {
        "type": "PREPAID",
        "size": "MICRO",
        "amount": {
            "inuse": 32,
            "available": 1
        }
    },
    {
        "type": "PREPAID",
        "size": "MINI",
        "amount": {
            "inuse": 5
        }
    }
]

Field details

Field	Flags	Description
type		type of SIM, (`PERSONAL`, `PREPAID`, `POSTPAID`)
size		size of SIM, (`MINI`, `MICRO`, `UNKNOWN`). The enumeration value of `UNKNOWN` is used if size of the SIM-card can’t be determined in a reliable way.
amount		Object containing SIMs currently available and used by devices
amount.inuse	O	number of SIMs associated with devices
amount.available	O	number of SIMs that aren’t associated with any devices

Examples

Summary of all SIM-cards for user’s account

curl -Gs 'https://api.uros-connect.com/account/sims/summary' \
    -H 'X-UROS-Username: john.doe@example.com' \
    -H 'X-UROS-API-Token: 12345678901234567890123456789012' \
    --compressed

Summary of all ‘PERSONAL’-type SIM-cards supporting Finland and Sweden as destinations

curl -Gs 'https://api.uros-connect.com/account/sims/summary?destinations=FI,SE' \
    -H 'X-UROS-Username: john.doe@example.com' \
    -H 'X-UROS-API-Token: 12345678901234567890123456789012' \
    --compressed

Query details for a single SIM-card

Query details for a single SIM-card identified by ICCID. If SIM-card isn’t found or isn’t associated with the user’s account, a 404 Not Found is returned.

Request URL

GET https://api.uros-connect.com/account/sims/%iccid%

Sample response

{
    "size": "MINI"
    "status": "INUSE"
    "destinations": [
        {
            "iccid": "8934123412341234123",
            "country": "SE",
            "timezone": "+01:00",
            "operator": "Hi3G Access AB",
            "type": "PERSONAL",
            "status": "ACTIVE"
        },
        {
            "iccid": "8934123412341234123",
            "country": "DK",
            "timezone": "+01:00",
            "operator": "Hi3G Access AB",
            "type": "PERSONAL",
            "status": "ACTIVE",
            "quota": {
                "enabled": true,
                "fairUseLimit": "980MB",
                "hardLimit": "1GB"
            }
        }
    ]
}

Field details

Field	Flags	Description
size		Size of the SIM-card (`MINI`, `MICRO`, `UNKNOWN`)
status		Availability status of the SIM-card (`INUSE`, `AVAILABLE`)
destinations		list of destinations/countries of SIM-card
destinations.country		ISO 3166-1 alpha-2 country-code of associated country
destinations.iccid		ICCID of SIM assigned for associated country
destinations.type		Type of SIM, `PERSONAL` for user owned personal SIMs attached to device, `PREPAID` for destination SIMs provided by UROS
destinations.timezone		Timezone offset for destination country
destinations.operator	O	Optional name of SIM operator
destinations.quota	O	object indicating allowed usage limits for daily data transfer for this destination country (KB, MB or GB). Only included if limits have been defined
destinations.quota.enabled		Boolean value indicating whether configured daily data transfer limit is enabled or disabled
destinations.quota.fairUseLimit	O	Fair-use limit for daily data transfer of destination country (KB, MB or GB). Device will throttle data transfer speed for this destination country until end of the current day after the limit has been reached
destinations.quota.hardLimit	O	Hard-use limit for daily data transfer of destination country (KB, MB or GB). Device will prevent data transfer for this destination country until end of the current day after the limit has been reached

Examples

Query details for a SIM-card with ICCID ‘8934123412341234123’

curl -Gs 'https://api.uros-connect.com/account/sims/8934123412341234123 \
    -H 'X-UROS-Username: john.doe@example.com' \
    -H 'X-UROS-API-Token: 12345678901234567890123456789012' \
    --compressed

Query details for a single destination from a SIM-card

Query details for a single destination country identified from a single SIM-card identified by ISO 3166-1 alpha-2 country code and ICCID. If SIM-card isn’t found or specified country isn’t available, a 404 Not Found is returned.

Request URL

GET https://api.uros-connect.com/account/sims/%iccid%/country/%country%

Sample response

{
    "iccid": "8934123412341234123",
    "country": "SE",
    "timezone": "+01:00",
    "operator": "Hi3G Access AB",
    "type": "PERSONAL",
    "status": "ACTIVE",
    "quota": {
        "enabled": true,
        "fairUseLimit": "980MB",
        "hardLimit": "1GB"
    }
}

Field details

Field	Flags	Description
iccid		ICCID of SIM assigned for associated country
country		ISO 3166-1 alpha-2 country-code of associated country
timezone		Timezone offset for destination country
operator	O	Name of the operator for the SIM-card
type		Type of SIM, either `PREPAID`, `POSTPAID` or `PERSONAL`
status	O	enumeration for the status of destination country (‘ACTIVE’, ‘INACTIVE’, ‘BLOCKED’).
quota	O	object indicating allowed usage limits for daily data transfer for this destination country (KB, MB or GB). Only included if limits have been defined
quota.enabled		Boolean value indicating whether configured daily data transfer limit is enabled or disabled
quota.fairUseLimit	O	Fair-use limit for daily data transfer of destination country (KB, MB or GB). Device will throttle data transfer speed for this destination country until end of the current day after the limit has been reached
quota.hardLimit	O	Hard-use limit for daily data transfer of destination country (KB, MB or GB). Device will prevent data transfer for this destination country until end of the current day after the limit has been reached

Examples

Query destination details for ‘Sweden’ from SIM-card with ICCID of ‘8934123412341234123’

curl -Gs 'https://api.uros-connect.com/account/sims/8934123412341234123/country/SE \
    -H 'X-UROS-Username: john.doe@example.com' \
    -H 'X-UROS-API-Token: 12345678901234567890123456789012' \
    --compressed

Change details for a single destination from a SIM-card

Change details for a single destination country identified from a single SIM-card identified by ISO 3166-1 alpha-2 country code and ICCID. If SIM-card isn’t found or specified country isn’t available, a 404 Not Found is returned.

Note that special permissions are required to manipulate separate destination properties. These permissions can be obtained by contacting support. Calling this method without the proper permissions will result to “403 Forbidden” being returned.

Request URL

PUT https://api.uros-connect.com/account/sims/%iccid%/country/%country%

Sample request

{
    "status": "ACTIVE"
    "quota": {
        "enabled": true,
        "fairUseLimit": "980MB",
        "hardLimit": "1GB"
    }
}

Field details

Field	Flags	Description
status	O	enumeration for the status of destination country (`ACTIVE`, `BLOCKED`). Assumes ACTIVE if value not provided
quota	O	object indicating allowed usage limits for daily data transfer for this destination country (KB, MB or GB).
enabled		Boolean value indicating whether daily data transfer limit is to be enabled or disabled
fairUseLimit	O	Fair-use limit for daily data transfer of destination country (KB, MB or GB). Device will throttle data transfer speed for this destination country until end of the current day after the limit has been reached.
hardLimit	O	Hard-use limit for daily data transfer of destination country (KB, MB or GB). Device will prevent data transfer for this destination country until end of the current day after the limit has been reached.

Examples

Block use of ‘Sweden’ from SIM-card with ICCID of ‘8934123412341234123’

curl -X PUT 'https://api.uros-connect.com/account/sims/8934123412341234123/country/SE \
    -H 'X-UROS-Username: john.doe@example.com' \
    -H 'X-UROS-API-Token: 12345678901234567890123456789012' \
    -H 'Content-Type: application/json' \
    -d '{ "status": "BLOCKED" }' \
    ---compressed

Enable use of ‘Sweden’ with custom fair usege limit from SIM-card with ICCID of ‘8934123412341234123’

curl -X PUT 'https://api.uros-connect.com/account/sims/8934123412341234123/country/SE \
    -H 'X-UROS-Username: john.doe@example.com' \
    -H 'X-UROS-API-Token: 12345678901234567890123456789012' \
    -H 'Content-Type: application/json' \
    -d '{ "status": "ACTIVE", "quota": { "enabled" : true, "fairUseLimit": "1GB" } }' \
    ---compressed

Get usage limits for a single destination country

Query usage limit details for a single destination country on a single SIM-card. If no usage limits have configured for the destination country, a response of 204 No Content is returned.

Request URL

GET https://api.uros-connect.com/account/sims/%iccid%/country/%country%/quota

Sample response

{
    "enabled": true,
    "fairUseLimit": "980MB",
    "hardLimit": "1GB"
}

Field details

Field	Flags	Description
enabled		Boolean value indicating whether configured daily data transfer limit is enabled or disabled
fairUseLimit	O	Fair-use limit for daily data transfer of destination country (KB, MB or GB). Device will throttle data transfer speed for this destination country until end of the current day after the limit has been reached
hardLimit	O	Hard-use limit for daily data transfer of destination country (KB, MB or GB). Device will prevent data transfer for this destination country until end of the current day after the limit has been reached

Examples

Query usage limits for destination country Denmark on SIM card 8935123412341234123

curl -Gs 'https://api.uros-connect.com/account/sims/8935123412341234123/country/DK/quota' \
    -H 'X-UROS-Username: john.doe@example.com' \
    -H 'X-UROS-API-Token: 12345678901234567890123456789012' \
    --compressed

Enable, disable or change usage limits for a destination country

Enable, disable or change usage limits for a single destination country on a single SIM card.

Request URL

GET https://api.uros-connect.com/account/sims/%iccid%/country/%country%/quota

Sample request:

{
    "enabled": true,
    "fairUseLimit": "980MB",
    "hardLimit": "1GB"
}

Field details

Field	Flags	Description
enabled		Boolean value indicating whether daily data transfer limit is to be enabled or disabled
fairUseLimit	O	Fair-use limit for daily data transfer of destination country (KB, MB or GB). Device will throttle data transfer speed for this destination country until end of the current day after the limit has been reached.
hardLimit	O	Hard-use limit for daily data transfer of destination country (KB, MB or GB). Device will prevent data transfer for this destination country until end of the current day after the limit has been reached.

Examples

Set fair-use limit to 1GB and disable hard-use limit for destination country Denmark on SIM card 8935123412341234123

curl -Gs 'https://api.uros-connect.com/account/sims/8935123412341234123/country/DK/quota' \
    -H 'X-UROS-Username: john.doe@example.com' \
    -H 'X-UROS-API-Token: 12345678901234567890123456789012' \
    -H 'Content-Type: application/json' \
    -d '{ "enabled": true, "fairUseLimit": "1GB" }' \
    ---compressed

Disable usage limits for destination country Denmark on SIM card 8935123412341234123

curl -Gs 'https://api.uros-connect.com/account/sims/8935123412341234123/country/DK/quota' \
    -H 'X-UROS-Username: john.doe@example.com' \
    -H 'X-UROS-API-Token: 12345678901234567890123456789012' \
    -H 'Content-Type: application/json' \
    -d '{ "enabled": false }' \
    ---compressed

Events for given time period

List all account’s events for a given time period. The query is executed by giving a set of criteria, for example a date range and a set of other, optional parameters. Returned events contain a type that determines what has happened and a reference that tells the relation. For instance for destination daypass payment events, the reference tells the serial number of the device that consumed the daypass. Reference can be also used as search criteria. A list of supported events and list of data provided is shown below.

The API endpoint allows access to 365 days old usage data. The query has a limitation of 1000 results. If the limit is reached, the result set is cut even if more results were available.

Request URL

GET https://api.uros-connect.com/account/events

Query parameters

Parameter	Flags	Description
start	O	Start date in date+offset (`yyyy-MM-dd'T'ZZ`) ISO8601-format. If omitted,
end	O	End date in date+offset (`yyyy-MM-dd'T'ZZ`) ISO8601-format
reference	O	reference search criteria. See meaning of the reference parameter in table below. A single request can contain more than one reference-parameters. If omitted, ignores this criteria (no reference filtering)
timezone	O	timezone for response data. If omitted, event times will be in UTC.

Sample response

[
    {
        "date": "2016-12-01T09:27:45+02:00",
        "type": "DAYPASS",
        "reference": "DM123412343",
        "data": {
            "country": "FI",
            "price": 7.20,
            "currency": "EUR"
        }
    },
    {
        "date": "2016-12-01T11:51:31+02:00",
        "type": "REFILL",
        "description": "DM123412343",
        "data": {
            "country": "FI",
            "price": 7.20,
            "currency": "EUR"
        }
    }
]

Field details

Field	Flags	Description
date		time of the event in ISO8601 -format
type		type of the event, see table in below chapter
reference	O	event reference, see table in below chapter
data	O	event type -specific data, see table in below chapter
data.country	O	country code where the event occurred (Only for events where this is applicable)
data.price	O	price, including VAT (Only in events that contain payment)
data.currency	O	currency code of the price (Only in events that contain payment)

List of event types and details

Type	Explanation	Reference	Data
DAYPASS	One daypass has been consumed	Device serial nr.	country (always), price and currency (if payment was involved)
REFILL	Daypass has been refilled	Device serial nr.	country (always), price and currency (if payment was involved)

Examples

Get consumption overview for all devices for January 2014 (UTC), convert days to +03:00 days in results.

curl -Gs 'https://api.uros-connect.com/account/events?start=2014-01-01T%2B00:00&end=2014-01-31T%2B00:00&timezone=%2B03:00' \
    -H 'X-UROS-Username: john.doe@example.com' \
    -H 'X-UROS-API-Token: 12345678901234567890123456789012' \
    --compressed