InPortSubscription

Overview

Method: POST
Endpoint: /api/InPortSubscription
Description: Transfers an existing phone number to a new subscription. This endpoint allows configuring the porting details, selecting the subscription type, and enabling additional services.

POST /api/InPortSubscription
Content-Type: application/json
{
    "phoneNumber": "06-######830",
    "subscriptionType": "VOICEDATA",
    "eSim": true,
    "email": "###@###.nl",
    "confirmationCode": "###########",
    "stnCustomerId": "###Sc3iA###MQCmA89",
    "portingWishDate": "2025-02-20T01:00:00+01:00",
    "note": "Inport request",
    "donorCustomerNumber": "######",
    "services": {
        "dataUsageNotification": "Data Usage Notification 500 MB",
        "dataRoamingLimitation": "Limit 50",
        "premiumServices": true,
        "voiceMail": true
    }
}

Request Body Parameters

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

phoneNumber (string, required): The phone number to be ported.
donorCustomerNumber (string, required): The customer number of the donor provider.
donorCustomerName (string, optional): Name of the donor provider.
portingWishDate (string, optional): The desired date for porting (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.
note (string, optional, max 164 characters): Additional notes related to the porting request.
services (object, optional): Defines additional services linked to the subscription.

Info

If eSim is set to true, an email and confirmationCode must be provided for activation.

If no portingWishDate is provided the porting will be effected as soon as allowed by the outporting party.

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.

Response Structure

The response returns an Activation object containing details of the porting request: (Mind, it can take a little while before the out-going party has responded to the request; untill then the portingStatus will stay 'INIT'.)

{
    "id": "###T3mhh###UBxCSZ",
    "createdAt": "2025-02-06T12:26:41.905+01:00",
    "modifiedAt": "2025-02-06T12:48:21.806+01:00",
    "status": "BUSY",
    "activationType": "INPORT",
    "providerEnvironment": "SP16001",
    "referenceNumber": "",
    "providerOrderNumber": "03####0/2##5",
    "subscriptionId": "###kh6QS###pWisPr",
    "phoneNumber": "06-######830",
    "info": {
        "isdn": "06-######830",
        "eSim": true,
        "subscriptionType": "VOICEDATA",
        "accessType": "INTERNETACCESS",
        "portingStatus": "INIT",
        "email": "###@###.nl",
        "confirmationCode": "##########",
        "stnCustomerId": "###Sc3iA###MQCmA89",
        "portingWishDate": "2025-02-20T01:00:00+01:00",
        "donorCustomerNumber": "######",
        "note": "Inport request naar ###"
    }
}

Field Descriptions

id: A unique identifier for the activation request.
createdAt: The timestamp when the activation request was created.
modifiedAt: The timestamp when the activation request was last modified.
status: The current status of the activation request:
- BUSY: The request is being processed.
- DONE: The porting has been successfully completed.
- ERROR: The request has failed.
activationType: Always set to INPORT for this request.
providerEnvrionment: The envrionment at the Provider where the activation is registered.
subscriptionId: The ID of the newly created subscription.
providerOrderNumber: The ordernummer which the service provider assigned to this request.
phoneNumber: The phone number being ported.
referenceNumber: The provided reference number for tracking purposes.
activatedDate: The timestamp when the porting process was completed.
info: Additional metadata related to the porting process.

Info

Only optional fields that were included in the request will appear in the response.

Warning

The in-porting process requires approval from the out-porting party. This approval may depend on ongoing contracts with the current provider, which can cause delays. Until confirmation is received with an initial porting date, the portingStatus in the info object will remain 'INIT'. Additionally, the firstPossibleDate and approvedDate fields will not be included in the response.

Beware that In-porting an number with an active contract at the out-porting party, may have financial consequenses for the customer when terminating this contract. You do not get a warning about an ongoing contract.

Usage Notes

The phoneNumber, donorCustomerNumber, and customerId are mandatory.
Use portingWishDate to schedule porting; otherwise, it will be processed immediately.
The services object can be used to configure additional features during the porting process.
For eSIM porting, ensure a valid email is provided.
Store the id from the response to track the porting status.
Check the NewSubscription API Call for a full list of the services.

Info

You can use the ChangeInPortSubscription message in case your receive an 'ERROR' on your request indicating the donorCustomerNumber is incorrect. Or you can just send a new InPortSubscription request.

Querying Porting Status

To track the status of the porting request, use the QueryActivation API until the status field is set to DONE or ERROR.

GET /api/QueryActivation?id=###P6LtM###hT3yZv

Example Response:

{
    "offset": 0,
    "total": 86,
    "results": [
        {
            "id": "###T3mhh###UBxCSZ",
            "createdAt": "2025-02-06T12:26:41.905+01:00",
            "modifiedAt": "2025-02-06T12:48:21.806+01:00",
            "status": "BUSY",
            "activationType": "INPORT",
            "providerEnvironment": "SP16001",
            "referenceNumber": "",
            "providerOrderNumber": "03####0/2##5",
            "subscriptionId": "###kh6QS###pWisPr",
            "phoneNumber": "06-######830",
            "info": {
                "isdn": "06-######830",
                "eSim": true,
                "subscriptionType": "VOICEDATA",
                "accessType": "INTERNETACCESS",
                "portingStatus": "APPROVED",
                "email": "###@###.nl",
                "confirmationCode": "##########",
                "stnCustomerId": "###Sc3iA###MQCmA89",
                "portingWishDate": "2025-02-20T01:00:00+01:00",
                "donorCustomerNumber": "######",
                "note": "Inport request naar ###",
                "firstPossibleDate": "2025-02-06T09:30:00+01:00",
                "approvedDate": "2025-02-20T01:00:00+01:00"
            }
        }
    ],
    "meta": {}
}

Error Response

An Inport request can end with a status 'ERROR'. Check the info object for further explaination. The response looks as follows:

{
    "offset": 0,
    "total": 90,
    "results": [
        {
            "id": "###Jjsn2###VOhfLl",
            "createdAt": "2025-02-06T16:41:31.813+01:00",
            "modifiedAt": "2025-02-06T16:52:58.886+01:00",
            "status": "ERROR",
            "activationType": "INPORT",
            "providerEnvironment": "SP16001",
            "referenceNumber": "",
            "subscriptionId": "###kh6QS###pWisPr",
            "phoneNumber": "06-######830",
            "info": {
                "isdn": "06-######830",
                "eSim": true,
                "subscriptionType": "VOICEDATA",
                "accessType": "INTERNETACCESS",
                "portingStatus": "REJECTED",
                "email": "###@###.nl",
                "confirmationCode": "####/####\\",
                "stnCustomerId": "###Sc3iA###MQCmA89",
                "portingWishDate": "2025-02-20T01:00:00+01:00",
                "donorCustomerNumber": "06-######830",
                "note": "Inport request van ###",
                "portingMessage": "Combination of MSISDN and Customer code is invalid."
            }
        }
    ],
    "meta": {}
}

portingMessage: field wil contain the reason for 'REJECTED'!

Summary

The /api/InPortSubscription endpoint facilitates number porting to a new subscription.

Requires phoneNumber, donorCustomerNumber, and customerId.
Supports scheduling via portingWishDate.
Allows configuring additional services during porting.
Provides a tracking id to monitor porting status via QueryActivation.

Use this API to efficiently transfer existing phone numbers to new subscriptions.