Syntax

The generic syntax of each API request and response operation includes a description, the base MDC container used by the operation, and the data elements used by the operation.

All data elements used by an operation are formatted in the API reference in tables, with columns being the name of the data element, the data type, any flags, and a description. Flags describes the element flags.
Table 1. Flags
Flag Description
Required The element is always required in requests.
Always Present The element is always present in responses.
Cond Conditionally required or present based on the presence or value of another field or container. For elements that are conditional, the conditions are listed in the Description column.
* The element occurs zero-or-more times, as with an optional array element.
+ The element occurs one-or-more times, as with a required array element.
0..n The element occurs at most n times, where n is the maximum number of times it can occur. For example, 0..1 indicates an optional field that can occur, at most, one time.
The description for a specific element can include allowed values for that element. In general, the REST APIs allow either a numeric value or its descriptive STRING equivalent. During processing, the numeric value for a REST API element is translated into the descriptive STRING value. The SubMan API's define certain integer fields as enumerations. When using the Java APIs, the raw integer values are used. When using the REST APIs, either the integer value or the enumeration value can be supplied. However, responses always use the enumeration value. When the Java API expects the numeric value, the reference topic for that API includes all possible numeric values for an element and their corresponding descriptive values. For example, the MtxRequestGroupTopupBalance EndTimeExtensionOffsetUnit field in the Java API reference indicates the following:
  • "hours" (1)
  • "days" (2)
  • "weeks" (3)
  • "months" (4)
  • "years" (5)
  • "minutes" (6)

When specifying a Subscriber ObjectType, you must use the numeric value, 2. The life cycle REST call can use either the numeric value for a subscriber, 2, or the string value, Subscriber.

Important: REST API requirements vary depending on the API and the URL or the request XML may require a non-numerical value only. Unless otherwise indicated, you should use only the non-numerical value in the API call.