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!
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 retrievedaccess_token
mvnoRef
: Customer account name provided by Transatel at setuptargetUrl
: The HTTPS url to which events will be postedevents
: 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 CreatedX-TSL-Request-Id: bfb49577-1453-4694-a5e4-2936b8d37d2eContent-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 retrievedaccess_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 OKX-TSL-Request-Id: bfade6bd-145c-4440-b41e-8915ab06b867Content-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 retrievedaccess_token
sim-serial
: SIM card serial number of the subscriber to modifyratePlan
: rate plan of the subscriberoptions
: here theRESTRICT_THRESHOLD_2GB
option set toon
If successful, the response returned will be as follows:
HTTP/1.1 201 CreatedX-TSL-Request-Id: 753bcf1c-b307-40fd-a6c4-a649a32920fdContent-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 transactiontransactionStatus
: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 OKX-TSL-Request-Id: 17f966ba-d6e7-4606-963b-e5a99e9982daContent-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