Table of Contents
API : MVNO Usage
Introduction
This request will return usage data for the MVNO account.
The usage data contains:
- Voice usage
- Data usage
- SMS usage
- MMS usage
- Overcharged SMS (only in JSON response)
The data is always returned for one or more whole months. If from and/or to dates are given, only the year and month part is used.
Request
| URL | https://api.telecomx.dk/mvno/ACCOUNT_ID/usage | |
|---|---|---|
| Method | GET | |
| Access level | VIEWER, MANAGER or OWNER if user belongs to the customer. RESELLER if customer belongs to the reseller. ADMIN. |
|
| Param | ACCOUNT_ID | Id of the MVNO account (24 hex-char string). |
| Query | fromDate | [optional] First month to return usage data for. Date format: yyyy-mm-dd. Defaults to today. Only year and month is used. |
| toDate | [optional] Last month to return usage data for. Date format: yyyy-mm-dd. Only year and month is used. |
|
| type | [optional] Type of response - JSON (default) or CSV. |
|
Query example
https://api.telecomx.dk/mvno/1234567890ABCDEF12345678/usage https://api.telecomx.dk/mvno/1234567890ABCDEF12345678/usage?fromDate=2014-07-01 https://api.telecomx.dk/mvno/1234567890ABCDEF12345678/cdr?fromDate=2014-07-01&toDate=2014-12-01 https://api.telecomx.dk/mvno/1234567890ABCDEF12345678/cdr?fromDate=2014-07-01&toDate=2014-12-01&type=CSV
Response (if type=JSON)
| JSON object | ||
|---|---|---|
| account._id | Id | Unique ID of the MVNO account. |
| account.number | String | Phone number in E.164 format. |
| account.name | String | Name of the person using the account. |
| account.ratePlan | Id | Id of the rateplan the account is using. |
| account.ratePlanName | String | Name of rateplan the account is using. |
| account.data | Number | Number of megabytes data included in homeland. |
| data | Array | Array of data usage data, see details below. |
| data[].date | Date | The year/month the usage statistics is for. |
| data[].regions | Array | List of roaming regions |
| data[].regions[]._id | ObjectID | ID of roaming region |
| data[].regions[].name | String | Name of roaming region |
| data[].regions[].roamLikeHome | Boolean | Whether this is the “Roam Like Home”-region |
| data[].regions[].homeland | Boolean | Whether this is the “Homeland”-region |
| data[].regions[].bytes | Number | Amount of bytes used |
| voice | Array | Array of voice usage data, see details below. |
| voice[].date | Date | the year/month the usage statistics is for. |
| voice[].homeland | Number | Remaining seconds towards national destinations. |
| voice[].euNordic | Number | Remaining seconds towards EU and the nordics. |
| voice[].restOfEurope | Number | Remaining seconds towards the rest of Europe and Thailand. |
| voice[].world1 | Number | Remaining seconds towards world region 1. |
| voice[].world2 | Number | Remaining seconds towards world region 2. |
| voice[].world3 | Number | Remaining seconds towards world region 3. |
| voice[].roamingRegions | Array | List of roaming regions |
| voice[].roamingRegions[]._id | ObjectID | ID of roaming region |
| voice[].roamingRegions[].name | String | Name of roaming region |
| voice[].roamingRegions[].roamLikeHome | Boolean | Whether this is the “Roam Like Home”-region |
| voice[].roamingRegions[].homeland | Boolean | Whether this is the “Homeland”-region |
| voice[].roamingRegions[].subscriptionSeconds | Number | Seconds included in subscription while roaming in this region |
| voice[].roamingRegions[].seconds | Number | Remaining seconds while roaming in this region |
| voice[].subscriptionHomeland | Number | Seconds included in subscription towards national destinations. |
| voice[].subscriptionEuNordic | Number | Seconds included in subscription towards EU and the Nordics. |
| voice[].subscriptionRestOfEurope | Number | Seconds included in subscription towards rest of Europe. |
| voice[].subscriptionWorld1 | Number | Seconds included in subscription towards region world 1. |
| voice[].subscriptionWorld2 | Number | Seconds included in subscription towards region world 2. |
| voice[].subscriptionWorld3 | Number | Seconds included in subscription towards region world 3. |
| sms | Array | Array of SMS usage data, see details below. |
| sms[].date | Date | The year/month the usage statistics is for. |
| sms[].homeland | Number | Number of SMS messages sent to nationals destinations. |
| sms[].international | Number | Number of SMS messages sent to international destinations. |
| sms[].roaming | Number | Number of SMS messages sent while roaming. |
| mms | Array | Array of MMS usage data, see details below. |
| mms[].date | Date | The year/month the usage statistics is for. |
| mms[].homeland | Number | Number of MMS messages sent to nationals destinations. |
| mms[].international | Number | Number of MMS messages sent to international destinations. |
| mms[].roaming | Number | Number of MMS messages sent while roaming. |
| charges | Array | Array of overcharged SMS messages, see details below. |
| charges[].date | Date | Date and time when the SMS was sent. |
| charges[].number | String | The number it was sent to. |
| charges[].description | String | Description of the SMS service it was sent to. |
| charges[].amount | Number | Number of SMS's sent. |
| charges[].price | Number | The price. |
| charges[].vat | Boolean | True if the SMS is VAT exempt. |
| charges[].wholesale | Number | The resellers price, usually the same as the price (RESELLER/ADMIN only). |
| charges[].cost | Number | The cost price, usually the same as the price (ADMIN only). |
| restOfWorldChangeLog | Array | Data regarding “Rest-of-World” activations in the given month. It will contain entries from the last month, if they cross into the current month |
| restOfWorldChangeLog[].type | Enum | Type of change - allowed values are: 'CHANGE', 'ACTIVATION', 'REVERSION'. CHANGE is when a user has bought a new RoW-SOC ACTIVATION is when the RoW-SOC is activated when roaming, both for initial activation and rebuying it REVERSION is when the SOC expires, and is changed back to the SOC in the rate plan. CHANGE_RATEPLAN The rate plan has been changed mid-month, and the customer has thus paid for a new rate plan. This means that if the new rate plan has an included auto-start RoW package, then the next activation will be included. |
| restOfWorldChangeLog[].soc | Object | SOC object, with the relevant SOC. Null when there is no relevant SOC to show, e.g reverting back to not having a SOC. This property will be the SOC that the MVNO account has at this given time, after the change. |
| restOfWorldChangeLog[].soc._id | String | SOC name |
| restOfWorldChangeLog[].soc.description | String | Short description of the SOC |
| restOfWorldChangeLog[].soc.rowType | Enum | 'AUTOSTART' or 'PURCHASE' |
| restOfWorldChangeLog[].cost | Number | The cost of the activation. Only used when type = ACTIVATION |
| restOfWorldChangeLog[].wholesale | Number | The wholesale price of the soc pr month. Only used when type = ACTIVATION |
| restOfWorldChangeLog[].price | Number | The customer price of the soc pr month. Only used when type = ACTIVATION |
| restOfWorldChangeLog[].when | Date | Time of creation of this changelog. If type = ACTIVATION, then this is the time of activation. |
| restOfWorldChangeLog[].expiresAt | Date | When the ROW-activation expires. Only used when type = ACTIVATION |
| restOfWorldChangeLog[].isIncluded | Boolean | Whether this ROW-activation was included in the phone plan or not - if it is included, then it is free (price and wholesale will also be 0) |
Response (if type=CSV)
First line is the column headers and additional line is the usage for a given month, dependent on the selected date range.
| Column headers |
|---|
| number |
| name |
| ratePlan |
| year |
| month |
| Voice Homeland secs |
| Voice EU/Nordic secs |
| Voice rest of europe secs |
| voice World 1 secs |
| Voice World 2 secs |
| Voice World 3 secs |
| Voice roaming <region name> secs |
| Voice subscription roaming <region name> secs |
| Voice subscription Homeland secs |
| Voice subscription EU/Nordic secs |
| Voice subscription rest of Europe secs |
| Voice subscription World 1 secs |
| Voice subscription World 2 secs |
| Voice subscription World 3 secs |
| Data Homeland bytes |
| Data EU/Nordic bytes |
| Data rest of Europe bytes |
| Data World 1 bytes |
| Data World 2 bytes |
| Data World 3 bytes |
| SMS Homeland |
| SMS international |
| SMS roaming |
| MMS Homeland |
| MMS international |
| MMS roaming |
For voice statistics
Remaining numbers can be negative. If no usage packages exists for a region (see the subscriptionXXX value) the number will always be negative and should be inverted to show the used seconds. If a usage package exists the value will should the remaining seconds before the package is used, and a negative number with the number of seconds used beyond what was included in the package.
subscriptionXXX values shows if a subscription package with a number of included voice minutes (though here shown in seconds) exists. This can be used to show how much of a subscription package has been used together with the remainingXXX value. If the subscriptionXXX value is 0, then there are no subscription package.
Example (if type=JSON)
{ account: { _id: "553ca0f477392ee4106e9526", number: "+4571919999", name: "Donald Duck", ratePlan: "5538b009d78aeb0e930035ff", ratePlanName: "Free speech, free text, 12Gb" data: 12288 }, data: [ { date: '2015-01-01T00:00:00.000Z', regions: [ { _id: "1234567890ABCD1234567890", name: "Danmark", roamLikeHome: false, homeland: true, bytes: 1024 } ] }, ... ], voice: [ { date: '2015-01-01T00:00:00.000Z', homeland: 23567, euNordic: -435, restOfEurope: 0, world1: 0, world2: 0, world3: 0, subscriptionHomeland: 36000, subscriptionEuNordic: 0, subscriptionRestOfEurope: 0, subscriptionWorld1: 0, subscriptionWorld2: 0, subscriptionWorld3: 0, roamingRegions: [ { _id: ObjectID("1234567890ABCD1234567890"), subscriptionSeconds: 6000, seconds: 4512, name: "Danmark", roamLikeHome: false, homeland: true, }, ] }, { ... } ], }, ... ], sms: [ { date: '2015-01-01T00:00:00.000Z', homeland: 243, international: 12, roaming: 2 }, ... ], mms: [ { date: '2015-01-01T00:00:00.000Z', homeland: 14, international: 0, roaming: 0 }, ... ], charges: [ { date: '2015-01-01T00:00:00.000Z', number: '+451231', description: 'X-Factor stemme, udbydes af DR', amount: 1, price: 2.50, vat: true, wholesale: 2.50, cost: 2.50 }, ... ], restOfWorldRoaming: [ { type: 'ACTIVATION', soc: { _id: 'ABCDEFG', description: 'Roaming Soc - 1 gb autostart', rowType: 'AUTOSTART' }, cost: 5, wholesale: 10, price: 15, when: '2024-06-15T10:00:00.000Z', expiresAt: '2024-07-15T10:00:00.000Z', isIncluded: false }, { ... } ] }
Errors
| Error code | Message | Description |
|---|---|---|
| 400 | bad_request | MVNO account id not found in request URI |
| 404 | sipAccount | MVNO account not found |
| 403 | access_denied | Insufficient access level |
| 422 | toDate | To date is before from date |
| 409 | toDate | The date span is too large, max 1 year |