Home
MATRIXX Subscriber Management API
SubMan API Reference
The SubMan API reference includes SubMan API and MDC descriptions.
Subscriber MDCs
This section lists the subscriber-related APIs.

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.
- SubMan API Reference
  The SubMan API reference includes SubMan API and MDC descriptions.
  - Application MDCs
    The application MDCs include information for each Rx application session in a response for device sessions.
  - Balance, Meter, Wallet MDCs
    This section includes balance-related MDCs.
  - Barclay MDCs
    This section describes the Barclay MDCs.
  - Bundle MDCs
    This section includes the bundle MDCs.
  - Billing MDCs
    This section includes billing-related MDCs.
  - Braintree MDCs
    This section includes the Braintree-specific SubMan APIs.
  - Catalog MDCs
    The catalog APIs return information about pricing catalogs for specified devices, groups, and subscriptions.
  - Catalog Item MDCs
    The catalog item APIs return information about eligible catalog items for specified devices, groups, and subscriptions.
  - Charge-Related MDCs
    This section describes the charge-related MDCs for MATRIXX API calls.
  - Contract MDCs
    Contract data is returned in the product offer API responses in the MtxPurchasedOfferInfo MDC.
  - Datatrans MDCs
    The Datatrans MDCs include information for the Datatrans Payment Gateway.
  - Data Migration MDCs
    Use the following MDCs to import data for users, subscriptions, groups, and devices and to import catalog item purchase information for a subscription.
  - Device MDCs
    This section lists the device-related MDCs.
  - Diameter MDCs
    This section includes the Diameter-related APIs.
  - Eligibility Rules MDCs
    This section describes the SubMan eligibility rules APIs.
  - Event MDCs
    This section includes the event-related APIs.
  - Evertec MDCs
    This section includes the Evertec-specific SubMan APIs.
  - External Payment MDCs
    External payment APIs query external payment requests and get a list of external payment request records in a wallet.
  - Group MDCs
    This section lists the group-related APIs.
  - Mastercard MDCs
    This section includes the Mastercard-specific SubMan APIs.
  - mPAY MDCs
    This section describes the mPAY MDCs.
  - Multi-Tenant MDCs
    The multi-tenant APIs return tenant information for individual tenants and all tenants.
  - Notification MDCs
    This section includes the notification MDCs.
  - Parameter MDCs
    This section includes the parameter MDCs.
  - Pay Now Payment MDCs
    The Pay Now payment SubMan APIs query payment information and add or remove payment method tokens for subscribers and groups.
  - Policy MDCs
    This section lists the MATRIXX Policy application APIs.
  - Pricing MDCs
    This section describes the pricing-related APIs.
  - Product Offer MDCs
    This section describes the product offer-related APIs.
  - Purchase Package MDCs
    Use the purchase package MDCs to manage catalog items in a purchase package, including adding and removing catalog items for subscriptions, groups, and devices, and suspending, resuming, and canceling purchase packages.
  - Purchased Item MDCs
    This section lists the purchased item APIs.
  - Recharge MDCs
    This section describes the recharge MDC fields.
  - Rehoming MDCs
    The rehoming APIs move a _glossary/subscription.html, group, or device from one customer sub-domain to a different sub-domain. For a description of the rehoming process, see the discussion about rehoming subscribers, groups, and devices in the object management overview.
  - Related Objects
    This section describes the common structures for related objects, related subscription objects, and related user objects.
  - Request/Response MDCs
    This section includes request and response APIs.
  - Roaming MDCs
    This section describes the roaming MDCs.
  - Romcard V2 MDCs
    This section describes the Romcard V2 MDCs.
  - Security MDCs
    The ApiEventSecurityInfo MDC records client security information.
  - Status MDCs
    The status APIs change the status of existing subscriptions, groups, and devices. They cancel any scheduled status change for a purchased item (offer or bundle) from subscriptions, groups, and devices. They cancel any scheduled status change for subscriptions, groups, and devices.
  - Subscriber MDCs
    This section lists the subscriber-related APIs.
    - MtxGeoData
      Geocode override using either GeoCode, PostalCode/Plus4 or Npa/Nxx values. Only one of these 3 is needed.
    - MtxSubscriberExtension
      Base MDC for user defined extensions to subscriber object
    - MtxSubscriberIdInfo
      subman_apis/r_mtx_subscriber_id_info.html#mtxsubscriberidinfo__table_ymx_d15_rjb describes the MtxSubscriberIdInfo fields.
    - MtxSubscriberSearchData
      Common structure for operations that need to lookup a subscriber by one of the supported lookup methods. Only one of these keys will actually be used.
    - MtxRequestSubscriberActivateOffer
      Request to activate a pre-active purchased catalog item.
    - MtxRequestSubscriberAddDevice
      Request that a device is added to the specified subscriber. This relationship establishes ownership of the device for rating operations. A subscriber can own multiple devices but a device can only have one owning subscriber.
    - MtxRequestSubscriberAddRechargeSchedule
      Request to associate a recharge schedule with the specified subscriber. There is only one recharge schedule per subscriber. If there is an existing recharge schedule, it will be replaced.
    - MtxRequestSubscriberAddThreshold
      Request to add a custom credit limit or threshold value to a balance in the subscriber wallet. The balance credit limit / threshold must have been defined in My MATRIXX. Any existing customization will be overwritten.
    - MtxRequestSubscriberAdjustBalance
      Adjust the balance owned by a subscriber.
    - MtxRequestSubscriberAdjustRolloverBalance
      Adjust the rollover balance owned by a subscriber.
    - MtxRequestSubscriberCancelOffer
      Request to cancel an existing subscription catalog item owned by a subscriber. The cancelled catalog item will still be visible on queries.
    - MtxRequestSubscriberContractDebtPayment
      Request to pay contract debt.
    - MtxRequestSubscriberCreate
      Request that a new subscriber is created in the subscriber DB and is initialized with the information provided. A unique OID will be created and returned. If supplied, the ExternalId must be unique within the subscriber database. The actual type of subscriber instance created depends on the type of the subscriber extension in the Attr field. If not supplied, the system default subscriber is created.
    - MtxRequestSubscriberDelete
      Delete the specified subscriber from the system. It must be in a state that allows deletion.
    - MtxRequestSubscriberEstimateRecurringCharge
      Estimate the balance impacts of upcoming recurring processing for a subscriber.
    - MtxRequestSubscriberFinanceContractPrincipalPayment
      Request used to to pay additional principal payments or completely pay-off the principal for a finance contract
    - MtxRequestSubscriberModify
      Request that information on an existing subscriber is modified. Only those values that are present in the request will be modified in the subscriber - all other subscriber values will be unchanged. If supplied, the Attr extension object must be of the same type as that used to create the subscriber.
    - MtxRequestSubscriberModifyAuthData
      Modify the authorization data associated with a subscriber.
    - MtxRequestSubscriberModifyOffer
      Request that information on an existing purchased catalog item is modified.
    - MtxRequestSubscriberModifyRechargeSchedule
      Request to modify the recharge schedule associated with the specified subscriber. If there is no existing recharge schedule, it will return an error.
    - MtxRequestSubscriberPayment
      Request that a payment be made on the subscriber's main balance
    - MtxRequestSubscriberPurchaseOffer
      Request to purchase one or more catalog items for the specified subscriber. Any required balances specified in an associated offer template will be created and initialized.
    - MtxRequestSubscriberQuery
      Request to query information about an existing subscriber including basic wallet information.
    - MtxRequestSubscriberQueryAggregation
      Request information on in-process event aggregations associated with the subscriber.
    - MtxRequestSubscriberQueryAuthData
      Query the authorization data associated with a subscriber.
    - MtxRequestSubscriberQueryEvent
      Request information on events associated with the subscriber.
    - MtxRequestSubscriberQueryMembership
      Request to query membership information for an existing subscriber.
    - MtxRequestSubscriberQueryOneTimeOffer
      Request to query cancelable one-time offer purchases associated with a subscriber.
    - MtxRequestSubscriberQueryRechargeSchedule
      Query recharge schedule associated with a subscriber.
    - MtxRequestSubscriberQueryRecurringRecharge
      Query recurring recharge information associated with a subscriber.
    - MtxRequestSubscriberQueryThresholdRechargeDefn
      Request to query threshold recharge definitions associated with a subscriber.
    - MtxRequestSubscriberQueryWallet
      Request to query the subscriber wallet.
    - MtxRequestSubscriberRecharge
      Subscriber request to recharge to prepaid main balance.
    - MtxRequestSubscriberRemoveDevice
      Request that the specified device is removed from the specified subscriber. The device must be associated with the specified subscriber and must not be INACTIVE. Any device specific catalog items will be removed as part of this operation.
    - MtxRequestSubscriberRemoveRechargeSchedule
      Request to remove the recharge schedule associated with the specified subscriber.
    - MtxRequestSubscriberRemoveThreshold
      Request to remove a custom credit limit or threshold value from a balance in the subscriber wallet. The balance threshold must have already been customized and the default credit limit / threshold defined in pricing will become active on successful removal of the custom value.
    - MtxRequestSubscriberResumeOffer
      Request to resume an existing purchased item (offer or bundle) owned by a subscriber.
    - MtxRequestSubscriberSuspendOffer
      Request to suspend an existing purchased item (offer or bundle) owned by a subscriber.
    - MtxRequestSubscriberSettlePayment
      Request to settle a subscriber payment.
    - MtxRequestSubscriberTopupBalance
      Topup a balance owned by a subscriber.
    - MtxRequestSubscriberTransferBalance
      Request a balance transfer from the source subscriber to the target subscriber or group. The source and target balance must be prepaid G/L balance instances of the same balance unit, for example, minutes or megabytes. The amount being transferred must be specified either as a positive absolute value or as a percentage of the available amount in the source balance.
    - MtxResponseAuthData
      Authentication information for a subscriber.
    - MtxResponseSubscriber
      Response to a subscriber query containing basic wallet information.
    - MtxResponseEventInfo
      Information on events.
  - Subscription MDCs
    The subscription APIs create, delete, modify, and query subscription objects.
  - Subscription/Group Membership MDCs
    This section describes the subscription/group membership MDC.
  - Tax MDCs
    This section lists the tax APIs.
  - Tenant MDCs
    This section lists the tenant APIs.
  - User MDCs
    This section describes the user object APIs.
  - MtxOpMsg
    MDC container for request/response handling.
- 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

Subscriber MDCs

This section lists the subscriber-related APIs.

Note: The same product offer APIs are used to purchase and cancel bundles and individual product offers. The APIs use the same pricing object ID to identify offers and bundles. You do not specify an object type (such as bundle).

You can filter the MtxRequestSubscriberQuery, MtxRequestDeviceQuery, MtxRequestGroupQuery, and MtxRequestSubscriptionQuery responses with the following Boolean fields:

FilterNonCatalogItems — When true, the PurchasedOfferArray in the response does not include purchased offers that are part of a bundle. Information about the required balances of each non catalog item is returned in the MtxPurchasedOfferInfo.RequiredBalanceArray array of the parent bundle in the API response.
FilterInvalidPurchasedOffer — When true, the response does not include expired purchased offers.
FilterInvalidBalance — When true, the BalanceArray in the response does not include expired balances. MtxRequestDeviceQuery does not have the FilterInvalidBalance field.

For multi-tenancy, the following event query APIs only return events for which the caller is authorized.

MtxRequestSubscriberQueryEvent
MtxRequestGroupQueryEvent
MtxRequestDeviceQueryEvent
MtxRequestUserQueryEvent
MtxRequestEventQuery

The MtxOpMsg TenantIdList field has the tenants for the caller. When the TenantIdList is null, the caller has access to all events. When the TenantIdList is not empty, the caller has access to events in the listed tenants and events without a TenantId. When the TenantIdList is empty, the caller has access to events without a TenantId. The MtxEvent TenantId field identifies the tenant to which the event initiator belongs.