Skip to main content

Instant Account Verification

The Atrium API's premium verification feature allows partners to access account and routing numbers for demand deposit accounts in just a few simple steps. Functionally, this means that only CHECKING and SAVINGS accounts are likely to be verified.

The verification process is very similar to 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.
    • Answer MFA, if necessary.
  3. If the verification is successful, reading the new member's account numbers.

Workflow with API requests only​

info

Verification now includes two separate API workflows depending on the partner's needs. In the new default flow (shown below), the partner or end user must choose only one account associated with the member to verify — this is done through a specialized MFA challenge. This flow is generally faster, which is why it is now the default. The legacy workflow, on the other hand, verifies every account associated with a member.

New partners will default to the new workflow. They can, however, have MX enable the legacy flow if desired. Existing partners will be left with the legacy workflow but may have the new flow enabled if desired.

  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.
  3. Calling the verify endpoint.
  4. Poll the member's verification status.
  5. Answering MFA, if necessary.
  6. Answer the special account-selection challenge (the legacy flow skips this step and instead verifies all accounts).
  7. Poll the verification status until an end state is reached.
    • A verification is successful when the connection_status is CONNECTED and the is_aggregating field changes from true to false.
  8. If the verification is successful, listing the new member's account numbers.

Using The Connect Widget​

Step 1

Create A User​

For further details on users, click here.

Endpoint: POST /users

Request
Response
Language:shell

_11
curl -i -X POST 'https://vestibule.mx.com/users' \
_11
-H 'Accept: application/vnd.mx.atrium.v1+json' \
_11
-H 'Content-Type: application/json' \
_11
-H 'MX-API-Key: {mx_api_key}' \
_11
-H 'MX-Client-ID: {mx_client_id}' \
_11
-d '{
_11
"user": {
_11
"identifier": "unique_id",
_11
"metadata": "{\"first_name\": \"Steven\"}"
_11
}
_11
}'

Step 2

Load The Connect Widget in Verification Mode​

Endpoint: POST /users/{user_guid}/connect_widget_url

Request
Response
Language:shell

_10
curl -i -X POST 'https://vestibule.mx.com/users/{user_guid}/connect_widget_url' \
_10
-H 'Accept: application/vnd.mx.atrium.v1+json' \
_10
-H 'Content-Type: application/json' \
_10
-H 'MX-API-Key: {mx_api_key}' \
_10
-H 'MX-Client-ID: {mx_client_id}'
_10
-d '{
_10
"color_scheme": "dark",
_10
"mode": "verification"
_10
}'

Step 3

End Users Enter Their Credentials and Launch a Verification Process​

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 check the member's connection status.

Request
Response
Language:shell

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

Step 4

List the Account Numbers​

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

Request
Response
Language:shell

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

On this page