User Tools

Site Tools


api:mvno:account:usage

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
api/mvno/account/usage.txt · Last modified: 2024/07/05 07:50 by Joakim Andersen

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki