Modifying options

Discover how to modify your subscriber options

This guide shows you how to:

consult your options available in your offer
authenticate yourself and retrieve an access token
create a webhook and subscribe to subscriber modification events
check the current subscriber configuration
modify the subscriber options
receive the subscriber modification event
check this subscriber configuration

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. 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:

Description	Option name	Default Value
No bandwidth throttling	RESTRICT_NO_THRESHOLD	on
Bandwidth throttling after 250 MB	RESTRICT_THRESHOLD_250MB	off
Bandwidth throttling after 500 MB	RESTRICT_THRESHOLD_500MB	off
Bandwidth throttling after 1 GB	RESTRICT_THRESHOLD_1GB	off
Bandwidth throttling after 2 GB	RESTRICT_THRESHOLD_2GB	off

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!

According to your business need, you may need to receive events when your subscriber modification is complete. If so, you will need to create a webhook and subscribe to modification event: CONNECTIVITY-MANAGEMENT/SUBSCRIBER/MODIFIED.
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 modification 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/MODIFIED\"
      ]
    }" \
    '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 modification 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/MODIFIED",
        "description": "A subscriber's contact information or service options have been modified",
        "domain": "CONNECTIVITY-MANAGEMENT",
        "category": "subscribers",
        "_links": {
          "doc": {
            "href": "https://api.transatel.com/connectivity-managements/events/docs/index.html#tag/Subscribers/paths/CONNECTIVITY-MANAGEMENT~1SUBSCRIBER~1MODIFIED/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.

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:

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/8944133397300000000'

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:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "simSerial": "8944133397300000000",
    "msisdn": "+33612345678",
    "primaryImsi": "234858800000000",
    "activationDate": "2022-01-06T14:14:39.887+01:00",
    "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:

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/8944133397300000000/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:

HTTP/1.1 201 Created
Content-Type: application/json
{
  "transactionId": "c1e2fac8-0572-4e2c-a487-c3cc5cbbc85c",
  "simSerial": 8944133397300000000,
  "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:

{
  "header": {
    "eventId": "627e77fc-7694-4188-8f19-13ca3dbf8f51",
    "eventType": "CONNECTIVITY-MANAGEMENT/SUBSCRIBER/MODIFIED",
    "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": "RESTRICT_THRESHOLD_2GB",
        "value": "on",
        "activationDate": "2023-05-01"
      },
      {
        "name": "RESTRICT_NO_THRESHOLD",
        "value": "off"
      }
    ]
  }
}

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.

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:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "simSerial": "8944133397300000000",
    "msisdn": "+33612345678",
    "primaryImsi": "234858800000000",
    "activationDate": "2022-01-06T14:14:39.887+01:00",
    "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

Modifying options

Endpoints

1. Retrieve your available options

2. API Authentication

3. Subscribe to modification events (optional)

4. Retrieve the subscriber current configuration

5. Request a modification on a subscriber

6. Receive subscriber modification event (optional)

7. Check the result of the modification (optional)

What to do next?