If you use bank transfer, don't forget to top up your SIM card before the long weekend as banks will be closed from Saturday to Monday.

Request SIM
Let's continue the revolution

Mobile Vikings API documentation

We offer an API which you can use to get information about your SIM card or Mobile Vikings account. For example, you can get your current credit balance, a list of your top-ups, or Viking Points you have earned.

Many developers have published their apps on vikingapps.be. There are also libraries for many languages, most of them are announced on the Mobile Vikings API users group. Feel free to join the group if you have any questions!

Authentication

An application can authenticate a user by using OAuth or Basic authentication. However, we strongly encourage everyone to use OAuth.

OAuth

OAuth is a token-passing mechanism that allows users to control which applications have access to their data without giving away their passwords. More information on the OAuth specification can be found at oauth.net.

We have developed a python OAuth client for our API to help you get started. You can find the required OAuth API credentials on your account settings page.

Our API supports the xAuth extension. This allows your application to request access tokens without a redirect to the Mobile Vikings site, using an account's username and password instead. Your app should not store these user credentials! Only use them once to request the access token and discard them afterwards. xAuth is not enabled by default for your consumer. Send us a mail at api@mobilevikings.com to request it if you're developing a mobile app.

Access tokens do not expire at the moment. A user's access token will be invalidated if the user explicitly revokes your application's authorization or if we suspend your application. If your application is suspended, you'll be notified. In either case, your application should be able to handle token revocation gracefully.

Many users trust an application to read their information but not necessarily change their name or post new statuses. OAuth permissions are granular, allowing applications and users to agree on Read-Only or Read-Write access. Updating information through the REST API, although currently unavailable, requires an HTTP POST. Any API method that requires an HTTP POST is considered a write method and requires Read-Write access.

Basic authentication

Basic Authentication sends the user credentials in clear text in the header of the HTTP request. This makes it easy to use, but less secure, since the user needs to trust the application developer.

Output formats

You can select what response format you want from our API. Just change the emitter_format in the method call.

A list of supported formats:

Throttling

All requests are throttled to 70 reqs / hour. This means you can request the SIM balance for a user 70 times an hour. This limit is per user, not per SIM card. In case you have a high number of SIM cards, you can contact us and we can add an exception for your username. Note that you may also get the 503 - Throttled response in case our servers have issues. Check our status page if you suspect something is going on.

Methods

Only 1 GET parameter is required, msisdn. This will select the correct SIM card. All others are optional, they have defaults that will suffice in most use cases.

MSISDN list

List all MSISDN's the authenticated user has access to.

Endpoint
  • /api/2.0/oauth/msisdn_list.{emitter_format}
  • /api/2.0/basic/msisdn_list.{emitter_format}
Supported methods GET
Optional parameters
alias
will add the alias of the SIM cards, if set to 1. Default: 0
Example output in JSON
[
    "+32486000001",
    "+32486000002"
]
Example output in JSON (with ?alias=1)
[
    {
        "msisdn": "+32470046092",
        "alias": "Test 40"
    },
    {
        "msisdn": "+32486774093",
        "alias": "Test 15"
    },
    {
        "msisdn": "+32489922496",
        "alias": "Test 25"
    },
    {
        "msisdn": "+32489922497",
        "alias": "Test Data-only"
    }
]

 

Price plan details

Get the price plan details of the given mobile number.

The type and type_id represent a traffic type:

  • 1 is voice
  • 2 is data
  • 5 is SMS
  • 7 is MMS
  • 11 is voice super-on-net (between Mobile Vikings)
  • 15 is SMS super-on-net

Bundles is a list of bundle objects, which contain type (a nicer text of what type of bundle it is), a type_id and the amount. For data this is in MB and for voice super-on-net this is in seconds.

Prices is a list of the prices (when bundles have expired), which contain type (a nicer text of what traffic type it is), a type_id and the amount in EUR.

Required parameters
msisdn
the MSISDN (mobile number) of the SIM card you want the details from
Endpoint
  • /api/2.0/oauth/price_plan_details.{emitter_format}
  • /api/2.0/basic/price_plan_details.{emitter_format}
Supported methods GET
Example output in JSON
{
    "prices": [
        {
            "amount": "0.14",
            "type": "Voice call",
            "type_id": 1
        },
        {
            "amount": "0.50",
            "type": "Data sessions (GPRS)",
            "type_id": 2
        },
        {
            "amount": "0.10",
            "type": "SMS",
            "type_id": 5
        },
        {
            "amount": "0.24",
            "type": "MMS",
            "type_id": 7
        }
    ],
    "bundles": [
        {
            "amount": 1000,
            "type": "SMS",
            "type_id": 5
        },
        {
            "amount": 2048,
            "type": "Data sessions (GPRS)",
            "type_id": 2
        },
        {
            "amount": 1000,
            "type": "SMS super-on-net",
            "type_id": 15
        },
        {
            "amount": 3600,
            "type": "Voice super-on-net",
            "type_id": 11
        }
    ],
    "name": "Jumbo",
    "top_up_amount": "40.00"
}

 

SIM balance

Get SIM balance of the given mobile number.

Required parameters
msisdn
the MSISDN (mobile number) of the SIM card you want the details from
Optional parameters
add_price_plan
will add the price plan to each record, if set to 1. Default: 0
Endpoint
  • /api/2.0/oauth/sim_balance.{emitter_format}
  • /api/2.0/basic/sim_balance.{emitter_format}
Supported methods GET
Example output in XML
<response>
        <credits>25.38</credits>
        <sms>997</sms>
        <data>2047550564</data>
        <voice_super_on_net>3600</voice_super_on_net>
        <sms_super_on_net>986</sms_super_on_net>
        <valid_until>2012-06-18 10:22:13</valid_until>
        <is_expired>False</is_expired>
</response>

 

Top-up history

Get the top-up history of the authenticated user.

Required parameters
msisdn
the MSISDN (mobile number) of the SIM card you want the details from
Optional parameters
from_date
results after given date (format: `YYYY-MM-DDTHH:MM:SS`). Default: today
until_date
results before given date (format: `YYYY-MM-DDTHH:MM:SS`). Default: tomorrow
page_size
how many results are on 1 page. Default: 25
page
page number of results. Default: 1
Endpoint
  • /api/2.0/oauth/top_up_history.{emitter_format}
  • /api/2.0/basic/top_up_history.{emitter_format}
Supported methods GET
Example output in YAML
- {amount: '15.00', amount_ex_vat: '12.40',
    executed_on: !!timestamp '2010-03-26 07:55:10',
    method: Paypal,
    payment_received_on: !!timestamp '2010-03-26 07:55:09',
    status: Top-up done}
- {amount: '15.00', amount_ex_vat: '12.40',
    executed_on: !!timestamp '2010-02-21 09:29:48',
    method: Ogone,
    payment_received_on: !!timestamp '2010-02-21 09:29:47',
    status: Top-up done}
- {amount: '15.00', amount_ex_vat: '12.40',
    executed_on: !!timestamp '2010-02-05 08:02:48',
    method: Bank Transfer,
    payment_received_on: !!timestamp '2010-02-05 08:02:46',
    status: Top-up done}
- {amount: '15.00', amount_ex_vat: '12.40',
    executed_on: !!timestamp '2010-01-22 10:30:42',
    method: Manual,
    payment_received_on: !!timestamp '2010-01-22 10:30:41',
    status: Top-up done}

 

Usage

Get the usage of the given mobile number. This is a list of calls, SMSes and data sessions.

The duration_connection is the amount for which the customer was billed. For a voice call this is the length of the call, for a data connection it's the amount of bytes that went through the wire. The duration_call value is the total length of the session. E.g. for a voice connection it's duration_connection plus how long it took before the other side picked up the phone.

The duration_human contains a formatted string depending on the type (data, voice). If no senseable format can be determined, it shows n/a. For voice, it will be formatted as [HH:]MM:SS (with HH being optional). For data, it will be formatted to x MB (or GB or KB or bytes).

Required parameters
msisdn
the MSISDN (mobile number) of the SIM card you want the details from
Optional parameters
from_date
results after given date (format: `YYYY-MM-DDTHH:MM:SS`). Default: today
until_date
results before given date (format: `YYYY-MM-DDTHH:MM:SS`). Default: tomorrow
page_size
how many results are on 1 page. Default: 25
page
page number of results. Default: 1
add_price_plan
will add the price plan to each record, if set to 1. Default: 0
Endpoint
  • /api/2.0/oauth/usage.{emitter_format}
  • /api/2.0/basic/usage.{emitter_format}
Supported methods GET
Example output in JSON
[
    {
        "is_data": false,
        "start_timestamp": "2010-06-30 20:02:59",
        "balance": "0.000000",
        "duration_call": 113,
        "to": "011717431",
        "is_sms": false,
        "timestamp": 1277920979,
        "price": "0.000000",
        "duration_connection": 104,
        "duration_human": "1:44",
        "price_plan": "Jumbo",
        "is_incoming": true,
        "is_voice": true,
        "is_mms": false,
        "end_timestamp": "2010-06-30 20:04:52"
    },
    {
        "is_data": false,
        "start_timestamp": "2010-06-30 16:58:14",
        "balance": "0.000000",
        "duration_call": 1700,
        "to": "078353033",
        "is_sms": false,
        "timestamp": 1277909894,
        "price": "0.000000",
        "duration_connection": 1690,
        "duration_human": "28:10",
        "price_plan": "Classic",
        "is_incoming": true,
        "is_voice": true,
        "is_mms": false,
        "end_timestamp": "2010-06-30 17:26:34"
    }
]

 

SIM card information

Get the SIM card information for the given mobile number.

Required parameters
msisdn
the MSISDN (mobile number) of the SIM card you want the details from
Endpoint
  • /api/2.0/oauth/sim_info.{emitter_format}
  • /api/2.0/basic/sim_info.{emitter_format}
Supported methods GET
Example output in JSON
{
    "msisdn": "+32486000001",
    "cardnumber": "8932030200000000001",
    "pin2": "2222",
    "puk1": "12345678",
    "pin1": "1111",
    "puk2": "87654321",
    "imsi": "123456789098765"
}

 

Viking points statistics

Get statistics about the Viking Points for the user.

Endpoint
  • /api/2.0/oauth/points/stats.{emitter_format}
  • /api/2.0/basic/points/stats.{emitter_format}
Supported methods GET
Example output in JSON
{
    "used_points": 150,
    "unused_points": 750,
    "waiting_points": 150,
    "topups_used": 1,
    "earned_points": 900
}

 

Get the referral link(s) for the user. It is possible a user has multiple links.

Endpoint
  • /api/2.0/oauth/points/links.{emitter_format}
  • /api/2.0/basic/points/links.{emitter_format}
Supported methods GET
Example output in JSON
[
    {
        "alias": "+32496998877",
        "link": "http://mobilevikings.com/en/referral/1/"
    }
]

 

Viking points referrals

Get a list of all the referrals the user created.

Optional parameters
page_size
how many results are on 1 page. Default: 25
page
page number of results. Default: 1
Endpoint
  • /api/2.0/oauth/points/referrals.{emitter_format}
  • /api/2.0/basic/points/referrals.{emitter_format}
Supported methods GET
Example output in JSON
[
    {
        "status": "done",
        "method_str": "referral-sms",
        "amount": 150,
        "date": "2010-10-06 17:54:20",
        "method": "Reward, given by sending a SMS before registration",
        "name": "Tony"
    },
    {
        "status": "awaiting-top-up",
        "method_str": "referral-link",
        "amount": 0,
        "date": "2010-10-06 11:59:05",
        "method": "Referral link",
        "name": "Davy"
    },
    {
        "status": "done",
        "method_str": "viking-story-referral",
        "amount": 0,
        "date": "2010-07-24 19:39:47",
        "method": "Reward given, because of a Viking Story",
        "name": "Jan"
    },
    {
        "status": "done",
        "method_str": "referral-during-registration",
        "amount": 150,
        "date": "2010-07-19 17:27:47",
        "method": "Reward, given during registration",
        "name": "Paul"
    }
]

 

x

Are you sure?

Delete the following?

x