Request a FR MSISDN portability with activation

Discover how to activate a subscriber while keeping their MSISDN

You are a French 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. API Authentication

First things first, let's get your access token by following the getting started guide!

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

CONNECTIVITY-MANAGEMENT/PORTABILITY/FR/PORT_IN/ELIGIBILITY_OK
CONNECTIVITY-MANAGEMENT/PORTABILITY/FR/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_FR_OFR_INTERNAL\",
        \"status\": \"active\",
        \"targetUrl\": \"https://example.com/events\",
        \"email\": \"support@company.com\",
        \"events\": [
          \"CONNECTIVITY-MANAGEMENT/PORTABILITY/FR/PORT_IN/ELIGIBILITY_OK\",
          \"CONNECTIVITY-MANAGEMENT/PORTABILITY/FR/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 eligibility and completion event

If successful, the response returned will be as follows:

HTTP/1.1 201 Created
X-TSL-Request-Id: 358ed9ff-af09-4af1-aa8f-cb752a63a27f
Content-Type: application/json
{
  "Id": "257728ad-01ed-447d-b923-062604926f95",
  "mvnoRef": "MVNA_FR_OFR_INTERNAL",
  "status": "active",
  "targetUrl": "https://example.com/events",
  "email": "support@company.com",
  "events": [
    {
      "eventType": "CONNECTIVITY-MANAGEMENT/PORTABILITY/FR/PORT_IN/ELIGIBILITY_OK",
      "domain": "CONNECTIVITY-MANAGEMENT",
      "category": "portability",
      "description": "An ingoing portability request has been declared eligible",
      "_links": {
        "doc": {
          "href": "https://developers.transatel.com/api/connectivity-management/events/#tag/Portability-FR/paths/CONNECTIVITY-MANAGEMENT~1PORTABILITY~1FR~1PORT_IN~1ELIGIBILITY_OK/post"
        }
      }
    },
    {
      "eventType": "CONNECTIVITY-MANAGEMENT/PORTABILITY/FR/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-FR/paths/CONNECTIVITY-MANAGEMENT~1PORTABILITY~1FR~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. Activate the subscriber keeping its MSISDN

Now that we are ready to proceed, let's activate a subscriber and request the portability at the same time to keep the MSISDN!

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.
ratePlan: rate plan that you want to apply to this new subscriber. This identifier is provided by Transatel at contract signature.
portabilityMSISDN: the MSISDN you want to port in.
rio: RIO associated to the MSISDN you want to port in.
portabilityDate: the date you want the portability to be executed.

The below example shows how to activate a subscriber with TSL_BAR_DATA option activated:

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 \
    "{
        \"ratePlan\": \"M2MA_WW_TSL_PPU_A\",
        \"portabilityMSISDN\": \"33601234567\",
        \"rio\": \"80EM0017H+DE\",
        \"portabilityDate\": \"2023-04-19\",
        \"externalReference\": \"RX12345ZVGT\",
        \"group\": \"Group A1\",
        \"subscriberCountryOfResidence\": \"FR\",
        \"options\": [
            {
                \"name\": \"TSL_BAR_DATA\",
                \"value\": \"on\"
            }
        ]
    }" \
    'https://api.transatel.com/connectivity-management/api/portability/fr/sim-serial/8988247076000000319/activate-request'

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

Authorization header: This is where you provide the previously retrieved access_token.
options: an array of optional services you want to activate or deactivate for this subscriber. Here, the ability for the subscriber to initiate a data session is forbidden. When options are not provided a default value is applied. The full list of available options with their default values is provided by Transatel at contract signature.
group: subscriber's associated group name
subscriberCountryOfResidence: country of residence of the subscriber.
externalReference: your reference that you may want to register in Transatel system.

If successful, the response returned will be as follows:

HTTP/1.1 201 Created
X-TSL-Request-Id: 39eb71c3-2043-4cb3-830b-63e75820a9a9
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 activation 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 an eligibility request is sent to the donor.

4. Receive portability eligibility event (optional)

If you have subscribed to portability eligibility events in step 2, once a successful response from the donor operator has been received, then you will also receive a CONNECTIVITY-MANAGEMENT/PORTABILITY/FR/PORT_IN/ELIGIBILITY_OK event like the one shown below:

{
  "header": {
    "eventId": "627e77fc-7694-4188-8f19-13ca3dbf8f51",
    "eventType": "CONNECTIVITY-MANAGEMENT/PORTABILITY/FR/PORT_IN/ELIGIBILITY_OK",
    "eventDate": "2023-04-19T13:30:00Z"
  },
  "body": {
    "transactionId": "139311f7-63c0-4f51-adeb-3c5e36a5e746",
    "mvnoRef": "MVNA_FR_OFR_INTERNAL",
    "msisdn": "33601020304",
    "portabilityMsisdn": "33601234567",
    "simSerial": "8988247076000000319",
    "externalReference": "RX12345ZVGT",
    "source": "api",
    "portabilityStatus": "ELIGIBILITY_OK",
    "portabilityDate": "2023-04-21",
    "rio": "80EM0017H+DE",
    "dno": "01",
    "rno": "80",
    "subscriberNumber": "12345678.00000001"
  }
}

You will be able to identify this subscriber portability eligibility 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 neither you nor the donor can cancel nor reject it. If you have subscribed to portability completion event in step 2, once the portability is executed and the subscriber is created with the portability MSISDN and its SIM card activated with all services then you will receive a CONNECTIVITY-MANAGEMENT/PORTABILITY/FR/PORT_IN/DONE event like the one shown below:

{
  "header": {
    "eventId": "627e77fc-7694-4188-8f19-13ca3dbf8f51",
    "eventType": "CONNECTIVITY-MANAGEMENT/PORTABILITY/FR/PORT_IN/DONE",
    "eventDate": "2023-04-19T13:30:00Z"
  },
  "body": {
    "transactionId": "139311f7-63c0-4f51-adeb-3c5e36a5e746",
    "mvnoRef": "MVNA_FR_OFR_INTERNAL",
    "msisdn": "33601234567",
    "portabilityMsisdn": "33601234567",
    "simSerial": "8988247076000000319",
    "externalReference": "RX12345ZVGT",
    "source": "api",
    "portabilityStatus": "DONE",
    "portabilityDate": "2023-04-21",
    "rio": "80EM0017H+DE",
    "dno": "01",
    "rno": "80",
    "subscriberNumber": "12345678.00000001"
  }
}

You will be able to identify this 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 EGP 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