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:

Transatel APIsURL
Authenticationhttps://api.transatel.com/authentication/api
Connectivity Managementhttps://api.transatel.com/connectivity-management/subscribers/api
Webhookshttps://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:

DescriptionOption nameDefault Value
No bandwidth throttlingRESTRICT_NO_THRESHOLDon
Bandwidth throttling after 250 MBRESTRICT_THRESHOLD_250MBoff
Bandwidth throttling after 500 MBRESTRICT_THRESHOLD_500MBoff
Bandwidth throttling after 1 GBRESTRICT_THRESHOLD_1GBoff
Bandwidth throttling after 2 GBRESTRICT_THRESHOLD_2GBoff

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 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
X-TSL-Request-Id: bfb49577-1453-4694-a5e4-2936b8d37d2e
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://developers.transatel.com/api/connectivity-management/events/#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
X-TSL-Request-Id: bfade6bd-145c-4440-b41e-8915ab06b867
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
X-TSL-Request-Id: 753bcf1c-b307-40fd-a6c4-a649a32920fd
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
X-TSL-Request-Id: 17f966ba-d6e7-4606-963b-e5a99e9982da
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