Activating a subscriber

Discover how to activate your first subscriber

After reception of your first SIM cards (physical or eSIM codes), you will be able to activate a subscriber to benefit from Transatel connectivity. This guide shows you how to proceed and get confirmation of this activation thanks to the event 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. API Authentication

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

According to your business need, you may need to receive events when your subscribers activation is complete. If so, you will need to subscribe to activation events: CONNECTIVITY-MANAGEMENT/SUBSCRIBER/ACTIVATED.

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/SUBSCRIBER/ACTIVATED event 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/SUBSCRIBER/ACTIVATED event from the Subscribers category
Click on the Update data stream button

Please check the Data stream page for more information.

3. Activate the subscriber

Now that we are ready to proceed, let's activate a subscriber!

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.

The below example shows how to activate a subscriber with M2M_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_1\",
        \"externalReference\": \"RX12345ZVGT\",
        \"group\": \"Group A1\",
        \"subscriberCountryOfResidence\": \"FR\",
        \"options\": [
            {
                \"name\": \"M2M_TSL_BAR_DATA\",
                \"value\": \"on\"
            }
        ]
    }"\
    'https://api.transatel.com/connectivity-management/subscribers/api/subscribers/sim-serial/8933220000123456789/activate'

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: bca88afe-97b3-43c2-8ca2-0a27e31c9e06
Content-Type: application/json
{
  "transactionId": "c1e2fac8-0572-4e2c-a487-c3cc5cbbc85c",
  "simSerial": "8933220000123456789",
  "transactionStatus": "PENDING"
}

A successful response returns a HTTP/1.1 201 Created meaning that your activation request was 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 activation request is being processed in our back-end in order to provision all systems.

4. Receive subscriber activated event (optional)

If you subscribed to subscriber activation events in step 2, once the subscriber is created and their SIM card activated with all services then you will receive a CONNECTIVITY-MANAGEMENT/SUBSCRIBER/ACTIVATED event like the one shown below:

{
  "header": {
    "eventId": "627e77fc-7694-4188-8f19-13ca3dbf8f51",
    "eventType": "CONNECTIVITY-MANAGEMENT/SUBSCRIBER/ACTIVATED",
    "eventDate": "2023-05-19T13:30:00Z"
  },
  "body": {
    "transactionId": "139311f7-63c0-4f51-adeb-3c5e36a5e746",
    "mvnoRef": "M2MA_WW_TSL_MWC_INTERNAL",
    "msisdn": "33601234567",
    "simSerial": "8933220000123456789",
    "subscriberNumber": "12345678.00000001",
    "primaryImsi": "208220123456789",
    "source": "api",
    "externalReference": "RX12345ZVGT",
    "ratePlan": "M2MA_WW_TSL_PPU_1",
    "status": "Active",
    "statusDate": "2023-05-19T13:30:00Z",
    "activationDate": "2023-05-19T13:30:00Z",
    "options": [
      {
        "name": "M2M_TSL_BAR_DATA",
        "value": "on",
        "activationDate": "2023-05-19"
      }
    ]
  }
}

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

Please note that if the MSISDN was unknown before the activation, it is now provided to you.

Additionally, you can check the generated events directly in the Transatel Console under the Data stream tab, by clicking on Details on the contextual menu (...) of the data stream and select the Events tab. This tab will give you access to the event delivery history and status for your data stream.

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

What to do next?