Modifying options

Discover how to modify your subscriber options

This guide shows you how to:

1. consult your options available in your offer
2. authenticate yourself and retrieve an access token
3. create a webhook and subscribe to subscriber modification events
4. check the current subscriber configuration
5. modify the subscriber options
6. receive the subscriber modification event
7. check this subscriber configuration

Endpoints

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

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

1. Retrieve your available options

Before launching your first subscriber modification, you need to be aware of your available options depending on the selected rate plan. For that, you are going to need a user account in order to access our SIM management portal. Please reach your account manager or the fleet manager of your company and ask for your user creation.

Once logged into our SIM management portal, navigate to Catalogue > Options

As an example, we are going to modify a Data Fair-Use Policy option. In your options catalogue you will find something similar to the below table:

This option above is a multiple choice option, and you will need to select one of the possible option name to be set to on. Doing so the others will automatically be set to off. In this example, you can notice that the subscriber is configured with RESTRICT_NO_THRESHOLD by default.

2. API Authentication

Now let's use our authentication API and get your access token by following the getting started guide!

3. Subscribe to modification events (optional)

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

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

1. Click the Add data stream button under the Data Stream tab
2. Select the CONNECTIVITY-MANAGEMENT/SUBSCRIBER/MODIFIED event from the Subscribers category
3. Choose your preferred destination type
4. 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:

1. Click on Edit on the contextual menu (...) of the given data stream under the Data Stream tab
2. Select the CONNECTIVITY-MANAGEMENT/SUBSCRIBER/MODIFIED event from the Subscribers category
3. Click on the Update data stream button

Please check the Data stream page for more information.

4. Retrieve the subscriber current configuration

Now let’s check the current configuration of the subscriber for this particular Data Fair-Use Policy option.

Since modification orders are not allowed for SIM cards in Available status, we are going to choose an already activated subscriber. If you don't already have an activated subscriber, please refer to our dedicated guide in order to proceed to your first activation.

The below example shows how retrieve the current configuration of a given subscriber:

Copy
curl --location --request GET \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJidXNpbmVzc19lbnRpdGllcyI6WyJBbnkiXSwicHJpbmNpcGFsIjoib2NzLXN1YnNjcmlwdGlvbi1vcmRlci1tYW5hZ2VyIiwic2NvcGUiOlsiQ0FUQUxPR19QUk9EVUNUU19SRUFEX1RFQ0hOSUNBTCIsIkNBVEFMT0dfUFJPRFVDVFNfUkVBRCIsIlVTRVJfUkVBRCIsIklOVkVOVE9SWV9TVUJTQ1JJUFRJT05TX1JFQUQiXSwiZXhwIjoxNjE3MjYwNTYxLCJhdXRob3JpdGllcyI6WyJST0xFX0lOVEVSTkFMX1NZU1RFTSJdLCJqdGkiOiJmOTYwNTFmNS05ZmQzLTQxMDEtYjNkZC0xZjY2Y2Q2MWUzZjIiLCJjbGllbnRfaWQiOiJvY3Mtc3Vic2NyaXB0aW9uLW9yZGVyLW1hbmFnZXIifQ.KBTlltd459_4kPV0O3OfsBTFGBtoqRxG65o_NohK1U7IuJAvIjAa8Fj4Qon1ptFrrTR5M2o8l0f9Dl0D7r0Us6Ej6OsVlFXfQKUiXwVytNUTP7POB6l56Svc5CaVqkXgFKyt7_8h6Ii6R_RteujtSzJSWX7zeLSeemxsxKNtHLLIS_HLyNdQyIsVCZWRfFhdPJVQId_p6B08_A54sAwhrT7qssSbtpG1nGzdqsHdFfaqJt9ABhPedatHNlwcWtCnFthrOrD2rv0Yf8OnRLnt-ZWtypr0cqm6U-brtZeBMhcxgzF4afKlJbKN3K3drPJRrRPjL8L9bf2YvzsDWxY5lA' \
    'https://api.transatel.com/connectivity-management/subscribers/api/subscribers/sim-serial/8933220000123456789'

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

• Authorization header: This is where you provide the previously retrieved access_token
• sim-serial: SIM card serial number of the subscriber to modify

If successful, the response returned will be as follows:

Copy
HTTP/1.1 200 OK
X-TSL-Request-Id: bfade6bd-145c-4440-b41e-8915ab06b867
Content-Type: application/json
{
    "simSerial": "8933220000123456789",
    "msisdn": "33601234567",
    "primaryImsi": "208220123456789",
    "activationDate": "2023-04-19T13:30:00Z",
    "status": "Active",
    "ratePlan": "M2MA_WW_TSL_PPU_1",
    "options": [
      { 
        "name": "RESTRICT_NO_THRESHOLD",
        "value": "on"
      }
    ]
}

In our case we have to understand that the Data Fair-Use Policy option is set to RESTRICT_NO_THRESHOLD. Now, let's modify this subscriber.

5. Request a modification on a subscriber

In the below example we use the connectivity management API in order to modify the subscriber and configure Data Fair-Use Policy to RESTRICT_THRESHOLD_2GB:

Copy
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\",
      \"options\": [
        {
          \"name\": \"RESTRICT_THRESHOLD_2GB\",
          \"value\": \"on\"
        }
      ]
    }" \
    'https://api.transatel.com/connectivity-management/subscribers/api/subscribers/sim-serial/8933220000123456789/modify

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

• Authorization header: This is where you provide the previously retrieved access_token
• sim-serial: SIM card serial number of the subscriber to modify
• ratePlan: rate plan of the subscriber
• options: here the RESTRICT_THRESHOLD_2GB option set to on

If successful, the response returned will be as follows:

Copy
HTTP/1.1 201 Created
X-TSL-Request-Id: 753bcf1c-b307-40fd-a6c4-a649a32920fd
Content-Type: application/json
{
  "transactionId": "c1e2fac8-0572-4e2c-a487-c3cc5cbbc85c",
  "simSerial": "8933220000123456789",
  "status": "PENDING"
}

A successful response returns a HTTP/1.1 201 Created meaning that your modification 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

6. Receive subscriber modification event (optional)

If you subscribed to subscriber modification events in step 3, as soon as the modification has been processed a CONNECTIVITY-MANAGEMENT/SUBSCRIBER/MODIFIED event like the one shown below is generated:

Copy
{
  "header": {
    "eventId": "627e77fc-7694-4188-8f19-13ca3dbf8f51",
    "eventType": "CONNECTIVITY-MANAGEMENT/SUBSCRIBER/MODIFIED",
    "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-04-19T13:30:00Z",
    "activationDate": "2023-04-19T13:30:00Z",
    "options": [
      {
        "name": "RESTRICT_THRESHOLD_2GB",
        "value": "on",
        "activationDate": "2023-05-19"
      },
      {
        "name": "RESTRICT_NO_THRESHOLD",
        "value": "off",
        "activationDate": "2023-04-19",
        "inactivationDate": "2023-05-19"
      }
    ]
  }
}

As you can see in the above example, the new configuration has been taken into account. The Data Fair-Use Policy for the subscriber is now configured to RESTRICT_THRESHOLD_2GB. The previous value is also available in the event body RESTRICT_NO_THRESHOLD and is now set to off.

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.

7. Check the result of the modification (optional)

You just have to repeat step 4 in order to retrieve the updated configuration of the subscriber .

You should now have the following result:

Copy
HTTP/1.1 200 OK
X-TSL-Request-Id: 17f966ba-d6e7-4606-963b-e5a99e9982da
Content-Type: application/json
{
    "simSerial": "8933220000123456789",
    "msisdn": "33601234567",
    "primaryImsi": "208220123456789",
    "activationDate": "2023-04-19T13:30:00Z",
    "status": "Active",
    "ratePlan": "M2MA_WW_TSL_PPU_1",
    "options": [
      { 
        "name": "RESTRICT_THRESHOLD_2GB",
        "value": "on"
      }
    ]
}

As you can see, the new configuration has been taken into account. The Data Fair-Use Policy for the subscriber is now configured to RESTRICT_THRESHOLD_2GB.

What to do next?

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

• Overview
• API references