ID Prefixes and Formats
ID prefixes and formats ensure your IDs are easily recognizable and URL-safe for API requests. Follow these ID guidelines to maintain consistency and simplify your integration management.ID Prefixes
Consider using the prefxiesU- for users, M- for members, A- for accounts, and T- for transactions to make each ID easier to distinguish when multiple IDs are used in API requests.
ID Format
IDs appear in the URL for MDX Real Time and MDX On Demand requests. As such, they must be URL-safe. The MDX specification limits IDs to letters, numbers, hyphens, and underscores. If the value you need to use as an ID isn’t URL-safe, encode it with hex encoding or Base64URL. If you encode with Base64URL, remove character padding to make the ID URL-safe. You can do this by padding the ID to a multiple of three bytes before converting it to Base64. This eliminates the need for URL percent-encoding on the IDs.User ID Format
Use a value that already exists in the user’s record for the user ID. Don’t use an account number or other sensitive value. A record number or similar value is ideal. Using a value that already exists in the user’s record makes it predictable, which facilitates expanding your integration later to include additional APIs.Member ID Format
Base the member ID on the same value as the user ID so you only have a single value to deal with.Account ID Format
Account IDs must be unique within the member. If your system uses account IDs that are globally unique or unique per user, you can use this ID as the MX account ID. This appears in the URL for MDX On Demand and MDX Real Time requests. In the event that the account ID is a sensitive value, either use another value (such as a record number) or ensure the value is encrypted, hex encoded, or Base64 encoded.Transaction ID Format
Transaction IDs must be unique within the account and immutable. If you need to manufacture a transaction ID, you can combine a sequence number with the posted date to make a unique set of values within the account. For example, a transaction ID that uses the prefixT- to indicate a transaction, a six-digit sequence number, and a posted date would appear as T-20260820-123456. For pending transactions that don’t have a posted date, you can use the transaction date plus another field to ensure uniqueness.
Data Management
Consider your data management needs in the initial phases of integrating to MX. Data management considerations include actions such as deleting inactive or canceled users, updating user information, and updating member credentials if you use logins and passwords. If you’re integrating with MDX On Demand, account and transaction data is handled through ongoing updates via daily On Demand requests. MX APIs provide endpoints to perform all create, read, update, and delete actions on data entities in the MX platform. Use these endpoints as needed in your integration to keep your objects up to date. If you don’t account for data management in the initial phases of your integration and you end up needing to have large sets of data deleted or updated in the future, you can do so using Batch or a script using the MDX Real Time API, which is explained in MDX Real Time Workflow.On request, MX can initiate a purge of all data in your client. This typically is only used to remove test data when a test environment is refreshed or before going live.
Auto-enrollment Workflow
Use our auto-enrollment workflow during your login process to auto-enroll users. This workflow eliminates unnecessary API calls, and ensures that the user and member exist and are up to date in case data gets out of sync between MX and your system.Userkeys
When we send an MDX On Demand Create Session request, we provide the userkey you attached to the member when you created it. The userkey is not the same as the member ID that you assigned to the member, it’s a credential that you use to validate the user when we send the request. You can base the userkey on the same value you use for the user ID and member ID (for example,K-1234), or use a different value in your system that uniquely identifies the user (for example, an encrypted value). The userkey can contain any UTF-8 character so it is not limited to URL-safe characters. For more information about userkeys, refer to our Sessions guide.
Sending User Information
Provide user information (if available) such as first name, last name, email address, and postal code. Having this data in the MX system improves analytics data and troubleshooting for support issues on specific users.Handling Closed Accounts
We encourage data providers to provide account and transaction details for accounts closed within the past 30 days. This enables us to update these accounts on the MX platform so the user can tell the account is closed by its status and final zero balance. MX never assumes that an account has been closed. If a closed account doesn’t appear as such in the provider’s data feed, MX leaves the account in its current state and the account is displayed to the user as still having a balance, requiring them to mark the account as being closed via an MX widget or your UI. If you’re unable to include closed accounts in the data feed and would like to relay an account closure to MX, you can send MX a request via the MDX Real Time Update Account endpoint or Batch API Account endpoint. In the update, set theis_closed field to true and the balance field to 0.
MX only marks existing accounts as being closed. If the account doesn’t exist in the user’s data, MX ignores it. This prevents closed accounts from being added to a new user’s profile.
Omitting Fields Without Values
If your request contains a field that doesn’t have a value, or you don’t know what the correct value is, we suggest removing the field from your request. This prevents incorrect values from being set inadvertently, and prevents thenull value from overwriting the existing field’s data in PUT requests.
In rare cases where you’re not able to omit an empty field from a POST request, you can pass the field without a value in XML or JSON format. To do this in XML, use a set of self-closing tags (for example, <apr></apr>). If you’re using JSON, use the null value (for example, "apr":null). Never pass an empty string in JSON as the value of a field.
Values in Date Fields
MX has separate fields for the transaction date and the posted date. Both dates are required for posted transactions, but only the transaction date is required for a pending transaction. If only one date is available in your system, provide that date as both the transaction date and the posted date. There are two fields for each of the dates. For the transaction date, the fields aretransacted_at and transacted_on. For the posted date, the fields are posted_at and posted_on. You only need to provide one of the fields, not both. Use the _at field if your system has an accurate timestamp, otherwise use the _on field. For more information about date and time format, refer to Date and Time Formats.
Storing Data in the Metadata Field
Most objects on the MX platform include a writablemetadata field, enabling you to store additional information related to that object. For example, if you create a transaction, you may send information in the metadata field with the Create Transaction endpoint.
Contents of the metadata field are the responsibility of the party creating the object. MX doesn’t remove or alter the contents of this field.
Use JSON key-value pairs encoded as Base64 strings in the metadata field to ensure compatibility with JSON or XML payloads. This allows for flexible and scalable data storage without compromising existing values.
To do this, store the JSON object by converting it into a Base64 string, place the string value in the metadata field, then decode the string back into the key-value pair when reading the object.
For example, the JSON key-value pair {"rewards_eligible": true, "reward_program": "MILES"} would be converted into the Base64 string eyJyZXdhcmRzX2VsaWdpYmxlIjp0cnVlLCJyZXdhcmRfcHJvZ3JhbSI6Ik1JTEVTIn0=, then decoded back into {"rewards_eligible": true, "reward_program": "MILES"} when the object is read.