Connect to and verify financial data
Cleanse and categorize financial data
Personalized, digital financial experiences
Policies
Contact
MX Technologies, Inc.
© 2026 MX Technologies, Inc.
400 Bad Request error will be returned.
| Parameter | Required? |
| :--------- | :-------- |
| `metadata` | No |
| `name` | No |
`Endpoint: PUT /user/{user_guid}/categories`
` and `` elements should always be present in the error response body.
The format for sending an error is shown in the example.
| Code | Message | Description |
| ---- | ------------------- | ------------------------------------------------- |
| 4010 | Invalid Credentials | The user key or login and password were invalid. |
| 4011 | Locked | The login was valid, but the account was locked. |
| 4012 | Invalid Session Key | The provided session key was invalid. |
| 4013 | MFA Failed | The MFA login information provided was incorrect. |
```xml theme={null}
4010
Error message.
```
## Response Format
The MDX On Demand specification is XML-based. Responses are required to be UTF-8 encoded and XML tags must be lowercase. Reserved XML characters must be properly escaped. The XML response must not contain Unicode Byte Order Mark characters (for example, `0xfeff`).
## Compression
Gzip compression is supported when `Content-Encoding` is set to `gzip`.
## Data Sanitization
You are required to avoid sending identifiable account information such as complete account and/or credit card numbers for account IDs and names.
# Account Number Fields
Source: https://docs.mx.com/api-reference/more-apis/mdx/mdx-on-demand/reference/account-numbers/account-number-fields
Account number fields for the MDX On Demand API.
## Account Number Fields
| Field Name | Data Type | Description |
| ---------------- | --------- | ------------------------------------------------------------------------------- |
| `account_number` | `String` | The full, unmasked banking account number associated with a particular account. |
| `routing_number` | `String` | The routing number for the financial institution associated with the account. |
# List Account Numbers
Source: https://docs.mx.com/api-reference/more-apis/mdx/mdx-on-demand/reference/account-numbers/list-account-numbers
GET https://{partner_base_url}/{institution_id}/accounts/{account_id}/account_numbers
This endpoint should return a list of account numbers.
This endpoint should return a list of account number objects.
## Response Fields
The full, unmasked banking account number associated with a particular account.
` element. The `` element **must** contain an `` field and an `account_owner` element. Any other account fields will be ignored.
## Response Fields
` element should be returned.
MX will reconcile the accounts in our system with the accounts received in the response. This reconciliation process will insert new accounts and will update existing account details. Accounts that exist in the MX system that are not received in the data feed will **not** be removed.
MX recommends partners return recently-closed accounts in the response with the `is_closed` field set to `true`. This allows MX to mark the account as closed, but to retain the account's history for the user.
## Response Fields
This indicates whether the account has holdings associated with it. This field is used fo syncing holdings with MDX On Demand and is not included in models for other APIs such as MDX Real Time, Nexus, or Platform.
true `. Holdings will not be requested for any account that does not indicate it has holdings.
If the provided `account_id` is invalid, a `404 Not Found` error response should be returned.
The list holdings success response **must** contain an `` element. The `` element **must** contain an `` field and a `` element. Any other account fields will be ignored.
If the account contains no holdings, an empty or self-terminating `` element (including the required attributes) should be returned in the `` element.
## Pagination
Holdings responses may be paginated when there are more than can conveniently be returned in a single response. You can return any number of holdings, but the response must be received in a timely manner. If MX doesn't receive a response within 60 seconds, the request will time out and the job will be terminated. If you need to retrieve holdings data from more than one data repository, then pagination can be used so that the holdings from each data repository can be retrieved separately.
An MX request to `/accounts/{account_id}/holdings` always includes a `page` parameter on the URL. Your response must include `page` and `pages` attributes in the `` element. The `page` attribute will reflect the page being returned. MX always makes a request for page `1`. The `pages` attribute returned in the response for page `1` indicates how many pages should be requested. If `pages` is greater than one, MX will request the additional pages.
You can cause MX to "break out" of these requests by returning `pages="0"` in any response. This is an indication that the last page has been reached and that MX should not request additional pages.
For example: Your response to page `1` indicates there will be 5 pages. MX will normally make additional requests for pages 2 through 5. However, if any of those requests returns `pages="0"` in the response, MX will not make any further page requests. This allows "dynamic paging" where a partner can signal to MX that there are no more pages even if the initial `pages` value has not yet been reached.
## Query Parameters
The page of holdings to return to MX.
## Response Fields
` element (including the required attributes) should be returned.
A success response **must** contain an `` element. The `` element **must** contain an `` field and a `` element. Any other account fields will be ignored.
## Query Parameters
One of either `posted_at` or `posted_on` is required.
One of either `posted_at` or `posted_on` is required.
` element. The `page` attribute will reflect the page being returned. MX always makes a request for page `1`. The `pages` attribute indicates how many pages should be requested. If `pages` is greater than `1`then MX will make requests for the additional pages.
You can cause MX to "break out" of these requests by returning `pages=0` in a response. This indicates that the last page has been reached and MX should not request additional pages. For example, if your response to page 1 indicates there will be five pages, MX will normally make additional requests for pages 2 through 5. However, if any of those requests return `pages=0`, then MX will not make any further page requests. This allows "dynamic paging" where you can signal to MX that there are no more pages even if the initial `pages` value has not yet been reached.
# Transaction Fields
Source: https://docs.mx.com/api-reference/more-apis/mdx/mdx-on-demand/reference/transactions/transaction_fields
Transaction fields for the MDX On Demand API.
## Transaction Fields
> For compatibility, the MDX Real Time API accepts ISO 8601 dates with timestamps, but timestamp information is ignored.
The MDX On Demand API does not accept timestamps on ISO 8601 dates.
| Field Name | Data Type | Description |
| ------------------------ | --------- | ----------------------------------------------------------------------------------------- |
| `account_guid` | `String` | Unique identifier for the account this transaction belongs to. Defined by MX. |
| `account_id` | `String` | Partner-defined unique identifier for the account. |
| `amount` | `Decimal` | Unsigned transaction amount. Type determines effect on account. Max Length 10,2. |
| `category_guid` | `String` | Unique identifier for transaction category. Defined by MX. Matches Nexus API. |
| `category_name` | `String` | Human-readable category name. May be null. |
| `category` | `String` | Enumerated category value. If invalid or missing, MX auto-categorizes. |
| `check_image` | `String` | Base64 data URI for check image (png/jpg/jpeg). |
| `check_number` | `String` | Check number. |
| `currency_code` | `String` | ISO 4217 three-character currency code. |
| `description` | `String` | Human-readable transaction description. Max length 1024. |
| `guid` | `String` | Unique identifier for the transaction. Defined by MX. |
| `id` | `String` | Partner-defined unique transaction identifier. Cannot start with `TRN-`. Max Length 1024. |
| `is_international` | `Boolean` | Indicates whether transaction is international. |
| `latitude` | `Decimal` | Latitude of transaction location (signed decimal). |
| `localized_description` | `String` | Local-language transaction description. |
| `localized_memo` | `String` | Local-language memo. |
| `longitude` | `Decimal` | Longitude of transaction location (signed decimal). |
| `member_guid` | `String` | Unique identifier for member. Defined by MX. |
| `member_id` | `String` | Partner-defined member identifier. |
| `memo` | `String` | Additional transaction notes. Max length 1024. |
| `merchant_category_code` | `String` | Merchant category code. |
| `merchant_guid` | `String` | Unique merchant identifier. Defined by MX. |
| `merchant_location_guid` | `String` | Unique merchant location identifier. Defined by MX. |
| `metadata` | `String` | Partner-defined metadata for the transaction. |
| `posted_at` | `Integer` | Date/time transaction was posted (Unix epoch UTC). Required if POSTED. |
| `posted_on` | `String` | Posted date. Required if POSTED when `posted_at` not used. |
| `running_balance` | `Decimal` | Account balance after transaction (POSTED only). |
| `status` | `String` | Transaction status: `PENDING` or `POSTED`. |
| `transacted_at` | `Integer` | Date/time transaction occurred (Unix epoch UTC). |
| `transacted_on` | `String` | Date transaction occurred. |
| `type` | `String` | Transaction type: `DEBIT` or `CREDIT`. |
| `user_guid` | `String` | Unique user identifier. Defined by MX. |
| `user_id` | `String` | Partner-defined user identifier. |
# Read User (Deprecated)
Source: https://docs.mx.com/api-reference/more-apis/mdx/mdx-on-demand/reference/users/read_user
GET https://{partner_base_url}/{institution_id}/{client_id}/user
This endpoint has been deprecated.
## Response Fields
4001
One or more parameters were invalid
```
The MDX Real Time API uses conventional HTTP status codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing), and codes in the 5xx range indicate an error with the MX Platform.
**HTTP status code summary**
* 200 OK: Everything worked as expected.
* 204 No Content: Everything worked, but no content is being returned. Typically returned from a DELETE request.
* 400 Bad Request: Invalid or malformed request body.
* 401 Unauthorized: No valid API key provided.
* 403 Forbidden: The IP address doesn't match the API key provided.
* 404 Not Found: The requested item doesn't exist.
* 409 Conflict: The object being created already exists. Can only be returned from a POST request.
* 422 Unprocessable Entity: The data provided does not meet acceptable criteria. Typically returned from a POST or PUT request, when attempting to add a field with more characters than allowed in the Data Spec, or when a field contains invalid characters.
* 429 Too Many Requests: This error is triggered when exceeding the maximum number of concurrent connections or rate limit. See details below.
* 500, 502, 504 Server errors: Something went wrong on MX's end.
* 503 Service Unavailable: The MX Platform is being updated.
### 429 Too Many Requests
This error is triggered when the maximum number of concurrent connections has been exceeded or the rate limit for requests per second (RPS) has been surpassed. Requests receiving a 429 status code should be retried once the rate limit window has expired.
To prevent this error, decrease the number of concurrent connections or the number of requests per second. Rate limiting is applied per client with the following thresholds:
* GET: 2000/RPS
* POST: 750/RPS
* PUT: 750/RPS
* DELETE: 150/RPS
Individual features may implement specific rate limit overrides.
## Error Response Format
Sometimes simply returning the HTTP status code is not enough to indicate what went wrong. To compensate for this, endpoints *may* respond with a body containing more information about the error. Each error consists of a code and a message:
### Additional Error Codes
Error codes and messages are for logging and for informational purposes only and may change from time to time. Do not check for specific codes or messages as this may break your integration. The HTTP status response codes are sufficient for an integration workflow and processing of the error response body is not needed.
| Code | HTTP Status | Description |
| ---- | ----------- | ---------------------------------------------------------------------------------------------- |
| 4001 | 400 | One or more parameters were invalid. |
| 4002 | 400 | Required parameter(s) missing. |
| 4003 | 400 | One or more of the credentials provided in this request are not supported by this institution. |
| 4221 | 422 | One or more parameters had an invalid id format. |
| 5001 | 500 | Institution not found for member create. |
## Escaped Characters
If using JSON format, please use the standard JSON escapement for double quotes (") if included in any text/string fields.
If using XML format, please ensure it is valid XML by using standard XML escapement for all XML-reserved characters, or by wrapping these text/string fields that might contain these characters in CDATA tags.
## Headers
### Accept header
All requests require an accept header to specify the version and the encoding of the desired response body.
`Accept: application/vnd.moneydesktop.mdx.v5+xml`
OR
`Accept: application/vnd.moneydesktop.mdx.v5+json`
The encoding specified in the Accept header must match the encoding specified in the URL extension.
### Content-Type header
POST and PUT requests require a Content-Type header to specify the format of the request body.
`Content-type: application/vnd.moneydesktop.mdx.v5+xml`
OR
`Content-type: application/vnd.moneydesktop.mdx.v5+json`
## IP filtering
All requests sent to the MDX Real Time API are filtered by IP address. All IP addresses where API requests originate must be whitelisted. Requests made from invalid IP addresses will receive an `HTTP 403 FORBIDDEN`.
## Limitations
The MDX Real Time API limits partners to a specific number of requests per second. The limit is based on the partner's API key so it will apply to all requests from the partner for all clients. MX will work with each partner to set the maximum rate based on that partner's needs.
## Orchestration
The MDX Real Time API requires a partner be responsible for orchestrating requests to the MX Platform. Partners must create records that have dependencies first. For example, an account must be created before creating transactions under that account.
When deleting records, a cascading delete will be performed to delete all records under that record in the hierarchy. For example, it is not necessary to delete transactions attached to an account before deleting the account.
## Security
Requests must use TLS 1.2 (or higher) with known secure ciphers.
## URL Extension
The encoding of the response body is specified by an extension on the URL. If the extension is omitted, `xml` will be used.
Example request URL for a JSON response body: `https://live.moneydesktop.com/your_client_id/users.json`
## Versioning
We strive to make API changes backwards-compatible. When we make breaking changes, we increment the version, because of this, it is best to specify the version of the API with each request. Versions are passed as part of the request's Accept header and Content-Type header.
Requests that don't specify a version will get the latest representation of resources, and unsupported endpoints will simply return a `HTTP 404 NOT FOUND`.
### Enhancements Within the Current Version
MX continually makes enhancements to our APIs. Breaking changes are reserved for a new version, but non-breaking additions are regularly made in the current version. These include:
* New fields added to existing objects (e.g. Adding `currency_code` to `accounts`).
* New endpoints added (e.g. Adding `Create Holding`).
* New processes. At times MX will recommend a new process for accomplishing a task. The new process is an improvement on the previous process and is recommended for all integrations, but MX will continue to support the old process throughout the current version of the API.
Partners should expect these enhancements to occur regularly. A new field in an object should not affect any existing integrations since nothing is being removed, but partners need to ensure their system can process or ignore new fields automatically. Partners should not rely on a fixed data model in any object.
### Enhancements that will Require a New Version or Advanced Notice
The following changes are breaking changes so they will only be made in a new version of the API, or with advanced notice to partners.
* Removing a field from an object.
* Changing the format of a field, or the contents it returns.
* Removing an endpoint.
* Adding a new Enumerated Value to a string that returns a fixed set of values (e.g. transaction status).
* Major process changes (e.g. adding the requirement to use a new endpoint).
It is sometimes necessary to add new values to fields which return enumerators. Examples include `account_subtype` in the accounts model and `field_type` in the credentials model. Partner developers should allow for the addition of new enumerated values. MX will notify partners in advance when such additions are anticipated.
# Account Number Fields
Source: https://docs.mx.com/api-reference/more-apis/mdx/mdx-real-time/reference/account-numbers/account-number-fields
Account number fields for the MDX Real Time API.
## Account Number Fields
| Field Name | Data Type | Description |
| -------------------- | --------- | --------------------------------------------------------------------------------------- |
| `account_guid` | `String` | The unique identifier for the associated account. Defined by MX. |
| `account_id` | `String` | Partner-provided unique identifier for the account associated with this account number. |
| `account_number` | `String` | Full, unmasked banking account number associated with the account. |
| `institution_number` | `String` | Three-digit number identifying a Canadian banking institution. |
| `member_guid` | `String` | Unique identifier for the member of the associated account. Defined by MX. |
| `member_id` | `String` | Partner-provided unique identifier for the member of the associated account. |
| `passed_validation` | `String` | Indicates whether account and routing numbers passed MX validation checks. |
| `routing_number` | `String` | Routing number for the financial institution associated with the account. |
| `transit_number` | `String` | Five-digit number identifying the branch of a Canadian financial institution. |
| `user_guid` | `String` | Unique identifier for the user of the associated account. Defined by MX. |
| `user_id` | `String` | Partner-provided unique identifier for the user of the associated account. |
# Create or Update Account Number
Source: https://docs.mx.com/api-reference/more-apis/mdx/mdx-real-time/reference/account-numbers/create-update-account-number
PUT https://int-live.moneydesktop.com/{client_id}/users/{user_id}/members/{member_id}/accounts/{account_id}/account_number
Use this endpoint to set the full account number, routing number, transit numbers, and banking institution for an account as needed.
## Path Parameters
The full, unmasked banking account number associated with a particular account.
Must be three-digit number to identify a Canadian banking institution.
Must be valid nine-digit routing number.
Must be three-digit number to identify a Canadian banking institution.
# Delete Account Number
Source: https://docs.mx.com/api-reference/more-apis/mdx/mdx-real-time/reference/account-numbers/delete-account-number
DELETE https://int-live.moneydesktop.com/{client_id}/users/{user_id}/members/{member_id}/accounts/{account_id}/account_number
Use this endpoint to delete an account number.
## Path Parameters
The old `id`.
## Body Parameters
The new `id`.
# Update Account
Source: https://docs.mx.com/api-reference/more-apis/mdx/mdx-real-time/reference/accounts/update-account
PUT https://int-live.moneydesktop.com/{client_id}/users/{user_id}/members/{member_id}/accounts/{account_id}
Use this endpoint to update an account. This endpoint accepts the optional `MX-SKIP-WEBHOOK` header.
## Path Parameters
Paired with password credential.
Paired with login credential.
Credential used by itself.
# Delete Member
Source: https://docs.mx.com/api-reference/more-apis/mdx/mdx-real-time/reference/members/delete-member
DELETE https://int-live.moneydesktop.com/{client_id}/users/{user_id}/members/{member_id}
Use this endpoint to delete a member. This endpoint accepts the optional `MX-SKIP-WEBHOOK` header.
## Path Parameters
The old `id`.
## Body Parameters
The new `id`.
# Update Member
Source: https://docs.mx.com/api-reference/more-apis/mdx/mdx-real-time/reference/members/update-member
PUT https://int-live.moneydesktop.com/{client_id}/users/{user_id}/members/{member_id}
Use this endpoint to update a member. This endpoint accepts the optional `MX-SKIP-WEBHOOK` header.
## Path Parameters
paired with password credential
paired with login credential
credential used by itself
```shell Request theme={null}
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import org.json.JSONObject;
public class MDX_RealTime {
private String BaseUrl, ClientId, ApiKey;
public MDX_RealTime(String BaseUrl, String ClientId, String ApiKey) {
this.BaseUrl = BaseUrl;
this.ClientId = ClientId;
this.ApiKey = ApiKey;
}
public static void main(String[] args) throws Exception {
String base_url = "https://int-live.moneydesktop.com";
String client_id = ":client_id";
String api_key = ":api_key";
MDX_RealTime mdx = new MDX_RealTime(base_url, client_id, api_key);
/// Setup Member Update json object
String user_id = "U-39XBF7";
String member_id = "M-39XBF7";
JSONObject member = new JSONObject();
JSONObject fields = new JSONObject();
fields.put("userkey", "32423DHDJDJH3947378");
member.put("member", fields);
mdx.UpdateMember(user_id, member_id, member);
}
public void UpdateMember(String user_id, String member_id, JSONObject member) {
try {
String uri = BaseUrl + "/" + ClientId + "/users/" + user_id + "/members/" + member_id + ".json";
URL url = new URL(uri);
HttpsURLConnection con = (HttpsURLConnection) url.openConnection();
con.setRequestMethod("PUT");
con.setRequestProperty("Accept", "application/vnd.moneydesktop.mdx.v5+json");
con.setRequestProperty("Content-Type", "application/vnd.moneydesktop.mdx.v5+json");
con.setRequestProperty("MD-API-KEY", ApiKey);
con.setDoOutput(true);
OutputStream out = con.getOutputStream();
out.write(member.toString().getBytes("UTF-8"));
out.close();
BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
con.disconnect();
System.out.println(response.toString());
} catch (Exception e) {
System.out.println(e);
}
}
}
```
```json 200 theme={null}
{
"member": {
"guid": "MBR-3e4f6897-06ae-e08a-29b2-27d62e574978",
"id": "M-39XBF7",
"metadata": null,
"name": "Acme Bank",
"user_guid": "USR-fe9bb059-67c4-0e6b-e8cd-3fa00b2b5735",
"user_id": "U-39XBF7",
"is_disabled": false
}
}
```
# Create Transaction
Source: https://docs.mx.com/api-reference/more-apis/mdx/mdx-real-time/reference/transactions/create-transaction
POST https://int-live.moneydesktop.com/{client_id}/users/{user_id}/members/{member_id}/accounts/{account_id}/transactions
Use this endpoint to create a transaction. This endpoint accepts the optional `MX-SKIP-WEBHOOK` header. It is recommended that partners only send dates in one format, using either the `_on` or `_at` fields, but not both.
## Path Parameters
One of either `posted_at` or `posted_on` is required.
One of either `posted_at` or `posted_on` is required.
One of either `transacted_at` or `transacted_on` is required.
One of either `transacted_at` or `transacted_on` is required.
```shell Request theme={null}
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import org.json.JSONObject;
public class MDX_RealTime {
private String BaseUrl, ClientId, ApiKey;
public MDX_RealTime(String BaseUrl, String ClientId, String ApiKey) {
this.BaseUrl = BaseUrl;
this.ClientId = ClientId;
this.ApiKey = ApiKey;
}
public static void main(String[] args) throws Exception {
String base_url = "https://int-live.moneydesktop.com";
String client_id = ":client_id";
String api_key = ":api_key";
MDX_RealTime mdx = new MDX_RealTime(base_url, client_id, api_key);
/// Setup Account Create json object
String user_id = "U-39XBF7";
String member_id = "M-39XBF7";
String account_id = "A-XA5Y4L";
String transaction_id = "T-3QP5X0";
JSONObject transaction = new JSONObject();
JSONObject fields = new JSONObject();
fields.put("id", "T-3QP5X0");
fields.put("amount", 8.20);
fields.put("description", "COSTCO GAS STATION #22299");
fields.put("status", "PENDING");
fields.put("type", "DEBIT");
fields.put("transacted_on", "2017-01-20");
transaction.put("transaction", fields);
mdx.CreateTransaction(user_id, member_id, account_id, transaction);
}
public void CreateTransaction(String user_id, String member_id, String account_id, JSONObject transaction) {
try {
String uri = BaseUrl + "/" + ClientId + "/users/" + user_id + "/members/" + member_id + "/accounts/" + account_id + "/transactions.json";
URL url = new URL(uri);
HttpsURLConnection con = (HttpsURLConnection) url.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Accept", "application/vnd.moneydesktop.mdx.v5+json");
con.setRequestProperty("Content-Type", "application/vnd.moneydesktop.mdx.v5+json");
con.setRequestProperty("MD-API-KEY", ApiKey);
con.setDoOutput(true);
OutputStream out = con.getOutputStream();
out.write(transaction.toString().getBytes("UTF-8"));
out.close();
BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
con.disconnect();
System.out.println(response.toString());
} catch (Exception e) {
System.out.println(e);
}
}
}
```
```json 200 theme={null}
{
"transaction": {
"account_guid": "ACT-a341b026-635c-8318-002c-9f3a58b0eff8",
"account_id": "A-XZ5Y4L",
"amount": 8.2,
"category": "GAS",
"category_guid": "CAT-7829f71c-2e8c-afa5-2f55-fa3634b89874",
"category_name": "Gas",
"check_image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
"check_number": "9543",
"currency_code": null,
"description": "Costco (Gas)",
"guid": "TRN-cd2987fe-9afb-e912-a5e3-2eaabb866e43",
"id": "T-3QP5X0",
"is_international": false,
"latitude": "40.429675",
"localized_description": null,
"localized_memo": null,
"longitude": "-111.891982",
"member_guid": "MBR-3e4f6897-06ae-e08a-29b2-27d62e574978",
"member_id": "M-39XBF7",
"memo": "POS Purchase",
"merchant_category_code": null,
"merchant_guid": "MCH-bcd4eed1-f341-b7bb-4cbd-e2a854205306",
"merchant_location_guid": null,
"metadata": null,
"posted_at": 1382961600,
"posted_on": "2013-10-28",
"running_balance": 345.45,
"status": "POSTED",
"transacted_at": 1382961600,
"transacted_on": "2013-10-28",
"type": "DEBIT",
"user_guid": "USR-fe9bb059-67c4-0e6b-e8cd-3fa00b2b5735",
"user_id": "U-39XBF7"
}
}
```
# Delete Transaction
Source: https://docs.mx.com/api-reference/more-apis/mdx/mdx-real-time/reference/transactions/delete-transaction
DELETE https://int-live.moneydesktop.com/{client_id}/users/{user_id}/members/{member_id}/accounts/{account_id}/transactions/{transaction_id}
Use this endpoint to delete a transaction. This endpoint accepts the optional `MX-SKIP-WEBHOOK` header.
## Path Parameters
```shell Request theme={null}
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
public class MDX_RealTime {
private String BaseUrl, ClientId, ApiKey;
public MDX_RealTime(String BaseUrl, String ClientId, String ApiKey) {
this.BaseUrl = BaseUrl;
this.ClientId = ClientId;
this.ApiKey = ApiKey;
}
public static void main(String[] args) throws Exception {
String base_url = "https://int-live.moneydesktop.com";
String client_id = ":client_id";
String api_key = ":api_key";
MDX_RealTime mdx = new MDX_RealTime(base_url, client_id, api_key);
/// Setup IDs
String user_id = "U-39XBF7";
String member_id = "M-39XBF7";
String account_id = "A-XA5Y4L";
String transaction_id = "T-3QP5X0";
mdx.DeleteTransaction(user_id, member_id, account_id, transaction_id);
}
public void DeleteTransaction(String user_id, String member_id, String account_id, String transaction_id) {
try {
String uri = BaseUrl + "/" + ClientId + "/users/" + user_id + "/members/" + member_id + "/accounts/" + account_id + "/transactions/" + transaction_id + ".json";
URL url = new URL(uri);
HttpsURLConnection con = (HttpsURLConnection) url.openConnection();
con.setRequestMethod("DELETE");
con.setRequestProperty("Accept", "application/vnd.moneydesktop.mdx.v5+json");
con.setRequestProperty("MD-API-KEY", ApiKey);
BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
con.disconnect();
System.out.println(response.toString());
} catch (Exception e) {
System.out.println(e);
}
}
}
```
```json 204 theme={null}
204 No Content
```
# Read Transaction
Source: https://docs.mx.com/api-reference/more-apis/mdx/mdx-real-time/reference/transactions/read-transaction
GET https://int-live.moneydesktop.com/{client_id}/users/{user_id}/members/{member_id}/accounts/{account_id}/transactions/{transaction_id}
Use this endpoint to read a transaction.
Use this endpoint to read an transaction.
## Path Parameters
```shell Request theme={null}
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
public class MDX_RealTime {
private String BaseUrl, ClientId, ApiKey;
public MDX_RealTime(String BaseUrl, String ClientId, String ApiKey) {
this.BaseUrl = BaseUrl;
this.ClientId = ClientId;
this.ApiKey = ApiKey;
}
public static void main(String[] args) throws Exception {
String base_url = "https://int-live.moneydesktop.com";
String client_id = ":client_id";
String api_key = ":api_key";
MDX_RealTime mdx = new MDX_RealTime(base_url, client_id, api_key);
/// Setup IDs
String user_id = "U-39XBF7";
String member_id = "M-39XBF7";
String account_id = "A-XA5Y4L";
String transaction_id = "T-3QP5X0";
mdx.ReadTransaction(user_id, member_id, account_id, transaction_id);
}
public void ReadTransaction(String user_id, String member_id, String account_id, String transaction_id) {
try {
String uri = BaseUrl + "/" + ClientId + "/users/" + user_id + "/members/" + member_id + "/accounts/" + account_id + "/transactions/" + transaction_id + ".json";
URL url = new URL(uri);
HttpsURLConnection con = (HttpsURLConnection) url.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "application/vnd.moneydesktop.mdx.v5+json");
con.setRequestProperty("MD-API-KEY", ApiKey);
BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
con.disconnect();
System.out.println(response.toString());
} catch (Exception e) {
System.out.println(e);
}
}
}
```
```json 200 theme={null}
{
"transaction": {
"account_guid": "ACT-a341b026-635c-8318-002c-9f3a58b0eff8",
"account_id": "A-XZ5Y4L",
"amount": 8.2,
"category": "GAS",
"category_guid": "CAT-7829f71c-2e8c-afa5-2f55-fa3634b89874",
"category_name": "Gas",
"check_image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
"check_number": "9543",
"currency_code": null,
"description": "Costco (Gas)",
"guid": "TRN-cd2987fe-9afb-e912-a5e3-2eaabb866e43",
"id": "T-3QP5X0",
"is_international": false,
"latitude": "40.429675",
"localized_description": null,
"localized_memo": null,
"longitude": "-111.891982",
"member_guid": "MBR-3e4f6897-06ae-e08a-29b2-27d62e574978",
"member_id": "M-39XBF7",
"memo": "POS Purchase",
"merchant_category_code": null,
"merchant_guid": "MCH-bcd4eed1-f341-b7bb-4cbd-e2a854205306",
"merchant_location_guid": null,
"metadata": null,
"posted_at": 1382961600,
"posted_on": "2013-10-28",
"running_balance": 345.45,
"status": "POSTED",
"transacted_at": 1382961600,
"transacted_on": "2013-10-28",
"type": "DEBIT",
"user_guid": "USR-fe9bb059-67c4-0e6b-e8cd-3fa00b2b5735",
"user_id": "U-39XBF7"
}
}
```
# Remap Transaction ID
Source: https://docs.mx.com/api-reference/more-apis/mdx/mdx-real-time/reference/transactions/remap-transaction-id
PUT https://int-live.moneydesktop.com/{client_id}/users/{user_id}/members/{member_id}/accounts/{account_id}/transactions/{transaction_id}/remap_id
Use this endpoint to remap the ID assigned to the transaction.
This endpoint allows partners to re-assign their partner-defined transaction ID.
## Path Parameters
The old `id`.
## Body Parameters
The new `id`.
```shell Request theme={null}
curl -i -X PUT https://int-live.moneydesktop.com/{client_id}/users/{user_id}/members/{member_id}/accounts/{account_id}/transactions/{transaction_id}/remap_id.json \
-H 'Content-Type: application/vnd.moneydesktop.mdx.v5+json' \
-H 'Accept: application/vnd.moneydesktop.mdx.v5+json' \
-H 'MD-API-KEY: {api_key}' \
-d '{
"transaction": {
"id": "A-2345"
}
}'
```
```json 200 theme={null}
{
"transaction": {
"account_guid": "ACT-a341b026-635c-8318-002c-9f3a58b0eff8",
"account_id": "A-XZ5Y4L",
"amount": 8.2,
"category": "GAS",
"category_guid": "CAT-7829f71c-2e8c-afa5-2f55-fa3634b89874",
"category_name": "Gas",
"check_image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
"check_number": "9543",
"currency_code": null,
"description": "Costco (Gas)",
"guid": "TRN-cd2987fe-9afb-e912-a5e3-2eaabb866e43",
"id": "T-3QP5X0",
"is_international": false,
"latitude": "40.429675",
"localized_description": null,
"localized_memo": null,
"longitude": "-111.891982",
"member_guid": "MBR-3e4f6897-06ae-e08a-29b2-27d62e574978",
"member_id": "M-39XBF7",
"memo": "POS Purchase",
"merchant_category_code": null,
"merchant_guid": "MCH-bcd4eed1-f341-b7bb-4cbd-e2a854205306",
"merchant_location_guid": null,
"metadata": null,
"posted_at": 1382961600,
"posted_on": "2013-10-28",
"running_balance": 345.45,
"status": "POSTED",
"transacted_at": 1382961600,
"transacted_on": "2013-10-28",
"type": "DEBIT",
"user_guid": "USR-fe9bb059-67c4-0e6b-e8cd-3fa00b2b5735",
"user_id": "U-39XBF7"
}
}
```
# Transaction Fields
Source: https://docs.mx.com/api-reference/more-apis/mdx/mdx-real-time/reference/transactions/transaction-fields
Field definitions for the MDX Real Time transaction data model.
| Field | Type | Description |
| :----------------------- | :------ | :------------------------------------------------------------------------------------- |
| `account_id` | String | The partner-defined unique identifier for the account associated with the transaction. |
| `amount` | Decimal | The monetary amount of the transaction. Positive for credits, negative for debits. |
| `category` | String | The category assigned to the transaction by MX. |
| `check_number` | String | The check number associated with the transaction, if applicable. |
| `created_at` | String | The ISO 8601 date and time the transaction was created. |
| `currency_code` | String | The three-character ISO 4217 currency code, e.g. `USD`. |
| `date` | String | The date on which the transaction occurred (`YYYY-MM-DD`). |
| `description` | String | A human-readable description of the transaction. |
| `id` | String | The partner-defined unique identifier for the transaction. |
| `is_bill_pay` | Boolean | Indicates whether the transaction represents a bill payment. |
| `is_direct_deposit` | Boolean | Indicates whether the transaction represents a direct deposit. |
| `is_expense` | Boolean | Indicates whether the transaction represents an expense. |
| `is_fee` | Boolean | Indicates whether the transaction represents a fee. |
| `is_income` | Boolean | Indicates whether the transaction represents income. |
| `is_international` | Boolean | Indicates whether the transaction is international. |
| `is_manual` | Boolean | Indicates whether the transaction was manually created. |
| `is_overdraft_fee` | Boolean | Indicates whether the transaction represents an overdraft fee. |
| `is_payroll_advance` | Boolean | Indicates whether the transaction represents a payroll advance. |
| `is_subscription` | Boolean | Indicates whether the transaction represents a subscription payment. |
| `latitude` | Decimal | The latitude of the location where the transaction occurred. |
| `longitude` | Decimal | The longitude of the location where the transaction occurred. |
| `memo` | String | Additional descriptive information about the transaction. |
| `merchant_category_code` | Integer | The ISO 18245 merchant category code for the transaction. |
| `merchant_id` | String | The partner-defined unique identifier for the merchant. |
| `original_description` | String | The original description of the transaction as provided by the data feed. |
| `posted_at` | String | The ISO 8601 date and time the transaction was posted to the account. |
| `status` | String | The status of the transaction: `POSTED` or `PENDING`. |
| `top_level_category` | String | The parent category of the transaction's assigned category. |
| `transacted_at` | String | The ISO 8601 date and time the transaction took place. |
| `type` | String | The type of transaction: `CREDIT` or `DEBIT`. |
| `updated_at` | String | The ISO 8601 date and time the transaction was last updated. |
| `user_id` | String | The partner-defined unique identifier for the user associated with the transaction. |
## Transaction Categories
| Category | Subcategory |
| :---------------- | :---------------------------------------------------------------------------- |
| Auto & Transport | Gas & Fuel, Parking, Public Transportation, Ride Sharing, Service & Parts |
| Bills & Utilities | Gas & Electric, Internet, Mobile Phone, Television, Water |
| Business Services | Advertising, Legal, Office Supplies, Printing, Shipping |
| Education | Books & Supplies, Student Loan, Tuition |
| Entertainment | Arts, Movies & DVDs, Music, Newspapers & Magazines, Sports |
| Fees & Charges | ATM Fee, Bank Fee, Finance Charge, Late Fee, Overdraft, Service Fee |
| Financial | Financial Advisor, Life Insurance, Investment |
| Food & Dining | Alcohol & Bars, Coffee Shops, Fast Food, Groceries, Restaurants |
| Gifts & Donations | Charity, Gift |
| Health & Fitness | Dentist, Doctor, Eye Care, Gym, Health Insurance, Pharmacy |
| Home | Furnishings, Home Improvement, Home Insurance, Home Services, Mortgage & Rent |
| Income | Bonus, Interest Income, Paycheck, Reimbursement, Rental Income |
| Investments | Buy, Deposit, Dividend & Cap Gains, Sell, Withdrawal |
| Kids | Baby Supplies, Babysitter & Daycare, Child Support, Toys |
| Personal Care | Hair, Laundry, Spa & Massage |
| Pets | Pet Food & Supplies, Pet Grooming, Veterinary |
| Shopping | Books, Clothing, Electronics & Software, Hobbies, Sporting Goods |
| Taxes | Federal Tax, Local Tax, Property Tax, State Tax |
| Transfer | Credit Card Payment, Transfer |
| Travel | Air Travel, Hotel, Rental Car & Taxi, Vacation |
| Uncategorized | — |
# Update Transaction
Source: https://docs.mx.com/api-reference/more-apis/mdx/mdx-real-time/reference/transactions/update-transaction
POST https://int-live.moneydesktop.com/{client_id}/users/{user_id}/members/{member_id}/accounts/{account_id}/transactions/{transaction_id}
Use this endpoint to update a transaction. This endpoint accepts the optional `MX-SKIP-WEBHOOK` header.
## Path Parameters
```shell Request theme={null}
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import org.json.JSONObject;
public class MDX_RealTime {
private String BaseUrl, ClientId, ApiKey;
public MDX_RealTime(String BaseUrl, String ClientId, String ApiKey) {
this.BaseUrl = BaseUrl;
this.ClientId = ClientId;
this.ApiKey = ApiKey;
}
public static void main(String[] args) throws Exception {
String base_url = "https://int-live.moneydesktop.com";
String client_id = ":client_id";
String api_key = ":api_key";
MDX_RealTime mdx = new MDX_RealTime(base_url, client_id, api_key);
/// Setup Account Update json object
String user_id = "U-39XBF7";
String member_id = "M-39XBF7";
String account_id = "A-XA5Y4L";
JSONObject transaction = new JSONObject();
JSONObject fields = new JSONObject();
fields.put("status", "POSTED");
fields.put("posted_on", "2017-01-21");
transaction.put("transaction", fields);
mdx.UpdateTransaction(user_id, member_id, account_id, transaction_id, transaction);
}
public void UpdateTransaction(String user_id, String member_id, String account_id, String transaction_id, JSONObject transaction) {
try {
String uri = BaseUrl + "/" + ClientId + "/users/" + user_id + "/members/" + member_id + "/accounts/" + account_id + "/transactions/" + transaction_id + ".json";
URL url = new URL(uri);
HttpsURLConnection con = (HttpsURLConnection) url.openConnection();
con.setRequestMethod("PUT");
con.setRequestProperty("Accept", "application/vnd.moneydesktop.mdx.v5+json");
con.setRequestProperty("Content-Type", "application/vnd.moneydesktop.mdx.v5+json");
con.setRequestProperty("MD-API-KEY", ApiKey);
con.setDoOutput(true);
OutputStream out = con.getOutputStream();
out.write(transaction.toString().getBytes("UTF-8"));
out.close();
BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
con.disconnect();
System.out.println(response.toString());
} catch (Exception e) {
System.out.println(e);
}
}
}
```
```json 200 theme={null}
{
"transaction": {
"account_guid": "ACT-a341b026-635c-8318-002c-9f3a58b0eff8",
"account_id": "A-XZ5Y4L",
"amount": 8.2,
"category": "GAS",
"category_guid": "CAT-7829f71c-2e8c-afa5-2f55-fa3634b89874",
"category_name": "Gas",
"check_image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
"check_number": "9543",
"currency_code": null,
"description": "Costco (Gas)",
"guid": "TRN-cd2987fe-9afb-e912-a5e3-2eaabb866e43",
"id": "T-3QP5X0",
"is_international": false,
"latitude": "40.429675",
"localized_description": null,
"localized_memo": null,
"longitude": "-111.891982",
"member_guid": "MBR-3e4f6897-06ae-e08a-29b2-27d62e574978",
"member_id": "M-39XBF7",
"memo": "POS Purchase",
"merchant_category_code": null,
"merchant_guid": "MCH-bcd4eed1-f341-b7bb-4cbd-e2a854205306",
"merchant_location_guid": null,
"metadata": null,
"posted_at": 1382961600,
"posted_on": "2013-10-28",
"running_balance": 345.45,
"status": "POSTED",
"transacted_at": 1382961600,
"transacted_on": "2013-10-28",
"type": "DEBIT",
"user_guid": "USR-fe9bb059-67c4-0e6b-e8cd-3fa00b2b5735",
"user_id": "U-39XBF7"
}
}
```
# Create User
Source: https://docs.mx.com/api-reference/more-apis/mdx/mdx-real-time/reference/users/create-user
POST https://int-live.moneydesktop.com/{client_id}/users
Use this endpoint to create a user. This endpoint accepts the optional `MX-SKIP-WEBHOOK` header.
## Body Parameters
```shell Request theme={null}
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import org.json.JSONObject;
public class MDX_RealTime {
private String BaseUrl, ClientId, ApiKey;
public MDX_RealTime(String BaseUrl, String ClientId, String ApiKey) {
this.BaseUrl = BaseUrl;
this.ClientId = ClientId;
this.ApiKey = ApiKey;
}
public static void main(String[] args) throws Exception {
String base_url = "https://int-live.moneydesktop.com";
String client_id = ":client_id";
String api_key = ":api_key";
MDX_RealTime mdx = new MDX_RealTime(base_url, client_id, api_key);
/// Setup User Create json object
String user_id = "U-39XBF7";
JSONObject user = new JSONObject();
JSONObject fields = new JSONObject();
fields.put("id", user_id);
user.put("user", fields);
mdx.CreateUser(user);
}
public void CreateUser(JSONObject user) {
try {
String uri = BaseUrl + "/" + ClientId + "/users.json";
URL url = new URL(uri);
HttpsURLConnection con = (HttpsURLConnection) url.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Accept", "application/vnd.moneydesktop.mdx.v5+json");
con.setRequestProperty("Content-Type", "application/vnd.moneydesktop.mdx.v5+json");
con.setRequestProperty("MD-API-KEY", ApiKey);
con.setDoOutput(true);
OutputStream out = con.getOutputStream();
out.write(user.toString().getBytes("UTF-8"));
out.close();
BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
con.disconnect();
System.out.println(response.toString());
} catch (Exception e) {
System.out.println(e);
}
}
}
```
```json 200 theme={null}
{
"user": {
"id": "U-39XBF7",
"birthdate": "1959-07-17",
"gender": "MALE",
"first_name": "John",
"guid": "USR-c4321d57a-9ae4-1fe3-6c4e-96a84fb92b50",
"last_name": "Smith",
"metadata": "Additional Information",
"credit_score": 718,
"email": "example@example.com",
"phone": "(505) 555-1234",
"zip_code": "87101",
"is_disabled": false,
"logged_in_at": null
}
}
```
# Delete user
Source: https://docs.mx.com/api-reference/more-apis/mdx/mdx-real-time/reference/users/delete-user
## Path Parameters
```shell Request theme={null}
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
public class MDX_RealTime {
private String BaseUrl, ClientId, ApiKey;
public MDX_RealTime(String BaseUrl, String ClientId, String ApiKey) {
this.BaseUrl = BaseUrl;
this.ClientId = ClientId;
this.ApiKey = ApiKey;
}
public static void main(String[] args) throws Exception {
String base_url = "https://int-live.moneydesktop.com";
String client_id = ":client_id";
String api_key = ":api_key";
MDX_RealTime mdx = new MDX_RealTime(base_url, client_id, api_key);
/// Setup IDs
String user_id = "U-39XBF8";
mdx.DeleteUser(user_id);
}
public void DeleteUser(String user_id) {
try {
String uri = BaseUrl + "/" + ClientId + "/users/" + user_id + ".json";
URL url = new URL(uri);
HttpsURLConnection con = (HttpsURLConnection) url.openConnection();
con.setRequestMethod("DELETE");
con.setRequestProperty("Accept", "application/vnd.moneydesktop.mdx.v5+json");
con.setRequestProperty("MD-API-KEY", ApiKey);
BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
con.disconnect();
System.out.println(response.toString());
} catch (Exception e) {
System.out.println(e);
}
}
}
```
```shell 204 theme={null}
No Content
```
# Read User
Source: https://docs.mx.com/api-reference/more-apis/mdx/mdx-real-time/reference/users/read-user
GET https://int-live.moneydesktop.com/{client_id}/users/{user_id}
Use this endpoint to read a user.
## Path Parameters
```shell Request theme={null}
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
public class MDX_RealTime {
private String BaseUrl, ClientId, ApiKey;
public MDX_RealTime(String BaseUrl, String ClientId, String ApiKey) {
this.BaseUrl = BaseUrl;
this.ClientId = ClientId;
this.ApiKey = ApiKey;
}
public static void main(String[] args) throws Exception {
String base_url = "https://int-live.moneydesktop.com";
String client_id = ":client_id";
String api_key = ":api_key";
MDX_RealTime mdx = new MDX_RealTime(base_url, client_id, api_key);
/// Setup IDs
String user_id = "U-39XBF8";
mdx.ReadUser(user_id);
}
public void ReadUser(String user_id) {
try {
String uri = BaseUrl + "/" + ClientId + "/users/" + user_id + ".json";
URL url = new URL(uri);
HttpsURLConnection con = (HttpsURLConnection) url.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "application/vnd.moneydesktop.mdx.v5+json");
con.setRequestProperty("MD-API-KEY", ApiKey);
BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
con.disconnect();
System.out.println(response.toString());
} catch (Exception e) {
System.out.println(e);
}
}
}
```
```json 200 theme={null}
{
"user": {
"id": "U-39XBF7",
"birthdate": "1959-07-17",
"gender": "MALE",
"first_name": "John",
"guid": "USR-c4321d57a-9ae4-1fe3-6c4e-96a84fb92b50",
"last_name": "Smith",
"metadata": "Additional Information",
"credit_score": 718,
"email": "example@example.com",
"phone": "(505) 555-1234",
"zip_code": "87101",
"is_disabled": false,
"logged_in_at": null
}
}
```
# Remap User ID
Source: https://docs.mx.com/api-reference/more-apis/mdx/mdx-real-time/reference/users/remap-user-id
PUT https://int-live.moneydesktop.com/{client_id}/users/{user_id}/remap_id
This endpoint allows partners to re-assign their partner-defined user ID.
## Path Parameters
The old `id`.
## Body Parameters
The new `id`.
```shell Request theme={null}
// This code example will be added soon
```
```json 200 theme={null}
{
"user": {
"id": "U-39XBF7",
"birthdate": "1959-07-17",
"gender": "MALE",
"first_name": "John",
"guid": "USR-c4321d57a-9ae4-1fe3-6c4e-96a84fb92b50",
"last_name": "Smith",
"metadata": "Additional Information",
"credit_score": 718,
"email": "example@example.com",
"phone": "(505) 555-1234",
"zip_code": "87101",
"is_disabled": false,
"logged_in_at": null
}
}
```
# Update User
Source: https://docs.mx.com/api-reference/more-apis/mdx/mdx-real-time/reference/users/update-user
PUT https://int-live.moneydesktop.com/{client_id}/users/{user_id}
Use this endpoint to update a user. This endpoint accepts the optional `MX-SKIP-WEBHOOK` header.
## Path Parameters
```shell Request theme={null}
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import org.json.JSONObject;
public class MDX_RealTime {
private String BaseUrl, ClientId, ApiKey;
public MDX_RealTime(String BaseUrl, String ClientId, String ApiKey) {
this.BaseUrl = BaseUrl;
this.ClientId = ClientId;
this.ApiKey = ApiKey;
}
public static void main(String[] args) throws Exception {
String base_url = "https://int-live.moneydesktop.com";
String client_id = ":client_id";
String api_key = ":api_key";
MDX_RealTime mdx = new MDX_RealTime(base_url, client_id, api_key);
/// Setup User Update json object
String user_id = "U-39XBF7";
JSONObject user = new JSONObject();
JSONObject fields = new JSONObject();
fields.put("first_name", "Doug");
fields.put("gender", "MALE");
user.put("user", fields);
mdx.UpdateUser(user_id, user);
}
public void UpdateUser(String user_id, JSONObject user) {
try {
String uri = BaseUrl + "/" + ClientId + "/users/" + user_id + ".json";
URL url = new URL(uri);
HttpsURLConnection con = (HttpsURLConnection) url.openConnection();
con.setRequestMethod("PUT");
con.setRequestProperty("Accept", "application/vnd.moneydesktop.mdx.v5+json");
con.setRequestProperty("Content-Type", "application/vnd.moneydesktop.mdx.v5+json");
con.setRequestProperty("MD-API-KEY", ApiKey);
con.setDoOutput(true);
OutputStream out = con.getOutputStream();
out.write(user.toString().getBytes("UTF-8"));
out.close();
BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
con.disconnect();
System.out.println(response.toString());
} catch (Exception e) {
System.out.println(e);
}
}
}
```
```json 200 theme={null}
{
"user": {
"id": "U-39XBF7",
"birthdate": "1959-07-17",
"gender": "MALE",
"first_name": "John",
"guid": "USR-c4321d57a-9ae4-1fe3-6c4e-96a84fb92b50",
"last_name": "Smith",
"metadata": "Additional Information",
"credit_score": 718,
"email": "example@example.com",
"phone": "(505) 555-1234",
"zip_code": "87101",
"is_disabled": false,
"logged_in_at": null
}
}
```
# User Fields
Source: https://docs.mx.com/api-reference/more-apis/mdx/mdx-real-time/reference/users/user-fields
Field definitions for the MDX Real Time user data model.
| Field | Type | Description |
| :------------- | :------ | :------------------------------------------------------------------------- |
| `birthdate` | String | The user's date of birth (`YYYY-MM-DD`). |
| `created_at` | String | The ISO 8601 date and time the user was created. |
| `credit_score` | Integer | The user's credit score. |
| `email` | String | The user's email address. |
| `first_name` | String | The user's first name. |
| `gender` | String | The user's gender. |
| `id` | String | The partner-defined unique identifier for the user. |
| `is_disabled` | Boolean | Indicates whether the user is disabled. Disabled users are not aggregated. |
| `last_name` | String | The user's last name. |
| `metadata` | String | Additional information a partner can store on the user object. |
| `phone` | String | The user's phone number. |
| `updated_at` | String | The ISO 8601 date and time the user was last updated. |
| `zip_code` | String | The user's zip code. |
# Taggings Overview
Source: https://docs.mx.com/api-reference/nexus/reference/01-taggings-overview
Overview of tagging resource and field definitions
Taggings represent the connection of a `tag` to a `transaction` by a user.
Tags can only be created and managed by end users through MX's widgets or mobile platform.
## Tagging Fields
| Field name | Data type | Description |
| :-------------------------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `guid` | String | Unique identifier for the tagging. Defined by MX. |
| `member_is_managed_by_user` | Boolean | If the member the tagging belongs to is managed by the user, this field will be true. Otherwise, the member is managed by the MX partner and this field will be false. Members created with Nexus are considered to be managed by the user. |
| `tag_guid` | String | Unique identifier for the tag. Defined by MX. |
| `transaction_guid` | String | Unique identifier for the transaction. Defined by MX. |
| `user_guid` | String | Unique identifier for the user. Defined by MX. |
# Tags Overview
Source: https://docs.mx.com/api-reference/nexus/reference/01-tags-overview
Overview of tags resource and field definitions
Tags are custom labels that users create to organize and categorize their transactions beyond the default category system.
Tags can only be created and managed by end users through MX's widgets or mobile platform.
## Tags Fields
| `Field name` | Data type | Description |
| :----------- | :-------- | :------------------------------------------------ |
| `guid` | String | Unique identifier for the tagging. Defined by MX. |
| `name` | String | The name of the tag. Created by the user. |
| `user_guid` | String | Unique identifier for the user. Defined by MX. |
# Transaction Rules Overview
Source: https://docs.mx.com/api-reference/nexus/reference/01-transaction-rules-overview
Overview of transaction rules resource and field definitions
A transaction rule allows partners to specify a `match_description` and a `category`; all transactions matching the specified description will be placed in the chosen category.
Transaction rules override the default `category` MX gives to a `transaction`. Once a rule is created or updated, all past transactions with a matching cleansed `description` are placed in the partner-chosen `category`, and any future transactions will be placed in the chosen category as well.
For example, creating a rule with the `match_description` "Wal-mart" and the `category_guid` for "Groceries" will automatically apply that `category_guid` to any `transaction` with a matching `description`, including both existing and future transactions.
Partners must also provide a `description` when creating a `transaction_rule`. This string will replace all matched transactions' `description` value.
## Transaction Rule Fields
| Field name | Data type | Description |
| :------------------ | :-------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `category_guid` | String | A unique identifier for the category. Defined by MX. Use the list categories endpoint to get a complete list of available categories and their associated GUIDs. |
| `created_at` | String | The date and time the transaction\_rule was created, represented in ISO 8601 format with a timestamp, e.g. 2015-04-13T12:01:23-00:00. |
| `description` | String | The matched transaction's description will be updated to the string provided here. |
| `guid` | String | A unique identifier for the transaction\_rule. Defined by MX. |
| `match_description` | String | A string used to find a transaction to which the rule will be applied. Transaction matching is based on a comparison of match\_description to a transaction's cleansed description. |
| `updated_at` | String | The date and time the transaction\_rule was last updated, represented in ISO 8601 format with a timestamp, e.g. 2015-04-13T12:01:23-00:00. |
| `user_guid` | String | A unique identifier for the user to which the transaction\_rule belongs. Defined by MX. |
# Transactions Overview
Source: https://docs.mx.com/api-reference/nexus/reference/01-transactions-overview
Overview of transaction resource and field definitions
Transactions represent individual financial activities such as purchases, deposits, withdrawals, and transfers across user accounts.
## Transaction Fields
| Field Name | Data type | Description |
| :----------------------------- | :-------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `account_guid` | String | Unique identifier for the account. Defined by MX. |
| `amount` | Decimal | The transaction amount. This will always be a positive value. The Transaction Type determines how the transaction affects the account. |
| `amount_set_by` | Integer | The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ). See Transaction Set By for more information. |
| `amount_set_by_name` | String | The source that set the data ( FEED, USER, or SYSTEM ). See Transaction Set By for more information. |
| `category_guid` | String | Unique identifier for the transaction category. Defined by MX. |
| `category_name` | String | The name of the transaction category. |
| `category_set_by` | Integer | The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ). See Transaction Set By for more information. |
| `category_set_by_name` | String | The source that set the data ( FEED, USER, or SYSTEM ). See Transaction Set By for more information. |
| `check_number` | Integer | The check number for the transaction. (Deprecated). |
| `check_number_set_by` | Integer | The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ). See Transaction Set By for more information. |
| `check_number_set_by_name` | String | The source that set the data ( FEED, USER, or SYSTEM ). See Transaction Set By for more information. |
| `check_number_string` | String | The check number for the transaction. |
| `created_at` | String | Date and time the transaction was created, represented in ISO 8601 format with timestamp (e.g. 2015-04-13T12:01:23-00:00). |
| `currency_code` | String | The ISO 4217 three-character currency code (e.g. USD). |
| `currency_code_set_by` | Integer | The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ). See Transaction Set By for more information. |
| `currency_code_set_by_name` | String | The source that set the data ( FEED, USER, or SYSTEM ). See Transaction Set By for more information. |
| `date` | String | Date the transaction was created, represented in ISO 8601 format (e.g. 2011-03-28). |
| `date_set_by` | Integer | The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ). See Transaction Set By for more information. |
| `date_set_by_name` | String | The source that set the data ( FEED, USER, or SYSTEM ). See Transaction Set By for more information. |
| `description` | String | A human-readable description of the transaction. |
| `description_set_by` | Integer | The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ). See Transaction Set By for more information. |
| `description_set_by_name` | String | The source that set the data ( FEED, USER, or SYSTEM ). See Transaction Set By for more information. |
| `external_guid` | String | Partner created identifier for the transaction. |
| `feed_amount` | Decimal | Transaction amount, as provided by our data feed. See amount for more information. |
| `feed_check_number` | Integer | Check number, as provided by our data feed. See check\_number for more information. |
| `feed_check_number_string` | String | Check number, as provided by our data feed. See check\_number\_string for more information. |
| `feed_currency_code` | String | Currency code, as provided by our data feed. See currency\_code for more information. |
| `feed_description` | String | Description of the transaction, as provided by our data feed. See description for more information. |
| `feed_is_international` | Boolean | Whether the transaction is international, as provided by our data feed. See is\_international for more information. |
| `feed_latitude` | Decimal | Latitude for the transaction, as provided by our data feed. See latitude for more information. |
| `feed_longitude` | Decimal | Longitude for the transaction, as provided by our data feed. See longitude for more information. |
| `feed_memo` | String | The transaction memo, as provided by our data feed. See memo for more information. |
| `feed_posted_at` | String | Date and time the transaction was posted, as provided by our data feed. See posted\_at for more information. |
| `feed_posted_on` | String | Date the transaction was posted, as provided by our data feed. See posted\_on for more information. |
| `feed_status` | Integer | Status of the transaction, as provided by our data feed. See status for more information. |
| `feed_transacted_at` | String | Date and time the transaction took place, as provided by our data feed. See transacted\_at for more information. |
| `feed_transacted_on` | String | Date the transaction took place, as provided by our data feed. |
| `feed_transaction_type` | Integer | The type of transaction, as provided by our data feed. See transaction\_type for more information. |
| `feed_transaction_type_name` | String | The type of transaction, as provided by our data feed. See transaction\_type\_name for more information. |
| `guid` | String | Unique identifier for the transaction. Defined by MX. |
| `has_been_split` | Boolean | If the transaction is a split, this field will be true. Otherwise, this field will be false. |
| `has_been_viewed` | Boolean | If the transaction has been viewed, this field will be true. Otherwise, this field will be false. |
| `is_bill_pay` | Boolean | If the transaction is a bill pay, this field will be true. Otherwise, this field will be false. |
| `is_direct_deposit` | Boolean | If the transaction is a direct deposit, this field will be true. Otherwise, this field will be false. |
| `is_expense` | Boolean | If the transaction is an expense, this field will be true. Otherwise, this field will be false. |
| `is_fee` | Boolean | If the transaction is a fee, this field will be true. Otherwise, this field will be false. |
| `is_flagged` | Boolean | If the transaction has been flagged, this field will be true. Otherwise, this field will be false. |
| `is_hidden` | Boolean | If the transaction is hidden, this field will be true. Otherwise, this field will be false. |
| `is_income` | Boolean | If the transaction is income, this field will be true. Otherwise, this field will be false. |
| `is_international` | Boolean | If the transaction is international, as defined by the data provider, this field will be true. If the data provider determines it is not international, then it will be false. It will be null if the data provider does not provide this information. |
| `is_international_set_by` | Integer | The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ). See Transaction Set By for more information. |
| `is_international_set_by_name` | String | The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ). See Transaction Set By for more information. |
| `is_overdraft_fee` | Boolean | If the transaction is an overdraft fee, this field will be true. Otherwise, this field will be false. |
| `is_payroll_advance` | Boolean | If the transaction is a payroll advance, this field will be true. Otherwise, this field will be false. |
| `is_recurring` | Boolean | This field should be ignored. If this information is required, please reach out to MX to discuss an alternative. |
| `is_subscription` | Boolean | If the transaction represents a payment for a subscription service such as Netflix or Audible, this field will be true. Otherwise it will be false. |
| `latitude` | Decimal | The latitude of the location where the transaction occurred. The number is a signed decimal (e.g. Rio de Janeiro’s latitude is -22.9027800 and Tokyo’s latitude is 35.689488). |
| `latitude_set_by` | Integer | The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ). See Transaction Set By for more information. |
| `latitude_set_by_name` | String | The source that set the data ( FEED, USER, or SYSTEM ). See Transaction Set By for more information. |
| `localized_description` | String | A human-readable description of the transaction, provided in a local language. |
| `localized_memo` | String | Additional descriptive information about the transaction, provided in a local language. |
| `longitude` | Decimal | The longitude of the location where the transaction occurred. The number is a signed decimal (e.g. Rio de Janeiro’s longitude is -43.2075000 and Tokyo’s longitude is 139.691706). |
| `longitude_set_by` | Integer | The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ). See Transaction Set By for more information. |
| `longitude_set_by_name` | String | The source that set the data ( FEED, USER, or SYSTEM ). See Transaction Set By for more information. |
| `memo` | String | The memo is additional descriptive information about the transaction. |
| `memo_set_by` | Integer | The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ). See Transaction Set By for more information. |
| `memo_set_by_name` | String | The source that set the data ( FEED, USER, or SYSTEM ). See Transaction Set By for more information. |
| `member_is_managed_by_user` | Boolean | If the member the transaction belongs to is managed by the user, this field will be true. Otherwise, the member is managed by the MX partner and this field will be false. Members created with Nexus are considered to be managed by the user. |
| `merchant_category_code` | Integer | The merchant category code. |
| `merchant_guid` | String | Unique identifier for the merchant identified in the transaction. Defined by MX. |
| `merchant_location_guid` | String | The unique identifier for the merchant location associated with the transaction. Defined by MX. |
| `metadata` | String | Additional information a partner can store on the transaction. NOTE: this field may potentially be overwritten by the data provider when data is refreshed through aggregation. See the FAQs for more information. |
| `parent_guid` | String | The parent guid of the transaction. |
| `posted_at` | String | Date and time the transaction was posted, represented in ISO 8601 format with timestamp (e.g. 2015-04-13T12:01:23-00:00). |
| `posted_at_set_by` | Integer | The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ). See Transaction Set By for more information. |
| `posted_at_set_by_name` | String | The source that set the data ( FEED, USER, or SYSTEM ). See Transaction Set By for more information. |
| `revision` | Integer | The revision number of this transaction record. |
| `scheduled_payment_guid` | String | The unique identifier for the scheduled payment associated with this transaction. Defined by MX. |
| `status` | Integer | The status of the transaction (1 = POSTED, 2 = PENDING). See Status for more information. |
| `status_name` | String | The status of the transaction (POSTED or PENDING). See Status for more information. |
| `status_set_by` | Integer | The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ). See Transaction Set By for more information. |
| `status_set_by_name` | String | The source that set the data ( FEED, USER, or SYSTEM ). See Transaction Set By for more information. |
| `top_level_category_guid` | String | Unique identifier of the parent category that this transaction's category is assigned to. |
| `transacted_at` | String | Date and time the transaction took place, represented in ISO 8601 format with timestamp (e.g. 2015-04-13T12:01:23-00:00). |
| `transacted_at_set_by` | Integer | The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ). See Transaction Set By for more information. |
| `transacted_at_set_by_name` | String | The source that set the data ( FEED, USER, or SYSTEM ). See Transaction Set By for more information. |
| `transaction_type` | Integer | The type of transaction (1 = CREDIT, 2 = DEBIT). See Transaction Types for more information. |
| `transaction_type_name` | String | The type of transaction (CREDIT or DEBIT). See Transaction Types for more information. |
| `transaction_type_set_by` | Integer | The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ). See Transaction Set By for more information. |
| `transaction_type_set_by_name` | String | The source that set the data ( FEED, USER, or SYSTEM ). See Transaction Set By for more information. |
| `updated_at` | String | Date and time the transaction was updated, represented in ISO 8601 format with timestamp (e.g. 2015-04-13T12:01:23-00:00). |
| `user_guid` | String | Unique identifier for the user. Defined by MX. |
| `user_transaction_rule_guid` | String | The unique identifier for the transaction\_rule associated with the transaction. Defined by MX. |
## `categorized_by` Fields
The `categorized_by` fields of the Transactions endpoint will return integers. See the table below for the meaning behind each integer:
| Integer | String | Definition |
| :---------- | :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0 | `MONEY_DESKTOP` | One of MX's systems categorized this transaction. |
| 1 | `CATEGORIZATION_SOURCE_USER` | This was categorized by the user, not by MX. |
| 2 | `CATEGORIZATION_SOURCE_FEED` | The category was supplied by the feed for this transaction. |
| 3 | `USER_PREFERENCE` | Historically, the user categorized this transaction to this category. We keep history of preferred categorizations and apply them to transactions. |
| 4 and above | `MONEY_DESKTOP` | One of MX's systems categorized this transaction. |
## Described By Fields
| Integer | Enum | Definition |
| :------ | :------------------------------- | :------------------------------------------------------------------------------------------- |
| 0 | `DESCRIPTION_SOURCE_SCRUBBER` | The description is the result of various pattern replacement and other cleansing mechanisms. |
| 1 | `DESCRIPTION_SOURCE_USER` | The end user provided the description. |
| 2 | `DESCRIPTION_SOURCE_FEED` | The data feed provided the description. |
| 3 | `DESCRIPTION_SOURCE_LEVENSHTEIN` | This is obsolete and will no longer provide descriptions. |
| 4 | `DESCRIPTION_SOURCE_USER_RULE` | A transaction rule created by the end user provided the description. |
| 5 | `DESCRIPTION_SOURCE_TRAINER` | This is obsolete and will no longer provide descriptions. |
| 6 | `DESCRIPTION_SOURCE_SYSTEM_RULE` | A transaction rule created by MX provided the description. |
| 7 | `DESCRIPTION_SOURCE_CLIENT_RULE` | A transaction rule created by the partner provided the description. |
| 8 | `DESCRIPTION_SOURCE_FLOOR` | No cleansed description could be provided as such, rather than because other methods failed. |
## Status Fields
The `status` field of the transactions endpoint will return an integer or a null status.
If the aggregation source doesn't supply the status, null will be the response.
| Status | Definition |
| :----- | :--------- |
| null | null |
| 1 | POSTED |
| 2 | PENDING |
## Transaction Categories
* AUTO\_TRANSPORT
* AUTO\_INSURANCE
* AUTO\_PAYMENT
* GAS
* PARKING
* PUBLIC\_TRANSPORTATION
* SERVICE\_PARTS
* BILLS\_UTILITIES
* DOMAIN\_NAMES
* FRAUD\_PROTECTION
* HOME\_PHONE
* HOSTING
* INTERNET
* MOBILE\_PHONE
* TELEVISION
* UTILITIES
* BUSINESS\_SERVICES
* ADVERTISING
* LEGAL
* OFFICE\_SUPPLIES
* PRINTING
* SHIPPING
* EDUCATION
* BOOKS\_SUPPLIES
* STUDENT\_LOAN
* TUITION
* ENTERTAINMENT
* AMUSEMENT
* ARTS
* MOVIES\_DVDS
* MUSIC
* NEWSPAPERS\_MAGAZINES
* FEES\_CHARGES
* ATM\_FEE
* BANKING\_FEE
* FINANCE\_CHARGE
* LATE\_FEE
* SERVICE\_FEE
* TRADE\_COMMISSIONS
* FINANCIAL
* FINANCIAL\_ADVISOR
* LIFE\_INSURANCE
* FOOD\_DINING
* ALCOHOL\_BARS
* COFFEE\_SHOPS
* FAST\_FOOD
* GROCERIES
* RESTAURANTS
* GIFTS\_DONATIONS
* CHARITY
* GIFT
* HEALTH\_FITNESS
* DENTIST
* DOCTOR
* EYECARE
* GYM
* HEALTH\_INSURANCE
* PHARMACY
* SPORTS
* HOME
* FURNISHINGS
* HOME\_IMPROVEMENT
* HOME\_INSURANCE
* HOME\_SERVICES
* HOME\_SUPPLIES
* LAWN\_GARDEN
* MORTGAGE\_RENT
* INCOME
* BONUS
* INTEREST\_INCOME
* PAYCHECK
* REIMBURSEMENT
* RENTAL\_INCOME
* RETURNED\_PURCHASE
* INVESTMENTS
* BUY
* DEPOSIT
* DIVIDEND\_CAP\_GAINS
* SELL
* WITHDRAWAL
* KIDS
* ALLOWANCE
* BABY\_SUPPLIES
* BABYSITTER\_DAYCARE
* CHILD\_SUPPORT
* KIDS\_ACTIVITIES
* TOYS
* PERSONAL\_CARE
* HAIR
* LAUNDRY
* SPA\_MASSAGE
* PETS
* PET\_FOOD\_SUPPLIES
* PET\_GROOMING
* VETERINARY
* SHOPPING
* BOOKS
* CLOTHING
* ELECTRONICS\_SOFTWARE
* HOBBIES
* SPORTING\_GOODS
* TAXES
* FEDERAL\_TAX
* LOCAL\_TAX
* PROPERTY\_TAX
* SALES\_TAX
* STATE\_TAX
* TRANSFER
* CREDIT\_CARD\_PAYMENT
* TRANSFER\_FOR\_CASH\_SPENDING
* MORTGAGE\_PAYMENT
* TRAVEL
* AIR\_TRAVEL
* HOTEL
* RENTAL\_CAR\_TAXI
* VACATION
* UNCATEGORIZED
* CASH
* CHECK
## Transaction Classifier Fields
The transaction fields below are considered "classifiers." These indicate that the transaction represents a particular class of transaction such as an overdraft fee or a direct deposit. All are booleans.
* `is_bill_pay`
* `is_direct_deposit`
* `is_expense`
* `is_fee`
* `is_income`
* `is_overdraft_fee`
* `is_payroll_advance`
* `is_subscription`
## Transaction set\_by
The `set_by` fields return an integer and the `set_by_name` fields return a string. The table below shows the meaning of each value and how the integers map to the strings. See the Transactions sections in Endpoints for examples.
| Date Source | Definition | Information |
| :---------- | :--------- | :------------------------------------------ |
| 1 | FEED | Information provided from the MX data feed. |
| 2 | USER | Information provided from the user. |
| 3 | SYSTEM | Information provided from the MX system. |
## Transaction Types
The transaction type is either a CREDIT or a DEBIT. A CREDIT increases the user’s net worth. A DEBIT decreases the user’s net worth. This applies to all account types.
| Value | Transaction Type | Definition |
| :---- | :--------------- | :--------------------------------------------------------------------------------------------------------------------- |
| 1 | CREDIT | Increases the user's net worth, such as a deposit in a checking account or a payment applied to a credit card account. |
| 2 | DEBIT | Decreases the user's net worth, such as a withdrawal in a checking account or a purchase charged to a credit card |
# Users Overview
Source: https://docs.mx.com/api-reference/nexus/reference/01-users-overview
Overview of user resource and field definitions
## User Fields
| Field Name | Data Type | Description |
| :---------------------------------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `accepted_terms_and_conditions_at` | string | The most recent date and time the end user accepted either initial or updated terms and conditions. Represented in ISO 8601 format with a timestamp (e.g., 2015-04-13T12:01:23-00:00). |
| `birthday` | string | Birthdate of user, represented in ISO 8601 format (e.g. 2011-03-28). |
| `credit_score` | integer | Credit score of the user. |
| `email` | string | Email address of the user. |
| `email_is_verified` | boolean | If the email is verified, this field will be true. Otherwise, this field will be false. |
| `external_guid` | string | Partner created identifier for the user. |
| `failed_token_login_attempts_count` | integer | Number of failed login attempts for the user. Defaults to 0. |
| `first_name` | string | First name of the user. |
| `gender` | integer | Gender of the user. Returns 0 for male and 1 for female. |
| `guid` | string | Unique identifier for the user. Defined by MX. |
| `has_accepted_terms_and_conditions` | boolean | If the end user has accepted the initial terms and conditions, this field will be true. Otherwise, this field will be false. This field does not update. |
| `has_updated_terms_and_conditions` | boolean | If updated terms and conditions are available for the end user, this field will be true. This field will return to false when the user has accepted the updated terms. |
| `is_disabled` | boolean | If the user is disabled, this field will be true. Otherwise, this field will be false. |
| `is_restricted` | boolean | If the user is restricted, this field will be true. Otherwise, this field will be false. |
| `last_name` | string | Last name of the user. |
| `logged_in_at` | string | Date and time the user last logged in, represented in ISO 8601 format with timestamp (e.g. 2015-04-13T12:01:23-00:00). |
| `metadata` | string | Additional information a partner can store on the user. |
| `phone` | string | Phone number of the user. |
| `phone_is_verified` | boolean | Verifies the phone for the user. Returns true or false; defaults to false. |
| `postal_code` | string | US ZIP codes and Canadian postal codes are supported. Valid formats are: 12345, 12345-6789, A1B2C3, or A1B 2C3. |
| `revision` | integer | The revision number of this user record. |
# Verification Overview
Source: https://docs.mx.com/api-reference/nexus/reference/01-verification-overview
Overview of verification resource and field definitions
Users represent individual end-users in the system, containing their profile information and preferences.
## Account Number Fields
| Field Name | Data Type | Description |
| :------------------- | :-------- | :-------------------------------------------------------------------------------------------------------------------- |
| `account_guid` | String | The unique identifier for the account associated with a particular set of account and routing numbers. Defined by MX. |
| `account_number` | String | The banking account number associated with a particular account. |
| `institution_number` | String | The three-digit number identifying a Canadian banking institution. |
| `member_guid` | String | The unique identifier for the member associated with a particular set of account and routing numbers. Defined by MX. |
| `passed_validation` | Boolean | This indicates whether the account and routing numbers passed MX's internal validity checks. |
| `routing_number` | String | The routing number for the financial institution associated with the account. |
| `transit_number` | String | The five-digit number identifying the branch of a Canadian financial institution. |
| `user_guid` | String | The unique identifier for the user associated with a particular set of account and routing numbers. Defined by MX. |
# Categorize transactions
Source: https://docs.mx.com/api-reference/nexus/reference/categorize-transactions
openapi/nexus/v1.yaml POST /transactions/categorize_and_describe
This endpoint takes an array of transactions and automatically categorizes them based on `description`, `transaction_type`, and `amount`. This endpoint can receive and categorize a maximum of 100 transactions per call.
# (Deprecated) Create a split transaction
Source: https://docs.mx.com/api-reference/nexus/reference/create-deprecated-split-transaction
openapi/nexus/v1.yaml POST /transactions
In our efforts to improve our Nexus API, we have implemented newer, better endpoints to create and delete split transactions. As such, this endpoint has been deprecated, but it remains documented for previous integrations using this feature. All new integrations must use the improved split and delete transaction endpoints. This endpoint creates a new transaction that is branched from a previous transaction, allowing you to link multiple categories, descriptions, amounts, and additional information to a parent transaction. When a split transaction is created, the parent transaction's `has_been_split` field will automatically be updated to `true`, and the split transaction's `parent_guid` will have the transaction guid of the parent.
# Create manual transaction
Source: https://docs.mx.com/api-reference/nexus/reference/create-manual-transaction
openapi/nexus/v1.yaml POST /accounts/{account_guid}/transactions
This endpoint can only be used to create manual transactions that are under a manual account. This endpoint accepts the optional `MX-Skip-Webhook` header and `skip_webhook` parameter.
# Create a spending plan iteration item
Source: https://docs.mx.com/api-reference/nexus/reference/create-spending-plan-iteration-item
openapi/nexus/v1.yaml POST /spending_plans/{spending_plan_guid}/iterations/current/iteration_items
This endpoint creates a new `spending_plan_iteration_item`.
# Create split transactions
Source: https://docs.mx.com/api-reference/nexus/reference/create-split-transactions
openapi/nexus/v1.yaml POST /transactions/{transaction_guid}/split
This endpoint creates two or more child transactions that are branched from a previous transaction. This endpoint allows you to link multiple categories, descriptions, and amounts to a parent transaction.
When a split transaction is created, the parent transaction's `has_been_split` field will automatically be updated to `true` and the child transactions' `parent_guid` will have the transaction guid of the parent. The total amount of the child transactions must equal the amount of the parent transaction. Once a transaction has been split it can't be split again.
To re-split a transaction, it must first be un-split. This can be done by calling the Delete Split Transactions endpoint. Calling this endpoint will delete the existing child transactions and update the parent transaction's `has_been_split` field to false. You can then re-split the parent transaction by calling Create Split Transaction again.
# Create transaction rule
Source: https://docs.mx.com/api-reference/nexus/reference/create-transaction-rule
openapi/nexus/v1.yaml POST /transaction_rules
Use this endpoint to create a new transaction rule. The newly-created `transaction_rule` object will be returned if successful.
# Delete spending plan iteration item
Source: https://docs.mx.com/api-reference/nexus/reference/delete-spending-plan-iteration-item
openapi/nexus/v1.yaml DELETE /spending_plans/{spending_plan_guid}/iterations/current/iteration_items/{iteration_item_guid}
Use this endpoint to delete a particular spending plan iteration item according to its unique GUID.
# Delete split transactions
Source: https://docs.mx.com/api-reference/nexus/reference/delete-split-transactions
openapi/nexus/v1.yaml DELETE /transactions/{transaction_guid}/unsplit
This endpoint deletes all split transactions linked to a parent transaction, but it leaves the parent transaction active. This request will also update the parent transaction's `has_been_split` field to false. This endpoint accepts the optional `MX-Skip-Webhook` header.
# Delete transaction
Source: https://docs.mx.com/api-reference/nexus/reference/delete-transaction
openapi/nexus/v1.yaml DELETE /transactions/{transaction_guid}
This endpoint should be used to delete a manual transaction created with the create manual transaction endpoint.
# Delete a transaction rule
Source: https://docs.mx.com/api-reference/nexus/reference/delete-transaction-rule
openapi/nexus/v1.yaml DELETE /transaction_rules/{transaction_rule_guid}
Use this endpoint to permanently delete a transaction rule based on its unique GUID.
# List spending plan accounts
Source: https://docs.mx.com/api-reference/nexus/reference/list-spending-plan-accounts
openapi/nexus/v1.yaml GET /spending_plans/{spending_plan_guid}/spending_plan_account
This endpoint returns a list of `spending_plan_accounts` associated with the `spending_plan` according to its MX-defined GUID.
# List spending plan iteration items
Source: https://docs.mx.com/api-reference/nexus/reference/list-spending-plan-iteration-items
openapi/nexus/v1.yaml GET /spending_plans/{spending_plan_guid}/iterations/current/iteration_items
Use this endpoint to list all the spending plan `iteration_items` associated with the `iteration`.
# List taggings
Source: https://docs.mx.com/api-reference/nexus/reference/list-taggings
openapi/nexus/v1.yaml GET /taggings
Use this endpoint to list all taggings.
# List tags
Source: https://docs.mx.com/api-reference/nexus/reference/list-tags
openapi/nexus/v1.yaml GET /tags
Use this endpoint to list all tags.
# List transaction rules
Source: https://docs.mx.com/api-reference/nexus/reference/list-transaction-rules
openapi/nexus/v1.yaml GET /transaction_rules
Use this endpoint to read the attributes of all existing transaction rules belonging to the user.
# List transactions
Source: https://docs.mx.com/api-reference/nexus/reference/list-transactions
openapi/nexus/v1.yaml GET /transactions
This endpoint returns paginated results; each page will need to be requested separately to retrieve the data on that page. The total\_pages field returns an integer representing the total pages to be requested.
# List transactions by category GUID and date
Source: https://docs.mx.com/api-reference/nexus/reference/list-transactions-by-category-and-date
openapi/nexus/v1.yaml GET /transactions/by_category_guid/{category_guid}/by_date/{start_date}/{end_date}
This endpoint returns transactions with the specified category GUID within the date range provided. This endpoint returns paginated results; each page will need to be requested separately to retrieve the data on that page. The `total_pages` field returns an integer representing the total pages to be requested.
# List transactions by top-level category GUID and date
Source: https://docs.mx.com/api-reference/nexus/reference/list-transactions-by-top-level-category-and-date
openapi/nexus/v1.yaml GET /transactions/by_top_level/{category_guid}/by_date/{start_date}/{end_date}
This endpoint returns all transactions that match the provided category GUID between two dates. It includes all transactions in a subcategory of the provided category GUID. This endpoint returns paginated results; each page will need to be requested separately to retrieve the data on that page. The `total_pages` field returns an integer representing the total pages to be requested.
# List transactions created between two dates
Source: https://docs.mx.com/api-reference/nexus/reference/list-transactions-created-between-dates
openapi/nexus/v1.yaml GET /transactions/created_between/{start_date}/{end_date}
Use this endpoint to list transactions that were created between two dates. This endpoint returns paginated results; each page will need to be requested separately to retrieve the data on that page. The `total_pages` field returns an integer representing the total pages to be requested.
# List transactions updated between two dates
Source: https://docs.mx.com/api-reference/nexus/reference/list-transactions-updated-between-dates
openapi/nexus/v1.yaml GET /transactions/updated_between/{start_date}/{end_date}
Use this endpoint to list transactions that were updated between two dates. This endpoint returns paginated results; each page will need to be requested separately to retrieve the data on that page. The `total_pages` field returns an integer representing the total pages to be requested.
# Read account numbers
Source: https://docs.mx.com/api-reference/nexus/reference/read-account-numbers
openapi/nexus/v1.yaml GET /members/{member_guid}/account_numbers
Use this endpoint to check whether account number data is available for a specific member. This includes the transit number and institution number for Canadian institutions. For compatibility purposes, a Canadian transit number may sometimes appear in the `routing_number` field. However, all new integrations should rely on the `transit_number` field for this information.
# Read account numbers by account_guid
Source: https://docs.mx.com/api-reference/nexus/reference/read-account-numbers-by-account
openapi/nexus/v1.yaml GET /accounts/{account_guid}/account_number
Use this endpoint to check whether account number data is available for a specific account. This includes the transit number and institution number for Canadian institutions. For compatibility purposes, a Canadian transit number may sometimes appear in the `routing_number` field. However, all new integrations should rely on the `transit_number` field for this information.
# Read current iteration
Source: https://docs.mx.com/api-reference/nexus/reference/read-current-spending-plan-iteration
openapi/nexus/v1.yaml GET /spending_plans/{spending_plan_guid}/iterations/current
This endpoint returns information about the current `iteration` associated to the `spending_plan`.
# Read a spending plan account
Source: https://docs.mx.com/api-reference/nexus/reference/read-spending-plan-account
openapi/nexus/v1.yaml GET /spending_plans/{spending_plan_guid}/spending_plan_account/{spending_plan_account_guid}
This endpoint returns information about a specific `spending_plan_account` according to its MX-defined GUID.
# Read a spending plan iteration
Source: https://docs.mx.com/api-reference/nexus/reference/read-spending-plan-iteration
openapi/nexus/v1.yaml GET /spending_plans/{spending_plan_guid}/iterations/{iteration_number}
This endpoint returns information about a specific iteration according to its `iteration_number`.
# Read a spending plan iteration item
Source: https://docs.mx.com/api-reference/nexus/reference/read-spending-plan-iteration-item
openapi/nexus/v1.yaml GET /spending_plans/{spending_plan_guid}/iterations/current/iteration_items/{iteration_item_guid}
Use this endpoint to read the attributes of a specific spending plan `iteration_item` according to its unique GUID.
# Read transaction
Source: https://docs.mx.com/api-reference/nexus/reference/read-transaction
openapi/nexus/v1.yaml GET /transactions/{transaction_guid}
Use this endpoint to read the attributes of a specific transaction according to its unique GUID.
# Read transaction rule
Source: https://docs.mx.com/api-reference/nexus/reference/read-transaction-rule
openapi/nexus/v1.yaml GET /transaction_rules/{transaction_rule_guid}
Use this endpoint to read the attributes of an existing transaction rule based on the rule’s unique GUID.
# Read user
Source: https://docs.mx.com/api-reference/nexus/reference/read-user
openapi/nexus/v1.yaml GET /user
This endpoint returns information regarding the authenticated user.
# Update a spending plan iteration item
Source: https://docs.mx.com/api-reference/nexus/reference/update-spending-plan-iteration-item
openapi/nexus/v1.yaml PUT /spending_plans/{spending_plan_guid}/iterations/current/iteration_items/{iteration_item_guid}
Use this endpoint to update an existing `spending_plan_iteration_item`.
# Update transaction
Source: https://docs.mx.com/api-reference/nexus/reference/update-transaction
openapi/nexus/v1.yaml PUT /transactions/{transaction_guid}
Update a specific transaction according to its unique identifier.
# Update a transaction rule
Source: https://docs.mx.com/api-reference/nexus/reference/update-transaction-rule
openapi/nexus/v1.yaml PUT /transaction_rules/{transaction_rule_guid}
Use this endpoint to update the attributes of a specific transaction rule based on its unique GUID. Nexus will respond with the updated `transaction_rule` object. Any attributes not provided will be left unchanged. Updating the `category_guid` or description will also update all past and future transactions. Updating the `match_description` will only be applied to future transactions.
# Verify member
Source: https://docs.mx.com/api-reference/nexus/reference/verify-member
openapi/nexus/v1.yaml POST /members/{member_guid}/verify
This endpoint gathers information about account and routing numbers. Partners may optionally choose to transaction data in this request, potentially avoiding a separate aggregate member request. The verification workflow is similar to standard aggregation. Start the verification, poll the member, answer MFA if necessary by using the list member MFA challenges endpoint and the update member endpoint, poll the status again, then read the member's `account_numbers`. Before making a request to this endpoint, partners must make sure verification is enabled for the member's `institution`. Specifically, the institution's `supports_account_verification` field must be true. If the `institution` does not support verification, a `400 Bad Request` error will be returned with the message, `Member's institution does not support instant account verification`. If a request to this endpoint fails with a status of `403 Forbidden` but the member's `institution` nevertheless shows that verification is enabled, please contact support.
# Overview
Source: https://docs.mx.com/api-reference/sso/v3/index
The MX SSO API is a RESTful API that's used to authenticate users on the MX Platform. There are SSO API endpoints to obtain a URL for an MX widget, including those for our Personal Finance Management and Financial Insights widgets, and to obtain an `api_token` to open a Nexus API session.
The SSO API supports both XML and JSON encoding of the request and response bodies.
Always use the [get configurable widget URL](/api-reference/sso/v3/reference/widget-urls/get-widget-with-config-options) endpoint rather than the [list urls](/api-reference/sso/v3/reference/widget-urls/list-widget-urls) endpoint in testing and production. This is because as the latter endpoint has been deprecated.
MX will continue to support the use of **list urls** for existing integrations; however, using this endpoint presents several undesirable factors. First, it significantly impacts the API response time due to the fact that the MX system needs to generate a url for all widgets before sending a response. In addition, you are required to parse the API response to extract the url(s) they want. This increases the complexity of the implementation code and requires additional application resources. Finally, MX will not maintain which widgets are available through this endpoint, which means any new widgets will not be returned in the response.
In contrast, if you use the get configurable widget URL endpoint receive an API response much quicker, and can rely on the response to always contain the url field regardless of which widget was specified in the API request.
# Customer Consent Management Dashboard API
Source: https://docs.mx.com/api-reference/consent-management/overview/index
Integrate the consumer consent management dashboard into your UX.
Data Access provides an API to support building your own Consent Management dashboard UI. Use this API to manage so that your consumers can manage which third parties have access to their data from your mobile app or online site. This allows you to completely customize the end-user's experience.
To integrate a dashboard using this API:
1. Generate a token using your client id and secret in the Data Provider Portal.
2. Using the token, get a list of the consumer's consents. Each returned consent object contains ids.
3. Update consents as needed using the ids.
## Quick Links
Generate credentials. More about the Portal.
Learn more about data provider implementation.
## Consent Sample Data
This sample response shows the response you can expect to get for a consent object.
```json theme={null}
[
{
"id": "_sadfa3CKHJ23LKJHKJHLlNaODPmH1LqSb4",
"application_name": "Centz",
"application_icon_url": null,
"created_at": "2024-06-14T19:48:18.354Z",
"last_accessed": "2024-05-14T19:48:31.352Z",
"accounts": [
{
"enabled": true,
"nickname": "Lacrosse Fund",
"account_id": "1234123412341234",
"account_number_display": "XXXXXXXX1111"
},
{
"enabled": false,
"nickname": "Gymnastics Money",
"account_id": "234123412341234",
"account_number_display": "XXXXXXXX2222"
}
],
"auto_enable_future_accounts": true,
"consented_on": "2024-05-14T19:48:18.352Z",
"revoked_at": null
}
]
```
# Request Token
Source: https://docs.mx.com/api-reference/consent-management/reference/01-request-token
POST https://int-api.mx.com/api/{version}/token
Returns a bearer token needed for all Customer Consent Management Dashboard API requests. Each token expires in five minutes. A fresh token must be requested after expiration or revocation. This request requires a `client_id` and `client_secret` in the header. Only admins can view, generate, and rotate credentials. The body of the request must include the `consent_management` scope and the `customerId` which matches the `openid_connect_user_id`. To manage credentials in the Data Provider Portal, go to Configuration > Consent Dashboard Management and select **Generate API credentials**.
## Path Parameters
API version. Indicates which FDX version is in use. Default value = `v4`.
## Body Parameters
For Consent Management, `type` must be `consent_management`.
Include `customer.modify_consent:{customer_id}`. The is the customer's `openid_connect_user_id`.
```shell cURL theme={null}
curl -L -g -X POST 'http://{{baseurl}}/api/{{version}}/token' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic BASE_64_ENCODING_OF{client_id:client_secret}' \
--data-raw '{"type":"consent_management","scopes":"customer.modify_consent:{customer_id}"}'
```
```json 200 theme={null}
{
"access_token": "eyJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiY29uc2VudF9tYW5hZ2VtZW50Iiwic2NvcGVzIjp7ImN1c3RvbWVyLm1vZGlmeV9jb25zZW50IjoiZk43U3NJTWZKdkpKY05qS0JtQjZLZyJ9LCJleHAiOjE3NDYxNDM1MTMsImlhdCI6MTc0NjE0MzIxMywianRpIjoiYmQ0MWY3N2UtNjg4NC00MThjLTg2ZTAtM2JiMGRiYzEyYTc3IiwiX3R5cGUiOiJJbnN0aXR1dGlvbiIsIl9pZCI6ImJrdSJ9.q9dvdMTW9kiKOSAeSNICoSWWKsmsCW4MEk85JQA9OWY"
}
```
# Revoke Token
Source: https://docs.mx.com/api-reference/consent-management/reference/02-revoke-token
DELETE https://int-api.mx.com/api/{version}/token/{token}
Revokes token. Using the current token in the path, this endpoint updates the revoked_at field and revokes the token.
Revokes token. Using the current token in the path, this endpoint updates the `revoked_at` field and revokes the token.
This request requires a `client_id` and `client_secret` in the header. Only admins can view, generate, and rotate credentials.
## Path Parameters
API version. Indicates which FDX version is in use. Default value = `v4`.
Token to be revoked.
```shell cURL theme={null}
curl -L -g -X DELETE 'http://{{baseurl}}/api/{{version}}/token/{{token}}' \
-H 'Accept: application/json' \
-H 'Authorization: Basic BASE_64_ENCODING_OF{client_id:client_secret}'
```
```json 200 theme={null}
{
"id": 1,
"tokenable_id": 1,
"tokenable_type": "Institution",
"token": "GspYX0FhpSTJjBL5RIthHdVRxCjAGoOqOdnHP3g3uso",
"expires_in": 300,
"revoked_at": "2024-07-25T19:37:55.864Z",
"scopes": {
"customer.modify_consent": "f339c727-1378-44c9-e053-8462cc0a5b81"
},
"created_at": "2024-07-24T19:37:55.864Z",
"updated_at": "2024-07-25T19:37:55.864Z"
}
```
# Rotate Credentials
Source: https://docs.mx.com/api-reference/consent-management/reference/03-rotate-credentials
POST https://int-api.mx.com/api/{version}/api_access_credentials
API Access users may rotate API Access credentials from an external API. This request requires a `client_id` and `client_secret` in the header. Only admins can view, generate, and rotate credentials. To manage credentials in the Data Provider Portal, go to Configuration > Consent Dashboard Management and select **Generate API credentials**.
## Path Parameters
API version. Indicates which FDX version is in use. Default value = `v4`.
## Body Parameters
For Consent Management, `name` must be `consent_management`.
```shell cURL theme={null}
curl -L -g -X POST 'http://{{baseurl}}/api/{{version}}/api_access_credentials' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic BASE_64_ENCODING_OF{client_id:client_secret}' \
--data-raw '{"name":"consent_management"}'
```
```json 200 theme={null}
{
"client_id": "asdf",
"client_secret": "asdf2",
"name": "consent_management",
"created_at": "2024-06-14T19:48:18.354Z"
}
```
# Consent list
Source: https://docs.mx.com/api-reference/consent-management/reference/3-consent-list
openapi/consent-management/v4.yaml GET /api/{version}/consent_management
Returns all data sharing information for an end user. Use this endpoint to list an end user's current data sharing choices. Each of the end user's connected apps has a separate consent which is detailed in the response by a consent object. The consent object includes details such as the app's id, name, icon, and the sharing status of the end-user's accounts.
# Update Consented Account
Source: https://docs.mx.com/api-reference/consent-management/reference/account-enabled-status
openapi/consent-management/v4.yaml PUT /api/{version}/consent_management/{ConsentPublicId}/accounts/{AccountId}
Updates a consent by enabling or disabling an account. Use this endpoint when an end user wants to change whether or not an account is shared with an app.
# Update Auto Access
Source: https://docs.mx.com/api-reference/consent-management/reference/auto-access-update
openapi/consent-management/v4.yaml PUT /api/{version}/consent_management/{ConsentPublicId}/accounts
Set a consented app's auto update status. Use this endpoint to allow or disallow an app to automatically add new accounts to an end user's consent. This sets the consent object's `auto_enable_future_accounts` field to true or false.
# Revoke Consent
Source: https://docs.mx.com/api-reference/consent-management/reference/revoke-consent
openapi/consent-management/v4.yaml PUT /api/{version}/consent_management/{ConsentPublicId}/disable_app_sharing
Disables the selected consent and updates `revoked_at` with current time. Use this endpoint when an end user wants to stop all data sharing with an app.
# Analytics Events
Source: https://docs.mx.com/api-reference/more-apis/reporting/data-specifications/analytics-events
Analytics events cover a range of things related to both the Personal Finance Management widgets and our Mobile Banking app. Not all the analytics files will have data in them depending on whether partners are using Personal Finance Management, Mobile Banking, or both. For example, partners using Personal Finance Management widgets only (whether on desktop or mobile) will have data in analytics events files and analytics pageviews files, but not analytics screenviews nor analytics timed events.
| Resource | Data Source | Description |
| ------------------------ | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `analytics_events` | Personal Finance Management and Mobile Banking | Analytics events occur within a Personal Finance Management widget (desktop or mobile) or a Mobile banking app view. |
| `analytics_pageviews` | Personal Finance Management | Opening various widgets or tabs within the Master Widget. |
| `analytics_screenviews` | Mobile Banking | Opening various views or screens within the Mobile Banking app. |
| `analytics_timed_events` | Mobile Banking | Measures the timing of different events within the Mobile Banking app. |
## Analytics Event Fields
Analytics events occur within a Personal Finance Management widget (desktop or mobile) or a Mobile Banking app view.
**Analytics Event Fields**
| Field | Data Type | Definition |
| :------------------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `action` | String | The action by the end user that triggered the analytics event (e.g. `blur`, `click`, etc.). |
| `app_guid` | String | The unique identifier for the app based on the client and operating system (e.g., Epic Bank iOS and Epic Bank Android would have separate identifiers). Defined by MX. If the `data_source` is `web`, this field will be `null`. |
| `app_version` | String | The specific version of the application with which the end user interacted. |
| `category` | String | The category or feature with which the user interacted (e.g., `Add Manual Account`, `Credential Login`, etc.). |
| `client_guid` | String | The unique identifier for the client associated with this analytics event. Defined by MX. |
| `created_at` | Long | The date and time this analytics event was created. Represented as a Unix Epoch datetime (e.g. 1489883830). |
| `data_source` | String | The origin of the analytics event (e.g., `web` for web application or `app` for mobile application). |
| `device_guid` | String | The unique identifier for the device associated with the analytics event. Defined by MX. If the `data_source` is `web`, this field will be `null`. |
| `device_id` | String | The unique identifier for the device associated with the analytics event; resets on every login. Defined by MX. |
| `device_uid` | String | The unique identifier for the device associated with the analytics event; remains constant across logins. Defined by MX. |
| `external_user_guid` | String | The partner-defined identifier for the user associated with the event. |
| `guid` | String | The unique identifier for the analytics event. Defined by MX. |
| `is_mobile_webview` | Boolean | The widget configuration as it was set at the time of the API request to obtain the widget. |
| `mdx_session_id` | String | The hashed MDX session ID, provided as a custom dimension. |
| `name` | String | The name of the action taken that generated the analytics event (e.g., `Account Type - Collapse`, `Exclude Transaction - Start`, etc.). |
| `screen_resolution` | String | The resolution of the device display associated with the analytics event, given in pixels (e.g., `2048x1536`). |
| `session_id` | String | The unique identifier of the session, provided as a custom dimension. |
| `user_agent` | String | The end user's browser and operating system. |
| `user_guid` | String | The unique identifier for the user associated with the analytics event. Defined by MX. |
| `user_id` | String | The partner-defined identifier for the user associated with the event. |
| `user_ip_address` | String | The unique IP address for the user associated with the analytics event. |
| `value` | String | The screen object the user interacted with, if applicable (e.g., `Button`, `Menu`, `Previous Month`). |
## Analytics Pageviews
Analytics pageviews include pageviews only for the Personal Finance Management widgets.
**Analytics Pageview Fields**
| Field | Data Type | Definition |
| :------------------- | :-------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `app_version` | String | The version of the user's application. |
| `client_guid` | String | The unique identifier for the client associated with the analytics pageview. Defined by MX. |
| `created_at` | Long | The date and time at which the analytics pageview was created. |
| `data_source` | String | The origin of the analytics event, e.g. `transactions` for the transactions widget, `master/transactions` if the Master Widget is loaded, `app` for mobile application. |
| `external_user_guid` | String | The partner-defined identifier for the user associated with the pageview. |
| `guid` | String | The unique identifier for the analytics pageview. Defined by MX. |
| `host` | String | The host name of the server. |
| `is_mobile_webview` | Boolean | The widget configuration as it was set at the time of the API request to obtain the widget. |
| `name` | String | The name of the page in the case of a `pageview`. |
| `path` | String | The relative URL path of the event. |
| `screen_resolution` | String | The resolution of the device display associated with the analytics event; given in pixels (e.g. `2048x1536`). |
| `session_id` | String | The unique identifier of the session, provided as a custom dimension. |
| `user_agent` | String | The end user's browser and operating system. |
| `user_guid` | String | The unique identifier for the user associated with the analytics pageview. Defined by MX. |
| `user_id` | String | The partner-defined identifier for the user associated with the pageview. |
| `user_ip_address` | String | The IP address of the user associated with this analytics pageview. |
## Analytics Screenviews
Analytics screenviews include screenviews only for the Mobile Banking app.
**Analytics Screenview Fields**
| Field | Data Type | Definition |
| :------------------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `app_guid` | String | The unique identifier for the app based on the client and operating system (e.g., Epic Bank iOS and Epic Bank Android would have separate identifiers). Defined by MX. If the `data_source` is `web`, this field will be `null`. |
| `app_version` | String | The specific version of the application with which the end user interacted. |
| `client_guid` | String | The unique identifier for the client associated with this analytics screenview. Defined by MX. |
| `created_at` | Long | The date and time the analytics screenview was created, given in Unix epoch time. |
| `data_source` | String | The origin of the analytics screenview (e.g., `web` for web application or `app` for mobile application). |
| `device_guid` | String | The unique identifier for the device associated with the analytics screenview. Defined by MX. If the `data_source` is `web`, this field will be `null`. |
| `device_id` | String | The unique identifier for the device associated with the analytics screenview; resets on every login. Defined by MX. |
| `device_uid` | String | The unique identifier for the device associated with the analytics screenview; remains constant across logins. Defined by MX. |
| `external_user_guid` | String | The partner-defined identifier for the user associated with the screenview. |
| `guid` | String | The unique identifier for the analytics screenview. Defined by MX. |
| `mdx_session_id` | String | The hashed MDX session ID, provided as as custom dimension. |
| `name` | String | The name of the action taken in the analytics screenview. |
| `screen_resolution` | String | The resolution of the device display associated with the analytics screenview; given in pixels (e.g., `2048x1536`). |
| `session_id` | String | The unique identifier of the session, provided as a custom dimension. |
| `user_agent` | String | The end user's browser and operating system. |
| `user_guid` | String | The unique identifier for the user associated with the analytics screenview. Defined by MX. |
| `user_id` | String | The partner-defined identifier for the user associated with the screenview. |
| `user_ip_address` | String | The IP address of the user associated with this analytics pageview. |
## Analytics Timed Events
Analytics timed events measure the timing of different events within the Mobile Banking app.
**Analytics Timed Event Fields**
| Field | Data Type | Definition |
| :------------------- | :-------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `app_guid` | String | The unique identifier for the app based on the client and OS (e.g. Epic Bank iOS and Epic Bank Android would have separate identifiers). Defined by MX. If the `data_source` is `web`, this field will be `null`. |
| `app_version` | String | The version of the user's application. |
| `category` | String | The category or feature with which the user interacted (e.g. `Add Manual Account`, `Credential Login`, etc.). |
| `client_guid` | String | The unique identifier for the client associated with this analytics event. Defined by MX. |
| `created_at` | Long | The date and time at which the analytics timed event was created. |
| `data_source` | String | The origin of the analytics event (e.g. `web` for web application or `app` for mobile application). |
| `device_guid` | String | The unique identifier for the device associated with the analytics event. Defined by MX. If the `data_source` is `web`, this field will be `null`. |
| `device_id` | String | The unique identifier for the device associated with the analytics event; resets on every login. Defined by MX. |
| `device_uid` | String | The unique identifier for the device associated with the analytics event; remains constant across logins. Defined by MX. |
| `external_user_guid` | String | The partner-defined identifier for the user associated with the pageview. |
| `guid` | String | The unique identifier for the analytics timed event. Defined by MX. |
| `interval` | Long | The duration of the analytics timed event from start to finish, given in milliseconds. |
| `mdx_session_id` | String | The hashed MDX session ID, provided as a custom dimension. |
| `name` | String | The name of the action taken which generated the analytics event (e.g. `Account Type - Collapse`, `Exclude Transaction - Start`, etc.). |
| `screen_resolution` | String | The resolution of the device display associated with the analytics event; given in pixels (e.g. `2048x1536`). |
| `session_id` | String | The unique identifier of the session, provided as a custom dimension. |
| `user_agent` | String | The end user's browser and operating system. |
| `user_guid` | String | The unique identifier for the user associated with the analytics timed event. Defined by MX. |
| `user_id` | String | The partner-defined identifier for the user associated with the pageview. |
| `user_ip_address` | String | The unique IP address for the user associated with the analytics event. |
| `version` | Long | The version of the user's application, given as an integer. |
# Base Resources
Source: https://docs.mx.com/api-reference/more-apis/reporting/data-specifications/base-resources
Data field specifications for all base Reporting API resources.
## Accounts
An account represents a financial account, for example, a user's checking or savings account. A member may have more than one account associated with it. For instance, a user may have both a checking and savings account associated with one Chase login and would therefore have two accounts associated with that member.
### Account Fields
| Field | Data Type | Definition |
| :--------------------------- | :-------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `account_number` | String | The account number associated with the `account`. This will typically be a masked or partial account number. |
| `apr` | Double | The annual percentage rate associated with the `account`. |
| `apy` | Double | The annual percentage yield associated with the `account`. |
| `available_balance` | Double | The balance that is *available for use* in asset accounts like checking and savings. `PENDING` transactions are typically taken into account with the available balance, but this may not always be the case.
`available_balance` will usually be a positive value for all account types, determined in the same way as the `balance` field. |
| `available_credit` | Double | The amount of credit *available for use* in liability accounts like credit cards and lines of credit. `PENDING` transactions are typically taken into account with available credit, but this may not always be the case.
`available_credit` will usually be a positive value for all account types, determined in the same way as the `balance` field. |
| `balance` | Double | The current balance of the account. `PENDING` transactions are typically not taken into account with the current balance, but this may not always be the case. This is the value used for the account balance displayed in MX UIs.
The balance will usually be a positive value for all account types. Asset-type accounts (`CHECKING`, `SAVINGS`, `INVESTMENT`) may have a negative balance if they are in overdraft. Debt-type accounts (`CREDIT_CARD`, `LOAN`, `LINE_OF_CREDIT`, `MORTGAGE`) may have a negative balance if they are overpaid. |
| `cash_advance_apr` | Double | APR values for cash advances. Value is a percentage (e.g. 2.99% is passed as 2.99). |
| `cash_balance` | Double | The cash balance of the `account`. |
| `cash_surrender_value` | Double | The sum of money paid to the policyholder or annuity holder in the event the policy is voluntarily terminated before it matures, or the insured event occurs. |
| `created_at` | Long | The date and time at which the `account` was created. |
| `credit_limit` | Double | The credit limit associated with the `account`. |
| `day_payment_is_due` | Long | The day of the month the payment is due. For example, the 14th is passed as `14`. |
| `death_benefit` | Double | The amount paid to the beneficiary of the account upon death of the account owner. |
| `guid` | String | The unique identifier for the `account`. Defined by MX. |
| `has_monthly_transfer_limit` | Boolean | This account limits the number of transfers each month. This is associated with government regulation D. |
| `holdings_value` | Double | The sum of all long holdings within this account, not including any that are shorted and not including cash. |
| `id` | String | The unique partner-defined identifier for the `account` |
| `institution_code` | String | A more human-friendly identifier for the institution that this account is associated with. Defined by MX. |
| `institution_guid` | String | The unique identifier for the institution that this account is associated with. Defined by MX. |
| `insured_name` | String | The name of the insured individual. |
| `interest_rate` | Double | The interest rate associated with the `account`. |
| `is_closed` | Boolean | This indicates whether an account has been closed. |
| `is_hidden` | Boolean | This indicates whether the account is hidden. Defaults to `false`. |
| `is_internal` | Boolean | This indicates whether the account belongs to a client's default institution. |
| `is_personal` | Boolean | This indicates whether the account is personal. |
| `last_payment_at` | Long | The date and time of the most recent payment on the `account`. |
| `last_payment_on` | String | The date of the account's most recent payment. |
| `last_payment` | Double | The amount of the most recent payment made on the `account`. |
| `loan_amount` | Double | The amount of the loan associated with the `account`. |
| `matures_at` | Long | The date and time at which the account matures, given as a Unix timestamp. |
| `matures_on` | String | The date on which the account will mature. |
| `member_guid` | String | The unique identifier for the `member` associated with the `account`. Defined by MX. |
| `member_id` | String | The unique, partner-defined, identifier for the `member` associated with this `account`. |
| `member_is_managed_by_user` | Boolean | This indicates whether the associated `member` is managed by the user or the MX partner. |
| `metadata` | String | Additional information a partner can store on the `account`. |
| `minimum_balance` | Double | The minimum balance associated with the `account`. |
| `minimum_payment` | Double | The minimum payment required for an account. This can apply to any debt account. |
| `monthly_transfer_count` | Long | The number of limited transfers that have occurred during the current month. Typically users will incur a fee for going over six transfers from a limited transfer account in a given month. This is associated with government regulation D. |
| `name` | String | The human-readable name for the `account`. |
| `nickname` | String | An alternate name for the `account`. |
| `original_balance` | Double | The original balance associated with the `account`. This will always be positive. |
| `pay_out_amount` | Double | The amount paid out to the insured individual or beneficiary under the conditions of the insurance policy. |
| `payment_due_at` | Long | The date and time at which the next payment is due on the `account`. Represented as a Unix Epoch datetime (e.g. 1479166089). |
| `payment_due_on` | String | The date on which the next payment is due on the `account`. |
| `payoff_balance` | Double | The payoff balance for a debt `account`. This will normally be a positive number. |
| `pending_balance` | Double | The available balance after accounting for pending transactions. |
| `premium_amount` | Double | The insurance policy's premium amount. |
| `property_type` | String | The property type of the account, if applicable. |
| `revision` | Long | The revision number of the `account` record. |
| `started_at` | Long | The date and time at which a debt `account` was started. |
| `started_on` | String | The date on which a debt `account` was started. |
| `statement_balance` | Double | The balance at the end of the account's last statement period. |
| `statement_on` | String | The closing date — i.e., the statement compilation date — of the account's last billing cycle. |
| `sub_type` | String | The account's subtype, e.g., `PLAN_401_K`, `MONEY_MARKET`, or `HOME_EQUITY`. |
| `total_account_value` | Double | The sum of the long and short positions, the sweep account and/or cash balance, and any margin debt associated with a particular account. This amount includes the market value of all positions held in the account and is reduced by any debit balance and the amount of short options positions that are "in the money". This may sum to a negative value, and it **does not** represent an account balance. |
| `type` | String | The general or parent type of the `account`. |
| `updated_at` | Long | The date and time at which the `account` was most recently updated. |
| `user_guid` | String | The unique identifier for the user the account is associated with. Defined by MX. |
| `user_id` | String | The unique, partner-defined, identifier for the `user` associated with this `account`. |
### Account Types and Subtypes
**Parent Types**:
* `ANY` (not provided by data partner or invalid number provided)
* `CHECKING`
* `SAVINGS`
* `LOAN`
* `CREDIT_CARD`
* `INVESTMENT`
* `LINE_OF_CREDIT`
* `MORTGAGE`
* `PROPERTY`
* `CASH`
* `INSURANCE`
* `PREPAID`
* `CHECKING_LINE_OF_CREDIT`
**Subtypes**
| Subtype | Parent Type |
| :------------------------------------------ | :----------- |
| `MONEY_MARKET` | `SAVINGS` |
| `CERTIFICATE_OF_DEPOSIT` | `SAVINGS` |
| `AUTO` | `LOAN` |
| `STUDENT` | `LOAN` |
| `SMALL_BUSINESS` | `LOAN` |
| `PERSONAL` | `LOAN` |
| `PERSONAL_WITH_COLLATERAL` | `LOAN` |
| `HOME_EQUITY` | `LOAN` |
| `PLAN_401_K` | `INVESTMENT` |
| `PLAN_403_B` | `INVESTMENT` |
| `PLAN_529` | `INVESTMENT` |
| `IRA` | `INVESTMENT` |
| `ROLLOVER_IRA` | `INVESTMENT` |
| `ROTH_IRA` | `INVESTMENT` |
| `TAXABLE` | `INVESTMENT` |
| `NON_TAXABLE` | `INVESTMENT` |
| `BROKERAGE` | `INVESTMENT` |
| `TRUST` | `INVESTMENT` |
| `UNIFORM_GIFTS_TO_MINORS_ACT` | `INVESTMENT` |
| `PLAN_457` | `INVESTMENT` |
| `PENSION` | `INVESTMENT` |
| `EMPLOYEE_STOCK_OWNERSHIP_PLAN` | `INVESTMENT` |
| `SIMPLIFIED_EMPLOYEE_PENSION` | `INVESTMENT` |
| `SIMPLE_IRA` | `INVESTMENT` |
| `BOAT` | `LOAN` |
| `POWERSPORTS` | `LOAN` |
| `RV` | `LOAN` |
| `HELOC` | `LOAN` |
| `PLAN_ROTH_401_K` | `INVESTMENT` |
| `FIXED_ANNUITY` | `INVESTMENT` |
| `VARIABLE_ANNUITY` | `INVESTMENT` |
| `VEHICLE_INSURANCE` | `INSURANCE` |
| `DISABILITY` | `INSURANCE` |
| `HEALTH` | `INSURANCE` |
| `LONG_TERM_CARE` | `INSURANCE` |
| `PROPERTY_AND_CASUALTY` | `INSURANCE` |
| `UNIVERSAL_LIFE` | `INSURANCE` |
| `TERM_LIFE` | `INSURANCE` |
| `WHOLE_LIFE` | `INSURANCE` |
| `ACCIDENTAL_DEATH_AND_DISMEMBERMENT` | `INSURANCE` |
| `VARIABLE_UNIVERSAL_LIFE` | `INSURANCE` |
| `HSA` | `INVESTMENT` |
| `TAX_FREE_SAVINGS_ACCOUNT` | `INVESTMENT` |
| `INDIVIDUAL` | `INVESTMENT` |
| `REGISTERED_RETIREMENT_INCOME_FUND` | `INVESTMENT` |
| `CASH_MANAGEMENT_ACCOUNT` | `INVESTMENT` |
| `EMPLOYEE_STOCK_PURCHASE_PLAN` | `INVESTMENT` |
| `REGISTERED_EDUCATION_SAVINGS_PLAN` | `INVESTMENT` |
| `PROFIT_SHARING_PLAN` | `INVESTMENT` |
| `UNIFORM_TRANSFER_TO_MINORS_ACT` | `INVESTMENT` |
| `PLAN_401_A` | `INVESTMENT` |
| `SARSEP_IRA` | `INVESTMENT` |
| `FIXED_ANNUITY_TRADITIONAL_IRA` | `INVESTMENT` |
| `VARIABLE_ANNUITY_TRADITIONAL_IRA` | `INVESTMENT` |
| `SEPP_IRA` | `INVESTMENT` |
| `INHERITED_TRADITIONAL_IRA` | `INVESTMENT` |
| `FIXED_ANNUITY_ROTH_IRA` | `INVESTMENT` |
| `VARIABLE_ANNUITY_ROTH_IRA` | `INVESTMENT` |
| `INHERITED_ROTH_IRA` | `INVESTMENT` |
| `COVERDELL` | `INVESTMENT` |
| `ADVISORY_ACCOUNT` | `INVESTMENT` |
| `BROKERAGE_MARGIN` | `INVESTMENT` |
| `CHARITABLE_GIFT_ACCOUNT` | `INVESTMENT` |
| `CHURCH_ACCOUNT` | `INVESTMENT` |
| `CONSERVATORSHIP` | `INVESTMENT` |
| `CUSTODIAL` | `INVESTMENT` |
| `DEFINED_BENEFIT_PLAN` | `INVESTMENT` |
| `DEFINED_CONTRIBUTION_PLAN` | `INVESTMENT` |
| `EDUCATIONAL` | `INVESTMENT` |
| `ESTATE` | `INVESTMENT` |
| `EXECUTOR` | `INVESTMENT` |
| `GROUP_RETIREMENT_SAVINGS_PLAN` | `INVESTMENT` |
| `GUARANTEED_INVESTMENT_CERTIFICATE` | `INVESTMENT` |
| `HRA` | `INVESTMENT` |
| `INDEXED_ANNUITY` | `INVESTMENT` |
| `INVESTMENT_CLUB` | `INVESTMENT` |
| `IRREVOCABLE_TRUST` | `INVESTMENT` |
| `JOINT_TENANTS_BY_ENTIRITY` | `INVESTMENT` |
| `JOINT_TENANTS_COMMUNITY_PROPERTY` | `INVESTMENT` |
| `JOINT_TENANTS_IN_COMMON` | `INVESTMENT` |
| `JOINT_TENANTS_WITH_RIGHTS_OF_SURVIVORSHIP` | `INVESTMENT` |
| `KEOUGH_PLAN` | `INVESTMENT` |
| `LIFE_INCOME_FUND` | `INVESTMENT` |
| `LIVING_TRUST` | `INVESTMENT` |
| `LOCKED_IN_RETIREMENT_ACCOUNT` | `INVESTMENT` |
| `LOCKED_IN_RETIREMENT_INVESTMENT_FUND` | `INVESTMENT` |
| `LOCKED_IN_RETIREMENT_SAVINGS_ACCOUNT` | `INVESTMENT` |
| `MONEY_PURCHASE_PLAN` | `INVESTMENT` |
| `PARTNERSHIP` | `INVESTMENT` |
| `PLAN_409_A` | `INVESTMENT` |
| `PLAN_ROTH_403_B` | `INVESTMENT` |
| `REGISTERED_DISABILITY_SAVINGS_PLAN` | `INVESTMENT` |
| `REGISTERED_LOCKED_IN_SAVINGS_PLAN` | `INVESTMENT` |
| `REGISTERED_PENSION_PLAN` | `INVESTMENT` |
| `REGISTERED_RETIREMENT_SAVINGS_PLAN` | `INVESTMENT` |
| `REVOCABLE_TRUST` | `INVESTMENT` |
| `ROTH_CONVERSION` | `INVESTMENT` |
| `SOLE_PROPRIETORSHIP` | `INVESTMENT` |
| `SPOUSAL_IRA` | `INVESTMENT` |
| `SPOUSAL_ROTH_IRA` | `INVESTMENT` |
| `TESTAMENTARY_TRUST` | `INVESTMENT` |
| `THRIFT_SAVINGS_PLAN` | `INVESTMENT` |
| `INHERITED_ANNUITY` | `INVESTMENT` |
| `CORPORATE_ACCOUNT` | `INVESTMENT` |
| `LIMITED_LIABILITY_ACCOUNT` | `INVESTMENT` |
### Account Property Types
| Property type |
| :----------------- |
| `REAL_ESTATE` |
| `VEHICLE` |
| `ART` |
| `JEWELRY` |
| `FURNITURE` |
| `APPLIANCES` |
| `COMPUTER` |
| `ELECTRONICS` |
| `SPORTS_EQUIPMENT` |
| `MISCELLANEOUS` |
## Beats
Beats are deprecated. Use [Insights](#insights) instead.
**Beats Fields**
| Field | Data Type | Definition |
| :------------------------- | :-------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `account_guids` | Array | An array of account GUIDs that are relevant to the information delivered in the `beat`. |
| `account_ids` | Array | An array of partner-defined identifiers for accounts that are relevant to the information delivered in the `beat`. |
| `active_at` | Long | The date and time the `beat` became active. |
| `created_at` | Long | The date and time this beat was created. |
| `description` | String | The human-readable information being delivered to the end user. |
| `digest` | String | A unique identifier derived from inputs to the `beat` which ensures beats are not duplicated. |
| `displayed _at` | Long | The date and time at which the `beat` was displayed to the end user. |
| `guid` | String | The unique identifier for the `beat`. Defined by MX. |
| `has_been_displayed` | Boolean | This indicates whether the `beat` has been displayed to the end user. |
| `html_description` | String | The beat's description, delivered as HTML. |
| `html_title` | String | The beat's title, delivered as HTML. |
| `is_deleted` | Boolean | This indicates whether the `beat` has been deleted. |
| `is_dismissed` | Boolean | This indicates whether the `beat` has been dismissed. |
| `is_relevant` | Boolean | This indicates whether a `beat` still contains information that is relevant, meaningful, or useable to the end user. For example, an `OverdraftWarning` will have `is_relevant` set to `false` if a large deposit is made into the associated account after the `beat` was created. Any `beat` which has already been displayed to or dismissed by the end user will be set to `false`. There are numerous examples and conditions. |
| `primary_account_guid` | String | The unique identifier for the `account` most relevant to the information delivered in the `beat`. |
| `primary_account_id` | String | The unique partner-defined identifier for the `account` most relevant to the information delivered in the `beat`. |
| `primary_transaction_guid` | String | The unique identifier for the `transaction` most relevant to the information delivered in the `beat`. |
| `primary_transaction_id` | String | The unique partner-defined identifier for the `transaction` most relevant to the information delivered in the `beat`. |
| `template` | String | A short label for the type of `beat` being delivered, e.g., `SubscriptionPriceIncrease` or `MonthlyCategoryTotal`. |
| `title` | String | The title for the specific `beat`, e.g., `Price Increase` or `Paycheck Deposit`. |
| `transaction_guids` | Array | An array of transaction GUIDs that are relevant to the information delivered in the `beat`. |
| `transaction_ids` | Array | An array of partner-defined transaction identifiers that are relevant to the information delivered in the `beat`. |
| `updated_at` | Long | The date and time this beat was most recently updated. |
| `user_guid` | String | The unique identifier for the `user` to which the `beat` belongs. Defined by MX. |
| `user_id` | String | The unique partner-defined identifier for the `user` to which the `beat` belongs. |
## Beat Feedback
Beats are deprecated. Use [insights](#insights) instead.
| Field | Data Type | Definition |
| :----------- | :-------- | :------------------------------------------------------------------------------------------------------------------- |
| `beat_guid` | String | The unique identifier for the beat associated with this feedback. Defined by MX. |
| `comments` | String | The feedback provided by the end user. |
| `created_at` | Long | The date and time associated with this beat feedback. |
| `guid` | String | The unique identifier for the beat feedback. Defined by MX. |
| `rating` | Long | The rating provided by the end user. `1` is the lowest rating, `5` is the highest. `0` means no rating was provided. |
| `template` | String | A short label for the type of `beat` being delivered, e.g., `NotifySalaryDeposit` or `SumSpendingCategory`. |
| `updated_at` | Long | The date and time at which the beat feedback was last updated. |
| `user_guid` | String | The unique identifier for the user associated with the beat feedback. Defined by MX. |
| `user_id` | String | The partner-defined identifier for the user associated with the beat feedback. |
## Budgets
Budgets represent an end users monthly budget for a given category. Budgets are offered as part of the following MX products and solutions:
* Mobile Banking
* Personal Finance Management
* Nexus API
**Budget Fields**
| Field | Data Type | Definition |
| :------------------- | :-------- | :----------------------------------------------------------------------------------------------------------------------- |
| `amount` | Long | The monthly amount allotted to this budget. |
| `category_guid` | String | The unique identifier for the category associated with this budget. Defined by MX. |
| `created_at` | Long | The date and time the budget was created. |
| `guid` | String | The unique identifier for the budget. Defined by MX. |
| `is_exceeded` | Boolean | This indicates that the budget has been exceeded. |
| `is_off_track` | Boolean | This indicates that the projected total monthly spending in the associated category exceeds 105% of the budgeted amount. |
| `metadata` | String | Additional information a partner can store on the budget. |
| `name` | String | The name of the budget. This is the same as the name of the spending category that the budget is associated with. |
| `parent_guid` | String | The unique identifier for the parent budget. Defined by MX. |
| `projected_spending` | Double | The projected amount of spending for the budget. |
| `revision` | Long | The revision number of the budget record. |
| `transaction_total` | Double | The cumulative amount of all transactions associated with this budget. |
| `updated_at` | Long | The date and time this budget was most recently updated. |
| `user_guid` | String | The unique identifier for the user the budget is associated with. Defined by MX. |
| `user_id` | String | The unique, partner-defined identifier for the user the budget is associated with. |
## Categories
Daily reporting files for categories reflect changes in custom transaction categories created by end users with the following MX products and solutions:
* Mobile Banking
* Personal Finance Management
* Nexus API
* Platform API
**Category Fields**
| Field | Data Type | Definition |
| :------------ | :-------- | :------------------------------------------------------------------------------------------------------------------------ |
| `created_at` | Long | The date and time the category was created. This field will always be `null` when `is_default` is true. |
| `guid` | String | The unique identifier of the category. Defined by MX. |
| `is_default` | Boolean | This indicates whether the category is an MX-created default category. This will always be `false` for custom categories. |
| `is_income` | Boolean | This indicates whether the category represents income. This will always be `false` for custom categories. |
| `metadata` | String | Addition information a partner can store on the category. |
| `name` | String | The name of the category. |
| `parent_guid` | String | The unique identifier for the parent category. Defined by MX. |
| `revision` | Long | The revision number of the category record. |
| `updated_at` | Long | The date and time the category was last updated. This field will always be `null` when `is_default` is true. |
| `user_guid` | String | The unique identifier of the user this category is associated with. Defined by MX. |
| `user_id` | String | The unique, partner-defined identifier of the user this category is associated with. |
## Devices
Devices represent devices using the Mobile Banking app.
**Device Fields**
| Field | Data Type | Definition |
| :----------- | :-------- | :--------------------------------------------------------------------------------- |
| `guid` | String | The unique identifier of the device. Defined by MX. |
| `make` | String | The name of the device's manufacturer. |
| `model` | String | The model of the device. |
| `os_name` | String | The name of the operating system that the device is running. |
| `os_version` | String | The operating system version that the device is running. |
| `updated_at` | Long | The date and time the device record was last updated. |
| `user_guid` | String | The unique identifier for the user the device is associated with. Defined by MX. |
| `user_id` | String | The unique, partner-defined identifier for the user the device is associated with. |
## Goals
Goals represent savings or payment goals created with the following MX products and solutions:
* Personal Finance Management
* Nexus
### Goal Fields
| Field | Data Type | Definition |
| :------------------------- | :-------- | :-------------------------------------------------------------------------------- |
| `account_guid` | String | The unique identifier for the account the goal is associated with. Defined by MX. |
| `amount` | Double | The amount of the goal. |
| `completed_at` | Long | The date and time the goal was completed. |
| `completed_on` | String | The date the goal was completed. |
| `created_at` | Long | The date and time the goal was created. |
| `created_by` | String | The source that created the goal. Can be `SYSTEM`, `USER`, or `null`. |
| `created_on` | String | The date the goal was created. |
| `current_amount` | Double | The current amount that has been committed to the goal. |
| `goal_type` | String | The type of the goal (`SAVE_AMOUNT` or `PAYOFF`). |
| `guid` | String | The unique identifier for the goal. Defined by MX. |
| `has_been_spent` | Boolean | This indicates that the goal has been spent. |
| `is_complete` | Boolean | This indicates that the goal has been completed. |
| `meta_type` | String | The meta type of the goal. |
| `metadata` | String | Additional information a partner can store on the goal. |
| `name` | String | The name of the goal. |
| `position` | Long | The priority position of the goal in relation to multiple goals. |
| `projected_to_complete_at` | Long | The date and time the goal is projected to be completed. |
| `revision` | Long | The revision number of the goal record. |
| `updated_at` | Long | The date and time this goal was last updated. |
| `user_guid` | String | The unique identifier for the user the goal is associated with. Defined by MX. |
| `user_id` | String | The unique, partner-defined identifier for the user the goal is associated with. |
### Goal Meta Types
* `AUTOMOBILE`
* `COLLEGE`
* `ELECTRONIC`
* `EMERGENCY_FUND`
* `HOUSE`
* `OTHER`
* `RECREATIONAL_VEHICLE`
* `RETIREMENT`
* `SETUP_BUDGETS`
* `START_MONEY_MANAGEMENT`
* `VACATION`
## Holdings
Holdings represent a stock, bond, or other type of investment, as found in the following MX products and solutions:
* Atrium API
* MDX Real Time
* Nexus API
* Platform API
### Holding Fields
As of January 1, 2025, CUSIP is no longer supported. Please refer to the most-up-to-date [investment documentation](/products/data/investment-data-enhancement/).
| Field | Data Type | Definition |
| :---------------------------- | :-------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `account_guid` | String | The unique identifier for the account associated with the holding. Defined by MX. |
| `bond_coupon_rate` | Double | The coupon rate for a bond. |
| `bond_maturity_date` | Long | The date and time a bond matures. |
| `classification` | String | An alias for the field `equity_classification`. |
| `cost_basis` | Double | The cost basis is the original value of an asset adjusted for stock splits, dividends, and capital distributions. |
| `created_at` | Long | The date and time the holding was created. |
| `daily_change` | Double | The change from the previous day in the price of the holding. |
| `deleted_at` | Long | The date and time the holding was deleted. |
| `description` | String | The description of the holding after being cleansed by MX into a human-readable format. |
| `equity_classification` | String | The equity classification of the holding. |
| `fixed_income_classification` | String | A graphical representation of the investment style of the fixed income funds within a holding (like bonds) according to the [Morningstar Style Box](https://www.morningstar.com/invglossary/morningstar_style_box.aspx). |
| `guid` | String | The unique identifier for the holding. Defined by MX. |
| `holding_type` | String | The type of holding, e.g., mutual fund, bond, etc. |
| `id` | String | The unique identifier for the holding. Defined by the data provider. |
| `is_deleted` | Boolean | This indicates that the holding has been deleted. |
| `isin` | String | The International Securities Identification Number (ISIN) in ISO 6166 format. |
| `market_value` | Double | The market value of the holding. |
| `member_is_managed_by_user` | Boolean | This indicates that the member associated with the holding is managed by the user. |
| `metadata` | String | Additional information a partner can store on the holding. |
| `purchase_price` | Double | The purchase price of the holding. |
| `revision` | Long | The revision number of the holding record. |
| `sector` | String | The area of the economy the holding is invested in. |
| `sedol` | String | The Stock Exchange Daily Official List (SEDOL) classification code, represented as a seven-character code (e.g. B03MM40). |
| `shares` | Double | The number of shares owned for the holding. |
| `symbol` | String | The ticker symbol, i.e. the abbreviation used to uniquely identify publicly traded stocks, bonds, mutual funds, and ETFs. |
| `updated_at` | Long | The date and time the holding was last updated. |
| `user_guid` | String | The unique identifier for the user the holding is associated with. Defined by MX. |
| `user_id` | String | The unique identifier for the user the holding is associated with. Defined by the partner. |
### Equity Classifications
* `UNKNOWN`
* `LARGE_VALUE`
* `LARGE_CORE`
* `LARGE_GROWTH`
* `MID_VALUE`
* `MID_CORE`
* `MID_GROWTH`
* `SMALL_VALUE`
* `SMALL_CORE`
* `SMALL_GROWTH`
### Fixed Income Classifications
* `UNKNOWN_FIXED_INCOME_CLASSIFICATION`
* `HIGH_LIMITED`
* `HIGH_MODERATE`
* `HIGH_EXTENSIVE`
* `MEDIUM_LIMITED`
* `MEDIUM_MODERATE`
* `MEDIUM_EXTENSIVE`
* `LOW_LIMITED`
* `LOW_MODERATE`
* `LOW_EXTENSIVE`
### Sectors
* `UNKNOWN_SECTOR`
* `BASIC_MATERIALS`
* `CONSUMER_CYCLICAL`
* `FINANCIAL_SERVICES`
* `REAL_ESTATE`
* `CONSUMER_DEFENSIVE`
* `HEALTHCARE`
* `UTILITIES`
* `COMMUNICATION_SERVICES`
* `ENERGY`
* `INDUSTRIALS`
* `TECHNOLOGY`
### Holding Types
* `UNKNOWN_TYPE`
* `EQUITY`
* `EXCHANGE_TRADED_FUND`
* `MONEY_MARKET`
* `MUTUAL_FUND`
* `HEDGE_FUND`
* `ANNUITY`
* `UNIT_INVESTMENT_TRUST`
* `CASH`
* `FIXED_INCOME`
* `OPTIONS`
## Insights
Insights are cards that are personalized for a user and appear on the UI. This relates to our [Financial Insights](/products/experience/insights) product.
| Field | Data Type | Definition |
| :---------------------------------- | :-------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `active_at` | Long | The date and time the `insight` is active. |
| `client_guid` | String | The unique identifier for the client associated with the insight. Defined by MX. |
| `created_at` | Long | The date and time the `insight` was created. |
| `description` | String | The human-readable information being delivered to the end user. |
| `guid` | String | The unique identifier for the `insight`. Defined by MX. |
| `has_associated_accounts` | Boolean | This indicates whether there are accounts associated with the insight. |
| `has_associated_categories` | Boolean | This indicates whether there are categories associated with the insight. |
| `has_associated_merchants` | Boolean | This indicates whether there are merchants associated with the insight. |
| `has_associated_scheduled_payments` | Boolean | This indicates whether there are scheduled payments associated with the insight. |
| `has_associated_transactions` | Boolean | This indicates whether there are transactions associated with the insight. |
| `has_been_displayed` | Boolean | This indicates whether the insight has been shown to the end user. |
| `is_dismissed` | Boolean | This indicates whether the insight has been dismissed by the end user. |
| `micro_call_to_action` | String | Returns a micro CTA if the insight template supports micro copy. |
| `micro_description` | String | A shortened version of the insight's description that displays to the end user in the Micro Insights Widget. |
| `micro_title` | String | A shortened version of the insight's title that displays to the end user in the Micro Insights Widget. For example, `Price Increase` or `Paycheck Deposit`. |
| `template` | String | A short label for the type of `insight` being delivered, for example, `SubscriptionPriceIncrease` or `MonthlyCategoryTotal`. See [Insights Library](/products/experience/insights/library) for more info. |
| `title` | String | The title for the specific `insight`, for example, `Price Increase` or `Paycheck Deposit`. |
| `updated_at` | Long | The date and time the `insight` was last updated. |
| `user_guid` | String | The unique identifier for the `user` to which the `insight` belongs. Defined by MX. |
| `user_id` | String | The unique partner-defined identifier for the `user` associated with the `insight`. |
## Members
A member represents the relationship between a user and an institution. A user may have multiple members, one each for their bank, their mortgage broker, their credit card provider, etc. Aggregation, verification, and many other processes are centered around a member. Daily change files reflect member changes resulting from background aggregation as well as from the following MX products or solutions:
* Atrium API
* Batch API
* Mobile Banking
* MDX Real Time
* Personal Finance Management, including the Connect and Connections widgets
* Nexus API
* Platform API
* SSO API
### Member Fields
| Field | Data Type | Definition |
| :------------------------------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connection_status_id` | Long | This indicates the state of a member's aggregation. This field will reflect the value as of the time that the daily files were generated, which is around midnight UTC. |
| `connection_status_message` | String | A message that can be displayed to the user to help them navigate the connection and aggregation process. |
| `connection_status` | String | This indicates the state of a member's aggregation. This field will reflect the value as of the time that the daily files were generated, which is around midnight UTC. |
| `created_at` | Long | The date and time the member was created. |
| `guid` | String | The unique identifier for the member. Defined by MX. |
| `id` | String | The partner-defined unique identifier for the member. |
| `institution_code` | String | A more human-friendly identifier for the institution that this member is associated with. Defined by MX. |
| `institution_guid` | String | The unique identifier for the institution associated with the member. Defined by MX. |
| `institution_id` | String | A partner-defined alternate unique identifier for the member's institution. |
| `is_managed_by_user` | Boolean | This indicates that the member is managed by the user. |
| `is_manual` | Boolean | This indicates that the member was created manually. |
| *`is_user_created`* (deprecated) | Boolean | If the member was created by the user, this field will be `true`. Otherwise, this field will be `false`. The field `is_user_created` has been deprecated. Partners should use the field `is_managed_by_user` instead. Both fields are included for backward compatibility. |
| `metadata` | String | Additional information a partner can store on the member. |
| `name` | String | The name of the member. |
| `revision` | Integer | The revision number of this member record. |
| `successfully_aggregated_at` | Integer | The date and time this member was last successfully aggregated. |
| `updated_at` | Integer | The date and time this member was last updated. |
| `use_cases` | Array | The use case associated with the member. Valid values are `PFM` and/or `MONEY_MOVEMENT`. For more info, see [Member Use Cases](/nexus/member-use-cases). |
| `user_guid` | String | The unique identifier for the user associated with the member. Defined by MX. |
| `user_id` | String | The unique partner-defined identifier for the user associated with the member. |
### Member Connection Statuses
The `connection_status` indicates the state of a `member`'s aggregation, meaning the state of a `user` connecting to a particular `institution`.
The `connection_status` field indicates the current state of an aggregation, meaning the state of a `user` connecting to a particular `institution`. For instance:
* `CREATED` means the member has just been created.
* `CHALLENGED` means the process has run into multifactor authentication.
* `FAILED` means the process was unsuccessful.
The connection statuses `CREATED`, `UPDATED`, `DELAYED`, and `RESUMED` represent transient states for different points in the process and don't require a specific action or end-user input. They may, however, require you to keep making `read` requests on the member until an actionable status or an end state appears.
The connection statuses `PREVENTED`, `DENIED`, `IMPEDED`, `IMPAIRED`, `REJECTED`, `EXPIRED`, `LOCKED`, `IMPORTED`, `DISABLED`, `DISCONTINUED`, and `CLOSED` represent end states that require you to start a new connection, and possibly end-user input, for future success.
Here are all the `member` statuses you might encounter, what they mean, and what to do about them.
| Integer Value | Status | Definition | Next Steps | End-User Message |
| :------------ | :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |
| null | `null` | The member exists but does not have credentials. A member that does not aggregate (e.g., a manual member) will always have this status. | None. | None. |
| 0 | `CREATED` | The member is new and has not yet been aggregated. | Aggregate the member once the end user logs in; poll for a status update. | **Connecting to \[...] ...** |
| 1 | `PREVENTED` | The end user's entered credentials have failed to connect three times in a row. MX has locked the account to avoid locking the end user out of their account on the financial institution's website. The end user must reenter their username and password to continue updating their data. | Display end-user message; after end user has updated their credentials, aggregate again. | **The last 3 attempts to connect have failed. Please re-enter your credentials to continue importing data.** |
| 2 | `DENIED` | The credentials provided for the member were invalid. | Display end-user message; after end user has updated their credentials, aggregate again. | **The credentials entered do not match your credentials at this institution. Please re-enter your credentials to continue importing data.** |
| 3 | `CHALLENGED` | The connection is waiting for the end user to complete a multifactor authentication (MFA) challenge. This is not an error and will change to an `EXPIRED` status if the end user fails to complete MFA. | Display end-user message; follow MFA pathway; after the user answers MFA, poll for a status update. | **To authenticate your connection to \[...], please answer the following challenge(s).** |
| 4 | `REJECTED` | An MFA challenge was answered incorrectly. | Display end-user message; another challenge may follow or aggregation may need to be restarted. | **The answer or answers provided were incorrect. Please try again.** |
| 5 | `LOCKED` | The financial institution is preventing authentication. The end user must go to the FI's website or contact the financial institution. | Display end-user message. | **Your account is locked. Please log in to the appropriate website for \[...] and follow the steps to resolve the issue.** |
| 6 | `CONNECTED` | The member was successfully authenticated and data is now aggregating. | Display the account as having been connected. | **Connected to \[...] ...** |
| 7 | `IMPEDED` | The end user’s attention is required at their online banking institution, e.g., there is a marketing message that must be viewed, terms and conditions that must be accepted, etc. | Display end-user message. | **Your attention is needed at this institution's website. Please log in to the appropriate website for \[...] and follow the steps to resolve the issue.** |
| 8 | `RECONNECTED` | The member has been migrated to a new data source and aggregation is likely to trigger one-time password MFA. MX will not perform background aggregation in order to avoid unnecessarily disruptive texts, emails, etc. The member must be re-aggregated in the foreground with the end user present. | Aggregate the member once the end user logs in; poll for a status update. | **Reconnecting to \[...] ...** |
| 9 | `DEGRADED` | Aggregation has failed at least three times within a short period of time. This could be due to website maintenance or other factors that are preventing account aggregation. | Display end-user message. | **We are upgrading this connection. Please try again later.** |
| 10 | `DISCONNECTED` | Aggregation has failed at least three times and has not succeeded for at least two weeks. | Display end-user message. | **It looks like your data from \[...] cannot be imported. We are working to resolve the issue.** |
| 11 | `DISCONTINUED` | The connection to this financial institution is no longer available. | Display end-user message. | **Connections to this institution are no longer supported. You may create a manual account and use manual transactions to track data for this account.** |
| 12 | `CLOSED` | The end user, MX, the client, or a partner has marked the member as closed. | Display end-user message. | **This connection has been closed. You may track this account manually. If reopened, you may connect the institution again.** |
| 13 | `DELAYED` | Aggregating the member has taken longer than expected and it has not yet been connected. This can be due to reasons outside of MX's control, such as internet bandwidth, problems at the financial institution's website, and other factors. | Display end-user message; poll for a status update. | **Importing your data from \[...] may take a while. Please check back later.** |
| 14 | `FAILED` | Aggregation failed without being connected. Most aggregation issues are temporary and self-resolve after 24 hours. | Display end-user message; try aggregating again later. | **There was a problem validating your credentials with \[...]. Please try again later.** |
| 15 | `UPDATED` | The member has been updated — i.e., credentials have been updated — but it has not yet been connected. | Aggregate the member once the end user logs in; poll for a status update. | **Connecting to \[...] ...** |
| 16 | `DISABLED` | Aggregation has been momentarily paused, but the member is still connected. | Display end-user message. | **Importing data from this institution has been disabled. Please contact us if you believe it has been disabled in error.** |
| 17 | `IMPORTED` | MX does not have credentials and will not try to aggregate the member until the end user provides credentials. | Display end-user message; re-aggregate after the end user updates credentials. | **You must re-authenticate before your data can be imported. Please enter your credentials for \[...].** |
| 18 | `RESUMED` | The answer to an MFA challenge was received, but it is not yet clear whether it was correct. | Poll for a status update. | **Connecting to \[...] ...** |
| 19 | `EXPIRED` | The MFA answer was not provided within the time allotted by the financial institution. | Display end-user message; re-aggregate the member if the end user initiates it. | **The answer or answers were not provided in time. Please try again.** |
| 20 | `IMPAIRED` | The member is missing some or all credentials needed in order to connect. | Display end-user message; re-aggregate after the end user updates credentials. | **You must re-authenticate before your data can be imported. Please enter your credentials for \[...].** |
| 21 | `PENDING` | The member is using OAuth to authenticate credentials and still needs to go through the financial institution's OAuth process. A `PENDING` status will appear only on members less than one hour old with `is_oauth: true`. Members that stay `PENDING` longer than one hour will be deleted by MX. | Redirect the end user to the `oauth_window_uri` provided in the create member response, or request one through the generate OAuth window URI endpoint. | None. |
## Notification Profiles
Notification profiles are related to our PFM widgets.
### Notification Profile Fields
| Field | Data Type | Definition |
| :------------------ | :-------- | :---------------------------------------------------------------------------------------------------------------------------------------------- |
| `created_at` | Long | The date and time at which the notification profile was created. |
| `email_channel` | Boolean | This indicates whether email notifications are enabled for the user. |
| `entity_guid` | String | The unique identifier for the object associated with this notification, e.g., `BGT-1234` or `TRN-2345`. |
| `guid` | String | The unique identifier for the notification profile. Defined by MX. |
| `is_enabled` | Boolean | This indicates whether notifications are enabled for the user. |
| `last_recorded_at` | Long | The date and time a notification of a given type was last triggered. |
| `notification_type` | String | The type of notification, e.g., `BUDGET_EXCEEDED` or `OFFER`. |
| `push_channel` | Boolean | This indicates whether push notifications are enabled for the user. |
| `scheduled_for` | Long | For recurring notification types such as `DEBT_PAYMENT_REMINDER`, this is the date and time the next notification is scheduled to be delivered. |
| `sms_channel` | Boolean | This indicates whether SMS notifications are enabled for the user. |
| `threshold` | Long | This is the monetary threshold that will trigger a notification for certain notification types, such as `BUDGET_EXCEEDED`. |
| `updated_at` | Long | The time at which the notification profile was last updated. |
| `user_guid` | String | The unique identifier for the `user` associated with the notification profile. Defined by MX. |
| `user_id` | String | The partner-defined unique identifier for the `user` associated with the notification profile. |
### Notification Types
| Type Integer | Type String |
| :-------------- | :----------------------------- |
| 1 | BUDGET\_EXCEEDED |
| 2 | BUDGET\_OFF\_TARGET |
| 3 | DEBT\_PAYMENT\_REMINDER |
| 4 (deprecated) | GUIDE\_ME\_STEP\_COMPLETE |
| 5 (deprecated) | GUIDE\_ME\_OFF\_TARGET |
| 6 | ACCOUNT\_BALANCE\_LOW |
| 7 | ACCOUNT\_DEPOSIT\_LARGE |
| 8 | TRANSACTION\_EXPENSE\_LARGE |
| 9 | TRANSACTION\_FEE\_CHARGE |
| 10 (deprecated) | SYSTEM\_NOTIFICATION |
| 11 | API\_NOTIFICATION |
| 12 | USER\_SUMMARY |
| 13 | OFFER |
| 14 | PASSWORD\_RESET\_TOKEN |
| 15 | PASSWORD\_CHANGED |
| 16 | EMAIL\_VERIFICATION |
| 17 | EMAIL\_VERIFIED |
| 18 | WELCOME\_NEW\_USER |
| 19 | DEVICE\_CREATED |
| 20 | DEVICE\_DELETED |
| 21 | SMS\_VERIFICATION |
| 22 | ACCOUNT\_NEARING\_ZERO |
| 23 | TRANSACTION\_IS\_INTERNATIONAL |
| 24 | INVALID\_CONTACT\_INFORMATION |
| 25 | GOAL\_PROGRESS |
| 26 | CREATE\_GOAL |
| 27 | FORGOT\_USERNAME\_REMINDER |
| 28 | SMS\_WELCOME\_MESSAGE |
| 29 | DUPLICATE\_PAYMENT |
## Taggings
Taggings represent the association of a tag to a transaction. In other words, with a tagging, a transaction can be assigned a specific tag, either the default business tag, or any other user-created tag. Daily files represent changes resulting from the following MX products and solutions:
* Personal Finance Management
* Nexus API
* Platform API
**Tagging Fields**
| Field | Data Type | Definition |
| :-------------------------- | :-------- | :--------------------------------------------------------------------------------------------------------------- |
| `guid` | String | The unique identifier for the tagging. Defined by MX. |
| `member_is_managed_by_user` | Boolean | This indicates that the member the associated with the tagging is managed by the user. |
| `revision` | Long | The revision number of the tagging record. |
| `transaction_guid` | String | The unique identifier for the transaction associated with the tag. Defined by MX. |
| `transaction_id` | String | The partner-defined unique identifier for the transaction associated with the tag. Defined by the data provider. |
| `tag_guid` | String | The unique identifier for the tag. Defined by MX. |
| `tag_name` | String | The name of the tag. |
| `updated_at` | Long | The date and time the tag was last updated. |
| `user_guid` | String | The unique identifier for the user the tag is associated with. Defined by MX. |
| `user_id` | String | The partner-defined unique identifier for the user associated with the tag. |
## Tags
Tags allow partners and end users to create a custom label for particular transactions. Daily files represent changes resulting from the following MX products and solutions:
* Personal Finance Management
* Nexus API
* Platform API
**Tag Fields**
| Field | Data Type | Definition |
| :----------- | :-------- | :---------------------------------------------------------------------------- |
| `guid` | String | The unique identifier for the tag. Defined by MX. |
| `name` | String | The name of them tag. |
| `revision` | Long | The revision number of the tag record. |
| `updated_at` | Long | The date and time the tag was last updated. |
| `user_guid` | String | The unique identifier for the user the tag is associated with. Defined by MX. |
| `user_id` | String | The unique partner-defined identifier for the user associated with the tag. |
## Transactions
A transaction represents any instance in which money moves into or out of an account, such as a purchase at a business, a payroll deposit, a transfer from one account to another, an ATM withdrawal, etc. Each transaction belongs to only one account. Daily files represent changes resulting from background aggregation as well as the following MX products and solutions:
* Atrium API
* Batch API
* Mobile Banking
* MDX Real Time
* Personal Finance Management, including the Connect and Connections widgets
* Nexus API
* Platform API
* SSO API
**Transaction Fields**
| Field | Data Type | Definition |
| :---------------------------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `account_guid` | String | The unique identifier for the account associated with this transaction. Defined by MX. |
| `account_id` | String | The unique partner-defined identifier for the account associated with the transaction. |
| `amount` | Double | The monetary amount of the transaction. |
| `category_guid` | String | The unique identifier for the category assigned to the transaction. |
| `category` | String | The category of the transaction. |
| *`check_number` (deprecated)* | Long | The check number for the transaction. This field will be `null` if the value is not an Integer, or if its value is too large to fit in a *long* object type. This filed has been deprecated; partners should use `check_number_String` instead. |
| `check_number_string` | String | The check number for the transaction. |
| `created_at` | Long | The date and time the transaction was created. |
| `date` | Long | The date on which the transaction took place. This is the field used when searching for transactions by date. This field is generally the same as `transacted_at`, but uses `posted_at` as a fallback. |
| `description` | String | A human-readable version of the `feed_description` field described below, e.g., "Sam's Club," "Johnny's Tavern." This is provided by the MX Platform. |
| `feed_description` | String | The original description of the transaction as provided by our data feed. See `description` above for more information. |
| `feed_localized_description` | String | The original description of the transaction as provided by our data feed, given in a local language. See `description` above for more information. |
| `feed_localized_memo` | String | Additional descriptive information about the transaction as provided by our data feed, given in a local language. |
| `feed_transaction_type` | String | The type of the transaction, as provided by our data feed. See `type` for more information. |
| `guid` | String | The unique identifier for the transaction. Defined by MX. |
| `has_been_split` | Boolean | This indicates whether the transaction has been split. |
| `has_been_viewed` | Boolean | This indicates whether the transaction has been viewed. |
| `id` | String | The unique partner-defined identifier for the transaction. |
| `is_bill_pay` | Boolean | This indicates whether the transaction represents a bill pay. |
| `is_direct_deposit` | Boolean | This indicates whether the transaction represents a direct deposit. |
| `is_expense` | Boolean | This indicates whether the transaction represents an expense. |
| `is_fee` | Boolean | This indicates whether the transaction represents a fee. |
| `is_flagged` | Boolean | This indicates whether the transaction has been flagged. |
| `is_hidden` | Boolean | This indicates whether the transaction is hidden. |
| `is_income` | Boolean | This indicates whether the transaction represents income. |
| `is_international` | Boolean | If the transaction is international, as defined by the data provider, this field will be true. If the data provider determines it is not international then it will be false. It will be `null` if the data provider does not provide this information. |
| `is_overdraft_fee` | Boolean | This indicates whether the transaction represents an overdraft fee. |
| `is_payroll_advance` | Boolean | This indicates whether the transaction represents a payroll advance. |
| `is_personal` | Boolean | This indicates whether the transaction has been marked as personal by the user. |
| `is_recurring` | Boolean | **This field should be ignored. If this information is required, please reach out to MX to discuss an alternative.** |
| `is_subscription` | Boolean | This indicates whether the transaction represents a payment for a subscription service such as Netflix or Audible. |
| `latitude` | Double | The latitude of the location where the transaction occurred. The number is a signed decimal (e.g. Rio de Janeiro's latitude is -22.9027800 and Tokyo's latitude is 35.689488). |
| `localized_description` | String | A human-readable description of the transaction, provided in a local language. |
| `localized_memo` | String | Additional descriptive information about the transaction, provided in a local language. |
| `longitude` | Double | The longitude of the location where the transaction occurred. The number is a signed decimal (e.g. Rio de Janeiro's longitude is -43.2075000 and Tokyo's longitude is 139.691706). |
| `member_is_managed_by_user` | Boolean | This indicates whether the associated `member` is managed by the user or the MX partner. |
| `memo` | String | This field contains additional descriptive information about the transaction. |
| `merchant_category_code` | Long | The ISO 18245 category code for the transaction. |
| `merchant_guid` | String | The unique identifier for the merchant associated with the transaction. Defined by MX. |
| `merchant_location_guid` | String | The unique identifier for the merchant location associated with the transaction. Defined by MX. |
| `metadata` | String | Additional information a partner can store on the transaction. |
| `parent_guid` | String | The unique identifier for the parent transaction associated with a split transaction. Defined by MX. |
| `posted_at` | Long | The date and time the transaction was posted to the account. |
| `posted_on` | String | The date the transaction was posted to the account. |
| `revision` | Long | The revision number of the transaction record. |
| `status` | String | The status of the transaction. This will be either `POSTED` or `PENDING`. |
| `top_level_category_guid` | String | The unique identifier for the parent category assigned to this transaction's category. Defined by MX. |
| `transacted_at` | Long | The date and time the transaction took place. |
| `transacted_on` | String | The date the transaction took place. |
| `type` | String | The type of transaction. This will be either `CREDIT` or `DEBIT`. |
| `updated_at` | Long | The date and time the transaction was last updated. |
| `user_guid` | String | The unique identifier for the user associated with the transaction. Defined by MX. |
| `user_id` | String | The unique partner-defined identifier for the `user` associated with the `transaction`. |
## Users
A user represents an end-user accessing the MX Platform API via your application, be it a mobile app, web app, desktop app, etc.
Daily files represent changes resulting the following MX solutions:
* Atrium API
* Batch API
* MDX Real Time
* Platform API
| Field | Data Type | Definition |
| :------------------ | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `birthdate` | String | The birthdate of end user. |
| `birthday` | String | An alias for the `birthdate` field. |
| `created_at` | Long | The date and time the user was created. |
| `email` | String | The end user's email address. |
| `email_is_verified` | Boolean | This indicates whether the end user has verified their email. |
| `first_name` | String | The first name of the end user. |
| `gender` | String | The gender of the end user. Returns either `MALE`, `FEMALE` or `null`. |
| `guid` | String | The unique identifier for the user. Defined by MX. |
| `id` | String | A unique, partner-defined, enforced identifier for the user. |
| `is_disabled` | Boolean | This indicates whether the user has been disabled through the API. |
| `last_name` | String | The last name of the end user. |
| `logged_in_at` | Long | The date and time the end user last logged in. |
| `metadata` | String | Additional information a partner can store on the user. |
| `phone` | String | The phone number of the end user. |
| `phone_is_verified` | Boolean | this indicates whether the end user has verified their phone number. |
| `postal_code` | String | An alias for the `zip_code` field. |
| `revision` | Long | The revision number of the user record. |
| `updated_at` | Long | The date and time the user was last updated. |
| `zip_code` | String | The postal code of the user. Postal codes from the following countries are supported: Canada, Indonesia, Japan, Malaysia, Philippines, South Korea, Thailand, United States, Vietnam. |
# Discovered Accounts
Source: https://docs.mx.com/api-reference/more-apis/reporting/data-specifications/discovered-accounts
Data field specifications for the Discovered Accounts and Discovered Transactions resources.
## Discovered Accounts Fields
| Field | Data Type | Definition |
| :------------------------------- | :-------- | :----------------------------------------------------------------------------------------------------------------- |
| `account_guid` | String | The unique identifier that links the discovered account to an associated account record. Defined by MX. |
| `client_guid` | String | The unique identifier for the client associated with the discovered account. Defined by MX. |
| `created_at` | Long | The date and time at which the discovered account was created. |
| `deleted_at` | Long | The date and time at which the discovered account was deleted. |
| `guid` | String | The unique identifier for the discovered account. Defined by MX. |
| `has_been_aggregated` | Boolean | This indicates whether the discovered account has been aggregated at some point by MX systems. |
| `is_deleted` | Boolean | This indicates whether the discovered account has been deleted on MX systems. |
| `most_recent_transaction_amount` | Double | The amount of the most recent known transaction for the discovered account. |
| `most_recent_transaction_date` | Long | The date and time of the most recent known transaction for the discovered account. |
| `most_recent_transaction_guid` | String | The unique identifier for the most recent known transaction associated with the discovered account. Defined by MX. |
| `name` | String | The name of the discovered account. |
| `organization_guid` | String | The unique identifier for the organization associated with the discovered account. Defined by MX. |
| `potentially_carries_a_balance` | Boolean | This indicates that the discovered account may carry a balance, based on the information available to MX. |
| `sub_type` | String | The discovered account's subtype, e.g., `PLAN_401_K`, `MONEY_MARKET`, or `HOME_EQUITY`. |
| `type` | String | The general or parent type of the discovered account. |
| `updated_at` | Long | The date and time the account was last updated. |
| `user_guid` | String | The unique identifier for the user associated with the discovered account. Defined by MX. |
| `user_id` | String | The unique, partner-defined identifier for the user associated with the discovered account. |
## Discovered Transactions
| Field | Data Type | Definition |
| :--------------------------- | :-------- | :---------------------------------------------------------------------------------------------------------------------------------- |
| `amount` | Double | The amount of the discovered transaction. |
| `created_at` | Long | The date and time at which the discovered transaction was created. |
| `date` | Long | The date on which the discovered transaction occurred, given in unix time. |
| `discovered_account_guid` | String | The unique identifier for the discovered account associated with the discovered transaction. Defined by MX. |
| `discovered_account_subtype` | String | The subtype of the discovered account associated with discovered transaction, e.g., `PLAN_401_K`, `MONEY_MARKET`, or `HOME_EQUITY`. |
| `discovered_account_type` | String | The general or parent type of the discovered account associated with the discovered transaction. |
| `guid` | String | The unique identifier for the discovered transaction. Defined by MX. |
| `has_been_aggregated` | Boolean | Whether the discovered account has been aggregated or is held at the same institution. |
| `id` | String | The unique, partner-defined identifier for the discovered transaction. |
| `organization_guid` | String | The unique identifier for the organization associated with the discovered transaction. Defined by MX. |
| `posted_at` | Long | The date and time at which the transaction was marked as posted. |
| `transacted_at` | Long | The date and time at which the transaction occurred. |
| `updated_at` | Long | The date and time at which the transaction was last updated. |
| `user_guid` | String | The unique identifier for the user associated with the discovered transaction. Defined by MX. |
| `user_id` | String | The unique, partner-defined identifier for the user associated with the discovered transaction. |
# User Communications
Source: https://docs.mx.com/api-reference/more-apis/reporting/data-specifications/user-communications
User communication profiles are related to MX's Personal Finance Management widgets.
**User Communication Profile Fields**
| Field | Data Type | Definition |
| :-------------------------------------------- | :-------- | :------------------------------------------------------------------------------------------------ |
| `created_at` | Long | The date and time the user communications profile was created. |
| `guid` | String | The unique identifier for the user communications profile. Defined by MX. |
| `opted_out_of_all_notifications` | Boolean | This indicates whether the user has opted out of all notifications. Defaults to `false`. |
| `opted_out_of_all_notifications_updated_at` | Long | The date and time this user opted out of all notifications. |
| `opted_out_of_email_notifications` | Boolean | This indicates whether the user has opted out of email notifications. Defaults to `false`. |
| `opted_out_of_email_notifications_updated_at` | Long | The date and time this user opted out of email notifications. |
| `opted_out_of_push_notifications` | Boolean | This indicates whether the user has opted out of push notifications. Defaults to `true`. |
| `opted_out_of_push_notifications_updated_at` | Long | The date and time this user opted out of push notifications. |
| `opted_out_of_sms_notifications` | Boolean | This indicates whether the user has opted out of SMS notifications. Defaults to `false`. |
| `opted_out_of_sms_notifications_updated_at` | Long | The date and time this user opted out of SMS notifications. |
| `user_guid` | String | The unique identifier for the user associated with the user communication profile. Defined by MX. |
# Reporting API Overview
Source: https://docs.mx.com/api-reference/more-apis/reporting/index
The Reporting API enables you to track changes for all your users' data held on the MX platform without having to read this data individually for each user. It programmatically pulls MX's data into your system on a per-client basis and provides daily change files that indicate how objects have changed throughout the day. This data is requested by providing the date, resource, and action.
All API responses are in an Avro file format. More information about Avro can be found on the official Avro documentation page. Avro files rely on schemas. When Avro data is read, the schema used when writing it is always present. This permits each datum to be written with no per-value overheads, making serialization both fast and small. This also facilitates use with dynamic scripting languages since data, together with its schema, is fully self-describing.
The resources available and the fields included for each are listed. We have included a list of what fields are recorded and written into these log files, but we may add additional fields at any time. See the [schema evolution](/api-reference/more-apis/reporting/requirements#schema-evolution) section for more information.
If a particular resource has no data for a given day, an Avro file with headers but no body is generated and made available for retrieval.
# Download Daily Files
Source: https://docs.mx.com/api-reference/more-apis/reporting/reference/daily-files/download-daily-files
GET https://int-logs.moneydesktop.com/download/{client_id}/{date}/{resource_type}/{action}
This endpoint downloads a daily reporting file for a specific resource, date, and action.
The Reporting API provides reports of any create, update or delete events that took place on a particular date for each available `resource_type`. There is a specific endpoint for each `action` that took place for the resource on that specific day.
If a particular resource has no data for a given day, a file with headers but no body is generated and made available for retrieval.
Files are generated daily at midnight (UTC), and you can begin to request them at that time; however, it can take some time for the files to finish being assembled; we recommend waiting until 01:00 UTC before requesting them.
Files are available for seven days after being generated. We recommend that you pull files daily as soon as they become available even if they are not able to process the data at that time. We don't have the ability to regenerate files once they are gone.
If a file being requested is no longer available, a `410 Gone` status is returned.
## Path Parameters
Your client ID.
The date of the file being requested.
This must be one of the following resource types: `accounts`, `analytics_events`, `analytics_screenviews`, `analytics_timed_events`, `beat`, `beat_feedback`, `budgets`, `categories`, `devices`, `discovered_accounts`, `discovered_transactions`, `goals`, `holdings`, `members`, `notification_profiles`, `tags`, `taggings`, `transactions`, `users`, `user_communication_profiles`.
This must be one of: `created`, `updated`, `deleted`.
```shell Request theme={null}
# If using curl, the output response can be saved
# to a file by adding the `-o` flag and
# specifying the download path and file name
# (e.g. `-o 20170626-transactions-created.avro`).
curl -X GET https://int-logs.moneydesktop.com/download/{client_id}/2017-06-26/transactions/created -o 20170626-transactions-created.avro \
-H 'Accept: application/vnd.mx.logs.v1+avro' \
-H 'MD-API-KEY: {api_key}'
```
# List Daily Files
Source: https://docs.mx.com/api-reference/more-apis/reporting/reference/daily-files/list-daily-files
GET https://int-logs.moneydesktop.com/download/{client_id}
This endpoint returns a list of daily files.
Use this endpoint to get a list of available daily files in JSON format. This endpoint should generally be used before downloading a file in order to check the file size and [determine whether byte serving is necessary](/api-reference/more-apis/reporting/using-the-api#byte-serving-for-large-files).
## Path Parameters
Your client ID.
## Response Fields
| Field | Type | Description |
| :------------------ | :------ | :------------------------------------------------------------------------------------------------------------------ |
| `checksum` | string | A checksum of the file which can be used to ensure the downloaded file contains what was expected. |
| `event_type` | string | This will be one of `CREATED`, `UPDATED`, or `DELETED`. |
| `file_size` | integer | The size of the file in bytes. |
| `guid` | string | The unique identifier for the daily file. Defined by MX. |
| `name` | string | The file name. |
| `number_of_records` | integer | The number of records in the daily file. |
| `resource_type` | string | The resource whose change records are contained in the file, for example, `ACCOUNTS`, `USERS`, `TRANSACTIONS`, etc. |
```shell Request theme={null}
curl -X GET https://int-logs.moneydesktop.com/download/{client_id} \
-H 'Accept: application/vnd.mx.logs.v1+json' \
-H 'MD-API-KEY: {api_key}'
```
```json 200 theme={null}
{
"daily_snapshot_files": [
{
"checksum": "939a313512aaf97b88732af822e3e10565ff038bdb18ed0e7d9c0a1e83601cb1",
"event_type": "CREATED",
"file_size": 3834,
"guid": "SLF-d7c8e264-4022-43bb-a0b8-515f2a21d7bf",
"name": "CLT-942128c7-62fd-42f1-a46f-86fe1bb1c330.2023-11-08.accounts.created",
"number_of_records": 0,
"resource_type": "ACCOUNTS"
},
{
"checksum": "6a9c444d27a64a2dac662573b4725f7a153094af6f6ff90f81f45a95f638a058",
"event_type": "UPDATED",
"file_size": 3834,
"guid": "SLF-95212615-b5d5-4516-b3e1-950ebf1c48ba",
"name": "CLT-942128c7-62fd-42f1-a46f-86fe1bb1c330.2023-11-08.accounts.updated",
"number_of_records": 0,
"resource_type": "ACCOUNTS"
}
]
}
```
# Download Snapshots
Source: https://docs.mx.com/api-reference/more-apis/reporting/reference/snapshots/download-snapshots
GET https://int-logs.moneydesktop.com/snapshot/{client_id}/{snapshot_guid}/{file_name}
The URLs returned in the list snapshot file URLs endpoint should be used to download each file individually.
## Path Parameters
Your client ID.
The unique identifier for the snapshot.
The name of the snapshot file to download.
```shell Request theme={null}
# If using curl, the output response can be
# saved to a file by adding the flag option
# `-o` and specifying the download path and
# file name (e.g. `-o transactions-snapshot.avro.gz`).
curl -X GET https://int-logs.moneydesktop.com/snapshot/ABCBank/CSS-2f5fcc32-2505-41c2-b04e-11a15c4dc37/transactions_cf3586e2a0eeb0049f7074926076acfe -o filename.avro.gz \
-H 'Accept: application/vnd.mx.logs.v1+avro' \
-H 'MD-API-KEY: {api_key}'
```
# List Snapshot File URLs
Source: https://docs.mx.com/api-reference/more-apis/reporting/reference/snapshots/list-snapshot-file-urls
GET https://int-logs.moneydesktop.com/snapshot/{client_id}/{snapshot_guid}/files
This endpoint returns a JSON array of snapshot file URLs.
## Path Parameters
Your client ID.
The unique identifier for the snapshot.
```shell Request theme={null}
# In this request, note the use of the
# `.json` URL extension and the accept
# header `application/vnd.mx.logs.v1+json`.
curl -i -X GET https://int-logs.moneydesktop.com/snapshot/{client_id}/{snapshot_guid}/files.json \
-H 'Accept: application/vnd.mx.logs.v1+json' \
-H 'MD-API-KEY: {api_key}'
```
# API Requirements
Source: https://docs.mx.com/api-reference/more-apis/reporting/requirements
Accept headers, authentication, base URLs, and schema evolution for the Reporting API.
## Accept Header
Requests require an Accept header to specify the version and the encoding of the desired response body. This is the value to the right unless otherwise specified.
```text theme={null}
Accept: application/vnd.mx.logs.v1+avro
```
## Authentication
Each request is authenticated with an API key that is specific to one MX environment. We'll provide you with separate API keys for the MX Integration and Production environments.
The API key is sent with the request in an `MD-API-KEY` header, as shown to the right.
The Reporting API is enabled on a per-client basis. Requests made for a client that is not enabled receive a `404 NOT FOUND` error.
```text theme={null}
MD-API-KEY: YOUR_ENVIRONMENT_SPECIFIC_API_KEY
```
## Base URL
All URL endpoints in the Reporting API have a base URL that depends on the environment being addressed.
**Integration Environment - used for initial integration testing**
```text theme={null}
https://int-logs.moneydesktop.com/download/:client_id
```
**Production Environment**
```text theme={null}
https://logs.moneydesktop.com/download/:client_id
```
## Data Availability and Null Values
Files are generated daily and are available for up to seven days after generation. It is your responsibility to download them before they are no longer available.
The Reporting API does not provide a full snapshot of historical data. If historical data is desired, MX can generate a [one-time data snapshot](/api-reference/more-apis/reporting/snapshots) for an additional cost.
Be aware that aggregation is not guaranteed to return all relevant information or even every data point on a given resource. For instance, aggregation may return the balance of an account, but return a null value for the apr and apy fields. This is to be expected in all resources and all aggregations.
## Date and Time Formats
Dates are represented in the following forms:
* Integer datetime fields that end with `_at` use Unix time format. Unix time is always in UTC.
* String date fields that end with `_on` use ISO 8601 format without a time component.
* String date fields which end in `date` or are otherwise unspecified are given in ISO 8601 format without a time component.
**Examples**
```text theme={null}
"1970-01-01" # January 1st 1970
90018780 # November 7th 1972 @ 2:13pm UTC
```
## Enabling Resource Groups
Reporting files come in four broad resource groups: Base, Analytics Events, Discovered Accounts, and User Communication. Enabling a group allows you to download daily files in that group. Base files are enabled by default. Contact MX to enable the others.
| Group | Resources |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Base | accounts
beat
beat\_feedback
budgets
categories
devices
goals
holdings
members
notification\_profiles
tags
taggings
transactions
users
|
| Analytics Events | analytics\_events
analytics\_pageviews
analytics\_screenviews
analytics\_timed\_events
|
| Discovered Accounts | discovered\_accounts
discovered\_transactions |
| User Communication | user\_communication\_profiles |
## Errors
The Reporting API uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, etc.) and codes in the 5xx range indicate an error with MX's servers.
Sometimes simply returning the HTTP status code is not enough to indicate what went wrong. So some endpoints may respond with a body containing more information about the error.
Error codes and messages are for logging and informational purposes only. Error messages may change from time to time.
**Error Message Format Example**
```text theme={null}
code
Error message.
```
| HTTP Status Code | Definition |
| :---------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200 OK` | Everything worked as expected. |
| `403 Forbidden` | The IP address doesn't match the API key provided. |
| `404 Not Found` | The requested item doesn't exist. Either an id on the URL does not exist, the URL format is invalid, or a resource is requested that is not enabled for that client. |
| `410 Gone` | The file is gone and no longer available. |
| `500`, `502`, `503`, `504`: server errors | Something went wrong on MX's end. |
## IP Filtering and Whitelisting
All requests sent to the Reporting API are filtered by IP address. Requests must be made from a whitelisted IP address. Requests made from invalid IP addresses will receive a `403 FORBIDDEN` error.
## Schema Evolution
MX may add additional fields to the writer schemas included in the response files at any time. This is not considered a breaking change to the Avro files. When new fields are added, this is done with backwards compatibility in mind and the order of the fields may change. This follows the standard set forth by [Avro's schema resolution documentation](https://avro.apache.org/docs/1.8.1/spec.html#Schema+Resolution).
A reader of Avro data, whether from an RPC or a file, can always parse that data because its schema is provided. But that schema may not be exactly the schema that was expected. For example, if the data was written with a different version of the software than it's read, then records may have had fields added or removed.
We call the schema used to write the data the writer's schema, and the schema that the application expects the reader's schema. Differences between these should be resolved according to the details outlined in the [schema resolution section of Avro's official documentation](https://avro.apache.org/docs/1.8.1/spec.html#Schema+Resolution).
To support some use cases, MX does include default values for all our fields.
## Security
Requests must use TLS 1.2 (or higher) with known secure ciphers. See [Authentication & Security](/api-reference/platform-api/overview/#authentication-and-security) for our Platform API for more information.
## Object history and revision numbers
Data returned in the Avro files represents a history of changes made to objects on the MX platform throughout the day. This means it is possible for a single daily file to have multiple entries for the same object. In order to enable partners to know the sequence of events, the fields `revision` and `updated_at` are included on each resource entry. Use the entry with the latest `revision` to ensure that the latest version of the object record is consumed.
## Versioning and Potentially Breaking Changes
We strive to make API changes backwards-compatible. When we make breaking changes, we increment a version. Because of this, it is best to specify the version of the API with each request. Versions are passed as part of the request's `Accept` header. The current version is `v1`.
Requests that don't specify a version get the latest representation of resources, and unsupported endpoints simply return a `404 NOT FOUND`.
### Deprecating Fields and Resources
We sometimes deprecate a field in an object. This is done when a new field is superior to the deprecated one. It is also possible that an entire resource may be deprecated if a new resource is introduced to take its place. A note in the documentation will explain each item that is deprecated, with a recommendation of what to use in its place.
New integrations should avoid using deprecated items. We'll maintain the deprecated fields and resources in the current version to support existing integrations, but existing integrations should also be updated to use the replacement fields and resources. Deprecated items aren't present in the next version of the API.
### Enhancements within the current version
We continually makes enhancements to our APIs. Expect these enhancements to occur regularly. Breaking changes are reserved for a new version, but non-breaking additions are regularly made in the current version. These non-breaking changes include:
* New fields added to existing objects (e.g., adding `currency_code` to the `accounts` object).
* New resources (e.g., adding `goals` to the list of available resources).
A new field in an object does not affect any existing integrations since nothing is being removed. You need to ensure your system can process or ignore new fields automatically. Do not rely on a fixed data model in any object. The order in which the fields occur in the file may also vary. The processing of the file should account for these possibilities.
If you're consuming the Avro file directly, parse the included schema each time a file is processed. The desired fields can then be extracted from the data. The process can ignore other fields so that the addition of a new field does not affect the processing of the file.
If you convert the Avro file to a CSV format, ensure a header row is included with such conversions. Parse the header row each time the CSV file is consumed to ensure the order of the fields is read, the desired fields are extracted properly, and any additional fields are ignored.
### Enhancements that require advanced notice or a new version
The following changes are breaking changes so they are made in a new version of the API or with advanced notice.
* Removing a field from an object.
* Changing the format of a field, or the contents it returns.
* Removing a resource.
* Adding a new enumerated value to a string that returns a fixed set of values (e.g., transaction status).
It is sometimes necessary to add new values to fields which return enumerated values. Examples include `account_subtype` in the accounts model and `field_type` in the credentials model. Allow for the addition of new enumerated values. We will notify you in advance when such additions are anticipated.
# Sample Files
Source: https://docs.mx.com/api-reference/more-apis/reporting/sample-files
Sample Avro files generated from the Reporting API.
Below are some sample Avro files generated from the Reporting API.
* Users:
* [users.created.avro](/static/users.created.avro)
* [users.updated.avro](/static/users.updated.avro)
* [users.deleted.avro](/static/users.deleted.avro)
* Members:
* [members.created.avro](/static/members.created.avro)
* [members.deleted.avro](/static/members.deleted.avro)
* [members.updated.avro](/static/members.updated.avro)
* Accounts:
* [accounts.created.avro](/static/accounts.created.avro)
* [accounts.deleted.avro](/static/accounts.deleted.avro)
* [accounts.updated.avro](/static/accounts.updated.avro)
* Transactions:
* [transactions.created.avro](/static/transactions.created.avro)
* [transactions.deleted.avro](/static/transactions.deleted.avro)
* [transactions.updated.avro](/static/transactions.updated.avro)
* Budgets:
* [budgets.created.avro](/static/budgets.created.avro)
* Goals:
* [goals.created.avro](/static/goals.created.avro)
# SFTP Delivery
Source: https://docs.mx.com/api-reference/more-apis/reporting/sftp-delivery
Optionally have MX deliver your daily reporting files to an SFTP server.
MX has halted SFTP enablement. New integrations should use the API endpoints as outlined in [Using The Reporting API](/api-reference/more-apis/reporting/using-the-api). Current integrations will remain supported.
You may optionally have us deliver your daily reporting files to an SFTP (Secure File Transfer Protocol) server rather than retrieving them through the API endpoints. In order to do so, there are certain requirements.
* You must provide an SFTP server.
* You must provide a public GPG key.
* SFTP server must use a non-standard port, i.e., not port 22
* You must provide a username and password to MX for authentication to the SFTP server.
* We need to whitelist any IP addresses for your SFTP server.
If a particular resource has no data for a given day, an Avro file with headers but no body is generated and delivered.
When using an SFTP, if your IP addresses ever change, you will need to contact MX to have them updated or you will not receive the daily avro files.
## Daily Files Manifest
Using SFTP also sends an encrypted manifest file in CSV format containing information about each daily file being delivered. This includes the resource type, the event type (created, updated, etc.), the date, number of records, and file size. Each row in the manifest file represents one daily file in the bunch.
Each manifest file is named according to the following format: `client_guid.snapshot_date-manifest.csv.pgp`.
Manifest files are encrypted using the same public key as the daily files.
### Manifest File Fields
| Field name | Data type | Definition |
| :------------------ | :-------- | :------------------------------------------------------------------------------------------ |
| `Checksum` | String | The SHA-256 hash value of the daily file. |
| `EffectiveDate` | String | The date for which the daily file was generated, given in ISO 8601 format with a timestamp. |
| `EncryptedFileSize` | Integer | The size of the encrypted daily file in bytes. |
| `EventType` | String | The action for the given resource, i.e., created, updated, deleted. |
| `FileName` | String | The name of the daily file without file extension. |
| `FileSize` | Integer | The size of the daily file in bytes. |
| `RecordCount` | Integer | The number of records in the daily file. |
| `ResourceType` | String | The type of resource for the daily file, e.g. accounts, analytics events, budgets, etc. |
### Resource Types
New resource types may be added at any time.
* `ACCOUNTS`
* `ANALYTICS_EVENTS`
* `ANALYTICS_PAGEVIEWS`
* `ANALYTICS_SCREENVIEWS`
* `ANALYTICS_TIMED_EVENTS`
* `BEAT_FEEDBACK`
* `BEAT`
* `BUDGETS`
* `CATEGORIES`
* `DEVICES`
* `DISCOVERED_ACCOUNTS`
* `DISCOVERED_TRANSACTIONS`
* `GOALS`
* `HOLDINGS`
* `MEMBERS`
* `NOTIFICATION_PROFILES`
* `TAGGINGS`
* `TAGS`
* `TRANSACTIONS`
* `USER_COMMUNICATION_PROFILES`
* `USERS`
### Event types
* `CREATED`
* `DELETED`
* `UPDATED`
> Example manifest file contents
```text theme={null}
ResourceType,EventType,RecordCount,EffectiveDate,FileSize,EncryptedFileSize,Checksum,FileName
USERS,DELETED,0,2020-06-14,1274,1198,8f3bd95d1c7dce50bee215dd8271bdc9b3409ef2cfb057cc7617f91686d28091,CLT-0858efd1-2d2e-6a5d-f2b5-c7dad42ef184.2020-06-14.users.deleted
USERS,UPDATED,0,2020-06-14,1274,1187,f3318a7071074bd0cb70bc4f0ce5d51cca0cc5bdfdc8d4b1054446f6fa6dbc98,CLT-0858efd1-2d2e-6a5d-f2b5-c7dad42ef184.2020-06-14.users.updated
TRANSACTIONS,DELETED,0,2020-06-14,3107,3057,5dc55906519b3936ab9dbc5857db8605cf71f875085d9b359e654d48042ce691,CLT-0858efd1-2d2e-6a5d-f2b5-c7dad42ef184.2020-06-14.transactions.deleted
```
## Providing a Public PGP Key
To enable the Reporting API, you must provide a public PGP key in PEM format. MX uses this key to encrypt the files you will receiving.
PGP (Pretty Good Privacy) is an encryption program that provides cryptographic privacy and authentication for data communication. PGP is used for signing, encrypting, and decrypting texts, e-mails, files, directories, and to increase the security of e-mail communications.
If you are unfamiliar with using PGP keys, reach out to your development and IT teams or ask your MX representative or our support team for help.
There are many tools available for generating PGP keys, including the commonly used GnuPG. GnuPG is a complete and free implementation of the OpenPGP standard.
# Snapshots
Source: https://docs.mx.com/api-reference/more-apis/reporting/snapshots
The Reporting API does not provide a full snapshot of historical data, but a one-time data snapshot can be generated for an additional cost.
The Reporting API does not provide a full snapshot of historical data. However, if a full dataset is desired, we can generate a one-time data snapshot for an additional cost.
We must generate the snapshot before it can be downloaded. This process can take several days depending on the amount of data on the platform. In order to keep file sizes reasonable for downloading, multiple files may be generated for each resource. Once snapshots have been generated, we provide you with a GUID which can be used to download the snapshot files.
The response is in an Avro file format with `gzip` compression. Files can be saved with `.gz` extension and then unpacked using gunzip.
More information about Avro can be found on the [official Avro documentation](http://avro.apache.org/) page. Avro files rely on schemas. When Avro data is read, the schema used when writing it is always present. This permits each datum to be written with no per-value overheads, making serialization both fast and small. This also facilitates use with dynamic scripting languages, since data, together with its schema, is fully self-describing.
We retain snapshot files long enough for you to retrieve them; however, these files do not remain available long-term. Once you have verified that the files have been retrieved, we remove the files from storage. It is your responsibility to download and retain the files in their own system.
We generate snapshots for the following resources:
* Accounts
* Devices
* Goals
* Members
* Notification profiles
* Transactions
* Users
# Using the Reporting API
Source: https://docs.mx.com/api-reference/more-apis/reporting/using-the-api
Best practices for consuming and staging Reporting API data in your system.
The MX Reporting API enables you to track changes for all data held on the MX platform for your clients without having to read this data individually for each user. This is done by providing daily change files which indicate how objects have changed throughout the day.
This guide provides best practices on consuming and staging the data in your system.
## Consuming Daily Reporting Files
Objects on the MX platform are organized in a hierarchy. This means that your systems must consume daily reporting files in a particular order so that the objects are created, updated, and deleted in the proper order in your data store/warehouse.
First, you must consume all files with **create** actions in this order:
1. Users
2. Members
3. Accounts
4. Transactions
5. Holdings
6. Categories
7. Tags
8. Taggings
9. Goals
10. Budgets
11. Notification Profiles
12. Beat
13. Beat Feedback
14. Devices
15. Analytics Events
16. Analytics Page Views
17. Analytics Screen Views
18. Analytics Timed Events
19. Insights
Second, you must consume all **update** files in the **same order** as above.
Third, you must consume all **delete** files in the **reverse order**. This ensures transactions are deleted on your systems before the account they belong to is deleted, and so forth.
## Generating Sample Data for the Integrations Environment
Files in the Reporting API are generated from system events which represent user activity and aggregated account and transactional data. This presents a challenge in the integrations environment because there are no users creating activity on the system.
If you need a more robust set of test data, add your own by creating internal test users that add accounts and use the system for a few days to generate log events.
The following steps describe this process:
1. Create test users in your integration client using whichever MX API you use for this purpose, e.g., the Platform API or MDX v5 Real Time.
2. Generate `master_widget` URLs for those users with the appropriate API, e.g., the Platform API the the SSO API.
3. Copy the URL from the `master_widget` response and paste it in a browser window.
4. Have your test user(s) use the system. Some recommended actions are:
* Add savings, checking, loans, and investment accounts;
* Categorize transactions;
* Add tags to transactions;
* Create custom categories;
* Create and update goals and budgets;
5. The next day, new files containing the event logs of the actions performed will become available to download via the [*download daily files*](/api-reference/more-apis/reporting/reference/daily-files/download-daily-files).
## Byte Serving for Large Files
Avro files can become very large (multiple gigabytes) which can result in partial downloads. This can be resolved by using byte serving, which allows you to request data in a set of ranged chunks that can later be assembled into the full raw Avro file response.
### Step 1: Check the Size of Available Files
Use the [list daily files](/api-reference/more-apis/reporting/reference/daily-files/list-daily-files) endpoint to get a list of all the files that are available from the last 7 days. This list will include the size of each file. All files larger than 1GB should be downloaded using byte serving.
```shell theme={null}
curl -X GET https://int-logs.moneydesktop.com/download/{client_id} \
-H 'Accept: application/vnd.mx.logs.v1+json' \
-H 'MD-API-KEY: {api_key}'
```
### Step 2: Download File Segments Using the curl Command
The command line tool `curl` can be used to download HTTP ranges by specifying the `-r` or `--range` option. This example shows a scenario where the Avro file is larger than 1GB. The first `curl` command specifies the range for the first gigabyte (`0-1073741823`) and the second command specifies the range for the rest of the data (`1073741824-`).
```shell theme={null}
# Download the first part of the file
curl -X GET -r 0-1073741823 https://int-logs.moneydesktop.com/download/{client_id}/2019-10-07/transactions/created -o 20191007-transactions-created.avro.part1 \
-H 'Accept: application/vnd.mx.logs.v1+avro' \
-H 'MD-API-KEY: {api_key}'
# Download the second part of the file
curl -X GET -r 1073741824- https://int-logs.moneydesktop.com/download/{client_id}/2019-10-07/transactions/created -o 20191007-transactions-created.avro.part2 \
-H 'Accept: application/vnd.mx.logs.v1+avro' \
-H 'MD-API-KEY: {api_key}'
```
### Step 3: Assemble the Segments Back into a Single File
The next step is to assemble the two file partials into a single file. The `cat` command `cat input1 input2 > output` can be used for this purpose. In this case `input1` and `input2` are the file segments downloaded in the previous step. The output file will be a complete Avro file.
```shell theme={null}
cat 20191007-transactions-created.avro.part1 20191007-transactions-created.avro.part2 > 20191007-transactions-created.avro
```
## Parsing Avro Files
Avro files are built in a way that they can be parsed and serialized easily into other formats. [Avro's documentation](http://avro.apache.org/docs/current/index.html) provides guidance on parsing these files using different methods.
Decimal numbers may be represented using exponential notation. Your implementation should accept decimals in exponential notation to avoid conversion errors.
Below we show how to read an Avro file into a Ruby script and parse the output to JSON and CSV. There is an Avro gem available from rubygems.org which we use to parse the Avro file.
**Avro to JSON**
```text theme={null}
require 'avro'
require 'json'
json_array = []
avro_file_path = "some_avro_file.avro"
Avro::DataFile.open(avro_file_path, "r") do |reader|
reader.each do |row|
json_array << row.to_json
end
end
```
**Avro to CSV**
```text theme={null}
require 'avro'
require 'csv'
result_file_path = "some_csv_file.csv"
avro_file_path = "some_avro_file.avro"
Avro::DataFile.open(avro_file_path, "r") do |reader|
CSV.open(result_file_path, "a+") do |csv|
reader.each_with_index do |row, index|
csv << row.keys if index == 0
csv << row.values
end
end
end
```
# API Requirements
Source: https://docs.mx.com/api-reference/sso/v3/api-requirements
## Authentication
### API Key
When accessing the SSO API, each request is authenticated using an environment specific API key that was issued to you during your initial integration. API keys are passed in a MD-API-Key request header as follows: `MD-API-Key: YOUR_ENVIRONMENT_SPECIFIC_API_KEY`
If a request is made with an invalid API key, or an API key from a different environment, a 401 (unauthorized) will be returned.
### IP Filtering
Requests to the SSO API are also filtered by IP address. All IP addresses where API requests originate must be whitelisted. Requests made from invalid IP addresses will receive a 403 (forbidden).
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.
## Base URL
All URL endpoints in the MX SSO API have a base URL. The base URL will depend on the environment being addressed:
* Production Server: `https://sso.moneydesktop.com/{client_id}`
* Integration Server (for initial integration testing): `https://int-sso.moneydesktop.com/{client_id}`
The `:client_id` identifies the client whose users are being managed and corresponds to the unique identifier setup with MX during that client's integration. See MX Architecture In the Getting Started Overview for information about clients in the MX architecture.
## HTTP Status Codes
The SSO API uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, etc.), and codes in the 5xx range indicate an error with MX's servers.
Error codes and messages are for logging and for informational purposes only and may change from time to time. Do not check for specific codes or messages as this may break your integration. The http status response codes are sufficient for an integration workflow and processing of the error response body is not needed.
Sometimes simply returning the HTTP status code is not enough to indicate what went wrong. To compensate for this, endpoints may respond with a body containing more information about the error:
| Status Code | Description |
| :--------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `200 OK` | Everything worked as expected. |
| `204 No Content` | Everything worked, but no content is returned. Typically returned from `DELETE` requests. |
| `400 Bad Request` | Often missing a required parameter. |
| `401 Unauthorized` | No valid API key provided. |
| `403 Forbidden` | The IP address doesn't match the API key provided. |
| `404 Not Found` | The requested item doesn't exist. Either an id on the URL does not exist or the URL format is invalid. This error will also be returned when a resource is requested that is not enabled for that user. |
| `429 Too Many Requests` | This error is triggered when exceeding the maximum number of concurrent connections or rate limit. See details below. |
| `500, 502, 503, 504 Server errors` | Something went wrong on MX's end. |
### 429 Too Many Requests
This error is triggered when the maximum number of concurrent connections has been exceeded or the rate limit for requests per second (RPS) has been surpassed. Requests receiving a 429 status code should be retried once the rate limit window has expired.
To prevent this error, decrease the number of concurrent connections or the number of requests per second. Rate limiting is applied per client with the following thresholds:
* GET: 2000/RPS
* POST: 750/RPS
* PUT: 750/RPS
* DELETE: 150/RPS
Individual features may implement specific rate limit overrides.
## Headers
### Accept Header
An Accept header is required for all requests. It contains the appropriate content type and version information.
Use either:
* `Accept: application/vnd.moneydesktop.sso.v3+xml`
* `Accept: application/vnd.moneydesktop.sso.v3+json`
### Content-Type Header
`POST` requests require a Content-Type header to specify the format of the request body.
Use either:
* `Content-Type: application/vnd.moneydesktop.sso.v3+xml`
* `Content-Type: application/vnd.moneydesktop.sso.v3+json`
## Resources
### Users
A User is a person that can use MX. A partner will create a User on the MX Platform using MDX Real Time to allow that person to use MX's products.
### Widget URLs
Widget URLs are used to authenticate users to the MoneyMap components and to open the widget view. URLs are single-use and expire 10 minutes after being issued. A new URL must be obtained each time a user is authenticated or whenever the widget needs to be reloaded.
### API Tokens
API tokens are used to authenticate users to MX's Nexus API. API tokens are single-use, so a new one should be retrieved each time a user is authenticated. API tokens expire 10 minutes after being issued.
## Response Format
A URL extension should be used to specify the desired response format. XML and JSON are supported:
* `https://sso.moneydesktop.com/{client_id}/users/{user_id}.xml`
* `https://sso.moneydesktop.com/{client_id}/users/{user_id}.json`
If not specified, XML will be returned.
## Security
Requests must use TLS 1.2 (or higher) with known secure ciphers. See MX Authentication for more information.
## Versioning
We strive to make changes to the API backwards-compatible. When do we make backwards-incompatible changes to the API, we increment the version. Because of this, it's best to specify the version of the API with each request. Versions are passed as part of the request's Accept header as shown in the examples to follow.
Requests that don't specify a version will return a 404 error.
# Get API Token
Source: https://docs.mx.com/api-reference/sso/v3/reference/api-token/get-api-token
GET https://int-sso.moneydesktop.com/{client_id}/users/{id}/api_token
This endpoint returns an api_token to open a Nexus session.
This endpoint returns an `api_token` to open a Nexus session. The `api_token` is one-time use and expires in ten minutes. A fresh `api_token` must be requested each time a Nexus session is initiated.
The endpoint will return a 404 response if the client does not have access to Nexus enabled. Please work with your account representative to add this functionality to the client.
```shell Request theme={null}
curl -i https://int-sso.moneydesktop.com/{client_id}/users/{user_id}/api_token.xml \
-H "Accept: application/vnd.moneydesktop.sso.v3+xml" \
-H "MD-API-KEY: {api_key}"
```
```xml Response theme={null}
XXXXX
```
# Delete User Session
Source: https://docs.mx.com/api-reference/sso/v3/reference/users/delete-user-session
DELETE https://int-sso.moneydesktop.com/{client_id}/users/{id}/session
This endpoint closes all open sessions for a user.
```shell Request theme={null}
curl -i https://int-sso.moneydesktop.com/{client_id}/users/{user_id}/api_token.xml \
-H "Accept: application/vnd.moneydesktop.sso.v3+xml" \
-H "MD-API-KEY: {api_key}"
```
```xml 204 theme={null}
204 No content
```
# Configuration Options
Source: https://docs.mx.com/api-reference/sso/v3/reference/widget-urls/config-options
| Configuration Option | Description | Data Type | Widget |
| :--------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------- | :------------------------------------ |
| `is_mobile_webview` | Renders the widget in a mobile WebView. Executes URL updates in place of the JavaScript event postMessages. | Boolean | All |
| `language` (deprecated) | See the SSO language section for preferred settings. Currently, only U.S. English (en-us) and French (fr and fr-ca) are supported. Defaults to en-us. | String | All |
| `ui_message_version` | Use this to specify which version of postMessage events are triggered. All new implementations must include this option when getting any widget URL and must set it to version 4. Prior versions are deprecated and supported only for existing partners. | Integer | All |
| `client_redirect_url` | A URL that MX will redirect to at the end of OAuth with additional query parameters. Only available with `oauth_referral_source: "APP"` or `is_mobile_webview: true`. | String | Connect |
| `color_scheme` | Load the Connect widget in the specified `color_scheme`; options are `light` and `dark`. Defaults to `light`. | String | Connect |
| `connections_use_case_filter` | To use this parameter, you must also set `use_cases` in the same request. If `connections_use_case_filter` is set to `true`, the Connections Widget will show connections (members) with the `use_cases` you set. For example, if you set `connections_use_case_filter` to `true` and `use_cases` to `["PFM"]`, then only members containing `PFM` as one of its use cases will show in the widget. If you make the same request but set `use_cases` to `["PFM", "MONEY_MOVEMENT"]`, then members containing either use case will show in the widget. | Boolean | Connections |
| `current_institution_code` | Load the widget into the credential view for the specified institution. | String | Connect |
| `current_institution_guid` | Load the widget into the credential view for the specified institution. | String | Connect |
| `current_member_guid` | Load to a specific member that contains an error or requires MFA from the most recent job. Takes precedence over `current_institution_code`. | String | Connect |
| `deep_link_params.account_guid` | Used to filter the data shown in the widget by account. Contains an `account_guid` (string) optional param. | String | Legacy Spending Widget |
| `deep_link_params.date_range` | Used to filter the data shown in the widget by date range. Set the `date_range` using `start_date` (string) and `end_date` (string). | Object | Legacy Spending Widget |
| `deep_link_params.launch_integration` | Enables a direct deposit integration. Set the `launch_integration` (string) param to `direct-deposit`. | Object | Actionable Integration Widget |
| `deep_link_params.widget` | Opens the Master Widget a specific widget. Set the `widget` (string) param to `accounts`, `budgets`, `cash_flow`, `debts`, `finstrong`, `goals`, `insights`, `investments`, `networth`, `recurringtransactions`, `spending`, `transactions`, or `trends`. | Object | Master Widget |
| `disable_background_agg` | Set to true or false to explicitly set the value of `background_aggregation_is_disabled` for new members created through the Connect Widget | Boolean | Connect |
| `disable_institution_search` | When set to true, the institution search feature will be disabled and end users will not be able to navigate to it. Must be used with `current_institution_code`, `current_institution_guid`, or `current_member_guid`. | Boolean | Connect |
| `include_identity` | This determines whether account owner identification data (AOI, previously called "identity verification") aggregates after the data that's specified by the `mode` finishes aggregating.
Defaults to `false`. This can be set in either `aggregation` or `verification` mode.
Setting this to `true` will produce the following behaviors: - The widget will only search for and display institutions that support the data the `mode` (`aggregation` or `verification`) is aggregating and AOI.
- The member connected postMessage event will not be sent until both aggregations are complete.
| | |
| `include_transactions` | When set to false while creating or updating a member, transaction data will not be automatically aggregated. Future manual or background aggregations will not be affected. Defaults to `true`. | Boolean | Connect |
| `insight_guid` | Set this to the insight guid you want to appear at the top of the insights feed. | String | Pulse |
| `iso_country_code` | An array of strings that filters institutions in the widget by the specified country code. Acceptable codes include `US`, `CA`, and `MX` (Mexico). | Array | Connect |
| `microwidget_instance_id` | Set this to a unique value for each instance of the Micro Insights Widget. This lets us collect unique data for each instance of the widget. | String | Micro Insights Widget |
| `mode` | Loads the Connect Widget into the specified mode; options are verification and aggregation. Defaults to `aggregation`. | String | Connect |
| `oauth_referral_source` | Must be either `BROWSER` or `APP` depending on the implementation. Defaults to `BROWSER`. | String | Connect |
| `ui_message_webview_url_scheme` | Used in postMessages and OAuth redirects in WebViews. Defaults to `mx`. | String | Connect |
| `update_credentials` (not recommended) | Loads widget to the update credential view of a current member. This option is no longer recommended. Forcing a user to update credentials may make connection errors worse. Use `current_member_guid` by itself instead. | Boolean | Connect |
| `use_cases` | Associates a use case with any `members` the widget creates. Valid values are `PFM` and/or `MONEY_MOVEMENT`. For more info, see [Member Use Cases](/nexus/member-use-cases). | Array | Connect, Connections |
| `wait_for_full_aggregation` (deprecated) | This option is now ignored. Connect now behaves as if this was set to true and will wait until the member is done aggregating before completing. This change does not require anyone to update their integration and only affects the timing of the member connected post message. If you strongly feel like you need the old behavior, reach out to support. | Boolean | Connect |
| `hide_mark_as_duplicate` | Hides the "mark as duplicate" feature option in the widget. | Boolean | Connections |
| `hide_partner_managed_members` | Hides any "home" members that are managed by the partner. | Boolean | Connections |
| `selected_institution_guid` | Loads the widget to a specific selected institution. | String | Connections |
| `selected_member_guid` | Loads the widget to a selected member. | String | Connections |
| `update_credentials` | Loads to the update credential feature for a current member. Optionally used with `selected_member_guid`. | Boolean | Connections |
| `hide_account_filter` | Hides the account filter feature within the widget. | Boolean | Transactions |
| `selected_account_guid` | Loads the widget to a selected account. | String | Transactions |
| `locale` | Sets the language of the widget. If you're requesting the Connect or Connections Widgets, you must use the Accept-Language header. | String | All **except** Connect or Connections |
| `style` | Sets the widget's font. Pass `font_name: {font name}` with any Google font to change it. | Object | All |
| `view` | When used with the Cash Flow, Settings, or Money Dashboard widget, sets the widget's default view. Valid value for Cash Flow or Money Dashboard Widgets is `manage_income.` Valid values for the Notifications section of the Settings Widget (`notifications_settings_widget`) are `accounts`, `budgets`, or `insights`. | Money Dashboard, Cash Flow, or Settings | |
# Connect Widget Configuration Scenarios
Source: https://docs.mx.com/api-reference/sso/v3/reference/widget-urls/connect-widget-config-scenarios
The following shows several scenarios which partners may wish to present to end users, along with the correct configuration settings for each situation.
## Add a new member (default)
Opens Connect to let the user add a new financial institution connection. No additional configuration required — this is the default behavior.
```json theme={null}
{
"widget_type": "connect_widget"
}
```
## Update credentials for an existing member
Opens Connect directly to the credential entry screen for a specific member, useful when a member's `connection_status` requires updated credentials.
```json theme={null}
{
"widget_type": "connect_widget",
"current_member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
"update_credentials": true
}
```
## Verify account numbers (verification mode)
Opens Connect in verification mode, which guides the user through connecting an account to retrieve account and routing numbers for ACH purposes. Background aggregation is disabled by default in this mode.
```json theme={null}
{
"widget_type": "connect_widget",
"mode": "verification"
}
```
## Add a member and verify in one flow
Combines account connection and verification in a single widget session.
```json theme={null}
{
"widget_type": "connect_widget",
"mode": "verification",
"include_transactions": false
}
```
## Aggregation mode (explicit)
Opens Connect in standard aggregation mode. Use this when you want to be explicit about the mode, though this is the default.
```json theme={null}
{
"widget_type": "connect_widget",
"mode": "aggregation"
}
```
# Get SSO Login URL
Source: https://docs.mx.com/api-reference/sso/v3/reference/widget-urls/get-sso-login-url
GET https://int-sso.moneydesktop.com/{client_id}/users/{id}/urls/login
This endpoint returns an api_token to open a Nexus session
This URL is not to be used without discussing its implementation with an MX Integration engineer.
This URL can be used to create a full screen version of the widget software that is capable of being refreshed without ending the session. This is not a recommended usage but is provided for compatibility purposes for certain circumstances.
```shell Request theme={null}
curl -i https://int-sso.moneydesktop.com/{client_id}/users/{user_id}/urls/login.xml \
-H "Accept: application/vnd.moneydesktop.sso.v3+xml" \
-H "MD-API-KEY: {api_key}"
```
```xml XML theme={null}
unique-user-id
login
https://widgets.moneydesktop.com/login/XXXXX
```
```json JSON theme={null}
{
"url":{
"url":"https://widgets.moneydesktop.com/login/XXXXX",
"type":"login",
"user_id":"unique-user-id"
}
}
```
# Get Widget URL With Configuration Options
Source: https://docs.mx.com/api-reference/sso/v3/reference/widget-urls/get-widget-with-config-options
POST https://int-sso.moneydesktop.com/{client_id}/users/{id}/urls
This endpoint returns a widget URL with configuration options.
This endpoint allows you to get a URL by passing the `widget_type` in the request body along with the desired configuration options. Only set the `use_cases` field if you've opted in to using the feature, in which case setting this field is required. Each URL contains an embedded token that expires after ten minutes or when used, whichever comes first. A fresh URL must be obtained each time a page is loaded or reloaded.
See [Widget Types](/api-reference/sso/v3/reference/widget-urls/widget-types) for supported values.
Options may be tied to a particular `widget_type`. These are described in the [Configuration Options](/api-reference/sso/v3/reference/widget-urls/config-options) section. You may also pass an optional Accept-Language header. Note that this is a POST request, and that JSON data must be used in the request.
Automatic aggregation is triggered when any widget URL retrieved from this endpoint is **loaded** (as opposed to when the request was made), except for the `connect_widget` and `connections_widget`. If you'd like automatic aggregation for the `connect_widget` and `connections_widget`, please reach out to MX.
```shell Request theme={null}
curl -i -X POST https://int-sso.moneydesktop.com/{client_id}/users/{user_id}/urls.json \
-H 'Content-Type: application/vnd.moneydesktop.sso.v3+json' \
-H 'Accept: application/vnd.moneydesktop.sso.v3+json' \
-H 'MD-API-KEY: {api_key}' \
-d '{
"url": {
"is_mobile_webview": false,
"style": {
"font_name": "Roboto"
},
"type": "connect_widget",
"use_cases": ["PFM"],
"ui_message_version": 4
}
}'
```
```json Response theme={null}
{
"url": {
"url": "https://int-widgets.moneydesktop.com/md/connect/XXXXXX",
"type": "connect_widget",
"user_id": "USR-1234"
}
}
```
# Get Widget URL Without Configuration Options
Source: https://docs.mx.com/api-reference/sso/v3/reference/widget-urls/get-widgets-without-config-options
GET https://int-sso.moneydesktop.com/{client_id}/users/{id}/urls/{widget_type}
This endpoint returns a widget URL without configuration options.
Use this endpoint to request a widget URL without any configuration options. Each URL contains an embedded token that expires after ten minutes or when used, whichever comes first. A fresh URL must be obtained each time a page is loaded or reloaded.
See [Widget Types](/api-reference/sso/v3/reference/widget-urls/widget-types) for supported values.
Successful requests to this endpoint — regardless of the `widget_type` — automatically trigger aggregation for all members associated with the user.
You may also pass an optional Accept-Language header.
```shell Request theme={null}
curl -i https://int-sso.moneydesktop.com/{client_id}/users/{user_id}/urls/master_widget.xml \
-H 'Accept: application/vnd.moneydesktop.sso.v3+xml' \
-H 'MD-API-KEY: {api_key}'
```
```xml XML theme={null}
https://widgets.moneydesktop.com/md/master/XXXXX
master_widget
unique-user-id
```
```json JSON theme={null}
{
"url":{
"url":"https://widgets.moneydesktop.com/md/master/XXXXX",
"type":"master_widget",
"user_id":"unique-user-id"
}
}
```
# Language Options
Source: https://docs.mx.com/api-reference/sso/v3/reference/widget-urls/language-options
MX widgets support the following languages via the `Accept-Language` request header or the `ui_message_webview_url_scheme` configuration option.
| Language | Code |
| :------------------ | :------ |
| English (US) | `en-US` |
| English (Canada) | `en-CA` |
| French (Canada) | `fr-CA` |
| Spanish | `es` |
| Portuguese (Brazil) | `pt-BR` |
Pass the language code in the `Accept-Language` header when requesting a widget URL:
```shell Request theme={null}
curl -i -X POST https://int-sso.moneydesktop.com/{client_id}/users/{id}/urls.xml \
-H 'Content-Type: application/vnd.moneydesktop.sso.v3+xml' \
-H 'Accept: application/vnd.moneydesktop.sso.v3+xml' \
-H 'MD-API-KEY: {api_key}' \
-H 'Accept-Language: fr-CA' \
-d '
connections_widget
true
'
```
# List Widget URLs (Deprecated)
Source: https://docs.mx.com/api-reference/sso/v3/reference/widget-urls/list-widget-urls
GET https://int-sso.moneydesktop.com/{client_id}/users/{id}/urls
This endpoint returns an api_token to open a Nexus session
This endpoint has been deprecated.
This endpoint was originally intended to generate URLs for all enabled widgets for a client. This is no longer needed because the get URL with configuration options endpoint supports all MX widgets and MX does not need to enable particular widgets for each client.
New implementations should not use this endpoint in testing or in production. MX will continue to support this endpoint for existing partners who have implemented it, but we encourage all partners to switch to the get URL with configuration optinos endpoint to generate URLs for each individual widget they wish to use.
```shell Request theme={null}
curl -i https://int-sso.moneydesktop.com/{client_id}/users/{user_id}/urls.xml \
-H "Accept: application/vnd.moneydesktop.sso.v3+xml" \
-H "MD-API-KEY: :api_key"
```
```xml Response theme={null}
unique-user-id
master_widget
https://widgets.moneydesktop.com/md/master/XXXXX
unique-user-id
accounts_widget
https://widgets.moneydesktop.com/md/accounts/XXXXX
```
# Widget Types
Source: https://docs.mx.com/api-reference/sso/v3/reference/widget-urls/widget-types
If you're using the SSO API to embed a widget in a mobile context, such as a WebView, you must call some widgets using their mobile-specific `widget_type` to get accurate analytics data from MX systems. Analytics data on mobile vs. desktop visits is unavailable for widgets without a mobile-specific `widget_type`.
| Widget | `widget_type` |
| :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Accounts | `accounts_widget`. For analytics purposes, the mobile-specific `mobile_accounts_widget` value is available for this widget. |
| Mini Accounts | `mini_accounts_widget` |
| Actionable Integration | `actionable_integration_widget` |
| Budgets | `budgets_widget`. For analytics purposes, the mobile-specific `mobile_budgets_widget` value is available for this widget. |
| Mini Budgets | `mini_budgets_widget` |
| Cash Flow | `cash_flow_widget` |
| Mini Cash Flow | `mini_cash_flow_widget` |
| Connect | `connect_widget` |
| Connections | `connections_widget` |
| Debts | `debts_widget` |
| Finstrong | `finstrong_widget` |
| Mini Finstrong | `mini_finstrong_widget` |
| Goals | `goals_widget` |
| Help | `help_widget` |
| Insights | `pulse_widget` |
| Mini Insights | `mini_pulse_carousel_widget` |
| Micro Insights | `micro_pulse_carousel_widget` |
| Investments | `investments_widget` |
| Master | `master_widget`. For analytics purposes, the mobile-specific `mobile_master_widget` is available for this widget. `mobile_master_widget` can use all widgets, except for the Investments Widget, which is unavailable on mobile. |
| Money Dashboard | `money_dashboard_widget` |
| Net Worth | `net_worth_widget` |
| Mini Net Worth | `mini_net_worth_widget` |
| Notifications Settings | `notifications_settings_widget` |
| Recurring Transactions | `recurringtransactions_widget` |
| Mini Recurring Transactions | `mini_recurringtransactions_widget` |
| Setting | `settings_widget` |
| Spending | `spending_widget`. For analytics purposes, the mobile-specific `mobile_spending_widget` value is available for this widget. |
| Mini Spending | `mini_spending_widget` |
| Spending Plan | `spending_plan_widget` |
| Mini Spending Plan | `mini_spending_plan_widget` |
| Transaction Rules | `transaction_rules_widget` |
| Transactions | `transactions_widget`. For analytics purposes, the mobile-specific `mobile_transactions_widget` value is available for this widget. |
| Trends | `trends_widget` |
| Mini Trends | `mini_trends_widget` |
## Deprecated Widget Types
* `manage_institutions_widget` – use `connections_widget` instead
* `mini_accounts_widget` – this widget is no longer supported
* `mini_transactions_widget` – this widget is no longer supported