Quick Start Guide

When you first start querying data from the sTN API server, you might feel a little lost. This guide provides a quick tour of the essential steps you may need to take. We'll describe the steps and the API calls to use. You can find the full API descriptions further below.

Step 1: Retrieve a List of Your SIM Cards

If you are a new client beginning to use sTN services, you will first need to retrieve a list of all SIM cards assigned to you. The QuerySimcard API call allows you to do this. (Detailed info: QuerySimcard)

The response provides a list of SIMs assigned to your company. It is recommended to store this list for future reference. The id and simCardNumber fields are particularly important as they uniquely identify each SIM and do not change.

A SIM card with a status of FREE does not yet have a phoneNumber assigned to it. The number will be assigned upon subscription activation.

GET /api/QuerySimcard

To retrieve only unassigned SIM cards:

GET /api/QuerySimcard?status=FREE

Example Response:

[
  {
    "id": "###6a5b###cQvh7wo",
    "simCardNumber": "89310836########76",
    "status": "FREE",
    "simCardType": "USIM"
  }
]

Step 2: Initiate a New Subscription

Once you have retrieved your list of SIMs, you can begin assigning them to customers. Before a SIM card can be used for calls or internet access, a subscription must be activated.

Use the NewSubscription API call to activate a SIM. You must provide the simCardNumber and specify a wishDate (the desired activation date). The subscriptionType should be set to either VOICEDATA (for both calls and data) or DATAONLY (for data use only). The default is VOICEDATA.

(Detailed info: NewSubscription)

POST /api/NewSubscription
Content-Type: application/json
{
    "simCardNumber": "89310836########76",
    "referenceNumber": "Test ###",
    "subscriptionType": "VOICEDATA",
    "wishDate": "2025-01-31T12:00:00+01:00",
    "services": {
        "internationalDialing": false,
        "voiceMail": false,
        "voiceRoaming": true
    }
}

Important:

Subscription activations are processed in the background and are not immediate.
The response will contain an id that can be used to check the activation status later.

Example Response:

{
    "id": "###eP7ds###WQJoIE",
    "createdAt": "2025-01-31T09:01:39.1761963+01:00",
    "modifiedAt": "2025-01-31T09:01:39.1761963+01:00",
    "status": "INIT",
    "activationType": "ACTIVATENEW",
    "referenceNumber": "Test ###",
    "subscriptionId": "###3Vp17###7Xg79e",
    "info": {
        "simCardNumber": "89310836########76",
        "eSim": false,
        "subscriptionType": "VOICEDATA",
        "accessType": "INTERNETACCESS",
        "customerId": "###A1",
        "stnCustomerId": "###Sc3iA###MQCmA89",
        "wishDate": "2025-01-31T12:00:00+01:00",
        "services": {
            "voiceMail": false,
            "voiceRoaming": true,
            "internationalDialing": false
        }
    }
}

Step 3: Check Subscription Activation Status

To check whether a subscription has been activated, use the QueryActivation API call. Provide the activation id from Step 2 to get status updates.

GET /api/QueryActivation?Id=###eP7ds###WQJoIE

Example Response:

{
    "offset": 0,
    "total": 65,
    "results": [{
        "id": "###eP7ds###WQJoIE",
        "createdAt": "2025-01-31T09:01:39.1761963+01:00",
        "modifiedAt": "2025-01-31T09:01:39.1761963+01:00",
        "status": "BUSY",
        "activationType": "ACTIVATENEW",
        "referenceNumber": "Test NewSubscription",
        "subscriptionId": "###mPuAf###WJmSPv",
        "info": {
            "simCardNumber": "89310836########76",
            "eSim": false,
            "subscriptionType": "VOICEDATA",
            "accessType": "INTERNETACCESS",
            "wishDate": "2025-01-31T12:00:00+01:00",
            "services": {
                "voiceMail": false,
                "voiceRoaming": true,
                "internationalDialing": false
            }
        }
    }],
    "meta": {}
}

If you did not store the id, you can query all activation records using a timeframe filter:

GET /api/QueryActivation?createdAtBetween=2025-01-25,2025-02-10&activationType=ACTIVATENEW

Once the status changes to DONE, the SIM has been activated.

Example Response once "ACTIVATED":

{
    "offset": 0,
    "total": 68,
    "results": [
        {
            "id": "###eP7ds###WQJoIE",
            "createdAt": "2025-01-31T09:01:39.176+01:00",
            "modifiedAt": "2025-01-31T10:52:55.537+01:00",
            "status": "DONE",
            "activationType": "ACTIVATENEW",
            "referenceNumber": "Test ###",
            "subscriptionId": "###3Vp17###7Xg79e",
            "phoneNumber": "06-######969",
            "activatedDate": "2025-01-31T11:20:50+01:00",
            "info": {
                "simCardNumber": "89310836########76",
                "eSim": false,
                "subscriptionType": "VOICEDATA",
                "accessType": "INTERNETACCESS",
                "wishDate": "2025-01-31T12:00:00+01:00",
                "services": {
                    "voiceMail": false,
                    "voiceRoaming": true,
                    "internationalDialing": false
                }
            }
        }
    ],
    "meta": {}
}

Step 4: Retrieve Subscription Details

After activation, you can query the subscription details using QuerySubscription.

GET /api/QuerySubscription?Id=###mPuAf###WJmSPv

If activation is complete, the response will include full details, including the assigned phoneNumber.

{
    "offset": 0,
    "total": 0,
    "results": [
        {
            "id": "###3Vp17###7Xg79e",
            "state": "ACTIVE",
            "phoneNumber": "06-######969",
            "simCardNumber": "89310836########76",
            "pin": "####",
            "puk": "########",
            "providerGroup": "KPNMOBIEL",
            "isDataSim": false,
            "isEsim": false,
            "activationDate": "2025-01-31",
            "services": {
                "voiceMail": false,
                "voiceRoaming": true,
                "internationalDialing": false,
                "premiumServices": true,
                "entertainmentServices": true,
                "dataUsageNotification": "No Data Usage Notification",
                "accessType": "Internet Access",
                "internetAccess": true,
                "mobilePay": false,
                "blockData": false,
                "dataRoamingEU": false,
                "notificationInfo": true,
                "unlimitedVoiceNLEUGroup": true,
                "dataRoamingLimitation": "Limit 50",
                "dataRoamingLimitationNotification": true,
                "dataRoamingLimitationOverrideAllowed": true,
                "dataRoamingOutsideEU": true,
                "benefitCountriesA15000MB": true,
                "benefitCountriesA15000MBMax": false,
                "benefitCountriesB7500MB": true,
                "benefitCountriesB7500MBMax": false,
                "restOfTheWorld5000MB": true,
                "restOfTheWorld5000MBMax": false,
                "worldBundle7500MB": false,
                "fixedIp": false,
                "voicePriority": false
            }
        }
    ],
    "meta": {}
}

Step 5: Modify Subscription Services

You can modify a subscription by using SetServicesSubscription. For example, enabling international dialing:

POST /api/SetServicesSubscription
Content-Type: application/json
{
    "subscriptionId": "###3Vp17###7Xg79e",
    "services": {
       "internationalDialing": true
    }
}

Example Response:

{
    "id": "###WaEac###McgYzl",
    "createdAt": "2025-01-31T15:47:38.1146014+01:00",
    "modifiedAt": "2025-01-31T15:47:38.1146014+01:00",
    "status": "INIT",
    "activationType": "SETSERVICES",
    "referenceNumber": "",
    "subscriptionId": "###3Vp17###7Xg79e",
    "phoneNumber": "06-######969",
    "info": {
        "services": {
            "internationalDialing": true
        }
    }
}

Check the status of the change with QueryActivation:

GET /api/QueryActivation?Id=###WaEac###McgYzl

If status changes to DONE, the modification is complete.

Conclusion

Every API modification that involves a POST request creates an Activation record. To track changes:

Send the request.
Store the response id.
Use QueryActivation to check progress.
Once the status is DONE, retrieve full details with QuerySubscription.