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
Webhooks	https://api.transatel.com/webhooks/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 create a webhook and subscribe to the following events:

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

Please check the integration guide to learn more about it.

To do so, we will use the Webhooks API.

The below example shows how to create a webhook and subscribe to those events:

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 \
    "{
      \"mvnoRef\": \"MVNA_PAYM_UK_OUK_INTERNAL\",
      \"status\": \"active\",
      \"targetUrl\": \"https://example.com/events\",
      \"email\": \"support@company.com\",
      \"events\": [
        \"CONNECTIVITY-MANAGEMENT/PORTABILITY/UK/PORT_IN/VALIDATED\",
        \"CONNECTIVITY-MANAGEMENT/PORTABILITY/UK/PORT_IN/DONE\"
      ]
    }" \
    'https://api.transatel.com/webhooks/api/webhooks'

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

Authorization header: This is where you provide the previously retrieved access_token
mvnoRef: Customer account name provided by Transatel at setup
targetUrl: The HTTPS url to which events will be posted
events: An array with the events you want to subscribe to, here the portability request validation and completion event

If successful, the response returned will be as follows:

HTTP/1.1 201 Created
X-TSL-Request-Id: b87f1c60-aadc-4685-bd31-1f85cdbeca3c
Content-Type: application/json
{
  "Id": "257728ad-01ed-447d-b923-062604926f95",
  "mvnoRef": "MVNA_PAYM_UK_OUK_INTERNAL",
  "status": "active",
  "targetUrl": "https://example.com/events",
  "email": "support@company.com",
  "events": [
    {
      "eventType": "CONNECTIVITY-MANAGEMENT/PORTABILITY/UK/PORT_IN/VALIDATED",
      "domain": "CONNECTIVITY-MANAGEMENT",
      "category": "portability",
      "description": "An ingoing portability request has been validated",
      "_links": {
        "doc": {
          "href": "https://developers.transatel.com/api/connectivity-management/events/#tag/Portability-UK/paths/CONNECTIVITY-MANAGEMENT~1PORTABILITY~1UK~1PORT_IN~1VALIDATED/post"
        }
      }
    },
    {
      "eventType": "CONNECTIVITY-MANAGEMENT/PORTABILITY/UK/PORT_IN/DONE",
      "domain": "CONNECTIVITY-MANAGEMENT",
      "category": "portability",
      "description": "An ingoing portability request has been done",
      "_links": {
        "doc": {
          "href": "https://developers.transatel.com/api/connectivity-management/events/#tag/Portability-UK/paths/CONNECTIVITY-MANAGEMENT~1PORTABILITY~1UK~1PORT_IN~1DONE/post"
        }
      }
    },
  ],
  "_links": {
    "self": {
      "href": "https://api.transatel.com/webhooks/api/webhooks/257728ad-01ed-447d-b923-062604926f95"
    }
  }
}

A successful response returns a HTTP/1.1 201 Created with the details of the webhook.

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/8988247076000000319/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": "8988247076000000319",
  "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": "8988247076000000319",
    "externalReference": "RX12345ZVGT",
    "source": "api",
    "portabilityStatus": "VALIDATED",
    "portabilityDate": "2023-04-21",
    "authorizationCode": {
      "type": "PAC",
      "code": "ONE007628"
    },
    "subscriberNumber": "12345678.00000001"
  }
}

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

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-19T13:30:00Z"
  },
  "body": {
    "transactionId": "139311f7-63c0-4f51-adeb-3c5e36a5e746",
    "mvnoRef": "MVNA_PAYM_UK_OUK_INTERNAL",
    "msisdn": "447123456789",
    "portabilityMsisdn": "447123456789",
    "simSerial": "8988247076000000319",
    "externalReference": "RX12345ZVGT",
    "source": "api",
    "portabilityStatus": "DONE",
    "portabilityDate": "2023-04-21",
    "authorizationCode": {
      "type": "PAC",
      "code": "ONE007628"
    },
    "dno": "VF",
    "rno": "HM",
    "subscriberNumber": "12345678.00000001"
  }
}

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

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