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 the user has enabled for this notification. Possible values are `in_app`, `email`, `sms`, and `push`.
`user_email`	String	When the user has enabled email notifications, this will contain the email address MX has on file, otherwise it will be empty.
`user_mobile`	String	When the user has enabled SMS notifications, this will contain the mobile number MX has on file, otherwise it will be empty.

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 at which the account was created.
`currency_code`	String	The three-letter 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	When the account is a checking or savings account, the threshold a balance would need to cross to be considered low.
`member_guid`	String	The unique identifier for the member associated with this account. Defined by MX.
`minimum_payment`	Decimal	When the account is a debt account (such as a credit card), the minimum payment that must be made.
`name`	String	The name of the account.
`payment_due_at`	Integer	The date at which the minimum payment is due.
`revision`	Integer	The revision number for the account.
`updated_at`	Integer	The date and time at which 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 `low_balance_threshold`.
`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 the budget was created.
`guid`	String	The unique identifier for the budget. Defined by MX.
`is_exceeded`	Boolean	This indicates whether the budget has been exceeded.
`is_off_track`	Boolean	This indicates 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 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`	User has spent more than 100% of their budgeted amount.
`BUDGET_OFF_TARGET`	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 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 at which 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 at which 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 at which 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 for the account.
`account_number`	String	The partner-provided account number.
`amount`	Decimal	The amount the transaction is for.
`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 at which the transaction was created.
`currency_code`	String	The three-letter ISO 4217 currency code. This value may be empty or `null`; in rare circumstances, it may be invalid.
`date`	Integer	The date 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	This indicates whether the transaction represents a fee.
`is_international`	Boolean	This indicates whether the transaction is international.
`is_overdraft_fee`	Boolean	This indicates whether the transaction represents an overdraft fee.
`member_guid`	String	The unique identifier for the member associated with this transaction. 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 at which 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 at which the user was created.
`email_verification_url`	String	When the notification is of type `EMAIL_VERIFICATION`, this will be a one-time use URL that is valid for 24 hours. 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	When the notification is of type `SMS_VERIFICATION`, this will be a one-time use token that is valid for 10 minutes. The user will need to input this token into the MoneyMap UI in order to validate their phone number for receiving texts.
`updated_at`	Integer	The date and time at which 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