Notifications - MX Documentation

Notifications webhooks notify you whenever an alertable action occurs on the MX system. 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.

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

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"
  }
}

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

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"
  }
}

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

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"
  }
}

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

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"
  }
}

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

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"
  }
}

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

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"
  }
}

​Account-Related Notifications

​Budget-Related Notifications

​Device-Related Notifications

​Offer-Related Notifications

​Transaction-Related Notifications

​User-Related Notifications

Account-Related Notifications

Budget-Related Notifications

Device-Related Notifications

Offer-Related Notifications

Transaction-Related Notifications

User-Related Notifications