> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Notifications

> Notifications webhooks notify you whenever an alertable action occurs on the MX system, including channels, contact info, and related details.

The payload will contain the action that triggered the webhook, the channels the user has opted into for that notification, the user's contact information, and an object with additional information that relates to the notification.

**Generic Payload Fields**

| Field | Data Type | Definition |
| :- | :- | :- |
| `action` | String | The name of the notification that occurred on the MX system. |
| `enabled_channels` | Array | The channels that the user has enabled for this notification. Possible values include `in_app`, `email`, `sms`, and `push`. |
| `user_email` | String | The email address that MX has on file for the user. This populates only when the user has email notifications enabled. |
| `user_mobile` | String | The mobile number that MX has on file for the user. This populates only when the user has SMS notifications enabled. |

## Account-Related Notifications

| Field | Data Type | Definition |
| :- | :- | :- |
| `account_number` | String | The partner-provided account number. |
| `available_balance` | Decimal | The balance the account owner has available. |
| `balance` | Decimal | The total balance the account owner has available, including any account minimums. |
| `client_id` | String | The unique partner-defined identifier for the institution the account belongs to. |
| `created_at` | Integer | The date and time when the account was created. |
| `currency_code` | String | The ISO 4217 currency code. This value may be empty or null; in rare circumstances, it may be invalid. |
| `guid` | String | The unique identifier for the account. Defined by MX. |
| `estimated_payment_due_at` | Integer | The estimated day and time the payment is due. Defaults to the `payment_due_at` field if present and set to a future date. Otherwise, MX calculates an estimated date based on the `day_payment_is_due` field (typically provided by the end user). |
| `low_balance_threshold` | Decimal | The threshold a balance would need to cross to be considered low. This applies only to checking and savings accounts. |
| `member_guid` | String | The unique identifier for the member. Defined by MX. |
| `minimum_payment` | Decimal | The minimum payment that must be made. This applies only to debt accounts (such as a credit card). |
| `name` | String | The name of the account. |
| `payment_due_at` | Integer | The date on which the minimum payment is due. |
| `revision` | Integer | The revision number for the account. |
| `updated_at` | Integer | The date and time when the account was updated. |
| `user_guid` | String | The unique identifier for the user the account is attached to. Defined by MX. |
| `user_id` | String | The unique partner-defined identifier for the user. |

**Action Types for Account Notifications**

| Type | Definition |
| :- | :- |
| `ACCOUNT_BALANCE_LOW` | The account has fallen below the value of the `low_balance_threshold` field. |
| `DEBT_PAYMENT_REMINDER` | The account has an upcoming debt payment that needs to be made. |

**Example Account-Related Notification Request Delivered**

```json JSON theme={null}
POST /admin/webhooks
HTTP/1.1
content-type: application/json; charset=utf-8
accept: application/json
User-Agent: HTTPClient/1.0 (2.7.1, ruby 2.2.2
(2015-09-02)) Date: Thu, 14 Apr 2016 04:26:04 GMT Content-Length: 123
Host: abc.com
{
  "action": "ACCOUNT_BALANCE_LOW",
  "enabled_channels": ["email","in_app","push","sms"],
  "user_email": "test@abc.com",
  "user_mobile": "123-456-7890",
  "account": {
    "account_number": "A-1234",
    "available_balance": 11.34,
    "balance": 12.34,
    "client_id": "C-1234",
    "created_at": 123456890,
    "currency_code": "USD",
    "estimated_payment_due_at": "12345678990",
    "guid": "ACT-0288c67b-aa25-db63-1914-3c22f442cad6",
    "low_balance_threshold": 100.00,
    "member_guid": "MBR-37460bb7-6b0f-a960-1256-dd07130443f5",
    "minimum_payment": 25.00,
    "name": "Visa Platinum",
    "payment_due_at": 12345678990,
    "revision": 12,
    "updated_at": 123456890,
    "user_guid": "USR-c8f30aa7-670f-c920-1155-cd06120243e5",
    "user_id": "U-1234"
  }
}
```

## Budget-Related Notifications

| Field | Data Type | Definition |
| :- | :- | :- |
| `amount` | Decimal | A budget amount set by the user for a category's transaction total during a month. |
| `category_guid` | String | The unique identifier for the budget category. Defined by MX. |
| `client_id` | String | The unique partner-defined identifier for the institution the account belongs to. |
| `created_at` | Integer | The date and time when the budget was created. |
| `guid` | String | The unique identifier for the budget. Defined by MX. |
| `is_exceeded` | Boolean | Whether the budget has been exceeded. |
| `is_off_track` | Boolean | Whether the budget is off track. |
| `metadata` | String | Additional information a partner can store on the budget. |
| `name` | String | The name of the budget category. |
| `parent_guid` | String | The unique identifier for the parent budget. Defined by MX. |
| `projected_spending` | Decimal | The projected amount of spending for the budget. |
| `revision` | Integer | The revision number for the budget. |
| `transaction_total` | Decimal | The cumulative amount of all transactions under the budget. |
| `updated_at` | Integer | The date and time when the budget was updated. |
| `user_guid` | String | The unique identifier for the user the budget is attached to. Defined by MX. |
| `user_id` | String | The unique partner-defined identifier for the user. |

**Action Types for Budget Notifications**

| Type | Definition |
| :- | :- |
| `BUDGET_EXCEEDED` | The user has spent more than 100% of their budgeted amount. |
| `BUDGET_OFF_TARGET` | The user is projected to go over budget this month based on current transactions and an analysis of transaction data over the past 90 days. |

**Example Budget-Related Notification Request Delivered**

```json JSON theme={null}
POST /admin/webhooks
HTTP/1.1
content-type: application/json; charset=utf-8
accept: application/json
User-Agent: HTTPClient/1.0 (2.7.1, ruby 2.2.2
(2015-09-02)) Date: Thu, 14 Apr 2016 04:26:04 GMT Content-Length: 123
Host: abc.com
{
  "action": "BUDGET_EXCEEDED",
  "enabled_channels": ["email","in_app","push","sms"],
  "user_email": "test@abc.com",
  "user_mobile": "123-456-7890",
  "budget": {
    "amount": 1312.00,
    "category_guid": "CAT-b709172b-4eb7-318e-3b5d-e0f0500b32ac",
    "client_id": "C-1234",
    "created_at": 123456890,
    "guid": "BGT-0288c67b-aa25-db63-1914-3c22f442cad6",
    "is_exceeded": true,
    "is_off_track": true,
    "metadata": null,
    "name": "Home",
    "parent_guid": null,
    "projected_spending": 1420.24,
    "revision": 12,
    "transaction_total": 1420.24,
    "updated_at": 123456890,
    "user_guid": "USR-c8f30aa7-670f-c920-1155-cd06120243e5",
    "user_id": "U-1234"
  }
}
```

## Device-Related Notifications

| Field | Data Type | Definition |
| :- | :- | :- |
| `client_id` | String | The unique partner-defined identifier for the institution the device belongs to. |
| `client_product_name` | String | The display name to use for the sender of the alert. |
| `created_at` | Integer | The date and time when the device was created. |
| `guid` | String | The unique identifier for the device. Defined by MX. |
| `make` | String | The manufacturer of the device. |
| `model` | String | The model of the device. |
| `name` | String | The name of the device. |
| `os_name` | String | The operating system the device is running. |
| `os_version` | String | The version of the operating system the device is running. |
| `updated_at` | Integer | The date and time when the device was updated. |
| `user_guid` | String | The unique identifier for the user the device is attached to. Defined by MX. |
| `user_id` | String | The unique partner-defined identifier for the user. |

**Action Types for Device Notifications**

| Type | Definition |
| :- | :- |
| `DEVICE_CREATED` | A mobile device has been added to a user's account. |
| `DEVICE_DELETED` | A mobile device has been removed from a user's account. |

**Example Device-Related Notification Request Delivered**

```json JSON theme={null}
POST /admin/webhooks
HTTP/1.1
content-type: application/json; charset=utf-8
accept: application/json
User-Agent: HTTPClient/1.0 (2.7.1, ruby 2.2.2
(2015-09-02)) Date: Thu, 14 Apr 2016 04:26:04 GMT Content-Length: 123
Host: abc.com
{
  "action": "DEVICE_CREATED",
  "enabled_channels": ["email","in_app","push","sms"],
  "user_email": "test@abc.com",
  "user_mobile": "123-456-7890",
  "device": {
    "client_id": "C-1234",
    "client_product_name": "MoneyDesktop",
    "created_at": 123456890,
    "guid": "DEV-0288c67b-aa25-db63-1914-3c22f442cad6",
    "make": "Google",
    "model": "Pixel XL",
    "name": "My Pixel",
    "os_name": "android",
    "os_version": 12,
    "updated_at": 123456890,
    "user_guid": "USR-c8f30aa7-670f-c920-1155-cd06120243e5",
    "user_id": "U-1234"
  }
}
```

## Offer-Related Notifications

| Field | Data Type | Definition |
| :- | :- | :- |
| `client_id` | String | The unique partner-defined identifier for the institution the offer comes from. |
| `client_product_name` | String | The display name to use for the sender of the alert. |
| `created_at` | Integer | The date and time when the offer was created. |
| `offer` | String | The text to display to the user as part of the offer. |
| `updated_at` | Integer | The date and time when the offer was updated. |
| `user_guid` | String | The unique identifier for the user the offer is sent to. Defined by MX. |
| `user_id` | String | The unique partner-defined identifier for the user. |

**Action Types for Offer Notifications**

| Type | Definition |
| :- | :- |
| `OFFER` | An offer is to be sent to a user as part of a campaign. |

**Example Offer-Related Notification Request Delivered**

```json JSON theme={null}
POST /admin/webhooks
HTTP/1.1
content-type: application/json; charset=utf-8
accept: application/json
User-Agent: HTTPClient/1.0 (2.7.1, ruby 2.2.2
(2015-09-02)) Date: Thu, 14 Apr 2016 04:26:04 GMT Content-Length: 123
Host: abc.com
{
  "action": "OFFER",
  "enabled_channels": ["email","in_app","push","sms"],
  "user_email": "test@abc.com",
  "user_mobile": "123-456-7890",
  "offer": {
    "client_id": "C-1234",
    "client_product_name": "MoneyDesktop",
    "created_at": 123456890,
    "offer": "Offer text",
    "updated_at": 123456890,
    "user_guid": "USR-c8f30aa7-670f-c920-1155-cd06120243e5",
    "user_id": "U-1234"
  }
}
```

## Transaction-Related Notifications

| Field | Data Type | Definition |
| :- | :- | :- |
| `account_guid` | String | The unique identifier for the account this transaction is under. Defined by MX. |
| `account_name` | String | The name of the account. |
| `account_number` | String | The partner-provided account number. |
| `amount` | Decimal | The amount of the transaction. |
| `category_guid` | String | The unique identifier for the transaction category. Defined by MX. |
| `client_id` | String | The unique partner-defined identifier for the institution the transaction is a part of. |
| `created_at` | Integer | The date and time when the transaction was created. |
| `currency_code` | String | The ISO 4217 currency code. This value may be empty or `null`; in rare circumstances, it may be invalid. |
| `date` | Integer | The date on which the transaction was created. |
| `description` | String | A short description of what the transaction is about. |
| `guid` | String | The unique identifier for the transaction. Defined by MX. |
| `is_fee` | Boolean | Whether the transaction represents a fee. |
| `is_international` | Boolean | Whether the transaction is international. |
| `is_overdraft_fee` | Boolean | Whether the transaction represents an overdraft fee. |
| `member_guid` | String | The unique identifier for the member. Defined by MX. |
| `revision` | Integer | The revision number for the transaction. |
| `status` | String | The status of the transaction, if known. May be `PENDING`, `POSTED`, or empty if not known. |
| `transaction_threshold` | Decimal | The amount that a transaction would have to be greater than to be considered large. |
| `type` | String | The type of transaction, if known. May be `DEBIT`, `CREDIT`, or empty if not known. |
| `updated_at` | Integer | The date and time when the transaction was updated. |
| `user_guid` | String | The unique identifier for the user the transaction is attached to. Defined by MX. |
| `user_id` | String | The unique partner-defined identifier for the user. |

**Action Types for Transaction Notifications**

| Type | Definition |
| :- | :- |
| `ACCOUNT_DEPOSIT_LARGE` | A large deposit has been detected in an account. |
| `TRANSACTION_EXPENSE_LARGE` | A large expense has been detected in an account. |
| `TRANSACTION_FEE_CHARGE` | An account fee has been charged. |
| `TRANSACTION_IS_INTERNATIONAL` | An international transaction has been detected in an account. |

**Example Transaction-Related Notification Request Delivered**

```json JSON theme={null}
POST /admin/webhooks
HTTP/1.1
content-type: application/json; charset=utf-8
accept: application/json
User-Agent: HTTPClient/1.0 (2.7.1, ruby 2.2.2
(2015-09-02)) Date: Thu, 14 Apr 2016 04:26:04 GMT Content-Length: 123
Host: abc.com
{
  "action": "ACCOUNT_DEPOSIT_LARGE",
  "enabled_channels": ["email","in_app","push","sms"],
  "user_email": "test@abc.com",
  "user_mobile": "123-456-7890",
  "transaction": {
    "account_guid": "ACT-0288c67b-aa25-db63-1914-3c22f442cad6",
    "account_name": "My Checking",
    "account_number": "A-1234",
    "amount": 1312.00,
    "category_guid": "CAT-b709172b-4eb7-318e-3b5d-e0f0500b32ac",
    "client_id": "C-1234",
    "created_at": 123456890,
    "currency_code": "USD",
    "date": 1234567890,
    "description": "Paycheck deposit from ACME Corp",
    "guid": "TRN-0288c67b-aa25-db63-1914-3c22f442cad6",
    "is_fee": false,
    "is_international": false,
    "is_overdraft_fee": false,
    "member_guid": "MBR-37460bb7-6b0f-a960-1256-dd07130443f5",
    "revision": 2,
    "status": "POSTED",
    "transaction_threshold": 500.00,
    "type": "CREDIT",
    "updated_at": 123456890,
    "user_guid": "USR-c8f30aa7-670f-c920-1155-cd06120243e5",
    "user_id": "U-1234"
  }
}
```

## User-Related Notifications

| Field | Data Type | Definition |
| :- | :- | :- |
| `client_id` | String | The unique partner-defined identifier for the institution the transaction is a part of. |
| `client_product_name` | String | The display name to use for the sender of the alert. |
| `created_at` | Integer | The date and time when the user was created. |
| `email_verification_url` | String | A one-time use URL that is valid for 24 hours when the notification type is `EMAIL_VERIFICATION`. A `GET` request to this URL verifies the email address. |
| `first_name` | String | The user's first name. |
| `guid` | String | The unique identifier for the user. Defined by MX. |
| `institution_name` | String | The financial institution's display name. |
| `last_name` | String | The user's last name. |
| `sms_verification_token` | String | A one-time use token that is valid for 10 minutes when the notification type is `SMS_VERIFICATION`. The user will need to enter this token into the UI to validate their phone number for receiving texts. |
| `updated_at` | Integer | The date and time when the user was updated. |
| `user_id` | String | The unique partner-defined identifier for the user. |

**Action Types for User Notifications**

| Type | Definition |
| :- | :- |
| `EMAIL_VERIFICATION` | A new email address has been added that needs to be verified. |
| `EMAIL_VERIFIED` | A new email address has been successfully verified. |
| `PASSWORD_CHANGED` | The user's password has been changed. |
| `PASSWORD_RESET_TOKEN` | A request has been made to change the user's password. |
| `SMS_VERIFICATION` | A new SMS-enabled mobile device has been added that needs to be verified. |
| `WELCOME_NEW_USER` | A new user has logged into their account for the first time. |

**Example User-Related Notification Request Delivered**

```json JSON theme={null}
POST /admin/webhooks
HTTP/1.1
content-type: application/json; charset=utf-8
accept: application/json
User-Agent: HTTPClient/1.0 (2.7.1, ruby 2.2.2
(2015-09-02)) Date: Thu, 14 Apr 2016 04:26:04 GMT Content-Length: 123
Host: abc.com
{
  "action": "EMAIL_VERIFICATION",
  "enabled_channels": ["email","in_app","push","sms"],
  "user_email": "test@abc.com",
  "user_mobile": "123-456-7890",
  "user": {
    "client_id": "C-1234",
    "client_product_name": "MoneyDesktop",
    "created_at": 123456890,
    "email_verification_url": "https://widgets.moneydesktop.com/email_verifications/abc123",
    "first_name": "John",
    "guid": "USR-0288c67b-aa25-db63-1914-3c22f442cad6",
    "institution_name": "Epic Bank",
    "last_name": "Doe",
    "sms_verification_token": "123456",
    "updated_at": 123456890,
    "user_id": "U-1234"
  }
}
```