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
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 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 create a webhook and subscribe to activation event: CONNECTIVITY-MANAGEMENT/SUBSCRIBER/ACTIVATED.
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 subscriber activated 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\": \"M2MA_WW_TSL_MWC_INTERNAL\",
      \"status\": \"active\",
      \"targetUrl\": \"https://example.com/events\",
      \"events\": [
        \"CONNECTIVITY-MANAGEMENT/SUBSCRIBER/ACTIVATED\"
      ]
    }" \
    '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 subscriber activated event

If successful, the response returned will be as follows:

HTTP/1.1 201 Created
  Content-Type: application/json
  {
    "id": "257728ad-01ed-447d-b923-062604926f95",
    "mvnoRef": "M2MA_WW_TSL_MWC_INTERNAL",
    "status": "active",
    "targetUrl": "https://example.com/events",
    "events": [
      {
        "eventType": "CONNECTIVITY-MANAGEMENT/SUBSCRIBER/ACTIVATED",
        "description": "A subscriber has been activated with full service profile",
        "domain": "CONNECTIVITY-MANAGEMENT",
        "category": "subscribers",
        "_links": {
          "doc": {
            "href": "https://api.transatel.com/connectivity-managements/events/docs/index.html#tag/Subscribers/paths/CONNECTIVITY-MANAGEMENT~1SUBSCRIBER~1ACTIVATED/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

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/8944133397300000000/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
Content-Type: application/json
{
  "transactionId": "c1e2fac8-0572-4e2c-a487-c3cc5cbbc85c",
  "simSerial": "8944133397300000000",
  "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-04-19T13:30:00Z"
  },
  "body": {
    "transactionId": "139311f7-63c0-4f51-adeb-3c5e36a5e746",
    "mvnoRef": "M2MA_WW_TSL_MWC_INTERNAL",
    "msisdn": "33612345678",
    "simSerial": "8944133397300000000",
    "subscriberNumber": "12345678.00000001",
    "source": "api",
    "externalReference": "RX12345ZVGT",
    "rateplan": "M2MA_WW_TSL_PPU_1",
    "status": "Active",
    "statusDate": "2023-04-19T13:30:00Z",
    "activationDate": "2023-04-19T13:30:00Z",
    "endCommitmentDate": "2024-04-19",
    "holidayRemainingDays": 50,
    "options": [
      {
        "name": "M2M_TSL_BAR_DATA",
        "value": "on",
        "activationDate": "2023-05-01"
      }
    ]
  }
}

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.

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

What to do next?