Overview

Atrium’s verification allows partners to retrieve the account and routing information for an end user in just a few simple steps. These steps are very similar to those for standard aggregation.

Partners may optionally use the Connect widget as part of this process. The Connect widget simplifies creating members and answering multi-factor authentication while providing a ready-made user interface for these verification steps.

The general workflows you’ll follow depend on whether you decide to use the Connect widget or build your own UI that relies on Atrium.

These workflows are a simplified summary, and some will require multiple requests to different endpoints. The exact details are laid out in our technical reference.

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

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

For important information on errors, standards and conventions, and resource structure in Atrium, please see our technical reference.

Workflow with the Connect widget

  1. Creating a user;
  2. Loading the Connect widget for that user;
  • The end user will use Connect to create a member, start a verification job, and answer multi-factor authentication if necessary;
  • Listen for the messages sent by the Connect widget;
  1. Poll the member’s verification status until an end state is reached;
  • A verification is successful when the connection_status is CONNECTED and the the is_aggregating field changes from true to false;
  1. Answer MFA, if necessary;
  2. If the verification is successful, reading the new member’s account numbers.

Workflow with API requests only

  1. Creating a user;
  2. Creating a member using the correct institution code and credentials required by that institution;
  • When a member is created, a standard aggregation is automatically started; this can be stopped with the skip_aggregation parameter;
  1. Calling the verify endpoint;
  2. Poll the member’s verification status;
  3. Answering MFA, if necessary;
  4. Answer the special account-selection challenge (the legacy flow skips this step and instead verifies all accounts);
  5. Poll the verification status until an end state is reached;
    • A verification is successful when the connection_status is CONNECTED and the the is_aggregating field changes from true to false;
  6. If the verification is successful, listing the new member’s account numbers.

Using the Connect widget


1. Create a user

Use this endpoint to create a new user. The API will respond with the newly-created user object if successful.

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 Required?
email No
id No
is_disabled No
metadata No

2. Load the Connect widget in verification mode

To get started with Connect, 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"
  }
}

3. End users enter their credentials and launch a verification job

Connect handles the creation of a member as well as the verification and MFA processes. It automatically asks end users to search for an institution, give credentials, determine which specific account they’d like to verify, and deal with any errors along the way.

With all this in mind, you’ll need to listen for a couple important event messages from Connect: member status update and member connected. The first will give you the member_guid and the current connection_status, which will give you an idea of what’s happening with connection process; the second will tell you when the member has been successfully connected so you can move on to the next steps. If your implementation uses WebViews, you’ll need to listen for the same messages, but given through the postMessage alternative for WebViews.

Alternatively, if the end user closes Connect early or some other problem occurs before you see a CONNECTED status, you can simply use the member_guid to immediately check the member’s connection status as shown in step 4.


4. Poll the member connection status

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

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

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

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

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

Read member connection status fields

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

Status definitions (soon to be deprecated)

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

Endpoint:

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

Example request

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

Example response

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

5. Read the account numbers

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

Endpoint:

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

Example request

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

Example response

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

Using Atrium endpoints


1. Create a user

Use this endpoint to create a new user. The API will respond with the newly-created user object if successful.

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 Required?
email No
id No
is_disabled No
metadata No

2. Create a member

2.1. Get the institution code

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

2.2. Get the institution’s required credentials

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

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

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

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

Endpoint:

GET /institutions/{institution_code}/credentials

Example request

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

Example response

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

2.3. Create the member

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

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

OAuth members will be created with a connection status of PENDING; a one-time use redirect URI will be provided in the oauth_window_uri field of the response. Making a separate request to the oauth_window_uri will then take the end user to the registered OAuth application where they can provide credentials and choose 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.

Parameter Required?
identifier No
institution_code Yes
metadata No
skip_aggregation No
is_oauth No
referral_source 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":"chase",
          "metadata": "Additional information",
          "is_oauth": true
        },
        "referral_source": "APP",
        "ui_message_webview_url_scheme": "yourapp"
      }'

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": "chase",
    "is_being_aggregated": true,
    "metadata": "Additional information",
    "name": "Chase Bank",
    "oauth_window_uri": "https://dev-firefly1.moneydesktop.com/oauth/predirect_to/MBR-7aa13bdb-2866-ba38-b326-d9fb32268f9b/lk76038j23cAstpxnt4g58vybqZqg9vnn0lz29bwmvc40tss5rhjxlyf53pns05vfd99y5m766fdj7njpf615A5j3013xmdqA9mwz5nAgs9gr2887h0krh1l4gbAxfp8ztnpd47wk6j2ztjbz1f0lyr73nbxft0pwjwkqdjnfpA8ktn9tbvAbxqn40645vs4kxxcAx2rjc0vyxhtfhsk5vpq3Anrmdjtfj8qlpc617bkntbAwlpylfqf4AshyvA6lpmn5ptrzqhd933k98rzymzmjgqy9m25np0fqm7zw6Akr8qyy5ckb6wxxA31vfjw5xm7td8z6vh7d0djwsgw34Awvj58psh2l7xk9414?referral_source=APP&ui_message_webview_url_scheme=yourapp",
    "status": null,
    "successfully_aggregated_at": null,
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
  }
}

3. Verify the member

The verify endpoint begins a verification process for a member. It gathers information about account and routing numbers. Partners may optionally choose to include transaction data in this request, potentially avoiding a separate aggregate member request.

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

If a verification is already running, a 202 Accepted status will be returned. If another aggregation-type process is already running — like standard aggregation 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.

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

4. Poll the member connection status

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

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

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

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

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

Read member connection status fields

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

Status definitions (soon to be deprecated)

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

Endpoint:

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

Example request

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

Example response

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

5. Answer MFA if necessary

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

6. Answer the special account-selection challenge

The default flow for verification requires you or the end user to choose one account associated with the member to verify. In order to accomplish this, MX sends a special MFA challenge which lists all the accounts associated with the member. This challenge should appear on the read member status response, but you can also see it with the read member challenges endpoint.

Answer this challenge with a value for one account using the resume aggregation endpoint just as you would normal MFA.

If you are using the legacy flow, this step can be skipped.

6.1 Read the member’s status (or read the member’s challenges)

Endpoint:

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

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
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
  "member": {
    "aggregated_at": "2016-10-13T18:24:37+00:00",
    "challenges": [
      {
        "field_name": null,
        "guid": "CRD-6cad1604-d341-4e37-b63d-6f6cbb79f0b7",
        "label": "Please select an account:",
        "options": [
          {
            "label": "MX Bank Checking",
            "value": "account-bb0ca38d-2193-4ba7-8116-5703105a498a"
          },
          {
            "label": "MX Bank Savings",
            "value": "account-4de4392e-64a5-489d-a237-acde82e91fa5"
          }
        ],
        "type": "OPTIONS"
      }
    ],
    "connection_status": "CHALLENGED",
    "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "has_processed_accounts": false,
    "has_processed_transactions": false,
    "is_authenticated": false,
    "is_being_aggregated": true,
    "status": "CHALLENGED",
    "successfully_aggregated_at": "2016-10-13T18:08:04+00:00"
  }
}

6.2 Resume the aggregation

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
$ 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": "CRD-6cad1604-d341-4e37-b63d-6f6cbb79f0b7",
               "value": "account-bb0ca38d-2193-4ba7-8116-5703105a498a"
            }
          ]
        }
      }'

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

7. List the account numbers

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

Endpoint:

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

Example request

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

Example response

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

Testing verification

To test your setup without incurring the cost of calling the verify endpoint, Atrium has test endpoints available.

Simply modify the URL to contain the user GUID test_atrium and the member GUID test_atrium_member.

The endpoint URLs will then be as follows:

/users/test_atrium/members/test_atrium_member/verify

/users/test_atrium/members/test_atrium_member/account_numbers


Changelog

Date Documentation version Reference number Description of changes
2021.11.03 2021.019 P-362 Added:
  1. Information about all fields returned with the categorize transactions endpoint response.
2021.10.15 2021.018 P-293 Added:
  1. Restored a table describing status and error codes that was erroneously removed.
Changed:
  1. Aggregation throttling and the related 202 status were clarified.
2021.10.11 2021.017 P-307 Changed:
  1. The list members test endpoint example has been modified to no longer include a member with a duplicate guid.
2021.08.24 2021.016 P-320 Added:
  1. Documented the new logo_updated_at field for merchant resources.
2021.08.20 2021.015 P-311 Added:
  1. merchant_location_guid now appears in list transaction and read transaction responses.
2021.08.19 2021.014 P-317 Changed:
  1. The definition of the aggregated_at field for members was updated to include more detail on when it is set and updated.
2021.08.17 2021.013 P-312 Added:
  1. The updated_at field is now returned on merchant_location resources.
2021.07.21 2021.012 P-300 Changed:
  1. The description and example response for the list account owners endpoint was modified to make it clear that it may return multiple owners for a single account.
2021.07.19 2021.011 P-269 Changed:
  1. The definitions for the available_balance, available_credit, and balance fields were refined for clarity.
2021.07.13 2021.010 P-291 Added:
  1. Document the skip_aggregation query parameter for the generate OAuth window URI member endpoint.
2021.07.08 2021.009 P-268 Changed:
  1. The definitions for the date and posted_at fields were refined for clarity.
2021.07.07 2021.008 P-278 Added:
  1. Document the mx/connect/memberDeleted postMessage event.
2021.07.07 2021.007 P-278 Updated:
  1. Add deprecation notice for the mx/connect/memberAlreadyAdded post message.
2021.06.30 2021.006 P-279 Added:
  1. Documented the mx/connect/connected/primaryAction post message.
2021.06.25 2021.005 P-277 Added:
  1. The merchant_location_guid field is now returned in responses from the enhance transactions endpoint.
  2. A new changelog format was instituted to conform with that used in other areas of the docs. Previous entries appear below this table unchanged.

June 16, 2021

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

March 15, 2021

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

February 11, 2021

  • Added:
    1. Documented the new member field is_oauth.

February 5, 2021

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

January 29, 2021

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

December 16, 2020

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

December 1, 2020

  • Added:
  1. Documentation on the is_subscription field for the transaction resource.

November 24, 2020

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

November 5, 2020

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

October 7, 2020

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

August 3. 2020

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

June 25. 2020

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

May 11. 2020

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

May 1, 2020

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

April 27, 2020

  • Added
    1. The color_scheme configuration options for connect.

April 24, 2020

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

April 23, 2020

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

April 22, 2020

  • Added:
    1. New subtypes for accounts.

March 30, 2020

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

February 28, 2020

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

February 20, 2020

February 7, 2020

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

January 14, 2019

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

December 2, 2019

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

November 19, 2019

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

November 12, 2019

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

October 31, 2019

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

October 21, 2019

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

October 20, 2019

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

October 19, 2019

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

October 18, 2019

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

October 17, 2019

  • Added:
    1. New aggregate member account balances endpoint.

August 29, 2019

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

June 13, 2019

  • Updated:
    1. All guides were updated to reflect the correct MFA workflow. Specifically, calling the list member challenges endpoint is not usually necessary because the read member connection status endpoint will return MFA challenges whenever the connection_status is CHALLENGED.
    2. Corrected some incorrect code examples in the guides for identity and verification.
    3. Several images were updated to reflect the correct MFA workflow.
  • Added
  1. A full data model was added to the read member connection status endpoint to make it clear that this response is not the same as the response to read member or list members.

June 5, 2019

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

May 21, 2019

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

March 21, 2019

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

February 25, 2019

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

February 22, 2019

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

February 7, 2019

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

January 30, 2019

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

January 28, 2019

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

January 11, 2019

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

December 18, 2018

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

December 12, 2018

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

November 26, 2018

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

November 19, 2018

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

November 16, 2018

September 20, 2018

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

August 13, 2018

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

July 20, 2018

April 25, 2018

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

April 20, 2018

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

March 6, 2018

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

February 14, 2018

Added code examples for several languages.

December 5, 2017

November 21, 2017

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

October 4, 2017

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

September 13, 2017

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