Bulk Modify Subscriber Status

This API is used to amend in-use SIM related attributes of multiple subscribers in a single call. Requested changes in SIMs are executed via OTA commands sent by a binary SMSs.

The Requestor is eligible to modify his own subscribers' SIM settings information regardless of their actual existence (which level they reside in).

HTTP URL  
PATCH api/v2/bulk/subscriber/sim

Eligibility

The Requester is eligible to request a status change for its own subscribers or for its sub-customers’ subscribers.

API Request

Request Structure

Parameter Type M/O/CM Description
bulk Object M Array of main request body object.

Bulk data objects

Element Type M/O/CM Description
subscriberIdentifiers Object M Subscriber unique keys object, define the search criteria.
content Object M Main elements container object

subscriberidentifiers data objects

Element Type M/O/CM Description
type String M Define the search criteria: ENUMs: IMSI, ICCID, MSISDN, IMEI
value String M Type value. IMSI or ICCID or MSISDN or IMEI number.

Content data objects

Parameter Type M/O/CM Description
appletMode String O Set the SIM applet mode. Determines whether the active IMSI can be set manually, or the applet determines which IMSI to use. ENUM valid values: MANUAL, AUTOMATIC
activeImsi String O Set active IMSI. Must be from the subscriber identifiers list. Note: The system does not block an attempt to modify active IMSI even if the ‘appletMode’ is set to AUTOMATIC.
sim Object 0 Array of SIMs object – In-Use IMSIs only

SIM

Parameter Type M/O/CM Description
imsi String M IMSI number registered on current SIM instance
allowedCountries String O

Set an array of IMSI related Mobile Country Codes (MCC).

The device is allowed to make a connection while in this country/continent. Send ‘MCC’ Comma separated values. Max 16 items in the array are allowed.

Set the following values when allowing a whole mainland using a single item: 2FF,3FF,4FF,5FF,6FF,7FF

  • 2FF: Europe

  • 3FF: North America and the Caribbean

  • 4FF: Asia and the Middle East

  • 5FF: Australia and Oceania

  • 6FF: Africa 7FF: South and Central America

  • 7FF: South and Central America
preferredOperatorNetworks String O Set the list of operator networks (array of comma separated string) that get precedence on unlisted networks in current SIM instance (given IMSI) while roaming. Send MCCMNC value. Note: Passed value\s will override existing value\s. Empty string will reset the existing array list.
forbiddenNetworks String O Set the list of networks (array of comma separated string) that current SIM instance (given IMSI) cannot connect to while roaming. Send MCCMNC value. Note: Passed value\s will override existing value\s. Empty string will reset the existing array list.

API Response

Response Structure

Parameter Type M/O/CM Description
bulk Object M Array of main response body object.
pageable Object O Paging information object displayed when an API call was successful. For a failure, it will be empty.

 

Bulk data objects

Parameter Type M/O/CM Description
errorCode String O Failure code.
errorMessage String O Failure message.
requestId UUID CM

Request instance ID. To be used by external systems to query the call (operation) status, whether in progress, successful or failed. Displayed when an API call was successful. For a failure it will be empty.
subscriberIdentifiers Object M Subscriber unique keys object, defines the search criteria.
content Object O Main response body object that reflects a single node of the original request.

subscriberidentifiers data objects

Parameter Type M/O/CM Description
type String M Define the search criteria: ENUMs: IMSI, ICCID, MSISDN, IMEI
value String M Type value. IMSI or ICCID or MSISDN or IMEI number.

Content data objects

Element Type M/O/CM Description
appletMode String O SIM applet mode. Determines whether the active IMSI can be set manually, or the applet determines which IMSI to use. ENUM valid values: MANUAL, AUTOMATIC
activeImsi String O Active IMSI.
sim Object O Array of SIMs object

SIM

Parameter Type M/O/CM Description
imsi String M IMSI number registered on current SIM instance
allowedCountries String O

Array of IMSI related Mobile Country Codes (MCC). The device is allowed to make a connection while in this country/continent.

Following values can also be used when allowing a whole mainland using a single item: 2FF,3FF,4FF,5FF,6FF,7FF

  • 2FF: Europe

  • 3FF: North America and the Caribbean

  • 4FF: Asia and the Middle East

  • 5FF: Australia and Oceania

  • 6FF: Africa 7FF: South and Central America

  • 7FF: South and Central America
preferredOperatorNetworks String O Set the list of operator networks (array of comma separated string) that get precedence on unlisted networks in current SIM instance (given IMSI) while roaming. Send MCCMNC value. Note: Passed value\s will override existing value\s. Empty string will reset the existing array list.
forbiddenNetworks String O Set the list of networks (array of comma separated string) that current SIM instance (given IMSI) cannot connect to while roaming. Send MCCMNC value. Note: Passed value\s will override existing value\s. Empty string will reset the existing array list.

Pageable data objects

Element Type M/O/CM Description
page Numeric M Page number
size Numeric M Page size. Number of requested elements per page
totalPages Numeric M Total amount of available pages per requested page size
totalElements Numeric M Total amount of retrieved elements

Error Codes

In addition to the general success and failure codes, the following error codes are possible.

Code Message
GLOBAL_1001 Service unavailable. Please try again
SUBSCRIBER_1002 Subscriber does not exist

Examples

Request Body

Copy 
{
  "bulk": [
    {
      "subscriberIdentifiers": {
        "type": "IMSI",
        "value": "222013090961859"
      },
      "content": {
        "appletMode": "MANUAL",
        "activeImsi": "222013090961859",
        "sim": [
          {
            "imsi": "222013090961859",
            "allowedCountries": "001",
            "preferredOperatorNetworks": [
              "302220",
              "302500"
            ],
            "forbiddenNetworks": [
              "23430",
              "23415",
              "90146"
            ]
          },
          {
            "imsi": "310380501118337",
            "allowedCountries": "320",
            "preferredOperatorNetworks": [],
            "forbiddenNetworks": []
          }
        ]
      }
    },
    {
      "subscriberIdentifiers": {
        "type": "ICCID",
        "value": "8935711001000034535"
      },
      "content": {
        "sim": [
          {
            "imsi": "310370201128465",
            "allowedCountries": "001",
            "preferredOperatorNetworks": [],
            "forbiddenNetworks": []
          }
        ]
      }
    }
  ]
}

Response Body: Full Success ACK

Copy 
{
  "bulk": [
    {
      "errorCode": "",
      "errorMessage": "",
      "requestId": "ff74dca6-8e7f-4b85-a42b-13860913b370",
      "subscriberIdentifiers": {
        "type": "IMSI",
        "value": "222013090961859"
      },
      "content": {
        "appletMode": "MANUAL",
        "activeImsi": "222013090961859",
        "sim": [
          {
            "imsi": "222013090961859",
            "allowedCountries": "001",
            "preferredOperatorNetworks": [
              "302220",
              "302500"
            ],
            "forbiddenNetworks": [
              "23430",
              "23415",
              "90146"
            ]
          },
          {
            "imsi": "310380501118337",
            "allowedCountries": "320",
            "preferredOperatorNetworks": [],
            "forbiddenNetworks": []
          }
        ]
      }
    },
    {
      "errorCode": "",
      "errorMessage": "",
      "requestId": "7e74dce6-8eef-4c86-a4bb-1a860913c271",
      "subscriberIdentifiers": {
        "type": "ICCID",
        "value": "8935711001000034535"
      },
      "content": {
        "sim": [
          {
            "imsi": "310370201128465",
            "allowedCountries": "320",
            "preferredOperatorNetworks": [],
            "forbiddenNetworks": []
          }
        ]
      }
    }
  ],
  "pageable": {
    "page": 0,
    "size": 10,
    "totalPages": 1,
    "totalElements": 1
  }
}

Response Body: Includes Failure(s) (NAK)

Copy 
{
  "bulk": [
    {
      "errorCode": "SUBSCRIBER_1002",
      "errorMessage": "Subscriber does not exist",
      "requestId": "",
      "subscriberIdentifiers": {
        "type": "IMSI",
        "value": "222013090961859"
      },
      "content": {
        "appletMode": "MANUAL",
        "activeImsi": "222013090961859",
        "sim": [
          {
            "imsi": "222013090961859",
            "allowedCountries": "001",
            "preferredOperatorNetworks": [
              "302220",
              "302500"
            ],
            "forbiddenNetworks": [
              "23430",
              "23415",
              "90146"
            ]
          },
          {
            "imsi": "310370201128465",
            "allowedCountries": "310",
            "preferredOperatorNetworks": [],
            "forbiddenNetworks": []
          }
        ]
      }
    }
  ],
  "pageable": {
    "page": 0,
    "size": 10,
    "totalPages": 1,
    "totalElements": 1
  }
}