Porting a UK MSISDN from another network

Discover how to activate a subscriber while keeping their MSISDN

You are a UK MVNO and you have received your first SIM cards (physical or eSIM codes), you will be able to activate a subscriber to benefit from Transatel connectivity while keeping their MSISDN.

The process allowing your end user to switch from another network is a mobile number portability. This guide shows you how to proceed and get confirmation of the activation and the portability thanks to the events you will subscribe to.

Endpoints

Below are all APIs url that you will need for this guide:

Transatel APIs	URL
Authentication	https://api.transatel.com/authentication/api
Connectivity Management	https://api.transatel.com/connectivity-management/subscribers/api

All Transatel APIs are available through our unique API gateway https://api.transatel.com

1. Activate your subscriber

First things first, let's activate your subscriber by following this step by step guide. Keep your access token, you will reuse it to launch the portability process.

According to your business need, you may need to receive events regarding the eligibility of your portability request and finally when your subscriber portability is complete. If so, you will need to subscribe to the following events:

CONNECTIVITY-MANAGEMENT/PORTABILITY/UK/PORT_IN/VALIDATED
CONNECTIVITY-MANAGEMENT/PORTABILITY/UK/PORT_IN/DONE

If you haven't registered a data Stream yet, go to the Transatel Console and:

Click the Add data stream button under the Data Stream tab
Select the CONNECTIVITY-MANAGEMENT/PORTABILITY/UK/PORT_IN/VALIDATED and CONNECTIVITY-MANAGEMENT/PORTABILITY/UK/PORT_IN/DONE events from the Subscribers category
Choose your preferred destination type
Fill all the data stream information and click on the Create data stream button

If you already have a data Stream, go to the Transatel Console and:

Click on Edit on the contextual menu (...) of the given data stream under the Data Stream tab
Select the CONNECTIVITY-MANAGEMENT/PORTABILITY/UK/PORT_IN/VALIDATED and CONNECTIVITY-MANAGEMENT/PORTABILITY/UK/PORT_IN/DONE events from the Subscribers category
Click on the Update data stream button

Please check the Data stream page for more information.

3. Request portability

Now that we are ready to proceed, let's request the portability!

To do so, you must use the Connectivity management subscriber API and provide at least:

sim-serial: SIM card serial number. It can be found in the delivery file listing all information about SIM cards you have ordered.
portabilityMSISDN: the MSISDN you want to port in.
code: the valid PAC associated to the MSISDN you want to port in.

The below example shows how to request a portability:

curl --location --request POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJidXNpbmVzc19lbnRpdGllcyI6WyJBbnkiXSwicHJpbmNpcGFsIjoib2NzLXN1YnNjcmlwdGlvbi1vcmRlci1tYW5hZ2VyIiwic2NvcGUiOlsiQ0FUQUxPR19QUk9EVUNUU19SRUFEX1RFQ0hOSUNBTCIsIkNBVEFMT0dfUFJPRFVDVFNfUkVBRCIsIlVTRVJfUkVBRCIsIklOVkVOVE9SWV9TVUJTQ1JJUFRJT05TX1JFQUQiXSwiZXhwIjoxNjE3MjYwNTYxLCJhdXRob3JpdGllcyI6WyJST0xFX0lOVEVSTkFMX1NZU1RFTSJdLCJqdGkiOiJmOTYwNTFmNS05ZmQzLTQxMDEtYjNkZC0xZjY2Y2Q2MWUzZjIiLCJjbGllbnRfaWQiOiJvY3Mtc3Vic2NyaXB0aW9uLW9yZGVyLW1hbmFnZXIifQ.KBTlltd459_4kPV0O3OfsBTFGBtoqRxG65o_NohK1U7IuJAvIjAa8Fj4Qon1ptFrrTR5M2o8l0f9Dl0D7r0Us6Ej6OsVlFXfQKUiXwVytNUTP7POB6l56Svc5CaVqkXgFKyt7_8h6Ii6R_RteujtSzJSWX7zeLSeemxsxKNtHLLIS_HLyNdQyIsVCZWRfFhdPJVQId_p6B08_A54sAwhrT7qssSbtpG1nGzdqsHdFfaqJt9ABhPedatHNlwcWtCnFthrOrD2rv0Yf8OnRLnt-ZWtypr0cqm6U-brtZeBMhcxgzF4afKlJbKN3K3drPJRrRPjL8L9bf2YvzsDWxY5lA' \
    --data \
    "{
        \"portabilityMSISDN\": \"447123456789\",
        \"authorizationCode\": {
          \"type\": \"PAC\",
          \"code\": \"ONE007628\"
        },
        \"wishedPortabilityDate\": \"2023-04-19\"
    }" \
    'https://api.transatel.com/connectivity-management/api/portability/uk/sim-serial/8944120000123456789/request'

Above are highlighted the main information to provide to the API:

Authorization header: This is where you provide the previously retrieved access_token
wishedPortabilityDate: an optional date for the portability execution. If you don't provide it, the portability will be executed when the subscriber will be attached to Transatel network.

In order to terminate the contract on the donor side but without porting the MSISDN, you can provide a STAC instead of a PAC.

If successful, the response returned will be as follows:

HTTP/1.1 201 Created
X-TSL-Request-Id: 58af166e-1a57-4d7a-abb5-a1a5b7d5510e
Content-Type: application/json
{
  "transactionId": "c1e2fac8-0572-4e2c-a487-c3cc5cbbc85c",
  "simSerial": "8944120000123456789",
  "transactionStatus": "PENDING"
}

A successful response returns a HTTP/1.1 201 Created, meaning that your portability request has been accepted.

The response will contain the following main information:

transactionId: Unique identifier generated for this transaction
transactionStatus: PENDING means this is an asynchronous request

At this step, the portability request is being processed in our back-end and a validation request is sent to Syniverse.

4. Receive portability request validation event (optional)

If you have subscribed to portability request validation event in step 2, once a successful response from Syniverse has been received, then you will also receive a CONNECTIVITY-MANAGEMENT/PORTABILITY/UK/PORT_IN/VALIDATED event like the one shown below:

{
  "header": {
    "eventId": "627e77fc-7694-4188-8f19-13ca3dbf8f51",
    "eventType": "CONNECTIVITY-MANAGEMENT/PORTABILITY/UK/PORT_IN/VALIDATED",
    "eventDate": "2023-04-19T13:30:00Z"
  },
  "body": {
    "transactionId": "139311f7-63c0-4f51-adeb-3c5e36a5e746",
    "mvnoRef": "MVNA_PAYM_UK_OUK_INTERNAL",
    "msisdn": "447001020304",
    "portabilityMsisdn": "447123456789",
    "simSerial": "8944120000123456789",
    "subscriberNumber": "12345678.00000001",
    "primaryImsi": "234330123456789",
    "source": "api",
    "externalReference": "RX12345ZVGT",
    "portabilityStatus": "VALIDATED",
    "portabilityDate": "2023-04-21",
    "authorizationCode": {
      "type": "PAC",
      "code": "ONE007628"
    }
  }
}

You will be able to identify this subscriber portability request validation event thanks to the eventType, transactionId and simSerial fields.

Additionally, you can check the generated events directly in the Transatel Console under the Data stream tab, where you can view the event delivery history and status for your webhook data stream.

To learn more about the definition of this event, please check the connectivity management events page.

5. Receive portability completion event (optional)

The day before the portability, the request is frozen, meaning you cannot cancel it anymore. If you have subscribed to portability completion event in step 2, once the portability is executed and the MSISDN is ported then you will receive a CONNECTIVITY-MANAGEMENT/PORTABILITY/UK/PORT_IN/DONE event like the one shown below:

{
  "header": {
    "eventId": "627e77fc-7694-4188-8f19-13ca3dbf8f51",
    "eventType": "CONNECTIVITY-MANAGEMENT/PORTABILITY/UK/PORT_IN/DONE",
    "eventDate": "2023-04-21T13:30:00Z"
  },
  "body": {
    "transactionId": "139311f7-63c0-4f51-adeb-3c5e36a5e746",
    "mvnoRef": "MVNA_PAYM_UK_OUK_INTERNAL",
    "msisdn": "447123456789",
    "portabilityMsisdn": "447123456789",
    "simSerial": "8944120000123456789",
    "subscriberNumber": "12345678.00000001",
    "primaryImsi": "234330123456789",
    "source": "api",
    "externalReference": "RX12345ZVGT",
    "portabilityStatus": "DONE",
    "portabilityDate": "2023-04-21",
    "authorizationCode": {
      "type": "PAC",
      "code": "ONE007628"
    },
    "dno": "VF",
    "rno": "HM"
  }
}

You will be able to identify this subscriber portability completion event thanks to the eventType, transactionId and simSerial fields.

Additionally, you can check the generated events directly in the Transatel Console under the Data stream tab, where you can view the event delivery history and status for your webhook data stream.

To learn more about the definition of this event, please check the connectivity management events page.

Sometimes, you may want to cancel the request before its execution or the donor operator may have rejected it. In order to be notified of those events you may want to subscribe to them.

Please check the connectivity management events page, to discover those events.

What to do next?

Learn more about our Connectivity management API by checking the overview documentation and API reference