Introduction

The MX Atrium API supports over 48,000 data connections to thousands of financial institutions. It provides secure access to your users’ accounts and transactions with industry-leading cleansing, categorization, and classification.

Atrium is designed according to resource-oriented REST architecture and responds with JSON bodies and HTTP response codes.

Use Atrium’s development environment, vestibule.mx.com, to quickly get up and running. The development environment limits are 100 users and access to the top 15 institutions. Contact MX to purchase production access.

Production environment

https://atrium.mx.com/

Development environment

https://vestibule.mx.com/

Getting started

To get started right away with some of the most common tasks and frequently used features of Atrium, you can check out our detailed developer guide.

It covers things like aggregation, dealing with multi-factor authentication, creating users and members, and a lot more.

Our developer guide also explains our test endpoints and test credentials to help you get off the ground as soon as possible.

We’ve also provided wrapper libraries in several languages. Visit the appropriate GitHub page below.

Things you need to know

Aggregation and data availability

Aggregation is how Atrium is able to gather financial data from multiple sources and then deliver it to you. It is the core feature of the Atrium API.

MX automatically aggregates certain members in the background every 24 hours. Specifically, we aggregate all members whose connection_status is either CONNECTED, CREATED, IMPEDED, or UPDATED — unless the member has been disabled.

You may aggregate a member via the aggregate member endpoint to get the most up-to-date information on accounts and transactions. When you aggregate a member with this endpoint, MX will not initiate a background aggregation within the next 20-hour period.

Aggregation limits

The default minimum time between aggregation events is 10,800 seconds (3 hours), though this limit can vary by institution. Aggregating within this limit will not return an error, however; the response will simply contain the current state of the member, including the latest connection_status. Certain codepaths may also bypass this limit — for instance, updating a member’s credentials.

The MX Bank test institution has no aggregation limits.

Data availability

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 day_payment_is_due fields. This is to be expected in all resources and all aggregations.

API architecture and resource structure

Atrium is designed around the REST architecture and uses predictable, resource-oriented URLs. Requests are made with HTTP methods and HTTP response codes indicate the success or failure of those requests.

Atrium has five broad groups of resources, each with their own attributes and endpoints:

Resource	Description
`user`	A `user` represents a person using Atrium via your application, be it a mobile app, web app, desktop app, etc.
`institution`	An `institution` represents a financial institution like Chase or Wells Fargo. It’s important to point out that many real-world financial institutions will actually have several different `institution` objects within Atrium. This is because, for example, the mortgage division of Wells Fargo might use a separate system than its everyday banking division, which is different from its credit card division, etc.
`member`	A `member` represents the relationship between a `user` and an `institution`, and creating one is how you connect a `user` to an `institution`. A `user` may have one `member` each for their bank, their mortgage broker, their credit card provider, etc. Aggregation takes place via members.
`account`	An `account` represents a financial account held by a financial institution, e.g., a user’s checking or savings account. Because a user’s relationship with an institution may involve more than one account, a `member` may have more than one `account` associated with it. For instance, a user may have both a checking and savings account with Chase. In that case, the `user` would have a `member` that represents their connection with the Chase `institution`. That `member` would have two accounts, a checking `account` and a savings `account`.
`transaction`	A `transaction` represents any instance in which money moves into or out of an `account`. This could be 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`.

Authentication and security

Atrium API requests must be HTTPS with encryption TLSv1.2 or higher or else they will fail.

All requests are authenticated with tokens in request headers: MX-API-Key and MX-Client-ID. The production and development environments require separate tokens. Development tokens are granted automatically during the signup process; These can be found on your profile page.

Contact MX for information on moving to production.

Because these tokens grant access to all of your data, you must keep them secret and keep them safe. Do not share them in public areas, use them in client-side code, or otherwise use them in a way that may compromise their security. In some instances, requests that require authentication will return 404 Not Found, instead of 401 Unauthorized. This is to prevent leaking private information.

Caching

Certain Atrium resources are subject to change at any time; for instance, institutions and institution credentials. For this reason, MX discourages partners from caching lists of resources. If caching is necessary, MX recommends refreshing a cached list at least daily.

Character encoding

Requests to Atrium must use characters encoded with the UTF-8 standard.

Data format

JSON structured data is returned in all responses, including some errors.

Dates and times

Dates and times are always given in ISO 8601 format.

Fields which end in _on are given without a timestamp: 2018-07-18

Fields which end in _at are given with a timestamp: 2015-04-13T12:01:23-06:00.

Errors

Atrium uses conventional HTTP response codes to indicate the success or failure of a request, with supplementary error messaging as needed within response bodies.

Status codes

Status	Explanation
2xx Success
`200 OK`	Everything worked as expected with content returned.
`202 Accepted`	Everything worked and MX’s system is processing the request. When attempting a job on a `member`, a job of the same type is already running; e.g., calling aggregate member while a standard agg is still running, or calling verify member while a previous verification is still running. A standard aggregation has been attempted within the default minimum time between standard aggs.
`204 No Content`	Everything worked as expected without content returned.
4xx Requester error
`400 Bad Request`	A required parameter was missing. A premium aggregation-type job was requested, but the `institution` associated with the `member` does not support it.
`401 Unauthorized`	Invalid MX-API-Key or MX-Client-ID provided.
`403 Forbidden`	The request was made from a non-whitelisted address or the feature is not available to the client.
`404 Not Found`	Invalid item/id/URL requested.
`405 Method Not Allowed`	A constraint on the requested endpoint wasn’t met.
`406 Not Acceptable`	The request didn’t specify a valid API version.
`409 Conflict`	1. An object with the given attributes already exists. 2. When attempting an aggregation on a `member`, the `member` already has an an aggregation of a different type running; e.g., calling the verify endpoint while a standard aggregation is already running, or calling fetch statements while an identification aggregation is already running.
`422 Unprocessable Entity`	The data provided cannot be processed.
5xx Responder error — which are rare
`500, 502, 504 Server errors`	Something went wrong with MX’s servers.
`503 Service Unavailable`	The MX Platform is being updated.

Example error message

1
2
3
4
5
{
  "error": {
    "message": "Unrecognized institution.",
  }
}

Identifiers and metadata

Atrium gives you two special — but optional — fields which you can define for any resource created with the API: identifier and metadata. These fields make it easier to customize and integrate Atrium with your systems.

For instance, you may need to make certain that some resources are created only once. In these situations, you can give an unique identifier to resources created with Atrium. Atrium will return a 409 Conflict error if a resource is created with an identifier that already exists.

You might also use the metadata field to store custom data about a resource. For example, you could store a user’s username for your system, their sign-up date, the date and time of their last logon in your system, or all of these.

Field	Description
`identifier`	A unique, enforced identifier for a `user` or `member`, defined by you. An `identifier` may contain letters, numbers, dashes, and underscores — but they should not be longer than 200 characters. MX recommends using GUIDs. Atrium will return a `409 Conflict` error if a resource is created with an `identifier` that already exists.
`metadata`	This field that can be used to store additional information about a particular `user` or `member`. Any UTF-8 string can be stored, but MX recommends using structured key-value data such as JSON.

Example metadata request

1
2
3
4
5
6
7
8
9
10
$ curl -i -X POST 'https://vestibule.mx.com/users' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'Content-Type: application/json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}' \
  -d '{
        "user": {
          "metadata": "{\"username\":\"steven\"}"
        }
      }'

Example identifier request

1
2
3
4
5
6
7
8
9
10
$ curl -X POST 'https://vestibule.mx.com/users' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'Content-Type: application/json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}' \
  -d '{
        "user": {
          "identifier": "5935d8ef-20c0-4bc1-997c-b2cccf4d601d"
        }
      }'

Example of an identifier conflict response

Status: 409 Conflict

1
2
3
4
5
{
  "error": {
    "message": "A user already exists with identifier: '5935d8ef-20c0-4bc1-997c-b2cccf4d601d'."
  }
}

IP address whitelisting

All IP addresses which will make calls to Atrium’s production environment must be whitelisted first. A 403 Forbidden error will be returned for non-whitelisted addresses. The vestibule environment does not require any whitelisting.

You can whitelist IP addresses on your account profile.

Limits

User and member limits

The development environment limits developers to 100 users and access to the top 15 institutions.

No user may have more than 25 members in either the development or production environments.

Aggregation throttling

Standard aggregation jobs are throttled, and a new standard agg can only be started after the throttle period has elapsed. The default throttle period is three hours (10,800 seconds), though this limit can vary from one institution to another.

However, premium agg-type jobs won’t start the throttle period (extended history, identification, verification, statements, balance check). In other words, running a standard agg will always start the throttle period and prevent a new standard agg. Running any other type of job will not start the throttle period.

Premium aggregation-type jobs are never throttled. That is, you can run an account verification right after a standard agg (or balance request, or verification etc.). However, because standard aggs are throttled, you should generally use the include_transactions parameter on premium jobs if standard data is also required; this will prevent delays.

Throttled jobs will not return an error; the response will return with 202 Accepted and will contain the current state of the member, including the latest connection_status.

Jobs for members that have experienced credential-related errors won’t be throttled (connection_status: REJECTED, PREVENTED, UPDATED).

Balance jobs are limited to 5 requests every 2 hours.

There is no throttling of any kind when using the MX Bank test institution.

Numbers and number formats

Number limits are described by their precision and scale. Precision refers to the total number of digits. Scale refers to the number of digits to the right of the decimal. For example, 538.46’s precision,scale is 5,2.

Percentages are in decimal format without the percentage sign. For example, 2.99% is written 2.99.

Pagination

All endpoints which return lists are paginated. These endpoints also support two query parameters which specify the number of records per page and the page to be returned.

Each response will include a pagination object specifying information on the total number of entries and the current page.

Query parameters

Parameter	Definition
`page`	This specifies the page to be returned. Defaults to `1`.
`records_per_page`	This specifies the number of records to be returned on each page. Defaults to `25`. The valid range is from `10` to `100`.

Pagination fields

Field	Definition
`current_page`	The page delivered by the current response.
`per_page`	The number of records delivered with each page.
`total_entries`	The total number of records available.
`total_pages`	The total number of pages available.

Example pagination object:

1
2
3
4
5
6
"pagination": {
  "current_page": 1,
  "per_page": 25,
  "total_entries": 2,
  "total_pages": 1
}

Testing

The developer guide explains how to test your setup using our test endpoints and test credentials.

Versioning

We always try to make API changes backwards-compatible. However, when we make breaking changes to Atrium, we’ll increment the version number. The current version is v1. Versions are specified in a request’s Accept header. All requests will access the current version unless a different version is specified with the request, so it’s best to always specify the API version. The current Accept header is application/vnd.mx.atrium.v1+json.

Accounts

An account represents a financial account held by a financial institution, e.g., a user’s checking or savings account. An account belongs to a member, which represents the user’s overall relationship with a particular financial institution. A checking account may be just one part of a larger relationship that could also include a car loan and a savings account.

Account fields

Field	Data type	Description
`account_number`	String	The account number associated with the `account`. This will typically be a masked or partial account number.
`apr`	Decimal	The annual percentage rate associated with the `account`.
`apy`	Decimal	The annual percentage yield associated with the `account`.
`available_balance`	Decimal	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`	Decimal	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`	Decimal	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_balance`	Decimal	The cash balance of the `account`.
`cash_balance`	Decimal	The cash balance of the `account`.
`cash_surrender_value`	Decimal	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`	String	The date and time at which the `account` was created on the MX Platform.
`credit_limit`	Decimal	The credit limit associated with the `account`.
`currency_code`	String	The three-character ISO 4217 currency code.
`day_payment_is_due`	String	The day of the month the payment is due. For example, the 14th is passed as 14.
`death_benefit`	Integer	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.
`holdings_value`	Decimal	The value of the holdings associated with the account.
`institution_code`	String	A unique identifier for the `institution` associated with this `account`. Defined by MX.
`insured_name`	String	The name of the insured individual.
`interest_rate`	Decimal	The interest rate associated with the `account`.
`is_closed`	Boolean	This indicates whether an account has been closed.
`last_payment_at`	String	The date and time of the most recent payment on the `account`.
`last_payment`	Decimal	The amount of the most recent payment on the `account`.
`loan_amount`	Decimal	The amount of the loan associated with the `account`.
`matures_on`	String	The date on which the `account` matures.
`member_guid`	String	The unique identifier for the `member` to which the `account` belongs, assigned by MX.
`minimum_balance`	decimal	The minimum balance associated with the `account`.
`minimum_payment`	Decimal	The minimum payment required for an account. This can apply to any debt account. Max length is 10,2.
`name`	String	The human-readable name for the `account`.
`original_balance`	Decimal	The original balance associated with the `account`. This will always be positive.
`pay_out_amount`	String	The amount paid out to the insured individual or beneficiary under the conditions of the insurance policy.
`payment_due_at`	String	The date and time at which the next payment is due on the `account`.
`payoff_balance`	Decimal	The payoff balance for a debt `account`. This will normally be a positive number.
`premium_amount`	Decimal	The insurance policy’s premium amount.
`started_on`	String	The date on which a debt account was started.
`subtype`	String	The account’s subtype, e.g., `PLAN_401_K`, `MONEY_MARKET`, or `HOME_EQUITY`.
`total_account_value`	Decimal	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. Max length is 14,2.
`type`	String	The general or parent type of the `account`.
`updated_at`	String	The date and time at which the `account` was most recently updated.
`user_guid`	String	The unique identifier for the `user` to which the `account` belongs.

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

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

List accounts for a user

This endpoint returns a list of all the accounts associated with the specified user.

Endpoint:

GET /users/{user_guid}/accounts

Example request

1
2
3
4
$ curl -i 'https://vestibule.mx.com/users/{user_guid}/accounts' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
{
  "accounts": [
    {
      "account_number": null,
      "apr": null,
      "apy": 1.43,
      "available_balance": 1000.23,
      "available_credit": 100.23,
      "balance": 1000.23,
      "cash_balance": 1000.32,
      "cash_surrender_value": 1000.23,
      "created_at": "2016-10-13T17:57:37+00:00",
      "credit_limit": 100.23,
      "currency_code": "USD",
      "day_payment_is_due": 20,
      "death_benefit": 1000.12,
      "guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
      "holdings_value": 1000.21,
      "insured_name": null,
      "institution_code": "chase",
      "interest_rate": null,
      "is_closed": false,
      "last_payment": null,
      "last_payment_at": null,
      "loan_amount": null,
      "matures_on": null,
      "member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
      "minimum_balance": null,
      "minimum_payment": null,
      "name": "Test Account 2",
      "original_balance": null,
      "payment_due_at": null,
      "payoff_balance": null,
      "pay_out_amount": null,
      "premium_amount": null,
      "started_on": null,
      "subtype": null,
      "total_account_value": null,
      "type": "SAVINGS",
      "updated_at": "2016-10-13T18:08:00+00:00",
      "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 1,
    "total_pages": 1
  }
}

Read account

Reading an account allows you to get information about a specific account that belongs to a user. That includes the account type — e.g., CHECKING, MONEY_MARKET, or PROPERTY — the balance, the date the account was started, and much more.

There are two endpoints for reading an account. Both will return the same information.

Endpoint:

GET /users/{user_guid}/accounts/{account_guid}

Example request

1
2
3
4
$ curl -i 'https://vestibule.mx.com/users/{user_guid}/accounts/{account_guid}' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
{
  "account": {
    "account_number": null,
    "apr": null,
    "apy": 1.43,
    "available_balance": 1000.23,
    "available_credit": 100.23,
    "balance": 1000.23,
    "cash_balance": 1000.32,
    "cash_surrender_value": 1000.23,
    "created_at": "2016-10-13T17:57:37+00:00",
    "credit_limit": 100.23,
    "currency_code": "USD",
    "day_payment_is_due": 20,
    "death_benefit": 1000.12,
    "guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
    "holdings_value": 1000.21,
    "insured_name": null,
    "institution_code": "chase",
    "interest_rate": null,
    "is_closed": false,
    "last_payment": null,
    "last_payment_at": null,
    "loan_amount": null,
    "matures_on": null,
    "member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "minimum_balance": null,
    "minimum_payment": null,
    "name": "Test Account 2",
    "original_balance": null,
    "payment_due_at": null,
    "payoff_balance": null,
    "pay_out_amount": null,
    "premium_amount": null,
    "started_on": null,
    "subtype": null,
    "total_account_value": null,
    "type": "SAVINGS",
    "updated_at": "2016-10-13T18:08:00+00:00",
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
  }
}

List account transactions

This endpoint allows you to see every transaction that belongs to a specific account.

The from_date and to_date parameters can optionally be appended to the request if transactions in a specific date range are required.

Query string parameters

Field name	Required	Data type	Description
`from_date`	No	String	Return transactions occurring within a date range starting on this day. If not set, this defaults to 90 days prior to the day of the request. Must be in ISO 8601 format without a time component.
`to_date`	No	String	Return transactions occurring in a date range ending on this day. If not set, this defaults to 5 days forward from the day of the request so as to capture pending transactions. Must be in ISO 8601 format without a time component.

Endpoint:

GET /users/{user_guid}/accounts

Example request

1
2
3
4
$ curl -i 'https://vestibule.mx.com/users/{user_guid}/accounts/{account_guid}/transactions' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
{
  "transactions": [
    {
      "account_guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
      "amount": 61.11,
      "category": "Groceries",
      "check_number": 15234,
      "check_number_string": "00015234",
      "created_at": "2016-10-06T09:43:42+00:00",
      "currency_code": "USD",
      "date": "2013-09-23",
      "description": "Whole Foods",
      "guid": "TRN-265abee9-889b-af6a-c69b-25157db2bdd9",
      "is_bill_pay": false,
      "is_direct_deposit": false,
      "is_expense": true,
      "is_fee": false,
      "is_income": false,
      "is_international": false,
      "is_overdraft_fee": false,
      "is_payroll_advance": false,
      "latitude": -43.2075,
      "longitude": 139.691706,
      "member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
      "memo": null,
      "merchant_category_code": 5411,
      "merchant_guid": "MCH-7ed79542-884d-2b1b-dd74-501c5cc9d25b",
      "original_description": "WHOLEFDS TSQ 102",
      "posted_at": "2016-10-07T06:00:00+00:00",
      "status": "POSTED",
      "top_level_category": "Food & Dining",
      "transacted_at": "2016-10-06T13:00:00+00:00",
      "type": "DEBIT",
      "updated_at": "2016-10-07T05:49:12+00:00",
      "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
    },
    {
      "account_guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
      "amount": 23.4,
      "category": "Books",
      "check_number": 15234,
      "check_number_string": "00015234",
      "created_at": "2016-08-26T09:43:42+00:00",
      "currency_code": "USD",
      "date": "2013-09-23",
      "description": "Audible",
      "guid": "TRN-265abee9-889b-af6a-c69b-25157db2bdd9",
      "is_bill_pay": false,
      "is_direct_deposit": false,
      "is_expense": true,
      "is_fee": false,
      "is_income": false,
      "is_international": false,
      "is_overdraft_fee": false,
      "is_payroll_advance": false,
      "latitude": -43.2075,
      "longitude": 139.691706,
      "member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
      "memo": null,
      "merchant_category_code": 5411,
      "merchant_guid": "MCH-7ed79542-884d-2b1b-dd74-501c5cc9d25b",
      "original_description": "AUDIBLEBKS",
      "posted_at": "2016-08-27T06:00:00+00:00",
      "status": "POSTED",
      "top_level_category": "Entertainment",
      "transacted_at": "2016-08-26T13:00:00+00:00",
      "type": "DEBIT",
      "updated_at": "2016-08-27T05:49:12+00:00",
      "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 2,
    "total_pages": 1
  }
}

Holdings

Holdings represent a stock, bond, or other type of investment.

Holding fields

Field	Data type	Description
`account_guid`	String	The unique identifier for the `account` associated with the `holding`. Defined by MX.
`cost_basis`	Decimal	The cost basis is the original value of an asset adjusted for stock splits, dividends, and capital distributions.
`created_at`	String	Date and time the `holding` was created, represented in ISO 8601 format, with a timestamp.
`currency_code`	String	The three-character ISO 4217 currency code.
`cusip`	String	An identification number assigned to stocks and registered bonds.
`daily_change`	Decimal	The change from the previous day in the price of the `holding`.
`description`	String	A human-readable description of the holding.
`guid`	String	The unique identifier for the `holding`. Defined by MX.
`holding_type`	String	The type of `holding`, e.g., mutual fund, bond, etc.
`market_value`	Decimal	The market value of the holding.
`member_guid`	String	The unique identifier for the `member` associated with the `holding`.
`purchase_price`	String	The purchase price of the `holding`.
`shares`	Decimal	The number of shares 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`	String	The date and time the `holding` was last updated, represented in ISO 8601 format with timestamp.
`user_guid`	String	The unique identifier for the `user` associated with the `holding`.

Holding types

ANNUITY
CASH
EQUITY
EXCHANGE_TRADED_FUND
FIXED_INCOME
HEDGE_FUND
MONEY_MARKET
MUTUAL_FUND
OPTIONS
UNIT_INVESTMENT_TRUST
UNKNOWN_TYPE

List holdings by account

Use this endpoint to read all holdings associated with a specific account.

Endpoint:

GET users/{user_guid}/accounts/{account_guid}/holdings

Example request

1
2
3
4
$ curl -i 'https://vestibule.mx.com/users/USR-743e5d7f-1116-28fa-5de1-d3ba02e41d8d/accounts/ACT-d65683e8-9eab-26bb-bcfd-ced159c9abe2/holdings' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
{
  "holdings": [
    {
      "account_guid": "ACT-d65683e8-9eab-26bb-bcfd-ced159c9abe2",
      "cost_basis": 676,
      "created_at": "2015-04-13T12:01:23-06:00",
      "currency_code": "USD",
      "cusip": "18383M878",
      "daily_change": 2.59,
      "description": "Guggenheim Defensive Equity ETF",
      "guid": "HOL-d65683e8-9eab-26bb-bcfd-ced159c9abe2",
      "holding_type": "MONEY_MARKET",
      "market_value": 899.5,
      "member_guid": "MBR-d65683e8-9eab-26bb-bcfd-ced159c9abe",
      "purchase_price": 26.3,
      "shares": 6,
      "symbol": "DEF",
      "updated_at": "2015-04-13T12:01:23-06:00",
      "user_guid": "USR-743e5d7f-1116-28fa-5de1-d3ba02e41d8d"
    },
    {
      "account_guid": "ACT-d65683e8-9eab-26bb-bcfd-ced159c9abe2",
      "cost_basis": 827,
      "created_at": "2015-04-13T12:01:23-06:00",
      "currency_code": "USD",
      "cusip": "18383M878",
      "daily_change": 2.5,
      "description": "Guggenheim Defensive Equity ETF",
      "guid": "HOL-d65683e8-9eab-26bb-bcfd-ced159c9abe2",
      "holding_type": "MONEY_MARKET",
      "market_value": 989.5,
      "member_guid": "MBR-d65683e8-9eab-26bb-bcfd-ced159c9abe",
      "purchase_price": 26.3,
      "shares": 6,
      "symbol": "DEF",
      "updated_at": "2015-04-13T12:01:23-06:00",
      "user_guid": "USR-743e5d7f-1116-28fa-5de1-d3ba02e41d8d"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 1,
    "total_pages": 1
  }
}

List holdings by member

Use this endpoint to read all holdings associated with a specific member.

Endpoint:

GET users/{user_guid}/members/{member_guid}/holdings

Example request

1
2
3
4
$ curl -i 'https://vestibule.mx.com/users/USR-743e5d7f-1116-28fa-5de1-d3ba02e41d8d/members/MBR-d65683e8-9eab-26bb-bcfd-ced159c9abe/holdings' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
{
  "holdings": [
    {
      "account_guid": "ACT-d65683e8-9eab-26bb-bcfd-ced159c9abe2",
      "cost_basis": 676,
      "created_at": "2015-04-13T12:01:23-06:00",
      "currency_code": "USD",
      "cusip": "18383M878",
      "daily_change": 2.59,
      "description": "Guggenheim Defensive Equity ETF",
      "guid": "HOL-d65683e8-9eab-26bb-bcfd-ced159c9abe2",
      "holding_type": "MONEY_MARKET",
      "market_value": 899.5,
      "member_guid": "MBR-d65683e8-9eab-26bb-bcfd-ced159c9abe",
      "purchase_price": 26.3,
      "shares": 6,
      "symbol": "DEF",
      "updated_at": "2015-04-13T12:01:23-06:00",
      "user_guid": "USR-743e5d7f-1116-28fa-5de1-d3ba02e41d8d"
    },
    {
      "account_guid": "ACT-d65683e8-9eab-26bb-bcfd-ced159c9abe2",
      "cost_basis": 827,
      "created_at": "2015-04-13T12:01:23-06:00",
      "currency_code": "USD",
      "cusip": "18383M878",
      "daily_change": 2.5,
      "description": "Guggenheim Defensive Equity ETF",
      "guid": "HOL-d65683e8-9eab-26bb-bcfd-ced159c9abe2",
      "holding_type": "MONEY_MARKET",
      "market_value": 989.5,
      "member_guid": "MBR-d65683e8-9eab-26bb-bcfd-ced159c9abe",
      "purchase_price": 26.3,
      "shares": 6,
      "symbol": "DEF",
      "updated_at": "2015-04-13T12:01:23-06:00",
      "user_guid": "USR-743e5d7f-1116-28fa-5de1-d3ba02e41d8d"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 1,
    "total_pages": 1
  }
}

List holdings by user

Use this endpoint to read all holdings associated with a specific user.

Endpoint:

GET users/{user_guid}/holdings

Example request

1
2
3
4
$ curl -i 'https://vestibule.mx.com/users/USR-743e5d7f-1116-28fa-5de1-d3ba02e41d8d/holdings' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
{
  "holdings": [
    {
      "account_guid": "ACT-d65683e8-9eab-26bb-bcfd-ced159c9abe2",
      "cost_basis": 676,
      "created_at": "2015-04-13T12:01:23-06:00",
      "currency_code": "USD",
      "cusip": "18383M878",
      "daily_change": 2.59,
      "description": "Guggenheim Defensive Equity ETF",
      "guid": "HOL-d65683e8-9eab-26bb-bcfd-ced159c9abe2",
      "holding_type": "MONEY_MARKET",
      "market_value": 899.5,
      "member_guid": "MBR-d65683e8-9eab-26bb-bcfd-ced159c9abe",
      "purchase_price": 26.3,
      "shares": 6,
      "symbol": "DEF",
      "updated_at": "2015-04-13T12:01:23-06:00",
      "user_guid": "USR-743e5d7f-1116-28fa-5de1-d3ba02e41d8d"
    },
    {
      "account_guid": "ACT-d65683e8-9eab-26bb-bcfd-ced159c9abe2",
      "cost_basis": 827,
      "created_at": "2015-04-13T12:01:23-06:00",
      "currency_code": "USD",
      "cusip": "18383M878",
      "daily_change": 2.5,
      "description": "Guggenheim Defensive Equity ETF",
      "guid": "HOL-d65683e8-9eab-26bb-bcfd-ced159c9abe2",
      "holding_type": "MONEY_MARKET",
      "market_value": 989.5,
      "member_guid": "MBR-d65683e8-9eab-26bb-bcfd-ced159c9abe",
      "purchase_price": 26.3,
      "shares": 6,
      "symbol": "DEF",
      "updated_at": "2015-04-13T12:01:23-06:00",
      "user_guid": "USR-743e5d7f-1116-28fa-5de1-d3ba02e41d8d"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 1,
    "total_pages": 1
  }
}

Read a holding

Use this endpoint to read a specific holding associated with a specific user.

Endpoint:

GET users/{user_guid}/holdings/{holding_guid}

Example request

1
2
3
4
$ curl -i 'https://vestibule.mx.com/users/USR-743e5d7f-1116-28fa-5de1-d3ba02e41d8d/holdings/HOL-d65683e8-9eab-26bb-bcfd-ced159c9abe2' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "holding": {
    "account_guid": "HOL-d65683e8-9eab-26bb-bcfd-ced159c9abe2",
    "cost_basis": 827,
    "created_at": "2015-04-13T12:01:23-06:00",
    "currency_code": "USD",
    "cusip": "18383M878",
    "daily_change": 2.5,
    "description": "Guggenheim Defensive Equity ETF",
    "guid": "HOL-d65683e8-9eab-26bb-bcfd-ced159c9abe2",
    "holding_type": "MONEY_MARKET",
    "market_value": 989.5,
    "member_guid": "MBR-d65683e8-9eab-26bb-bcfd-ced159c9abe",
    "purchase_price": 26.3,
    "shares": 6,
    "symbol": "DEF",
    "updated_at": "2015-04-13T12:01:23-06:00",
    "user_guid": "USR-743e5d7f-1116-28fa-5de1-d3ba02e41d8d"
  }
}

Institutions

An institution represents a financial institution like Chase, Wells Fargo, or Mountain America Credit Union.

It’s important to point out that many real-world financial institutions will actually have several different institution objects within Atrium. This is because, for example, the banking and mortgage divisions of Wells Fargo may use separate online systems for accessing customer data, both of which may be different from the credit card division’s system, etc.

Institution fields

Field	Data type	Description
`code`	String	A unique identifier for each `institution`, defined by MX.
`medium_logo_url`	String	The URL for a 100px X 100px logo for each `institution`. A generic logo is returned for institutions that don’t have one.
`name`	String	An easy-to-read name for an `institution`, e.g., “Chase Bank” or “Wells Fargo Bank.”
`small_logo_url`	String	The URL for a 50px X 50px logo for each `institution`. A generic logo is returned for institutions that don’t have one.
`supports_account_identification`	Boolean	This indicates whether the `institution` supports account identification.
`supports_account_statement`	Boolean	This indicates whether the `institution` provides access to account statements.
`supports_account_verification`	Boolean	This indicates whether the `institution` supports account verification.
`supports_oauth`	Boolean	This indicates whether the `institution` supports OAuth authentication.
`supports_transaction_history`	Boolean	This indicates whether the `institution` allows access to up to 24 months of `transaction` data.
`url`	String	The URL for particular institution’s website , e.g., `www.chase.com`.

List or search institutions

This endpoint allows you to see what institutions are available for connection. Information returned will include the institution_code assigned to a particular institution, URLs for the financial institution’s logo, and the URL for its website.

This endpoint takes certain optional query string parameters to facilitate searching for specific institutions.

Parameter	Results
`name={string}`	Only institutions whose name contains the appended string will be returned.
`supports_account_identification=true`	Only institutions which support identity will be returned.
`supports_account_statement=true`	Only institutions which offer access to account statements will be returned.
`supports_account_verification=true`	Only institutions which support account verification will be returned.
`supports_transaction_history=true`	Only institutions which offer an extended transaction history will be returned.

Endpoint:

GET /institutions

Example request

1
2
3
4
$ curl -i 'https://vestibule.mx.com/institutions?name=chase' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "institutions": [
    {
      "code": "chase",
      "medium_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/default_100x100.png",
      "name": "Chase Bank",
      "small_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/default_50x50.png",
      "supports_account_identification": true,
      "supports_account_statement": true,
      "supports_account_verification": true,
      "supports_transaction_history": true,
      "url": "https://www.chase.com"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 1,
    "total_pages": 1
  }
}

Read institution

This endpoint allows you to see information for a specific institution.

Endpoint:

GET /institutions/{institution_code}

Example request

1
2
3
4
$ curl -i 'https://vestibule.mx.com/institutions/chase' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "institution": {
    "code": "chase",
    "medium_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/default_100x100.png",
    "name": "Chase Bank",
    "small_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/default_50x50.png",
    "supports_account_identification": true,
    "supports_account_statement": true,
    "supports_account_verification": true,
    "supports_transaction_history": true,
    "url": "https://www.chase.com"
  }
}

Read institution credentials

Use this endpoint to see which credentials will be needed to create a member for a specific institution.

Field	Data type	Description
`display_order`	Integer	The order in which the credential should be displayed to the end user; lower numbers should be displayed first.
`field_name`	String	Name of the credential field for the institution, e.g., “LOGIN”
`guid`	String	A unique identifier for the credential. Defined by MX.
`label`	String	A label for the credential, intended to be readable by the end user, e.g., “Username”
`type`	String	A name for the type of field, e.g., “PASSWORD”
`options`	Array	See explanation that immediately follows.

For credentials with the type OPTIONS, the credentials object will contain a nested array called options. This array lists various choices available for credential prompts, and includes further attributes.

Field	Data type	Description
`label`	String	A label for the credential prompt.
`value`	String	A response for the credential prompt.

Endpoint:

GET /institutions/{institution_code}/credentials

Example request

1
2
3
4
$ curl -i 'https://vestibule.mx.com/institutions/chase/credentials' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
    "credentials": [
        {
            "field_name": "login_email",
            "guid": "CRD-12ce94ad-032b-5441-8cb3-d7ebe3a35676",
            "label": "Email Address",
            "display_order": 0,
            "type": "LOGIN"
        },
        {
            "field_name": "login_password",
            "guid": "CRD-305767e4-f464-765b-8f83-881b5bd307ec",
            "label": "PayPal password",
            "display_order": 1,
            "type": "PASSWORD"
        }
    ]
}

Members

A member represents the relationship between a user and an institution, and creating one is how you connect one to the other. Thus, multiple members may be attached to a single user, e.g., one for their bank, another for their mortgage provider, another for their credit card provider, etc.

Member fields

Field	Data type	Description
`aggregated_at`	String	The date and time the most recent aggregation-type job was started, given in ISO 8601 format with a time component. A job will automatically be started when a member is created or its credentials are updated, unless the `skip_aggregation` parameter is used. Jobs can also be started via manual aggregations, background aggregations, API endpoints, or when opening an MX widget. A job can be a normal aggregation, or a premium job such as identification, verification, fetching statements, or fetching an extended transaction history. If a member is deleted and then re-created with the `skip_aggregation` parameter set to true or if it is re-created within the throttle window (typically three hours), the previous value will be returned.
`connection_status`	String	The status of a member’s aggregation.
`guid`	String	A unique identifier for the `member`. Defined by MX.
`identifier`	String	A unique, enforced identifier for the `member`. Defined by you.
`institution_code`	String	Unique identifier for the `institution`. Defined by MX.
`is_being_aggregated`	Boolean	This value is `true` if the `member` is being aggregated at the time of the request and `false` otherwise.
`metadata`	String	Additional information you can store on this `member`.
`name`	String	The name of the `member`. If omitted as a parameter when creating the `member`, the institution name within the MX platform will be used, e.g., “Chase Bank.”
`oauth_window_uri`	String	A URI which takes the end user to a UI for the registered OAuth application. This field only appears in a `member` response when creating an OAuth member or when requesting a URI with the generate OAuth window URI endpoint.
`status`	String	The status of a member’s aggregation. This field will soon be deprecated. Use `connection_status` above as more detailed indicator of a member’s status.
`successfully_aggregated_at`	String	The date and time the member was successfully aggregated.
`user_guid`	String	A unique identifier for the user. Defined by MX.

Aggregate member

Calling this endpoint initiates an aggregation event for the member. This gathers the latest account and transaction data from the connected institution. If this data has recently been updated, MX may not initiate an aggregation event.

If a standard aggregation is already running, a 202 Accepted status will be returned. If another aggregation-type process is already running — like verification or extended transaction history — a 409 Conflict will be returned.

For more information on this and other aggregation-type processes, please see our developer guide

Endpoint:

POST /users/{user_guid}/members/{member_guid}/aggregate

Example request

1
2
3
4
5
$ curl -i -X POST 'https://vestibule.mx.com/users/{user_guid}/members/{member_guid}/aggregate' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'Content-Type: application/json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "member": {
    "aggregated_at": "2016-10-13T18:07:57+00:00",
    "connection_status": "CONNECTED",
    "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "identifier": "unique_id",
    "institution_code": "chase",
    "is_being_aggregated": true,
    "metadata": "{\"credentials_last_refreshed_at\": \"2015-10-15\"}",
    "name": "Chase Bank",
    "status": "INITIATED",
    "successfully_aggregated_at": "2016-10-13T17:57:38+00:00",
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
  }
}

Aggregate member account balances

This endpoint operates much like the aggregate member endpoint except that it gathers only account balance information; it does not gather any transaction data at all.

If an account balance aggregation is already running, a 202 Accepted status will be returned. If another aggregation-type process is already running — like verification or extended transaction history — a 409 Conflict will be returned.

Repeated calls to this endpoint for the same member can only be made at intervals greater than two hours. If made more frequently, a 429 Too Many Requests status will be returned.

For more information on this and other aggregation-type processes, please see our developer guide

Endpoint:

POST /users/{user_guid}/members/{member_guid}/balance

Example request

1
2
3
4
5
6
curl -X POST \
  https://vestibule.mx.com/users/{user_guid}/members/{member_guid}/balance \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'Content-Type: application/json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "member": {
    "aggregated_at": "2019-10-07T16:25:27Z",
    "connection_status": "EXPIRED",
    "guid": "MBR-a4652b66-3ee5-cb9f-295a-72eddef61db5",
    "identifier": null,
    "institution_code": "mxbank",
    "is_being_aggregated": true,
    "metadata": null,
    "name": "MX Bank",
    "status": "INITIATED",
    "successfully_aggregated_at": "2019-10-07T15:58:59Z",
    "user_guid": "USR-72aba5cc-8c74-b22c-227c-4b1c095fa12e"
  }
}

Create member

This endpoint allows you to create a new member. Standard members are created with the required parameters credentials and institution_code.

Standard Members

When creating a standard member, you’ll need to include the correct type of credential required by the financial institution, with values provided by the end user. You can find out which credential type is required with the read institution credentials endpoint.

Once you successfully create a standard member, MX will immediately validate the provided credentials and attempt to aggregate data for accounts and transactions. You can prevent this automatic aggregation by setting the skip_aggregation parameter to true.

OAuth Members

OAuth members can only be created with institutions that support it. OAuth members require no credentials, but do require you to set the is_oauth parameter to true.

New OAuth members will be created with a connection status of PENDING; e redirect URI will be provided in the oauth_window_uri field of the response. Making a separate request to the MX-provided oauth_window_uri will then take the end user to their financial institution’s website where they can log in and select what data to share with MX. After completing the OAuth process, aggregation automatically will begin and the connection status will be updated, unless the skip_aggregation parameter was set to true.

oauth_window_uris are one-time use. Don’t hard code an expected URI into your application.

Don’t prepend the https:// protocol to the URI string, as MX includes this.

Parameter	Required?
`identifier`	No
`institution_code`	Yes
`metadata`	No
`skip_aggregation`	No
`is_oauth`	No
`referral_source`	No
`client_redirect_url`	No
`ui_message_webview_url_scheme`	No

Endpoint:

POST /users/{user_guid}/members

Example request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
$ curl -i -X POST 'https://vestibule.mx.com/users/{user_guid}/members' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'Content-Type: application/json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}' \
  -d '{
        "member": {
          "institution_code": "chase",
          "credentials": [
            {
              "guid": "CRD-1ec152cd-e628-e81a-e852-d1e7104624da",
              "value": "ExampleUsername"
            },
            {
              "guid": "CRD-1ec152cd-e628-e81a-e852-d1e7104624da",
              "value": "Pa$$vv@Rd"
            }
          ],
          "skip_aggregation": true
        }
      }'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "member": {
    "aggregated_at": "2016-10-13T17:57:36+00:00",
    "connection_status": "CONNECTED",
    "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "identifier": "unique_id",
    "institution_code": "chase",
    "is_being_aggregated": true,
    "metadata": "{\"credentials_last_refreshed_at\": \"2015-10-15\"}",
    "name": "Chase Bank",
    "status": "INITIATED",
    "successfully_aggregated_at": null,
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
  }
}

Example request for OAuth member

1
2
3
4
5
6
7
8
9
10
11
12
13
14
$ curl -i -X POST 'https://vestibule.mx.com/users/{user_guid}/members' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'Content-Type: application/json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}' \
  -d '{
        "member":{
          "institution_code":"mx_bank_oauth",
          "metadata": "Additional information",
          "is_oauth": true
        },
        "referral_source": "APP",
        "client_redirect_url": "https://mx.com"
      }'

Example response for OAuth member

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "member": {
    "aggregated_at": "2016-10-13T17:57:36+00:00",
    "connection_status": "PENDING",
    "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "identifier": "unique_id",
    "institution_code": "mx_bank_oauth",
    "is_being_aggregated": true,
    "metadata": "Additional information",
    "name": "MX Bank (OAuth)",
    "oauth_window_uri": "https://mxbank.mx.com/oauth/authorize?client_id=b8OikQ4Ep3NuSUrQ13DdvFuwpNx-qqoAsJDVAQCyLkQ&redirect_uri=https%3A%2F%2Fint-app.moneydesktop.com%2Foauth%2Fredirect_from&response_type=code&scope=openid&state=d273e4f71bc095cf16c4acbee011caf4",
    "status": null,
    "successfully_aggregated_at": null,
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
  }
}

Delete member

Accessing this endpoint will permanently delete a member.

Endpoint:

DELETE /users/{user_guid}/members/{member_guid}

Example request

1
2
3
4
$ curl -i -X DELETE 'https://vestibule.mx.com/users/{user_guid}/members/{member_guid}' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H

Example response

1
Status: 204 No Content

Generate OAuth window URI

This endpoint will generate an oauth_window_uri for the specified member.

Generating a new oauth_window_uri is necessary in order to send the end user through the OAuth process again. There are several situations where you might want to do this. Below are a few examples:

A previous attempt at OAuth failed — for instance if the end user closed the OAuth window before completing the process.
The financial institution has revoked a previous OAuth token or the token has expired.

The member in question must be connected to an institution which supports OAuth. if the institution does not support OAuth, a 400 Bad Request error will be returned with the message Member cannot use OAuth.

Query parameters

Parameter	Data type	Description	Required?
`skip_aggregation`	Boolean	Setting this parameter to `true` will prevent the member from automatically aggregating after being redirected from the authorization page.	No
`referral_source`	String	Must be either `BROWSER` or `APP` depending on the implementation. Defaults to `BROWSER`.	No
`client_redirect_url`	String	A URL that MX will redirect to at the end of OAuth with additional query parameters. Only available with `referral_source: "APP"`	No
`ui_message_webview_url_scheme`	String	A scheme for routing the user back to the application state they were previously in. Only available with `referral_source: "APP"`	No

Endpoint:

GET /users/{user_guid}/members/{member_guid}/oauth_window_uri

Example request

1
2
3
4
$ curl -i 'https://vestibule.mx.com/users/{user_guid}/members/{member_guid}/oauth_window_uri' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "member": {
    "aggregated_at": "2016-10-13T18:07:57+00:00",
    "connection_status": "CONNECTED",
    "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "identifier": "unique_id",
    "institution_code": "mx_bank_oauth",
    "is_being_aggregated": false,
    "metadata": "{\"credentials_last_refreshed_at\": \"2015-10-15\"}",
    "name": "MX Bank (OAuth)",
    "oauth_window_uri": "https://mxbank.mx.com/oauth/authorize?client_id=b8OikQ4Ep3NuSUrQ13DdvFuwpNx-qqoAsJDVAQCyLkQ&redirect_uri=https%3A%2F%2Fint-app.moneydesktop.com%2Foauth%2Fredirect_from&response_type=code&scope=openid&state=d273e4f71bc095cf16c4acbee011caf4",
    "status": "COMPLETED",
    "successfully_aggregated_at": "2016-10-13T17:57:38+00:00",
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
  }
}

List members

This endpoint returns an array which contains information on every member associated with a specific user.

Endpoint:

GET /users/{user_guid}/members

Example request

1
2
3
4
$ curl -i 'https://vestibule.mx.com/users/{user_guid}/members' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "members": [
    {
      "aggregated_at": "2016-10-13T18:07:57+00:00",
      "connection_status": "CONNECTED",
      "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
      "identifier": "unique_id",
      "institution_code": "chase",
      "is_being_aggregated": true,
      "metadata": "{\"credentials_last_refreshed_at\": \"2015-10-15\"}",
      "name": "Chase Bank",
      "status": "INITIATED",
      "successfully_aggregated_at": "2016-10-13T17:57:38+00:00",
      "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 1,
    "total_pages": 1
  }
}

List member credentials

This endpoint returns an array which contains information on every non-MFA credential associated with a specific member.

Field	Data type	Description
`display_order`	Integer	The order in which the credential should be displayed to the end user; lower numbers should be displayed first.
`field_name`	String	Name of the credential field for the institution, e.g., “LOGIN”.
`guid`	String	A unique identifier for the `credential`. Defined by MX.
`label`	String	A label for the `credential`, intended to be readable by the end user, e.g., `Username`.
`type`	String	A name for the type of field, e.g., `PASSWORD`.

Endpoint:

GET /users/{user_guid}/members/{member_guid}/credentials

Example request

1
2
3
4
$ curl -i 'https://vestibule.mx.com/users/{user_guid}/members/{member_guid}/credentials' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
    "credentials": [
        {
            "field_name": "login_email",
            "guid": "CRD-12ce94ad-032b-5441-8cb3-d7ebe3a35676",
            "label": "Email Address",
            "display_order": 0,
            "type": "LOGIN"
        },
        {
            "field_name": "login_password",
            "guid": "CRD-305767e4-f464-765b-8f83-881b5bd307ec",
            "label": "PayPal password",
            "display_order": 1,
            "type": "PASSWORD"
        }
    ]
}

List member accounts

This endpoint returns an array with information about every account associated with a particular member.

Endpoint:

GET /users/{user_guid}/members/{member_guid}/accounts

Example request

1
2
3
4
$ curl -i 'https://vestibule.mx.com/users/{user_guid}/members/{member_guid}/accounts' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
{
  "accounts": [
    {
      "apr": 1.12,
      "apy": 1.13,
      "available_balance": 1000.23,
      "available_credit": 100.23,
      "balance": 1000.23,
      "created_at": "2016-10-13T17:57:37+00:00",
      "credit_limit": 100,
      "currency_code": "USD",
      "day_payment_is_due": 20,
      "guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
      "institution_code": "chase",
      "interest_rate": null,
      "is_closed": false,
      "last_payment": null,
      "last_payment_at": null,
      "matures_on": null,
      "member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
      "minimum_balance": null,
      "minimum_payment": null,
      "name": "Test Account 2",
      "original_balance": null,
      "payment_due_at": null,
      "payoff_balance": null,
      "started_on": null,
      "subtype": null,
      "total_account_value": null,
      "type": "SAVINGS",
      "updated_at": "2016-10-13T18:08:00+00:00",
      "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 1,
    "total_pages": 1
  }
}

List member MFA challenges

Use this endpoint for information on what multi-factor authentication challenges need to be answered in order to aggregate a member.

If the aggregation is not challenged, i.e., the member does not have a connection status of CHALLENGED, then code 204 No Content will be returned.

If the aggregation has been challenged, i.e., the member does have a connection status of CHALLENGED, then code 200 OK will be returned — along with the corresponding challenges.

Field Name	Data type	Description
`field_name`	string	A non-unique identifier for the question.
`guid`	String	A unique identifier for the challenge, defined by MX.
`label`	String	A readable question that is presented to the user.
`type`	String	The type of challenge. Supported types include `TEXT`, `OPTIONS`, `TOKEN`, `IMAGE_DATA`, `IMAGE_OPTIONS`.
`image_data`	String	This field contains image data encoded as a base64 string. It will only be present when the challenge type is `IMAGE_DATA`.
`image_options`	Array	For challenge type `IMAGE_OPTIONS`, this field represents an array of choices. It will only be present when the challenge type is `IMAGE_OPTIONS`.
`options`	Array	For challenge type `OPTIONS`, this field represents an array of choices. It will only be present when the challenge type is `OPTIONS`.

Endpoint:

GET /users/{user_guid}/members/member_guid}/challenges

Example request

1
2
3
4
$ curl -i 'https://vestibule.mx.com/users/{user_guid}/members/{member_guid}/challenges' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}'

Example response for challenge type TEXT

1
2
3
4
5
6
7
8
9
10
{
  "challenges": [
    {
      "field_name": "What city were you born in?",
      "guid": "CRD-1ec152cd-e628-e81a-e852-d1e7104624da",
      "label": "What city were you born in?",
      "type": "TEXT"
    }
  ]
}

Example response for challenge type IMAGE_DATA

1
2
3
4
5
6
7
8
9
10
11
{
  "challenges": [
    {
      "field_name": "Who is this guy?",
      "guid": "CRD-ce76d2e3-86bd-ec4a-ec52-eb53b5194bf5",
      "label": "Who is this guy?",
      "type": "IMAGE_DATA",
      "image_data": "data:image/png;base64,iVBORw0KGgoAAAANSUh ... more image data ..."
    }
  ]
}

Example response for challenge type OPTIONS

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "challenges": [
    {
      "field_name": "One time passcode",
      "guid": "CRD-ce76d2e3-86bd-ec4a-ec52-eb53b5194bf5",
      "label": "Where should we send your one time passcode?",
      "type": "OPTIONS",
      "options": [
        {
          "label": "user_email@provider.org",
          "value": "0"
        },
        {
          "label": "(XXX) XXX-1234",
            "value": "1"
        },
        {
          "label": "(XXX) XXX-2345",
          "value": "2"
        }
      ]
    }
  ]
}

Example response for challenge type IMAGE_OPTIONS

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
  "challenges": [
    {
      "field_name": "Choose your image",
      "guid": "CRD-ce76d2e3-86bd-ec4a-ec52-eb53b5194bf5",
      "label": "Which is your image?",
      "type": "IMAGE_OPTIONS",
      "image_options": [
        {
          "label": "IMAGE_1",
          "value": "1",
          "data_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUh ... more image data ..."
        },
        {
          "label": "IMAGE_2",
          "value": "2",
          "data_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUh ... more image data ..."
        },
        {
          "label": "IMAGE_3",
          "value": "3",
          "data_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUh ... more image data ..."
        },
        {
          "label": "IMAGE_4",
          "value": "4",
          "data_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUh ... more image data ..."
        }
      ]
    }
  ]
}

List member transactions

Use this endpoint to get all transactions from all accounts associated with a specific member.

The from_date and to_date parameters can optionally be appended to the request if transactions in a specific date range are required.

Query string parameters

Field name	Required	Description
`from_date`	No	Return transactions occurring within a date range starting on this day. If not set, this defaults to 90 days prior to the day of the request. Must be in ISO 8601 format without a time component.
`to_date`	No	Return transactions occurring in a date range ending on this day. If not set, this defaults to 5 days forward from the day of the request so as to capture pending transactions. Must be in ISO 8601 format without a time component.

Endpoint:

GET /users/{user_guid}/members/{member_guid}/transactions

Example request

1
2
3
4
$ curl -i 'https://vestibule.mx.com/users/{user_guid}/members/{member_guid}/transactions' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
{
  "transactions": [
    {
      "account_guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
      "amount": 61.11,
      "category": "Groceries",
      "check_number": 15234,
      "check_number_string": "00015234",
      "created_at": "2016-10-06T09:43:42+00:00",
      "currency_code": "USD",
      "date": "2013-09-23",
      "description": "Whole Foods",
      "guid": "TRN-265abee9-889b-af6a-c69b-25157db2bdd9",
      "is_bill_pay": false,
      "is_direct_deposit": false,
      "is_expense": true,
      "is_fee": false,
      "is_income": false,
      "is_international": false,
      "is_overdraft_fee": false,
      "is_payroll_advance": false,
      "latitude": -43.2075,
      "longitude": 139.691706,
      "member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
      "memo": null,
      "merchant_category_code": 5411,
      "original_description": "WHOLEFDS TSQ 102",
      "posted_at": "2016-10-07T06:00:00+00:00",
      "status": "POSTED",
      "top_level_category": "Food & Dining",
      "transacted_at": "2016-10-06T13:00:00+00:00",
      "type": "DEBIT",
      "updated_at": "2016-10-07T05:49:12+00:00",
      "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 1,
    "total_pages": 1
  }
}

Read member

Use this endpoint to read the attributes of a specific member.

Endpoint:

GET /users/{user_guid}/members/{member_guid}

Example request

1
2
3
4
$ curl -i 'https://vestibule.mx.com/users/{user_guid}/members/{member_guid}' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "member": {
    "aggregated_at": "2016-10-13T18:07:57+00:00",
    "connection_status": "CONNECTED",
    "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "identifier": "unique_id",
    "institution_code": "chase",
    "is_being_aggregated": false,
    "metadata": "{\"credentials_last_refreshed_at\": \"2015-10-15\"}",
    "name": "Chase Bank",
    "status": "COMPLETED",
    "successfully_aggregated_at": "2016-10-13T17:57:38+00:00",
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"    
  }
}

Read member connection status

This endpoint provides the status of the member’s most recent aggregation-type event. This is an important step in the aggregation process (as well as identification, verification, etc.), and the results returned by this endpoint should determine what you do next in order to successfully aggregate a member.

MX has introduced new, more detailed information on the current status of a member’s connection to a financial institution and the state of its aggregation: the connection_status field. These are intended to replace and expand upon the information provided in the status field, which will soon be deprecated; support for the status field remains for the time being.

Member connection statuses should be used in conjunction with all the fields described below. For instance, when is_being_aggregated switches from true to false and the value of connection_status is CONNECTED, you can stop polling the status and list the member’s transactions or list the transactions for a specific account.

The response for this endpoint is not the same as the read member endpoint; this endpoint returns fields which are specifically focused on the state of the member’s aggregation, as well as including MFA challenges when the connection_status is CHALLENGED.

MX recommends a minimum polling interval of 3 seconds when using this endpoint.

Read member connection status fields

Field	Data type	Description
`aggregated_at`	String	The date and time the account was last aggregated.
`challenges`	Array	An array containing MFA challenges that have been issued. `challenges` will only be present when the `connection_status` is `CHALLENGED`.
`connection_status`	String	The status of a member’s aggregation. Read more about these statuses here.
`guid`	String	A unique identifier for the `member`. Defined by MX.
`has_processed_accounts`	Boolean	`true` when accounts have been processed for a `member`, `false` otherwise. Resets each time `/aggregate` is called.
`has_processed_transactions`	Boolean	`true` when transactions have been processed for a `member`, `false` otherwise. Resets each time `/aggregate` is called.
`is_authenticated`	Boolean	If the member’s credentials were authenticated during the most recent aggregation, this field will be `true`. Otherwise, this field will be `false`. Resets to `false` each time `/aggregate` is called. This field does not indicate that an aggregation is completed — only that the credentials used were good; MFA or other connection problems may occur while this value is `true`.
`is_being_aggregated`	Boolean	This value is `true` if the `member` is being aggregated at the time of the request and `false` otherwise.
`status`	String	The status of a member’s aggregation. This field will soon be deprecated. Use `connection_status` above as more detailed indicator of a member’s status.
`successfully_aggregated_at`	String	The date and time the member was successfully aggregated.

Status definitions (soon to be deprecated)

`status`	Description	Next steps
`INITIATED`	Aggregation has started.
`REQUESTED`	Request to get the data has started.
`CHALLENGED`	MFA challenged returned.	Resume `member` with updated credentials.
`RECEIVED`	Received response back from the request.
`TRANSFERRED`	Start saving the data into the MX Platform.
`PROCESSED`	Data has been processed into the MX Platform.
`COMPLETED`	Aggregation is complete.	List `member` accounts and transactions.
`PREVENTED`	Aggregation was prevented due to too many login attempts.	List member credentials, update member.
`DENIED`	Authentication failed due to invalid credentials or incorrect MFA answer.	List member credentials, update member. If MFA was answered incorrectly, restart aggregation.
`HALTED`	An exception occurred that was unrelated to authentication.	Retry aggregation tomorrow. If the `member` hits the `HALTED` status for 3 or more days, leave the member in its current state and contact support by submitting a ticket here.

Endpoint:

GET /users/{user_guid}/members/{member_guid}/status

Example request

1
2
3
4
$ curl -i 'https://vestibule.mx.com/users/{user_guid}/members/{member_guid}/status' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "member": {
    "aggregated_at": "2019-06-08T17:21:05Z",
    "connection_status": "CONNECTED",
    "guid": "MBR-a4652b66-3ee5-cb9f-295a-72eddef61db5",
    "has_processed_accounts": true,
    "has_processed_transactions": true,
    "is_authenticated": true,
    "is_being_aggregated": false,
    "status": "COMPLETED",
    "successfully_aggregated_at": "2019-06-07T21:16:03Z"
  }
}

Connection statuses

Connection status definitions

Connection status id (integer)	Connection status (string)	Definition	Next steps	End-user message
null	null	The member exists but does not have credentials.	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	MX is preventing aggregation until the member’s credentials have been updated.	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 member has been challenged by multi-factor authentication.	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 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.	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.	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.	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.

Resume aggregation from MFA

This endpoint answers the challenges needed when a member has been challenged by multi-factor authentication.

Endpoint:

PUT /users/{user_guid}/members/{member_guid}/resume

Example request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
$ curl -i -X PUT 'https://vestibule.mx.com/users/{user_guid}/members/{member_guid}/resume' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'Content-Type: application/json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}' \
  -d '{
        "member":{
          "challenges":[
            {
               "guid": "institution-credential-guid",
               "value": "user-entered-value"
            },
            {
              "guid": "institution-credential-guid",
               "value": "user-entered-value"
            }
          ]
        }
      }'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "member": {
    "aggregated_at": "2016-09-30T14:31:45-06:00",
    "connection_status": "RESUMED",
    "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "identifier":"unique_id",
    "institution_code": "chase",
    "is_being_aggregated": true,
    "metadata": "{\"credentials_last_refreshed_at\": \"2015-10-15\"}",
    "name": "Bank Name",
    "status": "RECEIVED",
    "successfully_aggregated_at": null,
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
  }
}

Update member

Use this endpoint to update a member’s attributes. Only the credentials, identifier, and metadata parameters can be updated. To get a list of the required credentials for the member, use the list member credentials endpoint.

Parameter	Required?
`background_aggregation_is_disabled`	No
`credentials`	No
`identifier`	No
`metadata`	No

Endpoint:

PUT /users/{user_guid}/members/{member_guid}

Example request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
$ curl -i -X PUT 'https://vestibule.mx.com/users/{user_guid}/members/{member_guid}' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'Content-Type: application/json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}' \
  -d '{
        "member":{
          "credentials":[
            {
               "guid": "CRD-598ec8d4-6200-8cda-345d-3dbb5fc17716",
               "value": "updated-username"
            },
            {
               "guid": "CRD-27d0edb8-1d50-5b90-bcbc-be270ca42b9f",
               "value": "updated-password"
            }
          ],
          "metadata": "{\"credentials_last_refreshed_at\": \"2015-10-16\"}"
        }
      }'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "member": {
    "aggregated_at": "2016-09-30T14:43:44-06:00",
    "connection_status": "CONNECTED",
    "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "identifier": "unique_id",
    "institution_code": "chase",
    "is_being_aggregated": false,
    "metadata": "{\"credentials_last_refreshed_at\": \"2015-10-16\"}",
    "name": "Bank Name",
    "status": "INITIATED",
    "successfully_aggregated_at": "2016-09-30T14:38:59-06:00",
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"    
  }
}

Merchants

A merchant contains information about the merchant, business, company, or seller associated with a specific transaction. This information includes a name, logo, and website.

Merchant fields

Field	Data type	Description
`created_at`	String	The date and time at which the `merchant` was created.
`guid`	String	The unique identifier for the `merchant`. Defined by MX.
`logo_url`	String	The URL for a 100px X 100px logo for the `merchant`.
`logo_updated_at`	String	The date and time the logo associated with this `merchant` was last updated.
`name`	String	A human-readable name for the `merchant` for display to the end user.
`updated_at`	String	The date and time at which the `merchant` was last updated.
`website_url`	String	The URL for the merchant’s website, e.g. `https://www.xfinity.com`.

List merchants

This endpoint returns a paginated list containing information on every merchant available in Atrium.

Endpoint:

GET /merchants

Example request

1
2
3
4
$ curl -i 'https://vestibule.mx.com/merchants' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
  "merchants": [
    {
      "created_at": "2018-09-17T19:13:53Z",
      "guid": "MCH-ad6d3405-ec03-721d-b0ca-eeceeebcb8b5",
      "logo_updated_at": "2021-08-09T16:19:23Z",
      "logo_url": "https://content.mx.com/logos/merchants/MCH-ad6d3405-ec03-721d-b0ca-eeceeebcb8b5.png",
      "name": "1-800 Contacts",
      "updated_at": "2021-08-09T16:19:23Z",
      "website_url": "https://www.1800contacts.com"
    },
    {
      "created_at": "2018-07-16T16:31:35Z",
      "guid": "MCH-dfef19bb-1af4-bbaa-db41-434b4b1c8f04",
      "logo_updated_at": "2021-02-19T15:58:10Z",
      "logo_url": "https://content.mx.com/logos/merchants/MCH-dfef19bb-1af4-bbaa-db41-434b4b1c8f04.png",
      "name": "1-800-Flowers.com",
      "updated_at": "2021-02-19T15:58:10Z",
      "website_url": "https://www.1800flowers.com"
    },
    {
      "created_at": "2018-04-23T20:23:59Z",
      "guid": "MCH-9559c6fb-c05f-ee9e-bb33-ce23078df1a0",
      "logo_updated_at": "2021-02-19T16:15:59Z",
      "logo_url": "https://content.mx.com/logos/merchants/MCH-9559c6fb-c05f-ee9e-bb33-ce23078df1a0.png",
      "name": "24 Hour Fitness",
      "updated_at": "2021-02-19T16:15:59Z",
      "website_url": "https://www.24hourfitness.com"
    },
•••
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 11443,
    "total_pages": 458
  }
}

Read merchant

The necessary merchant_guid can be determined by reading or listing transactions, as well as categorizing transactions.

The logo_url follows a pattern using a base URL: https://content.mx.com/logos/merchants/ + merchant_guid + .png. For example: https://content.mx.com/logos/merchants/MCH-ad2e487b-34e4-4b2b-820d-603e330d0ca9.png

MX may need to change this base URL from time to time, but in such cases partners will be notified and a redirect will be set up for the previous base URL.

The logo returned will be 100px X 100px.

Endpoint:

GET /merchants/{merchant_guid}

Example request

1
2
3
4
$ curl -i 'https://vestibule.mx.com/merchants/{merchant_guid}' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
{
  "merchant": {
    "created_at": "2018-09-17T19:13:53Z",
    "guid": "MCH-ad6d3405-ec03-721d-b0ca-eeceeebcb8b5",
    "logo_updated_at": "2021-08-09T16:19:23Z",
    "logo_url": "https://content.mx.com/logos/merchants/MCH-ad6d3405-ec03-721d-b0ca-eeceeebcb8b5.png",
    "name": "1-800 Contacts",
    "updated_at": "2021-08-09T16:19:23Z",
    "website_url": "https://www.1800contacts.com"
  }
}

Merchant locations

Merchant locations detail the physical address, longitude, latitude, contact information, etc. for a specific location of a merchant.

Merchant location fields

Field	Data Type	Definition
`city`	String	The city in which the `merchant` is located.
`country`	String	The country in which the `merchant` is located.
`guid`	String	The unique identifier for the `merchant` location. Defined by MX.
`latitude`	Decimal	The latitude of the `merchant` location. This number is a signed decimal (e.g., Rio de Janeiro’s latitude is -22.9027800 and Tokyo’s latitude is 35.689488).
`longitude`	Decimal	The longitude of the `merchant` location. This number is a signed decimal (e.g., Rio de Janeiro’s longitude is -43.2075000 and Tokyo’s longitude is 139.691706).
`merchant_guid`	String	The unique identifier for the `merchant` to which this location belongs. Defined by MX.
`phone_number`	String	The phone number for the `merchant` location.
`postal_code`	String	The postal code in which the `merchant` is located.
`state`	String	The state in which the `merchant` is located.
`store_number` (deprecated)	String	The store number for the `merchant` location. This will be removed in the next version.
`street_address`	String	The street address at which the `merchant` is located.
`updated_at`	String	The date and time the `merchant_location` was last updated.

Read merchant location

This endpoint returns the specified merchant_location resource.

Endpoint:

GET /merchant_locations/{merchant_location_guid}

1
2
3
4
curl -i 'https://vestibule.mx.com/merchant_locations/{merchant_location_guid}' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "merchant_location": {
    "city": "Greenwood Village",
    "country": "US",
    "guid": "MCL-00024e59-18b5-4d79-b879-2a7896726fea",
    "latitude": 39.5963005,
    "longitude": -104.89158799999998,
    "merchant_guid": "MCH-09466f0a-fb58-9d1a-bae2-2af0afbea621",
    "phone_number": "(303) 689-0728",
    "postal_code": "801121436",
    "state": "CO",
    "store_number": null,
    "street_address": "8547 E Arapahoe Rd, Ste 1",
    "updated_at": "2020-04-13T21:05:09Z"
  }
}

Transactions

A transaction represents any instance in which money moves into or out of an account. This could be 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.

Transaction fields

Field	Data type	Description
`account_guid`	String	A unique identifier for the `account` to which the transaction belongs. Defined by MX.
`amount`	Decimal	The monetary amount of the `transaction`. Max length is 10,2.
`category`	String	The category of the `transaction`.
`check_number`	Integer	DEPRECATED. Use `check_number_string` instead.
`check_number_string`	String	The check number for the `transaction`.
`created_at`	String	The date and time the transaction was stored in the MX system.
`currency_code`	String	The three-character ISO 4217 currency code, e.g. `USD`.
`date`	String	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 `original_description` field described below, e.g., “Sam’s Club,” “Johnny’s Tavern.” This is provided by the MX Platform.
`guid`	String	A unique identifier for the `transaction`. Defined by MX.
`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_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 have this 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 fee, this field will be `true`. Otherwise, this field will be `false`.
`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).
`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).
`member_guid`	String	A unique identifier for the `member` to which the transaction belongs. Defined by MX.
`memo`	string	This field contains additional descriptive information about the `transaction`.
`merchant_category_code`	Integer	The ISO 18245 category code for the transaction.
`merchant_guid`	String	The unique identifier for the `merchant` associated with this transaction. Defined by MX.
`merchant_location_guid`	String	The unique identifier for the `merchant_location` associated with this transaction. Defined by MX.
`original_description`	String	The original description of the transaction as provided by our data feed. See `description` above for more information.
`posted_at`	String	The date and time the transaction was posted to the account.
`status`	String	The status of the transaction, i.e., `POSTED` or `PENDING`.
`top_level_category`	String	The parent category that this transaction’s category is assigned to.
`transacted_at`	String	The date and time the `transaction` took place.
`type`	String	The type of transaction, i.e., `CREDIT` or `DEBIT`.
`updated_at`	String	The date and time the transaction was updated.
`user_guid`	String	A unique identifier for the `user` to which this `transaction` belongs. Defined by MX.

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

Merchant category codes

Merchant category code	MX category	Merchant category
742	Veterinary	Veterinary Services
763	Food & Dining	Agricultural Cooperative
780	Lawn & Garden	Landscaping Services
1520	Home Improvement	General Contractors
1711	Home Improvement	Heating, Plumbing, A/C
1731	Home Improvement	Electrical Contractors
1740	Home Improvement	Masonry, Stonework, and Plaster
1750	Home Improvement	Carpentry Contractors
1761	Home Improvement	Roofing/Siding, Sheet Metal
1771	Home Improvement	Concrete Work Contractors
1799	Home Improvement	Special Trade Contractors
2741	Printing	Miscellaneous Publishing and Printing
2791	Printing	Typesetting, Plate Making, and Related Services
2842	Home Services	Specialty Cleaning
3000	Air Travel	Default Category For 3000-3301
3351	Rental Car & Taxi	Default Category For 3351-3441
3501	Hotel	Default Category For 3501-3836
4011	Travel	Railroads
4111	Travel	Commuter Transport, Ferries
4112	Travel	Passenger Railways
4119	Doctor	Ambulance Services
4121	Rental Car & Taxi	Taxicabs/Limousines
4131	Travel	Bus Lines
4214	Shipping	Motor Freight Carriers and Trucking
4215	Shipping	Courier Services
4225	Shipping	Public Warehousing and Storage - Farm Products, Refrigerated Goods
4411	Travel	Cruise Lines
4457	Travel	Boat Rentals and Leases
4468	Travel	Marinas, Service and Supplies
4511	Air Travel	Airlines, Air Carriers
4582	Travel	Airports, Flying Fields
4722	Travel	Travel Agencies, Tour Operators
4723	Travel	TUI Travel - Germany
4784	Travel	Tolls/Bridge Fees
4789	Travel	Transportation Services (Not Elsewhere Classified)
4812	Home Phone	Telecommunication Equipment and Telephone Sales
4814	Home Phone	Telecommunication Services
4816	Internet	Computer Network Services
4821	Bills & Utilities	Telegraph Services
4829	Transfer	Wires, Money Orders
4899	Utilities	Cable, Satellite, and Other Pay Television and Radio
4900	Utilities	Utilities
5013	Service & Parts	Motor Vehicle Supplies and New Parts
5021	Furnishings	Office and Commercial Furniture
5039	Home Improvement	Construction Materials (Not Elsewhere Classified)
5044	Business Services	Photographic, Photocopy, Microfilm Equipment, and Supplies
5045	Electronics & Software	Computers, Peripherals, and Software
5046	Shopping	Commercial Equipment (Not Elsewhere Classified)
5047	Health & Fitness	Medical, Dental, Ophthalmic, and Hospital Equipment and Supplies
5051	Home	Metal Service Centers
5065	Home	Electrical Parts and Equipment
5072	Home	Hardware, Equipment, and Supplies
5074	Home	Plumbing, Heating Equipment, and Supplies
5085	Home	Industrial Supplies (Not Elsewhere Classified)
5094	Shopping	Precious Stones and Metals, Watches and Jewelry
5099	Shopping	Durable Goods (Not Elsewhere Classified)
5111	Office Supplies	Stationary, Office Supplies, Printing and Writing Paper
5122	Pharmacy	Drugs, Drug Proprietaries, and Druggist Sundries
5131	Clothing	Piece Goods, Notions, and Other Dry Goods
5137	Clothing	Uniforms, Commercial Clothing
5139	Clothing	Commercial Footwear
5169	Home	Chemicals and Allied Products (Not Elsewhere Classified)
5172	Gas	Petroleum and Petroleum Products
5192	Books	Books, Periodicals, and Newspapers
5193	Shopping	Florists Supplies, Nursery Stock, and Flowers
5198	Home Supplies	Paints, Varnishes, and Supplies
5199	Home	Nondurable Goods (Not Elsewhere Classified)
5200	Home	Home Supply Warehouse Stores
5211	Home	Lumber, Building Materials Stores
5231	Home	Glass, Paint, and Wallpaper Stores
5251	Home	Hardware Stores
5261	Lawn & Garden	Nurseries, Lawn and Garden Supply Stores
5271	Shopping	Mobile Home Dealers
5300	Shopping	Wholesale Clubs
5309	Shopping	Duty Free Stores
5310	Shopping	Discount Stores
5311	Shopping	Department Stores
5331	Shopping	Variety Stores
5399	Shopping	Miscellaneous General Merchandise
5411	Groceries	Grocery Stores, Supermarkets
5422	Groceries	Freezer and Locker Meat Provisioners
5441	Groceries	Candy, Nut, and Confectionery Stores
5451	Groceries	Dairy Products Stores
5462	Groceries	Bakeries
5499	Groceries	Miscellaneous Food Stores - Convenience Stores and Specialty Markets
5511	Auto & Transport	Car and Truck Dealers (New & Used) Sales, Service, Repairs Parts and Leasing
5521	Auto & Transport	Car and Truck Dealers (Used Only) Sales, Service, Repairs Parts and Leasing
5531	Auto & Transport	Auto and Home Supply Stores
5532	Auto & Transport	Automotive Tire Stores
5533	Auto & Transport	Automotive Parts and Accessories Stores
5541	Gas	Service Stations
5542	Gas	Automated Fuel Dispensers
5551	Auto & Transport	Boat Dealers
5561	Auto & Transport	Motorcycle Shops, Dealers
5571	Auto & Transport	Motorcycle Shops and Dealers
5592	Auto & Transport	Motor Homes Dealers
5598	Sporting Goods	Snowmobile Dealers
5599	Auto & Transport	Miscellaneous Auto Dealers
5611	Clothing	Men’s and Boy’s Clothing and Accessories Stores
5621	Clothing	Women’s Ready-To-Wear Stores
5631	Clothing	Women’s Accessory and Specialty Shops
5641	Clothing	Children’s and Infant’s Wear Stores
5651	Clothing	Family Clothing Stores
5655	Clothing	Sports and Riding Apparel Stores
5661	Clothing	Shoe Stores
5681	Clothing	Furriers and Fur Shops
5691	Clothing	Men’s, Women’s Clothing Stores
5697	Clothing	Tailors, Alterations
5698	Hair	Wig and Toupee Stores
5699	Clothing	Miscellaneous Apparel and Accessory Shops
5712	Furnishings	Furniture, Home Furnishings, and Equipment Stores, Except Appliances
5713	Furnishings	Floor Covering Stores
5714	Furnishings	Drapery, Window Covering, and Upholstery Stores
5718	Furnishings	Fireplace, Fireplace Screens, and Accessories Stores
5719	Furnishings	Miscellaneous Home Furnishing Specialty Stores
5722	Home	Household Appliance Stores
5732	Electronics & Software	Electronics Stores
5733	Music	Music Stores-Musical Instruments, Pianos, and Sheet Music
5734	Electronics & Software	Computer Software Stores
5735	Music	Record Stores
5811	Restaurants	Caterers
5812	Restaurants	Eating Places, Restaurants
5813	Alcohol & Bars	Drinking Places
5814	Fast Food	Fast Food Restaurants
5815	Entertainment	Digital Goods Media - Books, Movies, Music
5816	Entertainment	Digital Goods - Games
5817	Shopping	Digital Goods - Applications (Excludes Games)
5818	Shopping	Digital Goods - Large Digital Goods Merchant
5912	Pharmacy	Drug Stores and Pharmacies
5921	Alcohol & Bars	Package Stores-Beer, Wine, and Liquor
5931	Clothing	Used Merchandise and Secondhand Stores
5932	Shopping	Antique Shops
5933	Shopping	Pawn Shops
5935	Service & Parts	Wrecking and Salvage Yards
5937	Shopping	Antique Reproductions
5940	Sporting Goods	Bicycle Shops
5941	Sporting Goods	Sporting Goods Stores
5942	Books	Book Stores
5943	Office Supplies	Stationery Stores, Office, and School Supply Stores
5944	Shopping	Jewelry Stores, Watches, Clocks, and Silverware Stores
5945	Shopping	Hobby, Toy, and Game Shops
5946	Shopping	Camera and Photographic Supply Stores
5947	Shopping	Gift, Card, Novelty, and Souvenir Shops
5948	Shopping	Luggage and Leather Goods Stores
5949	Shopping	Sewing, Needlework, Fabric, and Piece Goods Stores
5950	Shopping	Glassware, Crystal Stores
5960	Financial	Direct Marketing - Insurance Services
5962	Travel	Direct Marketing - Travel
5963	Shopping	Door-To-Door Sales
5964	Shopping	Direct Marketing - Catalog Merchant
5965	Shopping	Direct Marketing - Combination Catalog and Retail Merchant
5966	Shopping	Direct Marketing - Outbound Tele
5967	Shopping	Direct Marketing - Inbound Tele
5968	Shopping	Direct Marketing - Subscription
5969	Shopping	Direct Marketing - Other
5970	Shopping	Artist’s Supply and Craft Shops
5971	Arts	Art Dealers and Galleries
5972	Shopping	Stamp and Coin Stores
5973	Shopping	Religious Goods Stores
5975	Health & Fitness	Hearing Aids Sales and Supplies
5976	Health & Fitness	Orthopedic Goods - Prosthetic Devices
5977	Personal Care	Cosmetic Stores
5978	Office Supplies	Typewriter Stores
5983	Gas	Fuel Dealers (Non Automotive)
5992	Shopping	Florists
5993	Shopping	Cigar Stores and Stands
5994	Books	News Dealers and Newsstands
5995	Pet Food & Supplies	Pet Shops, Pet Food, and Supplies
5996	Home	Swimming Pools Sales
5997	Personal Care	Electric Razor Stores
5998	Shopping	Tent and Awning Shops
5999	Shopping	Miscellaneous Specialty Retail
6010	Cash	Manual Cash Disburse
6011	Cash	Automated Cash Disburse
6012	Financial	Financial Institutions
6050	Uncategorized	Quasi Cash - Member Financial Institution
6051	Transfer	Non-FI, Money Orders
6211	Investments	Security Brokers/Dealers
6300	Financial	Insurance Underwriting, Premiums
6399	Financial	Insurance - Default
6513	Mortgage & Rent	Real Estate Agents and Managers - Rentals
6536	Transfer	MoneySend Intracountry
6540	Uncategorized	Non-Financial Institutions - Stored Value Card Purchase/Load
7011	Hotel	Hotels, Motels, and Resorts
7012	Vacation	Timeshares
7032	Vacation	Sporting/Recreation Camps
7033	Vacation	Trailer Parks, Campgrounds
7210	Laundry	Laundry, Cleaning Services
7211	Laundry	Laundries
7216	Laundry	Dry Cleaners
7217	Home Services	Carpet/Upholstery Cleaning
7221	Shopping	Photographic Studios
7230	Hair	Barber and Beauty Shops
7251	Clothing	Shoe Repair/Hat Cleaning
7261	Uncategorized	Funeral Services, Crematories
7273	Entertainment	Dating/Escort Services
7276	Financial	Tax Preparation Services
7277	Doctor	Counseling Services
7278	Shopping	Buying/Shopping Services
7296	Clothing	Clothing Rental
7297	Spa & Massage	Massage Parlors
7298	Spa & Massage	Health and Beauty Spas
7299	Business Services	Miscellaneous General Services
7311	Advertising	Advertising Services
7321	Financial	Credit Reporting Agencies
7333	Business Services	Commercial Photography, Art and Graphics
7338	Printing	Quick Copy, Repro, and Blueprint
7339	Business Services	Secretarial Support Services
7342	Home	Exterminating Services
7349	Home	Cleaning and Maintenance
7361	Business Services	Employment/Temp Agencies
7372	Business Services	Computer Programming
7375	Business Services	Information Retrieval Services
7379	Electronics & Software	Computer Repair
7392	Business Services	Consulting, Public Relations
7393	Business Services	Detective Agencies
7394	Business Services	Equipment Rental
7395	Business Services	Photo Developing
7399	Business Services	Miscellaneous Business Services
7511	Gas	Truck Stop
7512	Rental Car & Taxi	Car Rental Agencies
7513	Rental Car & Taxi	Truck/Utility Trailer Rentals
7519	Rental Car & Taxi	Recreational Vehicle Rentals
7523	Parking	Parking Lots, Garages
7531	Service & Parts	Auto Body Repair Shops
7534	Service & Parts	Tire Retreading and Repair
7535	Service & Parts	Auto Paint Shops
7538	Service & Parts	Auto Service Shops
7542	Service & Parts	Car Washes
7549	Service & Parts	Towing Services
7622	Electronics & Software	Electronics Repair Shops
7623	Home	A/C, Refrigeration Repair
7629	Home	Small Appliance Repair
7631	Shopping	Watch/Jewelry Repair
7641	Furnishings	Furniture Repair, Refinishing
7692	Service & Parts	Welding Repair
7699	Service & Parts	Miscellaneous Repair Shops
7829	Movies & DVDs	Picture/Video Production
7800	Entertainment	Government-Owned Lotteries
7801	Entertainment	Government Licensed On-Line Casinos (On-Line Gambling)
7802	Entertainment	Government-Licensed Horse/Dog Racing
7832	Movies & DVDs	Motion Picture Theaters
7841	Movies & DVDs	Video Tape Rental Stores
7911	Entertainment	Dance Hall, Studios, Schools
7922	Entertainment	Theatrical Ticket Agencies
7929	Entertainment	Bands, Orchestras
7932	Entertainment	Billiard/Pool Establishments
7933	Entertainment	Bowling Alleys
7941	Entertainment	Sports Clubs/Fields
7991	Entertainment	Tourist Attractions and Exhibits
7992	Entertainment	Golf Courses - Public
7993	Entertainment	Video Amusement Game Supplies
7994	Entertainment	Video Game Arcades
7995	Entertainment	Betting/Casino Gambling
7996	Entertainment	Amusement Parks/Carnivals
7997	Entertainment	Country Clubs
7998	Entertainment	Aquariums
7999	Entertainment	Miscellaneous Recreation Services
8011	Doctor	Doctors
8021	Dentist	Dentists, Orthodontists
8031	Doctor	Osteopaths
8041	Doctor	Chiropractors
8042	Eyecare	Optometrists, Ophthalmologist
8043	Eyecare	Opticians, Eyeglasses
8044	Eyecare	Opticians, Eyeglasses
8049	Doctor	Chiropodists, Podiatrists
8050	Health & Fitness	Nursing/Personal Care
8062	Doctor	Hospitals
8071	Doctor	Medical and Dental Labs
8099	Doctor	Medical Services
8111	Legal	Legal Services, Attorneys
8211	Education	Elementary, Secondary Schools
8220	Education	Colleges, Universities
8241	Education	Correspondence Schools
8244	Education	Business/Secretarial Schools
8249	Education	Vocational/Trade Schools
8299	Education	Educational Services
8351	Babysitter & Daycare	Child Care Services
8398	Gifts & Donations	Charitable and Social Service Organizations - Fundraising
8641	Gifts & Donations	Civic, Social, Fraternal Associations
8651	Gifts & Donations	Political Organizations
8661	Gifts & Donations	Religious Organizations
8675	Gifts & Donations	Automobile Associations
8699	Gifts & Donations	Membership Organizations
8734	Health & Fitness	Testing Laboratories
8911	Business Services	Architectural/Surveying Services
8931	Business Services	Accounting/Bookkeeping Services
8999	Business Services	Professional Services
9211	Legal	Court Costs, Including Alimony and Child Support - Courts of Law
9222	Legal	Fines - Government Administrative Entities
9223	Legal	Bail and Bond Payments
9311	Taxes	Tax Payments - Government Agencies
9399	Uncategorized	Government Services (Not Elsewhere Classified)
9402	Shipping	Postal Services - Government Only
9405	Taxes	U.S. Federal Government Agencies or Departments
9950	Business Services	Intra-Company Purchases

Transaction statuses

Transactions may have one of two statuses: PENDING or POSTED. How these statuses are reconciled depends on a number of factors.

All transaction data on MX systems represent what we get through our data feed, i.e., what institutions make available for aggregation. Many institutions simply do not provide data for pending transactions; transactions from those accounts will always have a status of POSTED.
For pending data we do get, it is sometimes possible for a single transaction to be updated from PENDING to POSTED and keep the same unique GUID. This is done through various matching methods performed automatically by MX.
If a single transaction can’t be updated, the PENDING transaction will often be deleted and replaced with a new POSTED transaction (with a new GUID) when it is sent to us; this is the most common scenario when pending data is available.
In unusual circumstances, there may be separate PENDING and POSTED transactions on MX systems for up to 14 days. All PENDING transactions are deleted after 14 days as a failsafe.

Categorize transactions

Use this endpoint to categorize, cleanse, and classify transactions. These transactions are not persisted or stored on the MX platform.

Parameters

Field name	Required?
`amount`	No
`description`	Yes
`identifier`	Yes
`merchant_category_code`	No
`type`	No

Field	Data type	Definition
`amount`	Decimal	The monetary amount of the `transaction`.
`categorized_by`	Integer	The method used to determine the category assigned to the `transaction`.
`category`	String	The category of the `transaction`.
`category_guid`	String	The unique identifier for the `category` assigned to the `transaction`.
`described_by`	Integer	The method used to describe the `transaction`.
`description`	String	A human-readable version of the `original_description` field described below, e.g., “Sam’s Club,” “Johnny’s Tavern.” This is provided by the MX Platform.
`identifier`	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_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 have 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_subscription`	Boolean	This indicates whether the transaction represents a payment for a subscription service such as Netflix or Audible.
`memo`	String	This field contains additional descriptive information about the `transaction`.
`merchant_category_code`	Integer	The ISO 18245 category code for the transaction.
`merchant_guid`	String	The unique identifier for the `merchant` associated with this transaction. Defined by MX.
`merchant_location_guid`	String	The unique identifier for the `merchant_location` associated with this transaction. Defined by MX.
`original_description`	String	The original description of the transaction as provided by our data feed. See `description` above for more information.
`type`	String	The type of transaction. This will be either `CREDIT` or `DEBIT`.

Categorized_by values

Integer	Enum	Definition
0	CATEGORIZATION_SOURCE_AUTOCAT	This is obsolete and will no longer assign categories.
1	CATEGORIZATION_SOURCE_USER	The end user assigned a category manually.
2	CATEGORIZATION_SOURCE_FEED	The data feed assigned a category.
3	CATEGORIZATION_SOURCE_LEVENSHTEIN	This is obsolete and will no longer assign categories.
4	CATEGORIZATION_SOURCE_PARSER	A parser created by MX assigned the category based on patterns in the available data.
5	CATEGORIZATION_SOURCE_TRAINER	This is obsolete and will no longer assign categories.
6	CATEGORIZATION_SOURCE_SPHINX	This is obsolete and will no longer assign categories.
7	CATEGORIZATION_SOURCE_NAIVE_BAYES	This is obsolete and will no longer assign categories.
8	CATEGORIZATION_SOURCE_TERMINATION	After other methods failed to assign a category, it was set to ‘UNCATEGORIZED’.
9	CATEGORIZATION_SOURCE_KEYWORD_CATEGORIZER	The category was assigned based on keywords appearing in the original description (feed description).
10	CATEGORIZATION_SOURCE_CATCHER	The category was assigned by a catcher based on the available data.
11	CATEGORIZATION_SOURCE_HOPSCOTCH	This is obsolete and will no longer assign categories.
12	CATEGORIZATION_SOURCE_USER_RULE	A transaction rule created by the end user assigned the category.
13	CATEGORIZATION_SOURCE_SYSTEM_RULE	A transaction rule created by MX assigned the category.
14	CATEGORIZATION_SOURCE_CLIENT_RULE	A transaction rule created by the partner assigned the category.
15	CATEGORIZATION_SOURCE_MERCHANT_CATEGORY_CODE	The category was assigned based on the merchant category code.
16	CATEGORIZATION_SOURCE_FLOOR	The transaction was assigned `UNCATEGORIZED` because it was uncategorizable as such, rather than because other methods failed; for example, the description simply contained `withdrawal` with no other information.
17	CATEGORIZATION_SOURCE_QUICKVERSE	The category was assigned by a machine-learning model.
18	CATEGORIZATION_SOURCE_MAPPING	The category was assigned by mapping from our new extended category system to legacy categories. This new system has yet to be fully released to clients.
19	CATEGORIZATION_SOURCE_TRANSFER_CATEGORIZER	The category was assigned by a categorizer designed specifically to look for transfers.

Described_by values

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.

Endpoint:

POST /transactions/cleanse_and_categorize

Example request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
$ curl -i -X POST 'https://vestibule.mx.com/transactions/cleanse_and_categorize' \
-H 'Content-Type: application/json' \
-H 'Accept: application/vnd.mx.atrium.v1+json' \
-H 'MX-API-Key: {mx_api_key}' \
-H 'MX-Client-ID: {mx_client_id}' \
-d '{
  "transactions": [
      {
          "amount": 11.22,
          "description": "BEER BAR 65000000764SALT LAKE C",
          "identifier": "12",
          "merchant_category_code": 6011,
          "type": "DEBIT"
      },
      {
          "amount": 21.33,
          "description": "IN-N-OUT BURGER #239AMERICAN FO",
          "identifier": "13",
          "merchant_category_code": 6011,
          "type": "DEBIT"
      },
      {
          "amount": 1595.33,
          "description": "ONLINE PAYMENT - THANK YOU",
          "identifier": "14",
          "type": "CREDIT"
      }
  ]
}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
{
  "transactions": [
    {
      "amount": 11.22,
      "categorized_by": 15,
      "category": "Cash",
      "category_guid": "CAT-08a5d861-2890-686e-ebaf-d7632ec88540",
      "described_by": 0,
      "description": "Beer Bar",
      "identifier": "12",
      "is_bill_pay": null,
      "is_direct_deposit": false,
      "is_expense": null,
      "is_fee": null,
      "is_income": false,
      "is_international": null,
      "is_overdraft_fee": false,
      "is_payroll_advance": null,
      "is_subscription": null,
      "memo": null,
      "merchant_category_code": 6011,
      "merchant_guid": null,
      "merchant_location_guid": null,
      "original_description": "BEER BAR 65000000764SALT LAKE C",
      "type": "DEBIT"
    },
    {
      "amount": 21.33,
      "categorized_by": 15,
      "category": "Cash",
      "category_guid": "CAT-08a5d861-2890-686e-ebaf-d7632ec88540",
      "described_by": 6,
      "description": "In-N-Out Burger",
      "identifier": "13",
      "is_bill_pay": null,
      "is_direct_deposit": null,
      "is_expense": null,
      "is_fee": null,
      "is_income": false,
      "is_international": null,
      "is_overdraft_fee": null,
      "is_payroll_advance": null,
      "is_subscription": null,
      "memo": null,
      "merchant_category_code": 6011,
      "merchant_guid": "MCH-4a889eb0-0459-f66f-a137-c5e06409d8e6",
      "merchant_location_guid": null,
      "original_description": "IN-N-OUT BURGER #239AMERICAN FO",
      "type": "DEBIT"
    },
    {
      "amount": 1595.33,
      "categorized_by": 13,
      "category": "Credit Card Payment",
      "category_guid": "CAT-2cc9b500-e09d-88be-e3e0-0a8a82a54586",
      "described_by": 6,
      "description": "Online Payment Thank You",
      "identifier": "14",
      "is_bill_pay": null,
      "is_direct_deposit": null,
      "is_expense": null,
      "is_fee": null,
      "is_income": false,
      "is_international": null,
      "is_overdraft_fee": null,
      "is_payroll_advance": null,
      "is_subscription": null,
      "memo": null,
      "merchant_category_code": null,
      "merchant_guid": null,
      "merchant_location_guid": null,
      "original_description": "ONLINE PAYMENT - THANK YOU",
      "type": "CREDIT"
    }
  ]
}

List transactions for a user

Use this endpoint to get all transactions that belong to a specific user, across all the user’s members and accounts.

The from_date and to_date parameters can optionally be appended to the request if transactions in a specific date range are required.

Query string parameters

Field name	Required?	Data type	Description
`from_date`	No	String	Return transactions occurring within a date range starting on this day. If not set, this defaults to 90 days prior to the day of the request. Must be in ISO 8601 format without a time component.
`to_date`	No	String	Return transactions occurring in a date range ending on this day. If not set, this defaults to 5 days forward from the day of the request so as to capture pending transactions. Must be in ISO 8601 format without a time component.

Endpoint:

GET /users/{user_guid}/transactions

Example URL with query parameters

https://vestibule.mx.com/users/{user_guid}/transactions?from_date=2016-09-20&to_date=2016-10-20

Example request

1
2
3
4
$ curl -i 'https://vestibule.mx.com/users/{user_guid}/transactions' \
-H 'Accept: application/vnd.mx.atrium.v1+json' \
-H 'MX-API-Key: {mx_api_key}' \
-H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
{
  "transactions": [
    {
      "account_guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
      "amount": 61.11,
      "category": "Groceries",
      "check_number": 15234,
      "check_number_string": "00015234",
      "created_at": "2016-10-06T09:43:42+00:00",
      "currency_code": "USD",
      "date": "2013-09-23",
      "description": "Whole Foods",
      "guid": "TRN-265abee9-889b-af6a-c69b-25157db2bdd9",
      "is_bill_pay": false,
      "is_direct_deposit": false,
      "is_expense": true,
      "is_fee": false,
      "is_income": false,
      "is_international": false,
      "is_overdraft_fee": false,
      "is_payroll_advance": false,
      "is_subscription": false,
      "latitude": -43.2075,
      "longitude": 139.691706,
      "member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
      "memo": null,
      "merchant_category_code": 5411,
      "merchant_guid": "MCH-7ed79542-884d-2b1b-dd74-501c5cc9d25b",
      "merchant_location_guid": null,
      "original_description": "WHOLEFDS TSQ 102",
      "posted_at": "2016-10-07T06:00:00+00:00",
      "status": "POSTED",
      "top_level_category": "Food & Dining",
      "transacted_at": "2016-10-06T13:00:00+00:00",
      "type": "DEBIT",
      "updated_at": "2016-10-07T05:49:12+00:00",
      "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
    },
    {
      "account_guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
      "amount": 23.4,
      "category": "Books",
      "check_number": 15234,
      "check_number_string": "00015234",
      "created_at": "2016-08-26T09:43:42+00:00",
      "currency_code": "USD",
      "date": "2013-09-23",
      "description": "Audible",
      "guid": "TRN-265abee9-889b-af6a-c69b-25157db2bdd9",
      "is_bill_pay": false,
      "is_direct_deposit": false,
      "is_expense": true,
      "is_fee": false,
      "is_income": false,
      "is_international": false,
      "is_overdraft_fee": false,
      "is_payroll_advance": false,
      "is_subscription": false,
      "latitude": -43.2075,
      "longitude": 139.691706,
      "member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
      "memo": null,
      "merchant_category_code": 5411,
      "merchant_guid": "MCH-7ed79542-884d-2b1b-dd74-501c5cc9d25b",
      "merchant_location_guid": null,
      "original_description": "AUDIBLEBKS",
      "posted_at": "2016-08-27T06:00:00+00:00",
      "status": "POSTED",
      "top_level_category": "Entertainment",
      "transacted_at": "2016-08-26T13:00:00+00:00",
      "type": "DEBIT",
      "updated_at": "2016-08-27T05:49:12+00:00",
      "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 2,
    "total_pages": 1
  }
}

Read a transaction

This endpoint allows you to view information about a specific transaction that belongs to a user.

Endpoint:

GET /users/{user_guid}/transactions/{transaction_guid}

Example request

1
2
3
4
$ curl -i 'https://vestibule.mx.com/users/{user_guid}/transactions/{transaction_guid}' \
-H 'Accept: application/vnd.mx.atrium.v1+json' \
-H 'MX-API-Key: {mx_api_key}' \
-H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
  "transaction": {
    "account_guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
    "amount": 61.11,
    "category": "Groceries",
    "check_number": 15234,
    "check_number_string": "00015234",
    "created_at": "2016-10-06T09:43:42+00:00",
    "currency_code": "USD",
    "date": "2013-09-23",
    "description": "Whole Foods",
    "guid": "TRN-265abee9-889b-af6a-c69b-25157db2bdd9",
    "is_bill_pay": false,
    "is_direct_deposit": false,
    "is_expense": true,
    "is_fee": false,
    "is_income": false,
    "is_international": false,
    "is_overdraft_fee": false,
    "is_payroll_advance": false,
    "is_subscription": false,
    "latitude": -43.2075,
    "longitude": 139.691706,
    "member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "memo": null,
    "merchant_category_code": 5411,
    "merchant_guid": "MCH-7ed79542-884d-2b1b-dd74-501c5cc9d25b",
    "merchant_location_guid": null,
    "original_description": "WHOLEFDS TSQ 102",
    "posted_at": "2016-10-07T06:00:00+00:00",
    "status": "POSTED",
    "top_level_category": "Food & Dining",
    "transacted_at": "2016-10-06T13:00:00+00:00",
    "type": "DEBIT",
    "updated_at": "2016-10-07T05:49:12+00:00",
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
  }
}

Users

A user represents a person using Atrium via your application, be it a mobile app, web app, desktop app, etc.

User fields

Field	Data Type	Description
`guid`	String	A unique identifier, defined by MX.
`identifier`	String	A unique, enforced identifier for the user, defined by you.
`is_disabled`	Boolean	True if you want the user disabled, false otherwise.
`metadata`	String	Additional information you can store about this user. MX recommends using JSON-structured data.

Create user

Call this endpoint to create a new user. Atrium will respond with the newly-created user object if successful.

This endpoint accepts several parameters: identifier, metadata, and is_disabled. The identifier and metadata fields are discussed above.

Disabling a user means that accounts and transactions associated with it will not be updated in the background by MX. It will also restrict access to that user’s data until they are no longer disabled.

Parameters

Field	Data Type	Required?
`identifier`	String	No
`is_disabled`	Boolean	No
`metadata`	String	No

Endpoint:

POST /users

Example request

1
2
3
4
5
6
7
8
9
10
11
$ curl -i -X POST 'https://vestibule.mx.com/users' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'Content-Type: application/json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}' \
  -d '{
        "user": {
          "identifier": "unique_id",
          "metadata": "{\"first_name\": \"Steven\"}"
        }
      }'

Example response

1
2
3
4
5
6
7
8
{
  "user": {
    "guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54",
    "identifier": "unique_id",
    "is_disabled": false,
    "metadata": "{\"first_name\": \"Steven\"}"
  }
}

Delete user

Calling this endpoint will permanently delete a user from Atrium. If successful, the API will respond with Status: 204 No Content.

Endpoint:

DELETE /users/{user_guid}

Example request

1
2
3
4
$ curl -i -X DELETE 'https://vestibule.mx.com/users/{user_guid}' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}'

Example response

1
Status: 204 No Content

List users

Use this endpoint to list every user you’ve created in Atrium.

Endpoint:

GET /users

Example request

1
2
3
4
$ curl -i 'https://vestibule.mx.com/users' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 2,
    "total_pages": 1
  },
  "users": [
    {
      "guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54",
      "identifier": "unique_id",
      "is_disabled": false,
      "metadata": "{\"first_name\": \"Steven\"}"
    },
    {
      "guid": "USR-7c6f361b-e582-15b6-60c0-358f12466b4b",
      "identifier": "unique_id",
      "is_disabled": false,
      "metadata": "{\"first_name\": \"Barb\"}"
    }
  ]
}

Read user

Use this endpoint to read the attributes of a specific user.

Endpoint:

GET /users/{user_guid}

Example request

1
2
3
4
$ curl -i 'https://vestibule.mx.com/users/{user_guid}' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
{
  "user": {
    "guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54",
    "identifier": "unique_id",
    "is_disabled": false,
    "metadata": "{\"first_name\": \"Steven\", \"last_name\": \"Universe\"}"
  }
}

Update user

Use this endpoint to update the attributes of a specific user. Atrium will respond with the updated user object.

To disable a user, update it and set the is_disabled parameter to true. Set it to false to re-enable the user.

Parameters

Field	Data Type	Required?
`identifier`	String	No
`is_disabled`	Boolean	No
`metadata`	String	No

Endpoint:

PUT /users/{user_guid}

Example request

1
2
3
4
5
6
7
8
9
10
$ curl -i -X PUT 'https://vestibule.mx.com/users/{user_guid}' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'Content-Type: application/json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}' \
  -d '{
        "user": {
          "metadata": "{\"first_name\": \"Steven\", \"last_name\": \"Universe\"}"
        }
      }'

Example response

1
2
3
4
5
6
7
8
{
  "user": {
    "guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54",
    "identifier": "unique_id",
    "is_disabled": false,
    "metadata": "{\"first_name\": \"Steven\", \"last_name\": \"Universe\"}"
  }
}

MX Connect widget

Connect is a ready-made and embeddable application that allows you to quickly add members to Atrium and navigate the complex aggregation process. It searches for institutions, creates new members, gathers credentials, prompts for MFA, resolves errors, and can start verification and aggregation jobs.

You can use Connect by embedding it in a website with an iframe or a mobile application with a WebView.

Get a URL

To get started with the Connect Widget, you will first need to create a user and then get a widget URL by making a POST request to /users/{user_guid}/connect_widget_url. You can also use one of our wrapper libraries to make this request.

Endpoint:

POST /users/{user_guid}/connect_widget_url

Example request

1
2
3
4
5
6
7
8
9
$ curl -i -X POST 'https://vestibule.mx.com/users/{user_guid}/connect_widget_url' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'Content-Type: application/json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}'
  -d '{
        "color_scheme": "dark",
        "mode": "verification"
      }'

Example response

1
2
3
4
5
6
{
  "user": {
    "connect_widget_url": "https://int-widgets.moneydesktop.com/md/connect/jb1rA14m85tw2lyvpgfx4gc6d3Z8z8Ayb8",
    "guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
  }
}

Configuration

Configuring the MX Connect widget really unlocks the potential and power of the widget. Configuration will help you with tasks like loading the widget for a specific institution, answering MFA, fixing a member in bad state, and more.

Options reference

Option	Data Type	Description
`client_redirect_url`	String	Specifies a URL to redirect the user to at the end of the OAuth. Must be used with `is_mobile_webview: true` or `oauth_referral_source: "APP"`
`color_scheme`	String	Load the Connect widget in the specified `color_scheme`; options are `light` and `dark`. Defaults to `light`.
`current_institution_code`	String	Load the widget into the credential view for the specified institution.
`current_member_guid`	String	Load to a specific member that contains an error or requires MFA from the most recent job. `current_member_guid` takes precedence over `current_institution_code`.
`disable_background_agg`	Boolean	Set to `true` or `false` to explicitly set the value of `background_aggregation_is_disabled` for new members created through the Connect widget
`disable_institution_search`	Boolean	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_instituion_guid`, or `current_member_guid`
`include_identity`	Boolean	When set to `true`, the widget will include an identity job with whatever other job it was configured to complete. Defaults to `false`. Can be used with `verification` or `aggregation` mode.
`include_transactions`	Boolean	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`.
`is_mobile_webview`	Boolean	Renders the widget in a mobile WebView. Executes URL updates in place of the JavaScript event postMessages.
`mode`	String	(Default) `aggregation` mode is used to retrieve data from multiple accounts to MX. `verification` mode securely retrieves account and routing/transit numbers. Learn more
`oauth_referral_source`	String	Specify what context the widget is in for OAuth purposes. Either “APP” or “BROWSER”. Defaults to “BROWSER”.
`ui_message_version`	Number	Use this to specify which version of postMessage events are triggered. All new implementations should use version 4. Prior versions are deprecated.
`ui_message_webview_url_scheme`	String	Used in postMessages and OAuth redirects in WebViews. Defaults to `atrium`.
`update_credentials` (not recommended)	Boolean	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.

Loading a specific institution

MX Connect can be loaded directly into a specific institution for gathering credentials.

You should consider using this configuration with the disable_institution_search option to prevent the end user from going back to the search and loading a separate institution manually.

Example request

1
2
3
4
5
6
7
# Load MXConnect with the given institution
$ curl -i -X POST 'https://vestibule.mx.com/users/{user_guid}/connect_widget_url' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'Content-Type: application/json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}' \
  -d '{ "current_institution_code": {bank code} }'

Loading a specific member

MX Connect can prompt for MFA, updating old credentials, or “repair” members that are in a bad state. This is done by loading Connect directly into a specific member.

Rather than trying to figure out what do with with each and every connection_status, it is often best to simply load Connect with the member_guid in question and allow it to automatically determine the best course of action for the end user.

You should consider using this configuration with the disable_institution_search option to prevent the end user from going back to the search to create a new member.

MX does not recommend using this configuration with the update_credentials option.

Example request

1
2
3
4
5
6
7
# Load MXConnect with the given member
$ curl -i -X POST 'https://vestibule.mx.com/users/{user_guid}/connect_widget_url' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'Content-Type: application/json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}' \
  -d '{ "current_member_guid": {member_guid} }'

Verification mode

Setting the mode to verification will change several behaviors in Connect:

The end user will be prompted to verify an existing connection (if they have one) before going to search.
Connect will only search for and display institutions that support verification.
After gathering credentials, Connect will start a verification job rather than an aggregation job.

Example request

1
2
3
4
5
6
7
# Load MXConnect in "verification" mode
$ curl -i -X POST 'https://vestibule.mx.com/users/{user_guid}/connect_widget_url' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'Content-Type: application/json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}' \
  -d '{ "mode": "verification" }'

Include identity

If you need to collect identity (account owner) data in addition to verification or aggregation, you can use the include_identity option.

If set to true, the widget will run an identity job in addition to the job defined by the mode parameter (aggregation or verification).

Example scenario:

You are using the Connect widget in verification mode for account and routing numbers, but need account owners as well. You can add include_identity: true to your configuration and the widget will:
- Only display institutions and members that support both verification and identity.

Start a verification job first; if this succeeds, it will then attempt an identification job.

The widget will handle all MFA and error paths that may happen and will not send the member connected event until both jobs are complete.

There is currently no standalone identity mode. Identity jobs must be run in addition to either verification or aggregation.

Example Request

1
2
3
4
5
6
7
# Load MXConnect in "verification" mode with include identity
$ curl -i -X POST 'https://vestibule.mx.com/users/{user_guid}/connect_widget_url' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'Content-Type: application/json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}' \
  -d '{ "mode": "verification", "include_identity": true }'

Mobile WebViews

It is imperative that you correctly configure Connect when embedding in a WebView. See the webview section for more information.

Waiting for "full" aggregation

The wait_for_full_aggregation 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. Using false is no longer supported or advised.

This change does not require anyone to update their integration and only affects the timing of the member connected post message.

Excluding transaction data

Sometimes you don’t need transaction data right away, or you may be concerned that gathering transaction data may take some time and delay your preferred flow. For those who don’t need the transaction data up front, you can use set the include_transactions option to false to potentially speed up a first-time aggregation.

Example request

1
2
3
4
5
6
7
# Do not include transaction data in the aggregation job after the user is connected
$ curl -i -X POST 'https://vestibule.mx.com/users/{user_guid}/connect_widget_url' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'Content-Type: application/json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}' \
  -d '{ "include_transactions": false }'

Embedding in a website

Once you’ve generated a URL, you can pass that to the web SDK. This SDK eases the integration between your webapp and the Connect widget’s iframe.

The example on the right is using the UMD build. But other options are available.

See the options reference for more details on what options can be passed.

Example usage

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <script src="node_modules/@mxenabled/web-widget-sdk/dist/umd/index.js" type="text/javascript"></script>
  <style>
    #connect-widget {
      width:  400px;
      height: 800px;
      margin: 0 auto;
    }
  </style>
</head>
<body>
  <div id="connect-widget"></div>
  <script type="text/javascript">
    const widget = new widgetSdk.ConnectWidget({
      url: "(Widget URL from the API)",
      container: "#connect-widget"
    })
  </script>
</body>
</html>

Embedding in WebViews

Because of the technical limitations of WebView-based implementations, an alternative to standard postMessages is required. If Connect is configured with is_mobile_webview set to true, we will use navigation events with window.location = url instead of window.postMessage(message)

ui_message_webview_url_scheme will be atrium:// by default.

Example navigation event schema:

{ui_message_webview_url_scheme}://{some/path}?metadata={jsonString}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
public class MainActivity extends AppCompatActivity {
    private WebView webView = null;
    @Override
    protected void onCreate(Bundle savedInstanceState) {
      webView = (WebView) findViewById(R.id.webview);
      webView.setWebViewClient(new AtriumWebViewClient());
      webView.getSettings().setDomStorageEnabled(true);
      webView.getSettings().setJavaScriptEnabled(true);
    }
    private class AtriumWebViewClient extends WebViewClient {
        @Override
        public boolean shouldOverrideUrlLoading(WebView view, String url) {
            if (url.equals("atrium://mxConnectLoaded")) {
                //Take action here.
                return true;
            } else if (url.startsWith("atrium://memberAdded")) {
                //Grab member guid and take action here.
                return true;
            }
            return false;
        }
    }
}

Example URL capture with Java

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
public class MainActivity extends AppCompatActivity {
    private WebView webView = null;
    @Override
    protected void onCreate(Bundle savedInstanceState) {
      webView = (WebView) findViewById(R.id.webview);
      webView.setWebViewClient(new AtriumWebViewClient());
      webView.getSettings().setDomStorageEnabled(true);
      webView.getSettings().setJavaScriptEnabled(true);
    }
    private class AtriumWebViewClient extends WebViewClient {
        @Override
        public boolean shouldOverrideUrlLoading(WebView view, String url) {
            if (url.equals("atrium://mxConnectLoaded")) {
                //Take action here.
                return true;
            } else if (url.startsWith("atrium://memberAdded")) {
                //Grab member guid and take action here.
                return true;
            }
            return false;
        }
    }
}

Example URL capture with Swift

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
class ViewController: UIViewController, WKUIDelegate {
  override func viewDidLoad() {
      super.viewDidLoad()
      webView.delegate = self
      ...
  }

  func webView(_ webView: WKWebView, decidePolicyFor
    navigationAction: WKNavigationAction,
    decisionHandler: @escaping (WKNavigationActionPolicy) -> Swift.Void) {

    // Intercept custom URI
    let surl = navigationAction.url?.absoluteString
    if (surl?.hasPrefix("atrium://"))! {
      // Take action here

      // Cancel request
      decisionHandler(.cancel)
      return
    }

    // Allow request
    decisionHandler(.allow)
  }
}

Using OAuth in Connect with WebViews

There are three configuration options WebViews will need in order to have the optimal OAuth flow:

is_mobile_webview: true — Allows the widget to know if it is in a WebView context.
ui_message_version: 4 — Allows the widget to send new postMessage events.
ui_message_webview_url_scheme: <your app> — Determines message scheme; this is is used by MX to redirect the user back to the client app in mobile contexts.

In-depth configuration documentation can be found here.

In-depth documentation on postMessages can be found here.

Example request

1
2
3
4
5
6
curl -i -X POST 'https://vestibule.mx.com/users/{user_guid}/connect_widget_url' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'Content-Type: application/json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}'
  -d '{ "is_mobile_webview": true, "ui_message_version": 4, "ui_message_webview_url_scheme": "{app scheme}" }'

Example navigation event schema:

{ui_message_webview_url_scheme}://{some/path}?metadata={jsonString}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
public class MainActivity extends AppCompatActivity {
    private WebView webView = null;
    @Override
    protected void onCreate(Bundle savedInstanceState) {
      webView = (WebView) findViewById(R.id.webview);
      webView.setWebViewClient(new AtriumWebViewClient());
      webView.getSettings().setDomStorageEnabled(true);
      webView.getSettings().setJavaScriptEnabled(true);
    }
    private class AtriumWebViewClient extends WebViewClient {
        @Override
        public boolean shouldOverrideUrlLoading(WebView view, String url) {
            if (url.equals("atrium://mxConnectLoaded")) {
                //Take action here.
                return true;
            } else if (url.startsWith("atrium://memberAdded")) {
                //Grab member guid and take action here.
                return true;
            }
            return false;
        }
    }
}

Example URL capture with Java

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
public class MainActivity extends AppCompatActivity {
    private WebView webView = null;
    @Override
    protected void onCreate(Bundle savedInstanceState) {
      webView = (WebView) findViewById(R.id.webview);
      webView.setWebViewClient(new AtriumWebViewClient());
      webView.getSettings().setDomStorageEnabled(true);
      webView.getSettings().setJavaScriptEnabled(true);
    }
    private class AtriumWebViewClient extends WebViewClient {
        @Override
        public boolean shouldOverrideUrlLoading(WebView view, String url) {
            if (url.equals("atrium://mxConnectLoaded")) {
                //Take action here.
                return true;
            } else if (url.startsWith("atrium://memberAdded")) {
                //Grab member guid and take action here.
                return true;
            }
            return false;
        }
    }
}

Example URL capture with Swift

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
class ViewController: UIViewController, WKUIDelegate {
  override func viewDidLoad() {
      super.viewDidLoad()
      webView.delegate = self
      ...
  }

  func webView(_ webView: WKWebView, decidePolicyFor
    navigationAction: WKNavigationAction,
    decisionHandler: @escaping (WKNavigationActionPolicy) -> Swift.Void) {

    // Intercept custom URI
    let surl = navigationAction.url?.absoluteString
    if (surl?.hasPrefix("atrium://"))! {
      // Take action here

      // Cancel request
      decisionHandler(.cancel)
      return
    }

    // Allow request
    decisionHandler(.allow)
  }
}

Redirecting the user

Since the MX WebView can’t reliably send the user from the app to the OAuth provider’s site in a native browser, the containing iOS or Android app will need to. To facilitate this, your app will need to react to the connect/oauthRequested postMessage request:

<ui_message_webview_url_scheme>://connect/oauthRequested?metadata=...

The OAuth URL is inside of the metadata query parameter under the url key.

Example redirect with Java

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
/**
 * This Client will capture urls from MX and cancel them. It will specifically
 * handle the oauthRequested URL. You will want to set this client as your
 * WebView's client or add this functionality to your own.
 */
public class MXWebViewClient extends WebViewClient {
    private Activity activity;

    public MXWebViewClient(Activity mainActivity) {
        activity = mainActivity;
    }

    @Override
    public boolean shouldOverrideUrlLoading(WebView view, String url) {
        // Ensure you are looking for schemes from both 'mx', 'atrium' and whatever you configured
        // ui_message_webview_url_scheme to be. In this example, it was 'appscheme'.
        boolean isFromMX = url.startsWith("mx://")  || url.startsWith("atrium://") || url.startsWith("appscheme://");

        if (isFromMX) {
            try {
                Uri mxURI = Uri.parse(url);

                // Handle the oauth url redirect. Send the user to the URL given.
                if (mxURI.getPath().equals("/oauthRequested")) {
                    JSONObject mxMetaData = new JSONObject(mxURI.getQueryParameter("metadata"));
                    String oauthURL = mxMetaData.getString("url");
                    Uri oauthPage = Uri.parse(oauthURL);
                    Intent intent = new Intent(Intent.ACTION_VIEW, oauthPage);
                    activity.startActivity(intent);
                }
            } catch (Exception err) {
                Log.e("sb: Error creating URI", err.getMessage());
            }
            return true;
        }

        return false;
    }
}

Example redirect with Swift

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
/**
 * Set up the WebView to capture URLs. You will want to cancel all urls from MX.
 */
class ViewController: UIViewController, WKNavigationDelegate {

    var webView: WKWebView!
    let appScheme = "appscheme://"
    let mxScheme = "mx://"
    let atriumScheme = "atrium://"

    func webView(_ webView: WKWebView,
                 decidePolicyFor navigationAction: WKNavigationAction,
                 decisionHandler: @escaping (WKNavigationActionPolicy) -> Swift.Void) {

        // Ensure you are looking for schemes from both 'mx', 'atrium', and whatever you configured
        // ui_message_webview_url_scheme to be. In this example, it was 'appscheme'.
        let url = navigationAction.request.url?.absoluteString
        let isFromMX = url?.hasPrefix(appScheme) == true || url?.hasPrefix(mxScheme) == true || url?.hasPrefix(atriumScheme) == true

        if isFromMX {
            let urlc = URLComponents(string: surl ?? "")
            let path = urlc?.path ?? ""
            // there is only one query parameter ("metadata")
            // so just grab the first one
            let metaDataQueryItem = urlc?.queryItems?.first

            if path == "/oauthRequested" {
                handleOauthRedirect(payload: metaDataQueryItem)
            }

            // Cancel request
            decisionHandler(.cancel)
            return
        }

        // Allow request
        decisionHandler(.allow)
    }

    /*
     * Handle the oauthRequested event. Parse out the OAuth URL from the event
     * and open Safari to that URL
     * NOTE: This code is somewhat optimistic, you'll want to add error handling
     * that makes sense for your app.
     */
    func handleOauthRedirect(payload: URLQueryItem?) {
        let metadataString = payload?.value ?? ""

        do {
            if let json = try JSONSerialization.jsonObject(with: Data(metadataString.utf8), options: []) as? [String: Any] {
                if let url = json["url"] as? String {
                    // open safari with the url from the json payload
                    UIApplication.shared.open(URL(string: url)!)
                }
            }
        } catch let error as NSError {
            print("Failed to parse payload: \(error.localizedDescription)")
        }
    }
}

Getting back to your app

Once the user completes the OAuth process, MX will send the user back to the client app via a URL scheme like so:

<ui_message_webview_url_scheme>://oauth_complete?status=<success|error>&member_guid=<guid>

This part is optional for OAuth, but highly recommended. If this is not set, the user will end on an MX page with a success or error message and will have to navigate back to your app manually. Make sure to pick a scheme that your app can respond to.

Postmessage events

A postMessage is an event-based protocol that allows partners to take action in their own codebase in response to events triggered within a widget’s user interface. They are intended specifically to allow a partner’s code and a widget user interface to work in concert, not to give a full picture of events happening on MX servers. PostMessage events should not be used for keeping data in sync between platforms.

Webhooks are a more reliable way of coordinating events between partner servers and MX servers, rather than the UI-oriented postMessages.

Events from MX will have mx, type, and metadata properties.

The mx field is provided as an easy way for partners to filter out postMessage events coming from MX.

The type field has the following scheme: mx/<entity|widget>/<event>. For example:

mx/account/created
mx/connect/institutionSelected
mx/transaction/updated

The type field identifies what the event represents at a high level. It is also useful for matching events for a given entity or widget, e.g, all account events will be prefixed with mx/account/*.

The metadata field is an object that has information related to the type that may be important, such as the account or transaction that was updated, the institution that was selected, etc. metadata objects will also have the user_guid and session_guid fields.

Example integration

1
2
3
4
5
6
7
function handleEvent(event) {
  if (event.data.mx) {
    // handle the mx post message using event.data.type and event.data.metadata.
  }
}

window.addEventListener('message', handleEvent)

Example event

1
2
3
4
5
6
7
8
9
const mxEvent = {
  mx: true,
  type: 'mx/account/created',
  metadata: {
    user_guid: 'USR-123',
    session_guid: 'ANS-123'
    // relevant data for the given type
  }
}

Application events

Widget load

Trigged when the app is loaded.

Widget ping

Used to keep the widget session alive.

Widget load event

1
2
3
4
{
  "type": "mx/load",
  "mx": true
}

Widget ping event

1
2
3
4
5
6
7
8
{
  "type": "mx/ping",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123"
  }
}

Connect events

The events below are specific to events that happen in the Connect widget.

Connect loaded

Triggers when the Connect widget loads. Useful to know what “step” or view the user started on. initial_step can be:

Value	Definition
`search`	The default initial step.
`selectMemeber`	The initial step when configured with `mode` set to `verification`.
`enterCreds`	The initial step when configured with `current_institution_guid` or `current_member_guid`, and `updated_credentials` set to `true`.
`mfa`	The initial step when configured with `current_member_guid` and the member has encountered multi-factor authentication.
`connected`	The initial step when configured with `current_member_guid` and the member is in a connected state.
`loginError`	The initial step when configured with `current_member_guid` and the member is in an error state.

Connect loaded

1
2
3
4
5
6
7
8
9
{
  "type": "mx/connect/loaded",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "initial_step": "search"
  }
}

Step change

Triggered when the end user changes from one “step” to another. This event is provided for gaining insight into what transitions users are making. Possible step values can be:

Value	Definition
`search`	Where the user searches for institutions.
`disclosure`	Where the user reads the MX privacy policy and agrees by selecting Continue. This is optional and is turned off by default.
`search`	Where the user searches for institutions.
`verifyExistingMember`	Where the user can verify existing members when `mode` set to verification.
`enterCreds`	Where the user enters credentials for a particular institution.
`oauth`	Where the user goes instead of enter credentials if the institution and client supports oauth.
`mfa`	Where the user enters in MFA responses.
`connecting`	Where the user goes while the connection is being attempted.
`existingMember`	Where the user lands if they are trying to add a member they have previously added.
`timeOut`	When the user has been connecting for more than 30 seconds without any updates to the member.
`connected`	Where the user lands when they have successfully connected.
`loginError`	Where the user lands when they have unsuccessfully connected due to user or system error.
`error`	Where the user lands when the member create was unsuccessful due to user or system error.
`addManualAccount`	Where the user creates manual accounts. Manual accounts are not currently offered in the Platform API, so partners should not expect to see this value.

Connect step change

1
2
3
4
5
6
7
8
9
10
{
  "type": "mx/connect/stepChange",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "previous": "search",
    "current": "enterCreds"
  }
}

Institution search

Triggered when the end user searches for an institution. This is useful in determining what users are searching for.

Institution search

1
2
3
4
5
6
7
8
9
{
  "type": "mx/connect/institutionSearch",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "query": "MX Bank"
  }
}

Institution selected

Triggered when an end user selects an institution from the institution list.

Institution selected

1
2
3
4
5
6
7
8
9
10
11
12
{
  "type": "mx/connect/selectedInstitution",
  "mx": true,
  "metadata": {
    "code": "mxbank",
    "guid": "INS-123",
    "name": "MX Bank",
    "session_guid": "ANS-123",
    "url": "www.example.com",
    "user_guid": "USR-123"
  }
}

Enter credentials

Triggered when a user submits credentials for a given institution for the first time.

Enter credentials

1
2
3
4
5
6
7
8
9
10
11
12
{
  "type": "mx/connect/enterCredentials",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "institution": {
      "code": "mxbank",
      "guid": "INS-123"
    }
  }
}

Update credentials

Triggered when a user submits credentials while trying to update their existing credentials.

Update credentials

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "type": "mx/connect/updateCredentials",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "member_guid": "MBR-123",
    "institution": {
      "code": "mxbank",
      "guid": "INS-123"
    }
  }
}

OAuth requested

Triggered when the user navigates to the OAuth providers site. Note that the redirect does not happen in WebViews. The native app will need to use this postMessage to send the user to the URL contained in the metadata.

OAuth requested:

1
2
3
4
5
6
7
8
9
10
11
{
  "type": "mx/connect/oauthRequested",
  "mx": true,
  "metadata": {
    "member_guid": "MBR-123",
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "url": "https://something.com",
    "member_guid": "MBR-123"
  }
}

OAuth error

Triggered when the user lands on the OAuth error page. This is a general error message and could represent a problem with the OAuth provider or MX.

OAuth error:

1
2
3
4
5
6
7
8
9
{
  "type": "mx/connect/oauthError",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "member_guid": "MBR-123"
  }
}

Submit MFA

Triggered when a user submits an MFA answer.

Submit MFA

1
2
3
4
5
6
7
8
9
{
  "type": "mx/connect/submitMFA",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "member_guid": "MBR-123"
  }
}

Member status update

Triggered when a member’s connection status has changed while connecting. This is useful in determining the current connection status of the member.

Member status update

1
2
3
4
5
6
7
8
9
10
{
  "type": "mx/connect/memberStatusUpdate",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "member_guid": "MBR-123",
    "connection_status": 6
  }
}

Member connected

Triggered when a member has successfully connected the account.

Member connected

1
2
3
4
5
6
7
8
9
{
  "type": "mx/connect/memberConnected",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "member_guid": "MBR-123"
  }
}

Member connected, primary action selected

Triggered when the user selects the primary button on the connected step.

Member connected

1
2
3
4
5
6
7
8
{
  "type": "mx/connect/connected/primaryAction",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123"
  }
}

Member deleted

Triggered when a member has been deleted in the widget.

Member deleted

1
2
3
4
5
6
7
8
9
{
  "type": "mx/connect/memberDeleted",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "member_guid": "MBR-123"
  }
}

Member already added error (deprecated)

This message is no longer sent because an error is no longer displayed when adding a duplicate member. Instead, the existing member is now updated.

Member already added

1
2
3
4
5
6
7
8
9
10
{
  "type": "mx/connect/memberAlreadyAdded",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "institution_guid": "INS-123",
    "institution_code": "mxbank"
  }
}

Member create error

Triggered when a member failed to get created when credentials were entered.

Member create error

1
2
3
4
5
6
7
8
9
10
{
  "type": "mx/connect/createMemberError",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "institution_guid": "INS-123",
    "institution_code": "mxbank"
  }
}

Member connection error

Triggered when a member has encountered an error state. This is useful in determining when the user is in an error state and resolving it based on the connection_status.

Member connection error

1
2
3
4
5
6
7
8
9
10
11
12
{
  "type": "mx/connect/memberError",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "member": {
      "guid": "MBR-123",
      "connection_status": 6
    }
  }
}

Minimum dimensions

Connect uses a responsive design. Page styles and layout are subject to change, and elements may become hidden or visible at different widths.

The following are the minimum dimensions supported for mobile/desktop platforms:

Minimum height: 550px
Minimum width: 320px

Below are the width breakpoints at which the design may change. These are based on typical industry device resolutions. These are subject to change in the future.

Small: 320px to 767px
Medium: 768px to 1199px
Large: 1200px or greater

Embedding in a website (deprecated)

Once you’ve generated a URL, you can pass that information on to a JavaScript loader. This loader allows you to further configure your Connect widget, including the size as well as all the supported configuration options, inside the config object.

It also allows you to listen for event messages that indicate loading or a successful member creation.

Parameters available for the JavaScript loader:

Parameter	Data Type	Description	Required?
`config`	Object	This object allows you to set additional parameters to load the MX Connect widget in a specific state.	No
`height`	String	Desired height of the iframe. Defaults to 600 pixels.	No
`id`	String	The `id` of the DOM element you’ll load the widget into.	Yes
`onLoad`	Function	An event message that is fired when the widget is loaded.	No
`onEvent`	Function	A general event handler. Only available with `ui_message_version: 4` or higher	No
`onSuccess`	Function	An event message that is fired upon successfully adding a new `member` for the `user`	No
`width`	String	Desired width of the iframe. Defaults to 100% of the parent.	No
`url`	String	A URL for the widget provided as a response to the `POST` request above.	No

Example usage

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
<script src="https://atrium.mx.com/connect.js"></script>
<script>
  // Create an instance of MXConnect with settings appropriate for your app.
  // There should only be one instance of MXConnect in your app.
  var mxConnect = new MXConnect({
    id: "addAccount",
    // `URL` is optional at initialization time. Generally you will want to
    // dynamically get the widget URL and pass it to the `load` method.
    url: "https://int-widgets.moneydesktop.com/md/connect/jb1rA14m85tw2ly...",
    onEvent: function (event) {
      // A unified event handler from the MX Connect widget.
      // Only called if `ui_message_version` is 4 or greater.
      // Should not be used with `onLoad` or `onSuccess`.
      console.log(event)
    }
    onLoad: function () {
      // *Deprecated* Connect widget successfully loaded.
      // Only called if the `ui_message_version` is below `4` or not set all.
      console.log("On Load");
    },
    onSuccess: function (memberGuid) {
      // *Deprecated* Member created successfully.
      // Only called if the `ui_message_version` is below `4` or not set all.
      console.log("On Success");
    },
  });

  var addAccountClick = function () {
    // Get a widget URL and call `load` with that URL.
    getConnectWidgetURL().then(url => {
      mxConnect.load(url);
    })
  };
</script>

Extend transaction history

Some institutions allow developers to access an extended transaction history with up to 24 months of data associated with a particular member. The process for fetching and then reading this extended transaction history is much like standard aggregation, and it may trigger multi-factor authentication.

Extend history

Use this endpoint to gather an extended transaction history for a particular member. This longer history can then be accessed though the standard transaction endpoints.

For more information on this and other aggregation-type processes, please see our developer guides.

Errors

If an extended history job is already running, a 202 Accepted status will be returned.
If an institution does not support extended history, a 400 Bad Request error will be returned.
If extended history is not enabled, a 403 Forbidden status will be returned. If you see 403 Forbidden but the member’s institution nevertheless shows that extended history is enabled, please contact support by submitting a ticket here.
If another aggregation-type process is already running — like standard aggregation or instant account verification — a 409 Conflict will be returned.

Endpoint:

POST /users/{user_guid}/members/{member_guid}/extend_history

Example request

1
2
3
4
$ curl -i -X POST 'https://vestibule.mx.com/users/{user_guid}/members/{member_guid}/extend_history' \
-H 'Accept: application/vnd.mx.atrium.v1+json' \
-H 'MX-API-Key: {mx_api_key}' \
-H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
"member": {
  "aggregated_at": "2016-10-13T18:07:57+00:00",
  "connection_status": "CONNECTED",
  "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
  "identifier": "unique_id",
  "institution_code": "chase",
  "is_being_aggregated": true,
  "metadata": "{\"credentials_last_refreshed_at\": \"2015-10-15\"}",
  "name": "Chase Bank",
  "status": "INITIATED",
  "successfully_aggregated_at": "2016-10-13T17:57:38+00:00",
  "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
}
}

Identity

Atrium Identity allows you to access data such as the name, street address, phone number, and email address for all the accounts associated with a particular member. The process for getting an account owner’s identity is much like standard aggregation. For more detailed information on the process, see the identity guide.

The identify endpoint may be used to gather this information on certain institutions, and then it can be accessed with another call to the account owners endpoint.

Account owner fields

Field	Data Type	Description
`account_guid`	String	The unique identifier for the `account` associated with the account owner. Defined by MX.
`address`	String	The account owner’s street address.
`city`	String	The account owner’s city.
`country`	String	The account owner’s country.
`email`	String	The account owner’s email address.
`member_guid`	String	The unique identifier for the `member` associated with the account owner. Defined by MX.
`owner_name`	String	The account owner’s name.
`phone`	String	The account owner’s phone number.
`postal_code`	String	The the account owner’s postal code.
`state`	String	The account owner’s state.
`user_guid`	String	The unique identifier for the `user` associated with the account owner. Defined by MX.

Identify a member

The identify endpoint begins an identification process for an already-existing member. It gathers information about account owners. Partners may optionally choose to include transaction data in this request, potentially avoiding a separate aggregate member request.

The identification workflow is similar to standard aggregation: Start the identification, poll the connection status, answer MFA if necessary by using the list member MFA challenges endpoint and the resume from MFA endpoint, poll the status again, then read the member’s account numbers.

For more information on this and other aggregation-type processes, please see our developer guide.

Errors

If an identification job is already running, a 202 Accepted status will be returned.
If an institution does not support identification, a 400 Bad Request error will be returned.
If identification is not enabled, a 403 Forbidden status will be returned. If you see 403 Forbidden but the member’s institution nevertheless shows that identification is enabled, please contact support by submitting a ticket here.
If another aggregation-type process is already running — like standard aggregation or extended transaction history — a 409 Conflict will be returned.

Parameters

Field name	Definition	Required?
include_transactions	When set to `true`, the identification will gather transaction data along with account owner data. Defaults to `false`.	No

Endpoint:

POST /users/{user_guid}/members/{member_guid}/identify

Example request

1
2
3
4
5
curl -i -X POST 'https://vestibule.mx.com/users/{user_guid}/members/{member_guid}/identify' \
-H 'Accept: application/vnd.mx.atrium.v1+json' \
-H 'Content-Type: application/json' \
-H 'MX-API-Key: {mx_api_key}' \
-H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
"member": {
  "aggregated_at": "2018-06-25T20:04:19Z",
  "connection_status": "CONNECTED",
  "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
  "identifier": "chase_ds",
  "institution_code": "6930ee63-16b3-fc5e-ab48-18bbc39379d0",
  "is_being_aggregated": true,
  "is_oauth": false,
  "metadata": null,
  "name": "chase ds",
  "status": "INITIATED",
  "successfully_aggregated_at": "2018-06-25T19:45:01Z",
  "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
}
}

List account owners

Use this endpoint to check whether identity data is available for a specific member. It returns the account_owners resource, which contains an array with data about the account owners for each account associated with the member.

Endpoint:

GET /users/{user_guid}/members/{member_guid}/account_owners

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
using System;
using Atrium.Api;
using Atrium.Model;

namespace Example
{
    public class ListAccountOwnersExample
    {
        public void main()
        {
            var client = new AtriumClient("YOUR_API_KEY", "YOUR_CLIENT_ID");

            var memberGuid = "MBR-123";  // string | The unique identifier for a `member`.
            var userGuid = "USR-123";  // string | The unique identifier for a `user`.

            try
            {
                // List member account owners
                AccountOwnersResponseBody response = client.identity.ListAccountOwners(memberGuid, userGuid);
                Console.WriteLine(response);
            }
            catch (Exception e)
            {
                Console.WriteLine("Exception when calling IdentityApi.ListAccountOwners: " + e.Message );
            }
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
package main

import (
  "context"
  "fmt"
  "github.com/mxenabled/atrium-go"
)

func main() {
  client := atrium.AtriumClient("YOUR_API_KEY", "YOUR_CLIENT_ID")
  ctx := context.Background()

  memberGUID := "MBR-123" // string | The unique identifier for a `member`.
  userGUID := "USR-123" // string | The unique identifier for a `user`.

  response, _, err := client.Identity.ListAccountOwners(ctx, memberGUID, userGUID)
  if err != nil {
    fmt.Printf("Error: %v\n", err)
  } else {
    fmt.Printf("Response: %s\n", response)
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import com.mx.atrium.*;
import com.mx.model.*;

public class IdentityApiExample {
    public static void main(String[] args) {
        AtriumClient client = new AtriumClient("YOUR_API_KEY", "YOUR_CLIENT_ID");

        String memberGuid = "MBR-123"; // String | The unique identifier for a `member`.
        String userGuid = "USR-123"; // String | The unique identifier for a `user`.

        try {
            AccountOwnersResponseBody response = client.identity.listAccountOwners(memberGuid, userGuid);
            System.out.println(response);
        } catch (ApiException e) {
            System.err.println("Exception when calling IdentityApi#listAccountOwners");
            e.printStackTrace();
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
var atrium = require('./atrium.js');

var client = new atrium.AtriumClient("YOUR_API_KEY", "YOUR_CLIENT_ID");

var memberGuid = "MBR-123"; // string | The unique identifier for a `member`.
var userGuid = "USR-123"; // string | The unique identifier for a `user`.

var response = client.identity.listAccountOwners(memberGuid, userGuid);

response.then(function(value) {
  console.log(value);
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<?php
require_once(__DIR__ . '/vendor/autoload.php');

$client = new atrium\Api\AtriumClient(
    "YOUR_API_KEY",
    "YOUR_CLIENT_ID",
    new GuzzleHttp\Client()
);

$member_guid = "MBR-123"; // string | The unique identifier for a `member`.
$user_guid = "USR-123"; // string | The unique identifier for a `user`.

try {
    $result = $client->identity->listAccountOwners($member_guid, $user_guid);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling IdentityApi->listAccountOwners: ', $e->getMessage(), PHP_EOL;
}
?>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
from __future__ import print_function
import time
import atrium
from atrium.rest import ApiException
from pprint import pprint

# create an instance of the AtriumClient
client = atrium.AtriumClient("YOUR_API_KEY", "YOUR_CLIENT_ID")

member_guid = "MBR-123" # str | The unique identifier for a `member`.
user_guid = "USR-123" # str | The unique identifier for a `user`.

try:
    # List member account owners
    response = client.identity.list_account_owners(member_guid, user_guid)
    pprint(response)
except ApiException as e:
    print("Exception when calling IdentityApi->list_account_owners: %s\n" % e)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# load the gem
require 'atrium-ruby'

client = Atrium::AtriumClient.new("YOUR_API_KEY", "YOUR_CLIENT_ID")

member_guid = "MBR-123" # String | The unique identifier for a `member`.
user_guid = "USR-123" # String | The unique identifier for a `user`.

begin
  #List member account owners
  response = client.identity.list_account_owners(member_guid, user_guid)
  p response
rescue Atrium::ApiError => e
  puts "Exception when calling IdentityApi->list_account_owners: #{e}"
end

1
2
3
4
$ curl -i 'https://vestibule.mx.com/users/{user_guid}/members/{member_guid}/account_owners' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
  "account_owners": [
    {
      "guid": "ACO-123",
      "user_guid": "USR-123",
      "member_guid": "MBR-123",
      "account_guid": "ACT-123",
      "owner_name": "Donnie Darko",
      "address": "123 This Way",
      "city": "Middlesex",
      "state": "VA",
      "postal_code": "00000-0000",
      "country": "US",
      "email": "donnie@darko.co",
      "phone": "555-555-5555"
    },
    {
      "guid": "ACO-456",
      "user_guid": "USR-123",
      "member_guid": "MBR-123",
      "account_guid": "ACT-123",
      "owner_name": "Susan Darko",
      "address": "456 That Way",
      "city": "Middlesex",
      "state": "VA",
      "postal_code": "00000-0000",
      "country": "US",
      "email": "susan@darko.co",
      "phone": "555-555-5555"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 2,
    "total_pages": 1
  }
}

Statements

Some institutions allow developers to access account statements associated with a particular member. The process for fetching and then reading account statements is much like standard aggregation, and it may trigger multi-factor authentication.

Statement fields

Field name	Data type	Definition
`account_guid`	String	The unique identifier for the `account` associated with the `statement`. Defined by MX.
`created_at`	String	The date and time the `statement` was created.
`content_hash`	String	The SHA-256 hash value of the statement’s byte payload.
`guid`	String	The unique identifier for the `statement`. Defined by MX.
`member_guid`	String	The unique identifier for the `member` to which the `statement` belongs. Defined by MX.
`updated_at`	String	The date and time at which the `statement` was last updated.
`uri`	String	The URI for accessing the byte payload of the `statement`.
`user_guid`	String	The unique identifier for the `user` associated with the `statement`. Defined by MX.

Download a statement PDF

Use this endpoint to download a specified statement PDF.

The endpoint URL is the the URI given in each statement object prepended with the host (i.e., https://vestibule.mx.com or https://atrium.mx.com) and appended with .pdf.

Endpoint:

GET /users/{user_guid}/members/{member_guid}/statements/{statement_guid}.pdf

Example request

1
2
3
4
$ curl -i 'https://vestibule.mx.com/users/{user_guid}/members/{member_guid}/statements/{statement_guid}.pdf' \
-H 'Accept: application/vnd.mx.atrium.v1+pdf' \
-H 'MX-API-Key: {mx_api_key}' \
-H 'MX-Client-ID: {mx_client_id}'

Fetch statements

Use this endpoint to fetch the statements associated with a particular member.

For more information on this and other aggregation-type processes, please see our developer guide.

Errors

If a fetch statements job is already running, a 202 Accepted status will be returned.
If an institution does not support statements, a 400 Bad Request error will be returned.
If statements are not enabled, a 403 Forbidden status will be returned. If you see 403 Forbidden but the member’s institution nevertheless shows that statements is enabled, please contact support by submitting a ticket here.
If another aggregation-type process is already running — like standard aggregation or instant account verification — a 409 Conflict will be returned.

Endpoint:

POST /users/{user_guid}/members/{member_guid}/fetch_statements

Example request

1
2
3
4
$ curl -i -X POST 'https://vestibule.mx.com/users/{user_guid}/members/{member_guid}/fetch_statements' \
-H 'Accept: application/vnd.mx.atrium.v1+json' \
-H 'MX-API-Key: {mx_api_key}' \
-H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
"member": {
  "aggregated_at": "2016-10-13T18:07:57+00:00",
  "connection_status": "CONNECTED",
  "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
  "identifier": "unique_id",
  "institution_code": "chase",
  "is_being_aggregated": true,
  "metadata": "{\"credentials_last_refreshed_at\": \"2015-10-15\"}",
  "name": "Chase Bank",
  "status": "INITIATED",
  "successfully_aggregated_at": "2016-10-13T17:57:38+00:00",
  "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
}
}

List statements

Use this endpoint to get an array of available statements.

Endpoint:

GET users/{user_guid}/members/{member_guid}/statements

Example request

1
2
3
4
$ curl -i 'https://vestibule.mx.com/users/USR-743e5d7f-1116-28fa-5de1-d3ba02e41d8d/members/MBR-d65683e8-9eab-26bb-bcfd-ced159c9abe2/statements' \
-H 'Accept: application/vnd.mx.atrium.v1+json' \
-H 'MX-API-Key: {mx_api_key}' \
-H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
"statements": [
  {
    "account_guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
    "content_hash": "ca53785b812d00ef821c3d94bfd6e5bbc0020504410589b7ea8552169f021981",
    "created_at": "2016-10-13T18:08:00+00:00",
    "guid": "STA-737a344b-caae-0f6e-1384-01f52e75dcb1",
    "member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "updated_at": "2016-10-13T18:09:00+00:00",
    "uri": "",
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
  }
],
"pagination": {
  "current_page": 1,
  "per_page": 25,
  "total_entries": 1,
  "total_pages": 1
}
}

Read a statement

Use this endpoint to read a JSON representation of the statement.

The endpoint URL is the host (e.g., https://vestibule.mx.com or https://atrium.mx.com) plus the URI given in each statement object.

Endpoint:

GET /users/{user_guid}/members/{member_guid}/statements/{statement_guid}

Example request

1
2
3
4
$ curl -i 'https://vestibule.mx.com/users/{user_guid}/members/{member_guid}/statements/{statement_guid}' \
-H 'Accept: application/vnd.mx.atrium.v1+json' \
-H 'MX-API-Key: {mx_api_key}' \
-H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
{
"statement": {
  "account_guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
  "created_at": "2016-10-13T18:08:00+00:00",
  "content_hash": "ca53785b812d00ef821c3d94bfd6e5bbc0020504410589b7ea8552169f021981",
  "guid": "STA-737a344b-caae-0f6e-1384-01f52e75dcb1",
  "member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
  "updated_at": "2016-10-13T18:09:00+00:00",
  "uri": "",
  "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
}
}

Verification

Account verification allows you to access account and routing numbers for demand deposit accounts associated with a particular member. Functionally, this means it is that only CHECKING and SAVINGS accounts are likely to be verified.

The process for account verification is much like standard aggregation.

Start the verification;
Check the connection_status;
Answer MFA if necessary;
Answer the special account-selection challenge (when using the default flow; the legacy flow skips this step);
Check the connection_status again;
List the member’s account numbers.

For more detailed information on the process, see the account verification guide.

Account number fields

Field	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.
`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.

List account numbers

Use this endpoint to check whether account and routing numbers are available for accounts associated with a particular member. It returns the account_numbers object, which contains account and routing number data for each account associated with the member.

Endpoint:

GET /users/{user_guid}/members/{member_guid}/account_numbers

Example request

1
2
3
4
$ curl -i 'https://vestibule.mx.com/users/{user_guid}/members/{member_guid}/account_numbers' \
-H 'Accept: application/vnd.mx.atrium.v1+json' \
-H 'MX-API-Key: {mx_api_key}' \
-H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
"account_numbers": [
  {
    "account_guid": "ACT-123",
    "account_number": "10001",
    "institution_number": null,
    "member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "routing_number": "68899990000000",
    "transit_number": null,
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
  }
],
"pagination": {
  "current_page": 1,
  "per_page": 25,
  "total_entries": 1,
  "total_pages": 1
}
}

List account numbers by account

Use this endpoint to check whether account and routing numbers are available for a specific account. It returns the account_numbers object, which contains account and routing number data.

Endpoint:

GET /users/{user_guid}/accounts/{account_guid}/account_numbers

Example request

1
2
3
4
$ curl -i 'https://vestibule.mx.com/users/{user_guid}/accounts/{account_guid}/account_numbers' \
-H 'Accept: application/vnd.mx.atrium.v1+json' \
-H 'MX-API-Key: {mx_api_key}' \
-H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
"account_numbers": [
  {
    "account_guid": "ACT-123",
    "account_number": "10001",
    "institution_number": null,
    "member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "routing_number": "68899990000000",
    "transit_number": null,
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
  }
],
"pagination": {
  "current_page": 1,
  "per_page": 25,
  "total_entries": 1,
  "total_pages": 1
}
}

Verify a member

The verify endpoint begins a verification process for a member. It gathers information about account and routing numbers. Partners may optionally choose to include 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 connection status, answer MFA if necessary by using the list member MFA challenges endpoint and the resume from MFA endpoint, poll the status again, then read the member’s account numbers.

For more information on this and other aggregation-type processes, please see our developer guide.

Errors

If a verification is already running, a 202 Accepted status will be returned.
If an institution does not support verification, a 400 Bad Request error will be returned.
If verification is not enabled, a 403 Forbidden status will be returned. If you see 403 Forbidden but the member’s institution nevertheless shows that verification is enabled, please contact support by submitting a ticket here.
If another aggregation-type process is already running — like standard aggregation or extended transaction history — a 409 Conflict will be returned.

Parameters

Field name	Definition	Required?
`include_transactions`	When set to `true`, the verification will gather transaction data along with account number data. Defaults to `false`.	No

Endpoint:

POST /users/{user_guid}/members/{member_guid}/verify

Example request

1
2
3
4
5
curl -i -X POST 'https://vestibule.mx.com/users/{user_guid}/members/{member_guid}/verify' \
-H 'Accept: application/vnd.mx.atrium.v1+json' \
-H 'Content-Type: application/json' \
-H 'MX-API-Key: {mx_api_key}' \
-H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "member": {
      "aggregated_at": "2018-06-25T20:04:19Z",
      "connection_status": "CONNECTED",
      "identifier": "chase_ds",
      "status": "INITIATED",
      "successfully_aggregated_at": "2018-06-25T19:45:01Z",
      "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
      "institution_code": "6930ee63-16b3-fc5e-ab48-18bbc39379d0",
      "is_being_aggregated": true,
      "metadata": null,
      "name": "chase ds",
      "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
  }
}

Webhooks overview and setup

MX provides webhooks that send HTTPS POST callback requests to the URL of your choice. This enables you to subscribe to certain events, be notified when those events occur, and have information related to that event delivered to you. If you are subscribed to multiple events, a different URL can be configured for each event.

You can set up and configure webhooks on the client dashboard.

Features

The current version of MX webhooks has the following features:

Webhooks are delivered via RESTful HTTPS requests to the partner’s listening service;
Webhooks are triggered when a qualifying event occurs in the MX system;
Webhooks can make requests to any specified URL;
- Configuration for this is done offline, out of band;
Each POST request includes a JSON-formatted payload;
The frequency of request retries diminishes over the course of approximately 24 hours, with no more than 12 total retries after an initial request.

Date and time formats

Date and time fields are supported in either Unix Epoch time (no milliseconds), or in ISO 8601 with no timestamp (YYYY-MM-DD).

Fields ending in _at are Unix Epoch time (no milliseconds), e.g. 1504224000.
Fields ending in _on are ISO 8601 (no timestamp), e.g. 2017-09-01.

Security

All webhook requests are encrypted by default. However, MX recommends using an additional layer of security as well. One or more of the following are typical:

HTTP Basic Authorization

Provide MX with a username and password for making basic HTTP requests to your chosen URL.

Mutual Certificate Authentication

In order to set up mutual authentication, MX will generate a Certificate Signing Request (CSR) for you. You’ll first need to provide MX with the following information:

Common Name
Organization
Department
City
State/Province
Country
Key Size: MX uses the recommended size of RSA 2048.

Use this CSR to purchase a certificate, and then send it to MX. This certificate will be used to authenticate requests originating from MX.

OAuth 2 Access Token Authentication (Client Credentials)

To secure webhooks with OAuth access tokens, provide MX with an ID and secret to be used for basic authorization. MX will use these to make a request to your token endpoint to generate a new access token using the client_credentials grant type. This token will then be used to make requests to your webhook URL until the token expires. MX then repeats the process.

MX can configure our token requests to send the grant type in either the body or the query string.

Grant Type in Query String

1
2
3
4
5
6
7
POST /token?grant_type=client_credentials HTTP/1.1
Host: server.example.com
Authorization: Basic YWNtZTo4NTdkM2Y1YWU0ZWNhNjUy
Accept: */*
Content-Length: 0
Date: Tue, 25 Oct 2022 18:38:10 GMT
User-Agent: HTTPClient/1.0 (2.8.3, ruby 2.6.8 (2022-06-27))

1
2
3
4
5
6
7
8
9
10
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "access_token": "MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
  "expires_in": 3600,
  "token_type": "bearer"
}

Grant Type in Body

1
2
3
4
5
6
7
8
9
10
POST /token HTTP/1.1
Host: server.example.com
Authorization: Basic YWNtZTo4NTdkM2Y1YWU0ZWNhNjUy
Accept: application/json
Content-Length: 29
Content-Type: application/x-www-form-urlencoded
Date: Tue, 25 Oct 2022 18:35:13 GMT
User-Agent: HTTPClient/1.0 (2.8.3, ruby 2.6.8 (2022-06-27))

grant_type=client_credentials

1
2
3
4
5
6
7
8
9
10
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "access_token": "MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
  "expires_in": 3600,
  "token_type": "bearer"
}

Error handling

MX checks the status code you send in your response and takes appropriate action based on that. MX will retry a webhook for all status codes outside of the successful 200 range listed above. This could be a connection timeout, write timeout, read timeout, DNS error, etc. Because of this, it’s important that you respond to each webhook request as soon as possible, whether with a success code or an error code. Delays tie up resources for both MX and the partner.

Retries always contain a payload identical to the initial request. This means it’s very important that partners only send error codes in situations where retrying the webhook will be beneficial, and not in cases where sending the same payload will result in the same error. In cases where the same error will occur, partners should return a success status code to MX and put the request into their own internal retry queue, or log the error internally for investigation. In other words, error codes should only be returned when the webhook was not successfully received.

For example, MX payloads may contain null values, and may include new fields not expected by partners. If your systems can’t parse these situations, sending an error code will not help because MX will respond by sending the exact same unexpected payload, resulting in the same error.

The most common error codes are within the 500 range (something went wrong on the receiving end) that prevent the partner from receiving the webhook. A 400-level error should only be returned in cases where a payload is truly invalid, such as if it contains invalid JSON, but not in situations where partners can’t process the payload for some internal reason.

Successful Status Codes

200 OK
201 CREATED
202 ACCEPTED
203 NON_AUTHORITATIVE_INFORMATION
204 NO_CONTENT
205 RESET_CONTENT
206 PARTIAL_CONTENT

Retries

MX webhooks will automatically retry a request in the case of a failed delivery such as a connection timeout, write timeout, read timeout, DNS error, etc.

Retry attempts will contain the same payload as the original request. Retry attempts follow a pattern of incrementally decreasing in frequency with each attempt. Partners can expect to see a number of retries within the first hour of the initial attempt and then gradually these retry attempts will become less and less frequent. Retry attempts have an element of randomness to them in order to avoid having a flood of retry requests be sent to a partner’s system all at once.

If the webhook cannot be successfully delivered after 12 successive retries, it will not be delivered.

Example Retry Schedule

Retry Number	Time Elapsed Since Initial Attempt
1	0h 0m 30s
2	0h 1m 16s
3	0h 2m 32s
4	0h 5m 8s
5	0h 10m 54s
6	0h 23m 4s
7	0h 46m 40s
8	1h 28m 56s
9	2h 39m 42s
10	4h 31m 48s
11	7h 21m 28s
12	11h 28m 44s

Changes to expected payloads

MX will not remove fields from a webhook payload without a major version change. However, fields may be added to a webhook payload at any time. Partners should allow for this and should assume neither a fixed set of fields nor a fixed ordering of fields. Any processing should allow for these changes.

Many fields can also return a null value. Partners should account for this in their handling of the webhook payload.

Testing

To test an existing webhook, please visit your webhook profile on the client dashboard.

Webhooks can be tested in two ways.

First, simple test webhooks can be generated from your dashboard for a limited number of webhook types. These contain dummy data and aren’t strictly part of your integration. But they will allow you to confirm that the URL and security settings you’ve chosen in the dashboard are working as expected.

Second, MX can generate special test webhooks at your request. These are tied to your particular integration and can be generated for any webhook type you are subscribed to. The payload of a special test webhook will have its action field set to test and includes a field indicating the type of webhook being tested, as shown in the example.

MX-generated Test Payload

1
2
3
4
5
{
  "action": "test",
  "account": {},
  "version": 1
}

Connection status

A partner subscribed to the connection status webhook will be notified whenever a member’s connection_status field enters into an end-user-actionable state.

The following connection statuses will trigger this webhook:

CHALLENGED
DENIED
EXPIRED
IMPAIRED
IMPEDED
LOCKED
PREVENTED
REJECTED

Fields for the connection status webhook

Field	Data type	Definition
`action`	String	This value should always equal `CHANGED`.
`connection_status`	String	This field indicates the state of a member’s aggregation, provided as a string.
`connection_status_id`	Integer	This field indicates the state of a member’s aggregation, provided as an integer.
`connection_status_message`	String	A message that can be displayed to the end user to help them navigate the connection and aggregation process.
`member_guid`	String	Unique identifier for the member that triggered the webhook. Defined by MX.
`type`	String	The type of webhook being delivered.
`user_guid`	String	The unique identifier for the user with which the member is associated. Defined by MX.

Example payload:

1
2
3
4
5
6
7
8
9
{
  "action": "CHANGED",
  "connection_status": "CHALLENGED",
  "connection_status_id": 3,
  "connection_status_message": "To authenticate your connection to Chase Bank, please answer the following challenge(s).",
  "member_guid": "MBR-48d9a481-f2a2-7e13-2685-62869cf0d33a",
  "type": "CONNECTION_STATUS",
  "user_guid": "USR-eaf4ac68-d17d-5e9b-7b46-959a5b315a9e"
}

Aggregation

A partner subscribed to the aggregation webhook will be notified when any new data is available after a successful aggregation. The webhook will include a count of new transactions and updated transactions.

These webhooks fire only after a completed aggregation, including background aggregations. Actions performed on the member through other endpoints will not trigger the webhook.

Fields for Aggregation Webhooks

Field	Data type	Description
`action`	String	The action that triggered the webhook, e.g., `member_data_updated`.
`completed_at`	Integer	The date and time at which the process that triggered the webhook was finished. Given in Unix time.
`completed_on`	String	The date on which the process that triggered the webhook was finished. Given in ISO 8601 without a timestamp.
`is_background`	Boolean	This indicates whether the aggregation was performed manually in the foreground or automatically in the background.
`job_guid`	String	The unique identifier for MX’s internal aggregation process. Defined by MX. This field is not relevant for partners using the Platform API and should be ignored.
`member_guid`	String	The unique identifier for the member which has new or updated transaction data. Defined by MX.
`transactions_created_count`	Integer	The number of newly created transactions.
`transactions_updated_count`	Integer	The number of newly updated transactions.
`type`	String	The type of webhook being delivered. Current possible values are `AGGREGATION`, `BALANCE`, `HISTORY`, and `STATEMENT`; however, additional values may be added at any time.
`user_guid`	String	Unique identifier for the user with which the data is associated. Defined by MX.
`user_id`	String	The unique partner-defined identifier for the user associated with the aggregation.

Example payload

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "action": "member_data_updated",
  "completed_at": 1531947410,
  "completed_on": "2018-07-18",
  "is_background": true,
  "job_guid": "JOB-823ab268-5107-4a67-97c8-60292572ac2e",
  "member_guid": "MBR-48d9a481-f2a2-7e13-2685-62869cf0d33a",
  "transactions_created_count": 3,
  "transactions_updated_count": 2,
  "type": "AGGREGATION",
  "user_guid": "USR-eaf4ac68-d17d-5e9b-7b46-959a5b315a9e",
  "user_id": "partner-defined-id"
}

Balance

A partner subscribed to the balance webhook will be notified when any new data is available after a successful balance fetch. The webhook will include a count of new transactions and updated transactions.

These webhooks fire only after a completed balance fetch. Actions performed on the member through other endpoints will not trigger the webhook.

Fields for Balance Webhooks

Field	Data type	Description
`action`	String	The action that triggered the webhook, e.g., `member_data_updated`.
`completed_at`	Integer	The date and time at which the process that triggered the webhook was finished. Given in Unix time.
`completed_on`	String	The date on which the process that triggered the webhook was finished. Given in ISO 8601 without a timestamp.
`memer_guid`	String	The unique identifier for the member which has new or updated transaction data. Defined by MX.
`type`	String	The type of webhook being delivered. Current possible values are `AGGREGATION`, `BALANCE`, `HISTORY`, and `STATEMENT`; however, additional values may be added at any time.
`user_guid`	String	Unique identifier for the user with which the data is associated. Defined by MX.

Example payload

1
2
3
4
5
6
7
8
{
  "action": "member_data_updated",
  "completed_at": 1531947410,
  "completed_on": "2018-07-18",
  "member_guid": "MBR-48d9a481-f2a2-7e13-2685-62869cf0d33a",
  "type": "BALANCE",
  "user_guid": "USR-eaf4ac68-d17d-5e9b-7b46-959a5b315a9e"
}

History

A partner subscribed to the history webhook will be notified when any new data is available after a successful history fetch. The webhook will include a count of new transactions and updated transactions.

These webhooks fire only after a completed history fetch. Actions performed on the member through other endpoints will not trigger the webhook.

Fields for history webhooks

Field	Data type	Description
`action`	String	The action that triggered the webhook, e.g., `member_data_updated`.
`completed_at`	Integer	The date and time at which the process that triggered the webhook was finished. Given in Unix time.
`completed_on`	String	The date on which the process that triggered the webhook was finished. Given in ISO 8601 without a timestamp.
`member_guid`	String	The unique identifier for the member which has new or updated transaction data. Defined by MX.
`transactions_created_count`	Integer	The number of newly created transactions.
`transactions_updated_count`	Integer	The number of newly updated transactions.
`type`	String	The type of webhook being delivered. Current possible values are `AGGREGATION`, `BALANCE`, `HISTORY`, and `STATEMENT`; however, additional values may be added at any time.
`user_guid`	String	Unique identifier for the user with which the data is associated. Defined by MX.

Example payload

1
2
3
4
5
6
7
8
9
10
{
  "action": "member_data_updated",
  "completed_at": 1531947410,
  "completed_on": "2018-07-18",
  "member_guid": "MBR-48d9a481-f2a2-7e13-2685-62869cf0d33a",
  "transactions_created_count": 3,
  "transactions_updated_count": 2,
  "type": "HISTORY",
  "user_guid": "USR-eaf4ac68-d17d-5e9b-7b46-959a5b315a9e"
}

Statement

A partner subscribed to the statement webhook will be notified when any new data is available after a successful statement fetch. The webhook will include a count of new statements.

These webhooks fire only after a completed statement fetch. Actions performed on the member through other endpoints will not trigger the webhook.

Fields for statement webhooks

Field	Data type	Description
`action`	String	The action that triggered the webhook, e.g., `member_data_updated`.
`completed_at`	Integer	The date and time at which the process that triggered the webhook was finished. Given in Unix time.
`completed_on`	String	The date on which the process that triggered the webhook was finished. Given in ISO 8601 without a timestamp.
`member_guid`	String	The unique identifier for the member which has new or updated transaction data. Defined by MX.
`statements_created_count`	Integer	The number of newly created transactions.
`type`	String	The type of webhook being delivered. Current possible values are `AGGREGATION`, `BALANCE`, `HISTORY`, and `STATEMENT`; however, additional values may be added at any time.
`user_guid`	String	Unique identifier for the user with which the data is associated. Defined by MX.

Example payload

1
2
3
4
5
6
7
8
9
{
  "action": "member_data_updated",
  "completed_at": 1531947410,
  "completed_on": "2018-07-18",
  "member_guid": "MBR-48d9a481-f2a2-7e13-2685-62869cf0d33a",
  "statements_created_count": 3,
  "type": "STATEMENT",
  "user_guid": "USR-eaf4ac68-d17d-5e9b-7b46-959a5b315a9e"
}

Changelog

Date	Documentation version	Reference number	Description of changes
2022.12.09	2022.030	P-628	Added: The Connect widget configuration now accepts the `include_identity` parameter.
2022.11.09	2022.013	P-607	Changed: Only standard aggregations will trigger the agg throttle period. This throttle only applies standard aggs, and no other agg-type jobs are throttled.
2022.10.17	2022.012	P-590	Added: A `400 Bad Request` error is returned when attempting premium aggregation-type jobs on members whose institution does not support it. This behavior is longstanding, but was undocumented.
2022.07.11	2022.011	P-482	Added: Section on how partners should handle webhook requests and under what circumstances an error response should be returned to MX. Section on changes that can occur in webhook payloads. Section on date and time formats in webhooks. More information on testing webhooks. Updated: Webhooks section was reorganized for easier reading and navigation.
2022.06.29	2022.010	P-475	Added: New section covering web SDK. Deprecated: Connect widget loader section.
2022.05.16	2022.009	P-434	Changed: `wait_for_full_aggregation` is no longer used. Widget behaves as if it was `true`
2022.06.06	2022.008	P-448	Added: Short descriptions of Connect’s mode options
2022.06.03	2022.007	P-424	Added: Balance jobs are limited to 5 every 2 hours.
2022.04.26	2022.006	P-429	Changed: Renamed stepChange’s `selectMember` step to `verifyExistingMember` for clarification.
2022.02.22	2022.005	P-406	Added: Added `member_guid` field to oauthRequest postMessage payload
2022.02.16	2022.004	P-399	Added: Added reference to a new Connect Widget option: `disable_background_agg`
2022.02.22	2022.003	P-406	Added: Added `member_guid` field to oauthRequest postMessage payload
2022.02.16	2022.002	P-399	Added: Added reference to a new Connect Widget option: `disable_background_agg`
2022.01.04	2022.001	P-385	Added: Only DDA accounts can be verified.
2021.11.03	2021.019	P-362	Added: Information about all fields returned with the categorize transactions endpoint response.
2021.10.15	2021.018	P-293	Added: Restored a table describing status and error codes that was erroneously removed. Changed: Aggregation throttling and the related `202` status were clarified.
2021.10.11	2021.017	P-307	Changed: The list members test endpoint example has been modified to no longer include a member with a duplicate GUID.
2021.08.24	2021.016	P-320	Added: Documented the new `logo_updated_at` field for merchant resources.
2021.08.20	2021.015	P-311	Added: `merchant_location_guid` now appears in list transaction and read transaction responses.
2021.08.19	2021.014	P-317	Changed: The definition of the `aggregated_at` field for members was updated to include more detail on when it is set and updated.
2021.08.17	2021.013	P-312	Added: The `updated_at` field is now returned on `merchant_location` resources.
2021.07.21	2021.012	P-300	Changed: The description and example response for the list account owners endpoint was modified to make it clear that it may return multiple owners for a single account.
2021.07.19	2021.011	P-269	Changed: The definitions for the `available_balance`, `available_credit`, and `balance` fields were refined for clarity.
2021.07.13	2021.010	P-291	Added: Document the `skip_aggregation` query parameter for the generate OAuth window URI member endpoint.
2021.07.08	2021.009	P-268	Changed: The definitions for the `date` and `posted_at` fields were refined for clarity.
2021.07.07	2021.008	P-278	Added: Document the `mx/connect/memberDeleted` postMessage event.
2021.07.07	2021.007	P-278	Updated: Add deprecation notice for the `mx/connect/memberAlreadyAdded` post message.
2021.06.30	2021.006	P-279	Added: Documented the `mx/connect/connected/primaryAction` post message.
2021.06.25	2021.005	P-277	Added: The `merchant_location_guid` field is now returned in responses from the enhance transactions endpoint. A new changelog format was instituted to conform with that used in other areas of the docs. Previous entries appear below this table unchanged.

June 16, 2021

Updated:
1. The examples for the read merchant location endpoint were incorrect, and have been corrected.
Removed:
1. Removed the list merchant locations endpoints that was erroneously documented.

March 15, 2021

Removed:
1. Removed documentation in the list member credentials endpoint of functionality that was never implemented in this API.

February 11, 2021

Added:
1. Documented the new member field is_oauth.

February 5, 2021

Added:
1. Documented the new insurance-related fields on the accounts resource: insured_name, pay_out_amount, and premium_amount.

January 29, 2021

Updated:
1. A new default flow for account verification was documented in both the main reference and the verification guide.

December 16, 2020

Updated:
1. The definitions of the from_date and to_date query parameters were clarified and moved into a table for all endpoints which return lists of transactions.

December 1, 2020

Added:

Documentation on the is_subscription field for the transaction resource.

November 24, 2020

Added:
1. Documentation on the generate OAuth URI endpoint.

November 5, 2020

Added:
1. Identify and verify endpoints now include the optional include_transactions parameter.

October 7, 2020

Changed:
1. Updated information on identification and verification to remove mention of standard aggregation as part of the workflow. Change made in technical reference as well as the guides for verification and identification.

August 3. 2020

Added:
1. The new mx/connect/oauthError postMessage(v4) event.

June 25. 2020

Added:
1. The addManualAccount step to the stepChange postMessage event.

May 11. 2020

Changed:
1. Reorganized the step-by-step guides for creating members and aggregating members on the “Getting Started” page.

May 1, 2020

Added
1. Create member and update member requests now support the optional background_aggregation_is_disabled parameter.

April 27, 2020

Added
1. The color_scheme configuration options for connect.

April 24, 2020

Added
1. Documentation on the balance type for the member data updated webhook.

April 23, 2020

Added:
1. The valid range for records_per_page was documented in the section on pagination.
Changed:
1. A broken link was fixed in the section on aggregation limits.
2. Information on background aggregation was clarified in things you need to know and aggregate member sections.

April 22, 2020

Added:
1. New subtypes for accounts.

March 30, 2020

Added:
1. The wait_for_full_aggregation, ui_message_version, and current_institution_guid configuration options for connect.
2. A new scenario on using the wait_for_full_aggregation configuration option.
Changed:
1. The “Connect Config Options” to have parity within all docs.

February 28, 2020

Added:
1. The institution_number and transit_number fields are now included in responses to account number requests.
2. The list merchants endpoint was added to the API.
3. Account balance requests must now be performed at an interval of at least two hours.

February 20, 2020

Added:
1. Pagination objects are now included for all cURL example responses. Pagination fields are now defined in the “Pagination” section.
Changed:
1. The “Things you need to know” section was reorganized for clarity.

February 7, 2020

Added:
1. Documented the include_transactions option for the connect widget and a scenario on how to use it.
Changed :
1. Reorganized the connect configuration options to be in alphabetical order and removed duplicate options.

January 14, 2019

Changed:
1. Improved the organization and documentation for the section on the Connect widget.
Added:
1. A table outlining scenarios for configuring the connect widget.

December 2, 2019

Added:
1. Documentation on how the logo_url field works for merchants;
2. A warning in the things you need to know section explaining that data for every field may not always be returned.
Changed:
1. Reorganized the things you need to know section to make it more alphabetical, as well as clarifying some of the language;
2. Various typos and mistakes.

November 19, 2019

Added:
1. Documentation on the merchant_category_code, as well as missing fields from some response examples for the cleanse and categorize endpoint.

November 12, 2019

Changed:
1. The response for the list MFA challenges endpoint was improperly documented, specifically for instances where type = IMAGE_OPTIONS. This has been corrected.

October 31, 2019

Changed:
1. Re-wrote and clarified the guide for verification, including added information on how to properly use the Connect widget with verification.

October 21, 2019

Changed:
1. Premium features were all grouped under their own heading, and additional clarifications about process and related errors were given.

October 20, 2019

Added:
1. Information on status codes to all aggregation-type endpoints: aggregate member, aggregate account balances, fetch statements, extended transaction history, verify member, and identify member.
2. A new section to the main developer guide on how to run multiple aggregation-type processes.

October 19, 2019

Changed:
1. Alphabetized section headings as well as subheadings within each section.

October 18, 2019

Added:
1. New is_authenticated field to the read member connection status response.

October 17, 2019

Added:
1. New aggregate member account balances endpoint.

August 29, 2019

Added:
1. New advanced configuration option for Connect: disable_institution_search.

June 13, 2019

Updated:
1. All guides were updated to reflect the correct MFA workflow. Specifically, calling the list member challenges endpoint is not usually necessary because the read member connection status endpoint will return MFA challenges whenever the connection_status is CHALLENGED.
2. Corrected some incorrect code examples in the guides for identity and verification.
3. Several images were updated to reflect the correct MFA workflow.
Added

A full data model was added to the read member connection status endpoint to make it clear that this response is not the same as the response to read member or list members.

June 5, 2019

Updated:
1. An example response in the Atrium guide contained an incorrect member status and was corrected.

May 21, 2019

Updated:
1. The section on webhooks now links back to the definitions for connection_status where appropriate.
2. The example responses for the list account transactions endpoint were missing the merchant_guid field.
3. The section on webhooks now directs developers to whitelist their own IP addresses at the appropriate portal page, rather than contacting support.
4. Certain values for account types and subtypes were missing underscores or used dashes inappropriately.

March 21, 2019

Added:
1. Documentation about configuring and testing webhooks, with a link to the webhooks profile in the Atrium portal.
Updated
1. Rearranged the documentation on webhooks for improved clarity.

February 25, 2019

Added:
1. Documentation on two new webhooks: extended history and statements.

February 22, 2019

Added:
1. Documentation on the new download statement PDF endpoint.
2. Documentation on the new read statement endpoint.

February 7, 2019

Removed:
1. Documentation related to the type parameter for aggregation events.
Added:
1. A new premium endpoint for gathering an extended transaction history.
2. A new premium endpoint for fetching account statements.

January 30, 2019

Added
1. Documentation on new aggregation types.
2. Documentation on the new statements endpoint.
3. Documented two new fields for institutions: supports_transaction_history and supports_account_statements.

January 28, 2019

Updated:
1. The definition of the total_account_value field for accounts has been modified for clarity.
2. The definition for connection_status field for members was updated to include the correct data type and fix a broken table.

January 11, 2019

Added:
1. Code examples in several new languages for the getting started guide.
2. Code examples in several new languages for the verification guide.
3. Code examples in several new languages for the identification guide.

December 18, 2018

Added:
1. Documentation for the new holdings endpoints and associated resources.

December 12, 2018

Added:
1. Documentation for the merchants endpoint.
2. Merchant GUIDs are now returned in responses for the cleanse and categorize endpoint.
Fixed
1. A number of typos and broken links were addressed.

November 26, 2018

Added:
1. The display_order field was added to both institution credentials and member credentials.

November 19, 2018

Added the fields supports_account_verification and supports_account_identification to the institution resource.
Added the ability to search institutions according to whether they support identity and/or verification.
Clarified that the limit of 25 members per user applies to all environments, not just the development environment.

November 16, 2018

Added:
1. Documentation for Atrium webhooks.

September 20, 2018

Added:
1. Added a warning about getting 403 errors for identity and/or verification even when these premium features are enabled on an institution.
Changed
1. Clarified information about the necessity of having MX enable premium features before they can be used, as well as error messages when they are not enabled.

August 13, 2018

Added:
1. Ruby code examples for all endpoints related to both identity and verification in both the technical reference and the guides.
2. The currency_code field on accounts and transactions.
3. Information on IP address whitelisting.

July 20, 2018

Added:
1. Documentation for the verify and account numbers endpoints under the new section on account verification.
2. Documentation for the identify and account owners endpoints under the new section on identity verification.
3. A guide to using Atrium Identity Verification.
4. A guide to using Atrium Account Verification.

April 25, 2018

Updated support escalation information in the Member statuses section of the Getting Started with Atrium guide.

April 20, 2018

Added the is_international field to the specification for transactions, as well as related code examples.

March 6, 2018

Added a new page entitled “Getting started with Atrium” containing information on common questions, workflows, procedures, etc. to help developers get going with the API as fast as possible.

February 14, 2018

Added code examples for several languages.

December 5, 2017

Member connection statuses have been taken out of beta. The section on reading the member status has been updated to reflect this.
The new is_being_aggregated field was added to facilitate the use of member connection statuses.

November 21, 2017

Fixed a mistake that resulted in listing the Investments categories as subcategories of Income.

October 4, 2017

Added documentation on the new list member credentials endpoint.
Updated the “next steps” column on the table under read member status to reflect the new flow when using the list member credentials endpoint.

September 13, 2017

Complete site redesign and documentation rewrite.
Added images to show correct aggregation workflow
Added change log to documentation
Added section on Beta member connection statuses