Home
MATRIXX Subscriber Management API
Object Management
The following sections introduce how the various in-memory objects are managed.
RS Gateway Bulk Operations
The process_bulk_csv.py script reads comma-separated values (CSV) files to perform bulk REST operations through the RS Gateway.
Credit and Debit Adjustments
subman_apis/c_rsgateway_credit_debit_bulk.html#concept_crb_ncc_fxb__table_EFD570FF3D9D4858892C32851C48F404 describes the credit and debit adjustment CSV column headings.

Welcome
MATRIXX Release Notes
MATRIXX Architecture
MATRIXX Installation and Upgrade
MATRIXX Configuration
MATRIXX Security
MATRIXX Integration
MATRIXX Diameter Integration
MATRIXX Call Control Framework Integration
MATRIXX TM Forum Integration
MATRIXX 5G Integration
MATRIXX 5G Event Streaming
MATRIXX Event Streaming
MATRIXX Administration
MATRIXX Web App Administration
MATRIXX Monitoring and Logging
MATRIXX Policy
MATRIXX Kafka CDR Consumer
MATRIXX Pricing and Rating
MATRIXX Pay Now
MATRIXX Subscriber Management
MATRIXX Subscriber Management API
- About Subscriber Management API
  MATRIXX Subscriber Management API provides information about the MATRIXX Engine APIs, including functions, syntax, and result codes, and the MATRIXX Engine REST and Java API implementations.
- Subscriber Management
  The following information is an overview of the SubMan APIs and architecture.
- Object Management
  The following sections introduce how the various in-memory objects are managed.
  - Subscription Management
    The subscription management APIs include the messaging required to operate on the subscription object (MtxSubscriberObject), which is a primary object for MATRIXX interactions.
  - Group Management
    The group management APIs include the messaging required to operate on the group object. The APIs include the messaging and data elements required to create, modify, associate, and query objects directly related to the group.
  - Device Management
    The device management APIs include the methods and functions required to operate on the device primary object. They include the data elements required to create, modify, and query devices, to add and remove a device from a subscription, and to delete a device from the Subscriber database.
  - User Management
    The user management APIs include the messaging required to operate on the user object, which is a primary object for MATRIXX interactions. The API bindings include the messaging and data elements required to create, modify, and query users and associate a user with a subscription. A user can be associated with zero or more subscriptions and groups.
  - Balance, Meter, and Wallet Management
    The balance management APIs include the messaging required to operate on a balance, meter, or wallet object. The primitives include the messaging and data elements required to create, modify, associate, and query objects directly related to a balance or meter, including their thresholds.
  - Product Offer and Bundle Management
    The product offer management APIs include the messaging to activate, purchase, cancel, and modify catalog items. You can identify a product offer by its object ID or the external ID assigned during pricing plan creation.
  - Catalog Item Management
    You can purchase, query, and cancel catalog items using the SubMan APIs.
  - Billing Cycle Management
    Billing cycles properties are configured during global system configuration and managed using the SubMan APIs with which you can create or change a subscription or group billing cycle.
  - Time Zone Management
    When you change a subscription or group time zone using the SubMan APIs, the change impacts wallet periodic balances, billing cycles, and _glossary/purchased-item_cycle.html.
  - Pricing Management
    The pricing management APIs return information about all aspects of pricing, including catalog items, balance templates, product offers, billing cycles, life cycles, notifications and so forth. You can also get status information for the currently-loaded pricing.
  - Data Migration
    Use the data import APIs to import data for users, subscriptions, groups, and devices and to import catalog item purchase information for a subscription. For example, create a subscription with a final status and a LastActivityUpdateTime and link that subscription to other objects (group, device, user, product offer).
  - Rehoming
    Rehoming is the process of moving a user, group, device, or subscription from one sub-domain to a different sub-domain in a multi-domain platform.
  - RS Gateway Bulk Operations
    The process_bulk_csv.py script reads comma-separated values (CSV) files to perform bulk REST operations through the RS Gateway.
    - Subscription Provisioning
      subman_apis/c_rsgateway_subscription_bulk.html#concept_olb_4bc_fxb__table_6089B3D1B0664C8B9F95D56E45F39544 describes the subscription provisioning CSV column headings.
    - Catalog Item Purchases
      subman_apis/c_rsgateway_catalog_items_bulk.html#concept_zry_wbc_fxb__table_3D515CDB0ACD4EEBB90F63131B3CCAA8 describes the catalog item purchase CSV column headings.
    - Credit and Debit Adjustments
      subman_apis/c_rsgateway_credit_debit_bulk.html#concept_crb_ncc_fxb__table_EFD570FF3D9D4858892C32851C48F404 describes the credit and debit adjustment CSV column headings.
    - Group Management
      You can provision groups, delete groups, and manage administrators of groups.
    - Subscriber Deletion
      subman_apis/c_rsgateway_subscriber_delete_bulk.html#concept_tqd_qdc_fxb__table_03A8512DC81A400C9D1756C5413BD3D7 describes the subscriber deletion CSV column headings.
    - User Creation and Deletion
      You can create and delete users with bulk operations.
    - Multi-level JSON Operations
      You can perform bulk operations with multi-level JSON formatting. You must format the column headings with a dot (.) to separate upper-level and sub-level multi-layer keys. subman_apis/c_rsgateway_multi_level_bulk.html#concept_ozk_h2c_fxb__table_A744DEE061994E5EBDC92280A1962FD2 describes the column headings.
    - Run RS Gateway Bulk Operations
      Perform this task to run operations such as subscription provisioning and catalog item purchases in bulk.
  - Object Validity End Time
    The validity end time indicates the time after which querying an object again may return a different definition of the object.
  - Purchased Item Cycle Alignment
    When purchasing a catalog item, you can specify if the purchased item cycle is independent or aligned to a billing cycle, balance cycle, or a different purchased item cycle. The cycle to which a purchased item cycle is aligned is the master cycle.
  - Offer Life Cycle Profiles
    An offer life cycle profile consists of a set of offer statuses, a set of policies associated with each offer status that describe behavior that can be executed in this status, and a set of transitions that can have conditions defined that can trigger a transition and actions defined that are executed after the transition is performed. Both offers and bundles can have an offer life cycle profile defined. Use offer life cycle profiles to customize the behavior of MATRIXX for your business processes.
  - Status Life Cycles
    A status life cycle is a collection of object states, policies, and transition rules that are defined for a specific object type. You can define a status life cycle for user, device, subscription, group, and offer objects to customize the behavior of MATRIXX for your business processes. For example, a device life cycle can begin with a provisioned status, transition to an active status, and finally transition to an inactive status.
  - Modifying Statuses
    Use the SubMan APIs to modify status values of subscriptions, groups, and devices. Status values are defined in object status life cycles.
  - Making Multiple Requests in One API Call
    You can perform multiple engine requests (MtxRequestMulti) using a POST call to the RS Gateway. For example, one request can create a subscriber, create a device, and associate the device with that subscriber.
  - SubMan Operation Search Terms
    In many of the SubMan API methods, you must specify a search term that identifies an instance of a specific object.
  - Getting Subclasses of MDC Definitions
    For each MDC definition, you can get a list of all classes that have that class as its base class.
  - Getting Subtype Code Values
    For each subtype, you can get a list of all codes and their values.
  - Adding Event Data in SubMan Requests
    You can pass data in SubMan requests in the MtxApiEventDataExtension MDC to be included in EDRs.
  - Working with Custom MDCs
    Custom MATRIXX Data Containers (MDCs) can stand alone or extend system MDCs or other custom MDCs. Use private MDCs to extend subscribers, devices, and purchased product offers with custom parameters. You can set values for these parameters in SubMan API calls within the <attr> element of the request XML in the REST APIs or in the Attr field of the Java APIs.
  - Message XSDs
    You can query the RS Gateway for XSD definitions for MDCs that can be used by third-party applications to validate their XML.
- SubMan API Reference
  The SubMan API reference includes SubMan API and MDC descriptions.
- REST API Management
  RS Gateway supports the REST API bindings for accessing subscriber data in MATRIXX Engine. RS Gateway consists of an rsgateway application and a set of REST APIs.
- REST API Reference
  This part describes how to use the REST API bindings to interface with MATRIXX Engine.
- Java API
  This part provides an overview of how to use the Java™ API binding for the SubMan v3 API as an interface to the MATRIXX Engine.
MATRIXX Business API SDK
My MATRIXX Help
MATRIXX Backoffice Customer Tool Help
MATRIXX Third-Party Licenses
Glossary

Credit and Debit Adjustments

Credit and Debit Adjustment Column Headings describes the credit and debit adjustment CSV column headings.

Table 1. Credit and Debit Adjustment Column Headings
Column Heading	Required/Optional	Notes
SubscriberSearchData	Required	This heading is used to identify the subscriber. The format must be ID type + ID value (for example, `Imsi+408239-2039` or `ExternalId+extId23`). Valid ID types are: SubscriberId ObjectId ExternalId PhoneNumber Imsi AccessNumber LoginId AccessId
BalanceResourceId	Required	The balance resource ID.
AdjustType	Required	The type of adjustment to apply. Values are: 1=Credit Balance, 2=Debit Balance, 3=Reset Meter
Amount	Required	The amount.
Reason	Required	The reason for the adjustment.
Voucher	Optional	The reference authorizing the top-up.
EndTime	Optional	The time to set as the new EndTime of a balance. If the specified EndTime value for a topup is earlier than the current time, the date change is not applied and an error is returned. Applied in addition to EndTimeExtensionOffset Unit and EndTimeExtensionOffset if they are present.
EndTimeExtensionOffsetUnit	Optional	Type of units for EndTimeExtensionOffsetused to specify the extension of the current EndTime of a balance. "hours" (1) "days" (2) "weeks" (3) "months" (4) "years" (5) "minutes" (6)
EndTimeExtensionOffset	Optional	The number of units (from EndTimeExtensionOffset Unit) by which to extend the current EndTime of a balance.

Credit and Debit Sample Data shows example data for credit and debit adjustments.

Table 2. Credit and Debit Sample Data
SubscriberSearchData	BalanceResourceId	Amount	Reason	AdjustType
ExternalId+Subscriber1	1	4085551213	loc1	1
ExternalId+Subscriber2	2	4085551213	loc2	2
ExternalId+Subscriber3	3	4085551213	loc3	1
ExternalId+Subscriber4	4	3435	loc2	1
ExternalId+Subscriber5	5	4085551213	loc3	1

The following code is an example of a CSV file for the credit and debit adjustments shown in Credit and Debit Sample Data.

SubscriberSearchData,BalanceResourceId,Amount,Reason,AdjustType
ExternalId+Subscriber1,1,4085551213,loc1,1
ExternalId+Subscriber2,1,4085551213,loc2,2
ExternalId+Subscriber3,1,4085551213,loc3,1
ExternalId+Subscriber4,1,345,loc2,1
ExternalId+Subscriber5,1,4085551213,loc3,1