Set Usage Levels
Purpose
Sets monitoring levels for SIM usage.
When a SIM reaches the warning level, an email notification is sent to the addresses registered with support. When a SIM reaches the limit level, another email is sent and traffic for the SIM is disabled.
Conditions and rules
- Usage levels can only be set for SIMs in Live groups. Attempts to set levels for SIMs in Pending or Suspended groups will return Invalid ICCID.
- If either <warning> or <limit> is omitted, the existing value for the omitted element will remain unchanged, except:
- <limit> must be greater than or equal to <warning>. If this is not the case, both warning and limit will be set to the <warning> value.
- Setting usage levels for Pre-Paid SIMs is not allowed and will return Invalid ICCID.
Meaning of values
The meaning of the values supplied depends on the SIM type:
Manx Telecom SIMs (1-NET, MultiNET Voda, MultiNET M2M, SMART O2 Voda)
- Values represent the nominal balance in £ Example: <warning>10</warning> triggers a warning when the nominal balance reaches £10.00
Other SIM types (MultiNET KPN-C, KPN-O, KPN-LBS, EE, O2 UK, MultiNET ROG-C, 3-Global, Verizon, Verizon-M1, Tele2)
- Values represent data usage in MB Example: <limit>20</limit> triggers cut-off when usage reaches 20 MB
Discrete usage levels
Values must match one of the supported discrete steps below. If a value does not match one of these steps, the response will be Invalid Content.
Usage level | API value |
|---|---|
1 MB | 1 |
1.5 MB | 1.5 |
2 MB | 2 |
3 MB | 3 |
4 MB | 4 |
5 MB | 5 |
6 MB | 6 |
7 MB | 7 |
8 MB | 8 |
10 MB | 10 |
12 MB | 12 |
15 MB | 15 |
20 MB | 20 |
25 MB | 25 |
30 MB | 30 |
40 MB | 40 |
50 MB | 50 |
60 MB | 60 |
70 MB | 70 |
80 MB | 80 |
100 MB | 100 |
120 MB | 120 |
150 MB | 150 |
200 MB | 200 |
250 MB | 250 |
300 MB | 300 |
400 MB | 400 |
500 MB | 500 |
600 MB | 600 |
700 MB | 700 |
800 MB | 800 |
1 GB | 1024 |
1.5 GB | 1536 |
2 GB | 2048 |
2.5 GB | 2560 |
3 GB | 3072 |
4 GB | 4096 |
5 GB | 5120 |
6 GB | 6144 |
7 GB | 7168 |
8 GB | 8192 |
10 GB | 10240 |
15 GB | 15360 |
20 GB | 20480 |
30 GB | 30720 |
40 GB | 40960 |
50 GB | 51200 |
60 GB | 61440 |
70 GB | 71680 |
80 GB | 81920 |
100 GB | 102400 |
150 GB | 153600 |
200 GB | 204800 |
250 GB | 256000 |
400 GB | 409600 |
500 GB | 512000 |
800 GB | 819200 |
1 TB | 1048576 |
2 TB | 2097152 |
5 TB | 5242880 |
Operational Impact
API commands perform live configuration changes.
- Changes take effect immediately.
- Commands may affect SIM status, service availability, charging, or usage limits.
- Requests cannot be undone automatically.
Ensure all parameters are validated before submitting requests to the production environment.
Endpoint
POST https://api.m2miportal.com
Content-Type: application/xml
Accept: application/xmlRequest (XML)
<set-usage-levels version="1" api-id="123456">
<authentication>
<username>username</username>
<password>password</password>
</authentication>
<iccid>1234567890123456789</iccid>
<warning>100</warning>
<limit>500</limit>
</set-usage-levels>Response (Success)
<set-usage-levels-response api-id="123456">
<api-outcome>Success</api-outcome>
</set-usage-levels-response>Response (Failure)
If a request cannot be processed, the response will include:
- api-outcome indicating failure
- An error description explaining the reason
Failure responses may occur due to:
- Invalid authentication credentials
- Invalid or unknown identifiers (for example ICCID or MSISDN)
- Invalid or missing parameters
- Values not permitted for the specified SIM type or account configuration
- Insufficient permissions
Integrating systems should validate input data before submission and implement appropriate error handling and logging.