Deactivating the data safeguard

Discover how you can temporarily deactivate your data safeguard option

This guide shows you how to retrieve your data safeguard option then temporarily deactivate your option.

Endpoints

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

Transatel APIs	URL
Authentication	https://api.transatel.com/authentication/api
OCS Inventory	https://api.transatel.com/ocs/inventory/api
OCS Subscriptions	https://api.transatel.com/ocs/subscriptions/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!

2. Retrieve the state of the data safeguard option (optional)

Now that you are authenticated, and you have an access token, let's use it to retrieve the state of the data safeguard option of one of your subscribers.

To do so, we will use OCS Inventory API.

The below example shows how to retrieve the data safeguard option for 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/ocs/inventory/api/subscriptions/options/dataSafeguard?msisdn=33612345678'

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

Authorization header: This is where you provide the previously retrieved access_token
msisdn: The mobile phone number of the subscriber

If successful, the response returned will be as follows:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "state": "active",
  "cutOff": {
    "limit": 6000,
    "unit": "CENTS",
    "currency": "EUR",
    "spent": 0,
    "reached": false
  },
  "nextRenewalDate": "2023-05-19T13:30:00Z",
  "eligibleStates": [
    "temporarily-inactive",
    "permanently-inactive"
  ]
}

A successful response returns a HTTP/1.1 200 OK, with the details of the data safeguard option. The eligibleStates array contains all possible states you can switch the option to.

3. Opt-out temporarily the data safeguard option

Now that we returned the data safeguard option, let's try to opt-out on the current period for this subscriber and verify that the data safeguard option has been correctly changed to temporarily-inactive.

To do so, we will use the OCS Subscriptions API.

The below example shows how to change the state of the data safeguard option:

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 \
    "{ 
      \"bind\": {
        \"msisdn\": \"33612345678\"
      },
      \"source\": \"api\",
      \"state\": \"temporarily-inactive\",
      \"transactionReference\": \"RX12345ZVGT\"
    }" \
    'https://api.transatel.com/ocs/subscriptions/api/orders/options/dataSafeguard'

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

Authorization header: This is where you provide the previously retrieved access_token
msisdn: The mobile phone number of the subscriber
state: The target state you want to apply

If successful, the response returned will be as follows:

HTTP/1.1 201 Created
Content-Type: application/json
{
  "bind": {
    "msisdn": "33612345678"
  },
  "orderReference": "SUBIcuMJjmmcSOhm2i57dsSA",
  "source": "api",
  "status": "done",
  "state": "temporarily-inactive",
  "submissionDate": "2019-08-24T14:15:22Z",
  "transactionReference": "RX12345ZVGT"
}

A successful response returns a HTTP/1.1 201 Created, meaning that your order was successfully processed and the data safeguard option state was successfully changed.

What to do next?

Learn more about our OCS APIs by checking their overview & API references: