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 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.
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
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