Fetch Account and Routing Numbers
This guide is for Platform API v2011101. For guidance on the newest version, see Connectivity Integration Guides.
The following guide starts at the beginning and shows you how to navigate the Platform API to get an end user's account and routing number for verification.
Before following the steps in this guide, you'll need to:
- Sign up for access to the Platform API and get your development API keys.
- Retrieve your
client_idandapi_keyas you’ll need them to pass requests. - Whitelist your IP addresses.
- Ensure all requests are using HTTPS with TLSv1.2 encryption or higher or else they will fail.
Keep the following in mind:
- IAV applies only to demand deposit accounts. Functionally, this means that only
CHECKINGandSAVINGSaccounts are likely to return account/routing numbers. - IAV does not provide a complete money movement or payments solution. Rather, it provides the necessary account numbers to facilitate payments through payment processors and the ACH system.
- Account and routing numbers can be used for ACH transfers for as long as the account is still open; in most cases, you don't need to use IAV for an account more than once.
Workflow
You’ll use this workflow with the Platform API.
- Create a
user. - Create a
memberusing the correct institution code and credentials required by that institution. When a member is created, an Account Aggregation is automatically started; this can be stopped with theskip_aggregationparameter. - Call the
verifyendpoint. - Poll the member’s connection status.
- Answer multifactor authentication, if necessary.
- Answer the special account-selection challenge.
- Poll the verification status until an end state is reached. A verification is successful when the
connection_statusisCONNECTEDand theis_aggregatingfield changes fromtruetofalse. - List the member’s account numbers.
Create a user
A user represents your end user in the MX Platform. Make a request to the Create User endpoint (POST /users).
We recommend that you include a unique id of your choice with the request. You may also include metadata, such as the date the user was created or the end user's name. Don't include any sensitive information here, such as credentials.
None of these parameters are required, but the user object can't be empty. We recommend that you always set the id parameter when creating a user.
In the response, the API gives each new user an MX-defined guid (or user_guid when appearing outside the user object). Between your id and the guid, you can map between your system and ours. You'll need the user guid for nearly every request on the MX API, at least when using basic authorization.
Create a Member
Next, create a member. A member represents the relationship between a user and an institution, and creating one is how you connect one to the other. Multiple members may be attached to a single user (for example, one member for their bank, another for their mortgage provider, another for their credit card provider, etc.).
To create a member:
- Search for an institution
- Get the institution-required credentials
- Make a request to the create member endpoint
a. Search for an Institution
First, you need to know what financial institution the member should be connected to and what type of credentials the institution expects to get.
Search for an institution by making a GET request using query parameters on the list institutions endpoint
The example that follows searches for MX Bank, which is MX’s institution for testing and development.
The response returns a paginated list of institutions that match the string you send in the name query parameter. Make a note of the code you find in the example response; you’ll need this for the next step.
b. Get the Institution-Required Credentials
Each institution requires different types of credentials. Some require an email and a password, some require a username and a password, and some may require other types of credentials.
Make a GET request to the list institution credentials endpoint.
Include the institution code retrieved from the previous step in the request URL. This endpoint returns the guid for each credential returned, which is used to match the credentials the end user provides to the required credential type in the next step.
c. Create the Member
After you have the user_guid, an institution_code, and a guid for each credential required by the institution, create a new member. For this step, you need the values provided by the end user for each necessary credential.
Make a POST request to the create member endpoint shown below. There are several parameters that you can pass in this request which are included in the table below.
| Parameter | Data Type | Description | Required? |
|---|---|---|---|
background_aggregation_is_disabled | Boolean | When set to true, background aggregation will be disabled for this member. | No |
credentials | Array | The credentials endpoint for the requested institution will give you a list of all the credentials required to create a member for a given institution. Each required credential will need to be included within this array. | Yes |
id | String | The unique partner-defined identifier for the member. | No |
institution_code | String | The unique code for the institution to which the member will connect. Defined by MX. | Yes |
metadata | String | Additional information you can store on this member. | No |
The following example uses MX Bank and requires a username and a password. It sets the username to mxuser and the password to password which are the credentials for the test user for MX Bank. For real institutions, these values must be the end user’s correct login information.
Note: Do not add multiple members that connect to the same institution using the same credentials on the same user. This will result in a 409 Conflict error.
If the request is successful, the response returns with the newly created member and indicates that the connection process has started. The connection_status should be CREATED and the is_being_aggregated field should be true.
The connection_status must be one of the following in order to continue with verification. For this guide, we just created a member so the connection_status is still CREATED and we can move forward, but if you've already connected a member for a different reason, validate that the status is one of the following. Also, validate that is_being_aggregated: false because you cannot initiate verification for a member if a connection already in process.
CREATEDCONNECTEDDEGRADEDDISCONNECTEDEXPIREDFAILEDIMPEDEDRECONNECTEDUPDATED
We suggest you add a Connection Status Webhook in the Client Dashboard. We provide webhooks that send HTTPS POST callback requests to the URL of your choice. This webhook notifies you whenever a member's connection_status field enters into an end-user-actionable state. For more information on webhooks, click here.
Fetch Account and Routing Number
Now that you've created a member, you can request account and routing number to verify the end-user's financial account using Instant Account Verification (IAV).
To start the process, make a POST request to the verify member endpoint.
The response indicates the status of the request. Next you'll check the connection status and answer any possible challenges.
a. Check the Connection Status
After verification has been initiated, poll the member by making a GET request to the read member endpoint. We suggest you invoke this call every 2 to 3 seconds until a member is in a connected state and no longer being aggregated.
_10curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/status' \_10-H 'Accept: application/vnd.mx.api.v1+json' \_10-u 'client_id:api_key'
Poll until the connection_status is CONNECTED and is_being_aggregated. This indicates that the member has been authenticated and verification has begun.
_10{_10 "member": {_10 "aggregated_at": null,_10 "connection_status": "CREATED",_10 "guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",_10 "is_authenticated": false,_10 "is_being_aggregated": true,_10 "successfully_aggregated_at": null_10 }_10}
b. Answer the Account-Selection Challenge
The end user must select which account to verify. If you have to select an account, the status switches to CHALLENGED, and the response includes the challenges you need to answer.
If you don’t get the challenge and the member goes to connection_status: IMPEDED and is_being_aggregated: false, it means that there are no eligible accounts to verify and there’s nothing more to do.
Use the Resume Endpoint
To answer the account-selection challenge, present the challenge from the previous step to end users, gather their response, and return it to MX using the resume endpoint. You may or may not run into MFA issued by the institution. If you do, you may get challenged multiple times.
Use the resume aggregation endpoint to answer the challenge. Include the appropriate credential GUID with the value chosen by the end user.
The response should come back with connection_status: RESUMED.
Check the Status Again
Check connection_status, is_being_aggregated, and successfully_aggregated_at.
- The
is_being_aggregatedfield indicates whether verification is complete; it’ll betruewhile IAV is running andfalsewhen complete. - When you see
connection_status: CONNECTEDandis_being_aggregated: falseat the same time, verification is done and you can pull account and routing data. - The
successfully_aggregated_atfield gives the exact time verification was finished.
Read the Account Numbers
When verification is complete, retrieve account and routing numbers. There are two endpoints for this: list account numbers by member and list account numbers by account. The first is shown here.
- If MX has both an account number and a routing number for at least one of the member's accounts, that information is returned. No information is returned for accounts that are missing a value for one or both of these fields.
- The account number returned from this endpoint may be a Tokenized Account Number (TAN). See the section on TANs for information on dealing with these properly.