Bulk Attach Subscriber Package

The Bulk Attach Subscriber Package API is used to attach a package to multiple subscribers in a single call. The system allows a customer to attach a 'Sell Package' to the subscribers of their sub-customers, or to attach a package created by their parent customer ('Buy Package') to its own subscribers in a self-service manner.

NOTE: The self-service attach mode is permitted only if the parent customer has granted permission to the specific sub-customerby enabling the 'allowOfferDelegation' flag.

Method	Path
POST	/api/v2/bulk/subscriber/package/attach

Eligibility

The requestor is eligible to attach a package to their sub-customers’ subscribers. However, they are not allowed to attach a package to their own subscribers unless the requestor's parent customer:

Grants permission by enabling the 'allowOfferDelegation' parameter.
Assigns at least one package to the requestor using the 'eligibleSubAccountIds' attribute when creating or modifying a package.

API Request

Request Structure

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

Bulk

Parameter	Type	M/O/CM	Description
subscriberIdentifiers	Object	M	Subscriber unique keys object; defines the search criteria.
content	Object	M	Main elements container object.

subscriberIdentifiers

Parameter	Type	M/O/CM	Description
type	String	M	Defines the search criteria. Valid type ENUMs are: ‘IMSI’, ‘ICCID’, ‘MSISDN’, ‘IMEI’, ‘IMEISV’.
value	String	M	Type value. IMSI, ICCID, MSISDN, IMEI, or IMEISV number.

Content

Parameter	Type	M/O/CM	Description
packageId	UUID	M	Package catalog ID.
myPackage	Boolean	O	Determines whether to attach one of the customer’s packages (Sell Package) to sub-account subscribers or one of the customer’s parent packages (Buy Packages) to own subscribers. True = Request to attach a parent package (Buy Package) to own subscribers. This 'self-service' functionality is allowed only if the sub-customer has been defined by its parent customer as allowed to delegate parent customer packages (allow_offer_delegation = true). False = Request to attach one of the customer’s packages (Sell Packages) to sub-account subscribers (normal operation). Default if not provided is 'false'.

Parameter

Type

M/O/CM

Description

packageId

UUID

Package catalog ID.

myPackage

Boolean

Determines whether to attach one of the customer’s packages (Sell Package) to sub-account subscribers or one of the customer’s parent packages (Buy Packages) to own subscribers.

True = Request to attach a parent package (Buy Package) to own subscribers. This 'self-service' functionality is allowed only if the sub-customer has been defined by its parent customer as allowed to delegate parent customer packages (allow_offer_delegation = true).
False = Request to attach one of the customer’s packages (Sell Packages) to sub-account subscribers (normal operation).

Default if not provided is 'false'.

API Response

Response Structure

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

Bulk

Parameter	Type	M/O/CM	Description
errorCode	String	O	Failure code.
errorMessage	String	O	Failure detailed description.
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 is successful. For a failure, it will be empty.
subscriberPackageId	UUID	M	Offer instance attached to the subscriber.
subscriberIdentifiers	Object	M	Subscriber unique keys object; defines the search criteria.
content	Object	M	Main response body object. Reflects a single node of the original request.

subscriberIdentifiers

Parameter	Type	M/O/CM	Description
type	String	M	Defines the search criteria. Valid type ENUMs are: ‘IMSI’, ‘ICCID’, ‘MSISDN’, ‘IMEI’, ‘IMEISV’.
value	String	M	Type value. IMSI, ICCID, MSISDN, IMEI, or IMEISV number.

Content

Parameter	Type	M/O/CM	Description
packageId	UUID	M	Package catalog ID.
myPackage	Boolean	O	Determines whether to attach one of the customer’s packages (Sell Package) to sub-account subscribers or one of the customer’s parent packages (Buy Packages) to own subscribers. True = Request to attach a parent package (Buy Package) to own subscribers. This ‘self-service’ functionality is allowed only when the sub-customer has been defined by its parent customer as allowed to delegate parent customer packages (allow_offer_delegation = true). False = Request to attach one of the customer’s packages (Sell Packages) to sub-account subscribers (normal operation). Default if not provided is ‘false’.

Parameter

Type

M/O/CM

Description

packageId

UUID

Package catalog ID.

myPackage

Boolean

Determines whether to attach one of the customer’s packages (Sell Package) to sub-account subscribers or one of the customer’s parent packages (Buy Packages) to own subscribers.

True = Request to attach a parent package (Buy Package) to own subscribers. This ‘self-service’ functionality is allowed only when the sub-customer has been defined by its parent customer as allowed to delegate parent customer packages (allow_offer_delegation = true).
False = Request to attach one of the customer’s packages (Sell Packages) to sub-account subscribers (normal operation).

Default if not provided is ‘false’.

Pageable

Parameter	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 per each of the ‘Bulk’ array elements:

Code	Message
GLOBAL_1001	Service unavailable. Please try again.
SUBSCRIBER_1058	Failed to attach package.
AUTH_1019	You are not allowed to attach parent customer package to your own SIM cards.

Examples

Request Body

Copy

{
  "bulk": [
    {
      "subscriberIdentifiers": {
        "type": "IMSI",
        "value": "222013090961859"
      },
      "content": {
        "packageId": "4543dedb-cce7-4bee-89f3-7af1447927e6",
        "myPackage": false
      }
    },
    {
      "subscriberIdentifiers": {
        "type": "ICCID",
        "value": "8935711001000034535"
      },
      "content": {
        "packageId": "e7fcef24-5c03-41dd-9e33-995b7d6f47e2",
        "myPackage": false
      }
    }
  ]
}

Response Body Full Success ACK

Copy

{
  "bulk": [
    {
      "errorCode": "",
      "errorMessage": "",
      "requestId": "ff74dca6-8e7f-4b85-a42b-13860913b370",
      "subscriberPackageId": "ab74dfe6-8e7f-4b45-a42b-14460913b459",
      "subscriberIdentifiers": {
        "type": "IMSI",
        "value": "222013090961963"
      },
      "content": {
        "packageId": "4543dedb-cce7-4bee-89f3-7af1447927e6",
        "myPackage": false
      }
    },
    {
      "errorCode": "",
      "errorMessage": "",
      "requestId": "7e74dce6-8eef-4c86-a4bb-1a860913c271",
      "subscriberPackageId": "bb64dfd6-2e1f-4a25-b32b-13461943c425",
      "subscriberIdentifiers": {
        "type": "ICCID",
        "value": "8935711001000035687"
      },
      "content": {
        "packageId": "e7fcef24-5c03-41dd-9e33-995b7d6f47e2",
        "myPackage": true
      }
    }
  ],
  "pageable": {
    "page": 0,
    "size": 10,
    "totalPages": 1,
    "totalElements": 1
  } 
}

Response Body Includes Failure NAK

Copy

{
  "bulk": [
    {
      "errorCode": "AUTH_1019",
      "errorMessage": "You are not allowed to attach parent customer package to your own SIM cards",
      "requestId": "",
      "subscriberIdentifiers": {
        "type": "IMSI",
        "value": "222013090961963"
      },
      "content": {
        "packageId": "e7fcef24-5c03-41dd-9e33-995b7d6f47e2",
        "myPackage": true
      }
    }
  ],
  "pageable": {
    "page": 0,
    "size": 10,
    "totalPages": 1,
    "totalElements": 1
  }
}