NewSubscription

Overview

• Method: POST
• Endpoint: /api/NewSubscription
• Description: Creates a new subscription with a new phone number. This endpoint provisions a new subscription, including the configuration of subscription type and additional services.

POST /api/NewSubscription
{
  "wishDate": "2025-01-30T12:00:00+01:00",
  "eSim": 1
}

---

Request Body Parameters

The request body should be a JSON object with the following structure:

• wishDate (string, optional): Desired date and time for subscription activation (ISO 8601 format).
• providerEnvironment (string, optional): Desired provider environment. Default is SP16001.
• eSim (boolean, optional): Indicates if the subscription uses an eSIM.
• simCardNumber (string, conditional): SIM card number for the new subscription.
• subscriptionType (string, optional): Defines the type of subscription (VOICEDATA or DATAONLY). Default is VOICEDATA.
• email (string, conditional): Required for eSIM activation; email address for communication eSIM activation details to the customer.
• confirmationCode (string, conditional max 10 characters): Required for eSIM activation; user-defined confirmation code.
• referenceNumber (string, optional max 15 characters): A reference number for tracking the subscription.
• stnCustomerId (string, optional): The sTN Customer identifier. Required if your organization has multiple customer numbers.
• accessType (string, optional): The type of access for the subscription. Allowed values: INTERNETACCESS (default) and MOBILEPAY.
• services (object, optional): Defines additional services linked to the subscription.

Warning

• If both simCardNumber and eSim=true are provided, the request will be handled as an eSIM subscription, and simCardNumber is ignored.
• The stnCustomerId field is required only if your organization has multiple customer numbers in the sTN system.
• The confirmationCode is mandatory when activating an eSIM; the user must enter this code to install the eSIM.

Table possible providerEnvironments

Environment	Description	Default
SP16001	KPN SP16	true
SP16002	KPN Unlimited

Info

Please be aware that before using a providerEnvironment other than the default, you must first discuss this with your account manager, as the subscription fees differ and will affect the monthly costs invoiced to your company.

---

Services Configuration

The services object allows you to enable or disable specific features:

Table allowed services

Service	Description	Allowed Values	Default
voiceMail	Voicemail	true/false	false
voiceRoaming	Speach roaming (number is used in foreign country)	true/false	true
internationalDialing	Caling to foreign country (number is used within NL)	true/false	false
premiumServices	Premium services (0900)	true/false	true
entertainmentServices	0906, 0909 en 18xy numbers	true/false	true
internetAccess	Standard internet access	true/false	true
mobilePay	APN for Mobilepay	true/false	false
blockData	Block internet access	true/false	false
dataRoamingEU	Data roaming in EU countries	true/false	false
dataRoamingOutsideEU	Data roaming outside EU	true/false/null	null
benefitCountriesA15000MB	Benefit Countries A 15 GB	true/false	true
benefitCountriesA15000MBMax	Maximum of 10 per month (countries A)	true/false	false
benefitCountriesB7500MB	Benefit Countries B 7.5 GB	true/false	true
benefitCountriesB7500MBMax	Maximum of 10 per month (countries B)	true/false	false
restOfTheWorld5000MB	Rest of the World bundle 5 GB	true/false	true
restOfTheWorld5000MBMax	Maximum of 10 per month (countries row)	true/false	false
worldBundle7500MB	World Bundle per 7.5 GB	true/false	false
worldBundle7500MBMax	Maximum of 10 per month (world bundle)	true/false	false
notificationInfo	Receive foreign tariffs in an sms when abroad	true/false	true
dataRoamingLimitationNotification	KPN limit data roaming notification on/off	true/false	true
dataRoamingLimitationOverrideAllowed	KPN limit data roaming exceeding allowed	true/false	true
fixedIp	Fixed IP address*	true/false	false
blockExceptionCountries	Block country exceptions	true/false	false
blockSatelliteDestinations	Block satellite destinations	true/false	false
dataUsageNotification	Set that the end user receives a notification at certain data usage NL/EU	No Data Usage Notification Data Usage Notification 1000 MB Data Usage Notification 2000 MB Data Usage Notification 3000 MB Data Usage Notification 5000 MB Data Usage Notification 6000 MB Data Usage Notification 8000 MB Data Usage Notification 10000 MB Data Usage Notification 12000 MB Data Usage Notification 15000 MB Data Usage Notification 20000 MB Data Usage Notification 25000 MB Data Usage Notification 50000 MB	No Data Usage Notification
dataRoamingLimitation	Limit in EUROS for data usage abroad	No Limit Limit 10 Limit 30 Limit 50 Limit 100 Limit 150 Limit 200 Limit 500 Limit 1000 Limit 2000 Limit 5000	Limit 50

Info

^* Setting 'fixedIp' might need changes in settings on the device, for instance the APN settings. Contact the service desk about the neccesary changes. After setting the 'fixedIP' you will find the assigned IP address in the subscription information.

---

Response Structure

The response returns an Activation object with the following fields:

{
  "id": "string",
  "createdAt": "string (ISO 8601 datetime)",
  "modifiedAt": "string (ISO 8601 datetime)",
  "status": "string",
  "activationType": "string",
  "referenceNumber": "string",
  "subscriptionId": "string",
  "phoneNumber": "string",
  "activatedDate": "string (ISO 8601 datetime)",
  "info": {}
}

Field Descriptions

• id: A unique identifier for the activation request.
• createdAt: The timestamp when the activation request was created.
• modifiedAt: The timestamp of the last modification to the activation request.
• status: The current activation status:
  • INIT: The activation request is being initialized.
  • BUSY: The activation is being processed.
  • DONE: The activation has been completed successfully.
  • ERROR: The activation request has failed.
• activationType: Always set to ACTIVATENEW for new subscriptions.
• referenceNumber: A reference for tracking purposes.
• subscriptionId: The unique ID of the newly created subscription.
• phoneNumber: The assigned phone number (if available).
• activatedDate: The date and time when activation was completed.
• info: Additional metadata related to the activation request.

Warning

• The id in the response is required to track or cancel the subscription. Store it for future reference.
• The response includes a phoneNumber field, but it will initially be blank. You must query QueryActivation later to retrieve the assigned phone number.

---

Usage Notes

• If wishDate is omitted, the subscription is activated immediately.
• For eSIM subscriptions, an email is required to provision the eSIM.
• The services object should list only the desired services for the subscription.

---

Example Requests

Create a subscription with a physical SIM card

POST /api/NewSubscription
Content-Type: application/json

{
  "wishDate": "2025-01-30T12:00:00+01:00",
  "eSim": false,
  "simCardNumber": "8945001234567890123",
  "subscriptionType": "VOICEDATA",
  "email": "customer@example.com",
  "confirmationCode": "ABC123",
  "referenceNumber": "REF20241127",
  "stnCustomerId": "67890",
  "accessType": "INTERNETACCESS",
  "services": {
    "dataRoamingLimitation": "Limit 100",
    "dataUsageNotification": "Data Usage Notification 5000 MB"
  }
}

Create a subscription with an eSIM

POST /api/NewSubscription
Content-Type: application/json

{
  "wishDate": "2025-01-30T12:00:00+01:00",
  "eSim": true,
  "email": "customer@example.com",
  "subscriptionType": "VOICEDATA",
  "confirmationCode": "XYZ987",
  "referenceNumber": "REF20241128",
  "accessType": "INTERNETACCESS",
  "services": {
    "dataRoamingLimitation": "Limit 50"
  }
}

---

Example Errors

Create a subscription for esim with missing required fields

POST /api/NewSubscription
Content-Type: application/json
{
    "referenceNumber":"Test esim",
    "subscriptionType":"VOICEDATA",
    "wishDate": "2025-01-03T12:00:00+01:00",
    "subscriptionType": "VOICEDATA",
    "accessType": "INTERNETACCESS",
    "esim": true,
    "services": {
        "internationalDialing": false,
        "voiceMail": false,
        "voiceRoaming": true
    }

}

Response:

{
    "responseStatus": {
        "errorCode": "BadRequest",
        "message": "Email address is required when activating an eSim",
        "errors": []
    }
}

---

Summary

The /api/NewSubscription endpoint allows for the provisioning of new subscriptions with detailed configuration options.

• Supports eSIM and physical SIM activation.
• Enables configuration of additional services.
• Returns a reference ID for tracking and querying activation status.

Use this API to efficiently create and manage new mobile subscriptions.