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/
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.
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.
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.
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.
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 . |
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.
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.
Requests to Atrium must use characters encoded with the UTF-8 standard.
JSON structured data is returned in all responses, including some errors.
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
.
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 | Explanation |
---|---|
2xx Success | |
200 OK |
Everything worked as expected with content returned. |
202 Accepted |
|
204 No Content |
Everything worked as expected without content returned. |
4xx Requester error | |
400 Bad Request |
|
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.",
}
}
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'."
}
}
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.
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.
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.
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
.
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.
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 . |
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
}
The developer guide explains how to test your setup using our test endpoints and test credentials.
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
.
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.
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. |
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 |
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
}
}
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"
}
}
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 represent a stock, bond, or other type of investment.
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
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
}
}
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
}
}
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
}
}
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"
}
}
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.
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 . |
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
}
}
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"
}
}
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"
}
]
}
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.
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. |
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"
}
}
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"
}
}
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_uri
s 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"
}
}
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
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:
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"
}
}
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
}
}
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"
}
]
}
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
}
}
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 ..."
}
]
}
]
}
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
}
}
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"
}
}
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 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. |
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"
}
}
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"
}
}
A merchant
contains information about the merchant, business, company, or seller associated with a specific transaction
. This information includes a name, logo, and website.
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 . |
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
}
}
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 detail the physical address, longitude, latitude, contact information, etc. for a specific location of a merchant.
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. |
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"
}
}
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
.
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. |
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 |
Transactions may have one of two statuses: PENDING
or POSTED
. How these statuses are reconciled depends on a number of factors.
POSTED
.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.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.PENDING
and POSTED
transactions on MX systems for up to 14 days. All PENDING
transactions are deleted after 14 days as a failsafe.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 . |
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. |
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"
}
]
}
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
}
}
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"
}
}
A user
represents a person using Atrium via your application, be it a mobile app, web app, desktop app, etc.
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. |
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\"}"
}
}
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
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\"}"
}
]
}
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\"}"
}
}
Use this endpoint to update the attributes of a specific user
. Atrium will respond with the updated user
object.
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.
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\"}"
}
}
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.
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"
}
}
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.
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. |
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} }'
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} }'
Setting the mode
to verification
will change several behaviors in Connect:
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" }'
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
).
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.
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 }'
It is imperative that you correctly configure Connect when embedding in a WebView. See the webview section for more information.
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.
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 }'
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.
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>
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)
}
}
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)
}
}
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)")
}
}
}
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.
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
}
}
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"
}
}
The events below are specific to events that happen in the Connect widget.
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"
}
}
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"
}
}
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"
}
}
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"
}
}
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"
}
}
}
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"
}
}
}
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"
}
}
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"
}
}
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"
}
}
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
}
}
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"
}
}
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"
}
}
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"
}
}
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"
}
}
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"
}
}
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
}
}
}
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:
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.
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>
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.
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
202 Accepted
status will be returned.400 Bad Request
error will be returned.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.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"
}
}
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.
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. |
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
202 Accepted
status will be returned.400 Bad Request
error will be returned.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.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"
}
}
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
}
}
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.
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. |
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}'
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
202 Accepted
status will be returned.400 Bad Request
error will be returned.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.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"
}
}
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
}
}
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"
}
}
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.
connection_status
;connection_status
again;For more detailed information on the process, see the account verification guide.
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. |
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
}
}
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
}
}
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
202 Accepted
status will be returned.400 Bad Request
error will be returned.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.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"
}
}
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.
The current version of MX webhooks has the following features:
Date and time fields are supported in either Unix Epoch time (no milliseconds), or in ISO 8601 with no timestamp (YYYY-MM-DD).
_at
are Unix Epoch time (no milliseconds), e.g. 1504224000
._on
are ISO 8601 (no timestamp), e.g. 2017-09-01
.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:
Provide MX with a username and password for making basic HTTP requests to your chosen URL.
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:
Use this CSR to purchase a certificate, and then send it to MX. This certificate will be used to authenticate requests originating from MX.
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.
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"
}
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"
}
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.
200 OK
201 CREATED
202 ACCEPTED
203 NON_AUTHORITATIVE_INFORMATION
204 NO_CONTENT
205 RESET_CONTENT
206 PARTIAL_CONTENT
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 |
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.
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.
1
2
3
4
5
{
"action": "test",
"account": {},
"version": 1
}
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"
}
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"
}
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"
}
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"
}
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"
}
Date | Documentation version | Reference number | Description of changes |
---|---|---|---|
2022.12.09 | 2022.030 | P-628 | Added:
|
2022.11.09 | 2022.013 | P-607 | Changed:
|
2022.10.17 | 2022.012 | P-590 | Added:
|
2022.07.11 | 2022.011 | P-482 | Added:
|
2022.06.29 | 2022.010 | P-475 | Added:
|
2022.05.16 | 2022.009 | P-434 | Changed:
|
2022.06.06 | 2022.008 | P-448 | Added:
|
2022.06.03 | 2022.007 | P-424 | Added:
|
2022.04.26 | 2022.006 | P-429 | Changed:
|
2022.02.22 | 2022.005 | P-406 | Added:
|
2022.02.16 | 2022.004 | P-399 | Added:
|
2022.02.22 | 2022.003 | P-406 | Added:
|
2022.02.16 | 2022.002 | P-399 | Added:
|
2022.01.04 | 2022.001 | P-385 | Added:
|
2021.11.03 | 2021.019 | P-362 | Added:
|
2021.10.15 | 2021.018 | P-293 | Added:
|
2021.10.11 | 2021.017 | P-307 | Changed:
|
2021.08.24 | 2021.016 | P-320 | Added:
|
2021.08.20 | 2021.015 | P-311 | Added:
|
2021.08.19 | 2021.014 | P-317 | Changed:
|
2021.08.17 | 2021.013 | P-312 | Added:
|
2021.07.21 | 2021.012 | P-300 | Changed:
|
2021.07.19 | 2021.011 | P-269 | Changed:
|
2021.07.13 | 2021.010 | P-291 | Added:
|
2021.07.08 | 2021.009 | P-268 | Changed:
|
2021.07.07 | 2021.008 | P-278 | Added:
|
2021.07.07 | 2021.007 | P-278 | Updated:
|
2021.06.30 | 2021.006 | P-279 | Added:
|
2021.06.25 | 2021.005 | P-277 | Added:
|
is_oauth
.accounts
resource: insured_name
, pay_out_amount
, and premium_amount
.from_date
and to_date
query parameters were clarified and moved into a table for all endpoints which return lists of transactions.is_subscription
field for the transaction resource.include_transactions
parameter.mx/connect/oauthError
postMessage(v4) event.addManualAccount
step to the stepChange
postMessage event.background_aggregation_is_disabled
parameter.color_scheme
configuration options for connect.records_per_page
was documented in the section on pagination.wait_for_full_aggregation
, ui_message_version
, and current_institution_guid
configuration options for connect.wait_for_full_aggregation
configuration option.institution_number
and transit_number
fields are now included in responses to account number requests.include_transactions
option for the connect widget and a scenario on how to use it.logo_url
field works for merchants;merchant_category_code
, as well as missing fields from some response examples for the cleanse and categorize endpoint.type
= IMAGE_OPTIONS
. This has been corrected.is_authenticated
field to the read member connection status response.disable_institution_search
.connection_status
is CHALLENGED
.status
and was corrected.connection_status
where appropriate.merchant_guid
field.type
parameter for aggregation events.supports_transaction_history
and supports_account_statements
.total_account_value
field for accounts has been modified for clarity.connection_status
field for members was updated to include the correct data type and fix a broken table.display_order
field was added to both institution credentials and member credentials.supports_account_verification
and supports_account_identification
to the institution
resource.user
applies to all environments, not just the development environment.403
errors for identity and/or verification even when these premium features are enabled on an institution.currency_code
field on accounts and transactions.Updated support escalation information in the Member statuses section of the Getting Started with Atrium guide.
is_international
field to the specification for transactions, as well as related code examples.Added code examples for several languages.
is_being_aggregated
field was added to facilitate the use of member connection statuses.