> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mx.com/llms.txt
> Use this file to discover all available pages before exploring further.
# API-Only Implementation
## 1. Create a User
```shell theme={null}
curl -i -X POST https://int-live.moneydesktop.com/:client_id/users.json \
-H "Content-Type: application/vnd.moneydesktop.mdx.v5+json" \
-H "Accept: application/vnd.moneydesktop.mdx.v5+json" \
-H "MD-API-KEY: :api_key" \
-d '{
"user": {
"birthdate": "1959-07-17",
"credit_score": "718",
"email": "example@example.com",
"first_name": "John",
"gender": "MALE",
"id": "U-39XBF7",
"last_name": "Smith",
"metadata": "Additional Information",
"phone": "5055551234",
"zip_code": "87101"
}
}'
```
```json theme={null}
{
"user": {
"id": "U-39XBF7",
"birthdate": "1959-07-17",
"gender": "MALE",
"first_name": "John",
"guid": "USR-c4321d57a-9ae4-1fe3-6c4e-96a84fb92b50",
"last_name": "Smith",
"metadata": "Additional Information",
"credit_score": 718,
"email": "example@example.com",
"phone": "(505) 555-1234",
"zip_code": "87101",
"is_disabled": false,
"logged_in_at": null
}
}
```
## 2. Get an API Token
This endpoint returns an `api_token` which can then be used to open a Nexus session. The `user_id` must match the id specified when creating a the user.
Each api\_token is one-time use and expires in ten minutes. A fresh `api_token` must be requested each time a Nexus session is initiated.
```shell theme={null}
curl -i https://int-sso.moneydesktop.com/:client_id/users/:user_id/api_token.xml \
-H "Accept: application/vnd.moneydesktop.sso.v3+xml" \
-H "MD-API-KEY: :api_key"
```
```json theme={null}
{
"api_token": {
"token": "VVCFDQY3Iig3ODM3LTlmNDItMmY1OS03NDZhLWIwNTcwNDc2NGRiNXwzZjg1MTQ4YzAyMThkZjI2OTI2ZjFjYmJhNmY1MzU2MTI0MThiNTIyOGVjYjg4YTRjNjljODJhYTQ3MWMwMTQyZGY5ZmM1OGQ2YmU1M2ZiMjNlOWZhZTE3Y2MxNjU4YWYxYmE0NjRiMDg3Nzk4N2U0YzU5ZTE1NjM1MDUwYjEzMTkzYzYyMzhiYjY3MDhmNjEyOGIzNjIyMDIwMmMzZTIzfFlVam1oSmhaOHNMMGVlMTg0YWhBODdmZWlVRmh4YlNKVGhVZUM4RVl5QXc="
}
}
```
## 3. Open a Nexus Session
Use this endpoint to get a session token. This session token must be sent as a header with each Nexus request. Each Nexus session is opened in the context of a single user associated with that session token.
When using the verification endpoints the create session request body should contain `skip_aggregation:true`, as shown in the example below. This will prevent automatic aggregation being initiated for the user's existing members when the session is opened. Partners can then choose to aggregate the existing member, or to proceed directly to the verify member endpoint.
```shell theme={null}
curl -i -X POST https://int-data.moneydesktop.com/sessions \
-H 'MD-API-TOKEN: VVCFDQY3Iig3ODM3LTlmNDItMmY1OS03NDZhLWIwNTcwNDc2NGRiNXwzZjg1MTQ4YzAyMThkZjI2OTI2ZjFjYmJhNmY1MzU2MTI0MThiNTIyOGVjYjg4YTRjNjljODJhYTQ3MWMwMTQyZGY5ZmM1OGQ2YmU1M2ZiMjNlOWZhZTE3Y2MxNjU4YWYxYmE0NjRiMDg3Nzk4N2U0YzU5ZTE1NjM1MDUwYjEzMTkzYzYyMzhiYjY3MDhmNjEyOGIzNjIyMDIwMmMzZTIzfFlVam1oSmhaOHNMMGVlMTg0YWhBODdmZWlVRmh4YlNKVGhVZUM4RVl5QXc=' \
-H 'Content-Type: application/vnd.mx.nexus.v1+json' \
-H 'Accept: application/vnd.mx.nexus.v1+json' \
-d '{"session":{"skip_aggregation":true}}'
```
```json theme={null}
{
"session":{
"token":"de2uS4jEwSYN7W0eoF_ZiLJQ7rtQaDbA9NkCZr_U4gujctbMw_WZYz7u6q3NMDlTYYCSSR7O3ec1fOP2wArN0g"
}
}
```
## 4. Get Institution Information
Information about available institutions can be found in several ways. This example uses the search method.
Search criteria is specified in the request body; pagination is specified by appending it to the request URL.
Either a `name` or `url` must be sent in the request body for this endpoint to work properly. An empty request body will result in a `400` error.
```shell theme={null}
curl -i -X POST 'https://int-data.moneydesktop.com/institutions/search?records_per_page=2&page=1' \
-H 'MD-SESSION-TOKEN: YYYYY' \
-H 'Content-Type: application/vnd.mx.nexus.v1+json' \
-H 'Accept: application/vnd.mx.nexus.v1+json' \
-d '{
"institution":{
"name":"MX Bank"
}
}'
```
```json theme={null}
{
"institutions": [
{
"code": "mxbank",
"created_at": "2016-09-21T22:03:55+00:00",
"forgot_password_url": "https://www.mx.com/forgot-password",
"forgot_username_url": "https://www.mx.com/forgot-username",
"guid": "INS-1572a04c-912b-59bf-5841-332c7dfafaef",
"has_checking_accounts": true,
"has_credit_card_accounts": true,
"has_investment_accounts": true,
"has_line_of_credit_accounts": true,
"has_loan_accounts": true,
"has_mortgage_accounts": true,
"has_savings_accounts": true,
"is_hidden": false,
"is_test": true,
"medium_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/INS-1572a04c-912b-59bf-5841-332c7dfafaef_100x100.png",
"name": "MX Bank",
"popularity": 72664,
"small_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/INS-1572a04c-912b-59bf-5841-332c7dfafaef_50x50.png",
"supports_account_identification": true,
"supports_account_verification": true,
"supports_oauth": false,
"supports_transaction_history": true,
"trouble_signing_in_url": "https://www.mx.com/trouble-signing-in",
"updated_at": "2022-04-11T17:38:27+00:00",
"url": "https://www.mx.com"
},
•••
],
"pagination_data": {
"current_page": 1,
"records_on_current_page": 3,
"total_pages": 1,
"total_records_found": 3
}
}
```
## 5. Get the Institution's Required Credentials Using the Institution GUID
This endpoint returns information about what type of credentials the institution requires for authentication.
```shell theme={null}
curl -i https://int-data.moneydesktop.com/institutions/INS-1572a04c-912b-59bf-5841-332c7dfafaef/credentials \
-H 'MD-SESSION-TOKEN: CWforZl1Vn2vC_v6H4rnQRT1DoWpDouJAV-_5TBmiQRAtA8rsOG_BoajTiOSsL0A3bd-bmHXlA-eQzc9ywItKg' \
-H 'Content-Type: application/vnd.mx.nexus.v1+json' \
-H 'Accept: application/vnd.mx.nexus.v1+json'
```
```json theme={null}
{
"credentials": [
{
"answer_field_type": null,
"created_at": "2016-09-21T22:08:59+00:00",
"display_name": null,
"display_order": 1,
"editable": true,
"escaped": null,
"field_name": "LOGIN",
"field_type": 3,
"field_type_name": "LOGIN",
"guid": "CRD-9f61fb4c-912c-bd1e-b175-ccc7f0275cc1",
"institution_guid": "INS-1572a04c-912b-59bf-5841-332c7dfafaef",
"label": "Username",
"max_length": null,
"meta_data": null,
"mfa": false,
"optional": false,
"optional_mfa": null,
"size": null,
"updated_at": "2016-09-21T22:08:59+00:00",
"value_identifier": null,
"value_mask": null
},
{
"answer_field_type": null,
"created_at": "2016-09-21T22:08:59+00:00",
"display_name": null,
"display_order": 2,
"editable": true,
"escaped": null,
"field_name": "PASSWORD",
"field_type": 1,
"field_type_name": "PASSWORD",
"guid": "CRD-e3d7ea81-aac7-05e9-fbdd-4b493c6e474d",
"institution_guid": "INS-1572a04c-912b-59bf-5841-332c7dfafaef",
"label": "Password",
"max_length": null,
"meta_data": null,
"mfa": false,
"optional": false,
"optional_mfa": null,
"size": null,
"updated_at": "2016-09-21T22:08:59+00:00",
"value_identifier": null,
"value_mask": null
}
]
}
```
## 6. Create a Member Using Institution GUID and Required Credentials
Creating a `member` automatically starts a standard aggregation which is not necessary for verification. To prevent this unnecessary aggregation, set the `skip_aggregation` parameter to `true` when making your request.
```shell theme={null}
curl -i -X POST https://int-data.moneydesktop.com/members \
-H 'MD-SESSION-TOKEN: YYYYY' \
-H 'Content-Type: application/vnd.mx.nexus.v1+json' \
-H 'Accept: application/vnd.mx.nexus.v1+json' \
-d '{
"member": {
"credentials": [
{
"credential_guid": "CRD-af37bbfa-7fc7-f607-692c-2d2592fb25a3",
"value": "Username123"
},
{
"credential_guid": "CRD-2045d3f6-206a-b0ef-c42d-6ebc8835f898",
"value": "Password123"
}
],
"institution_guid": "INS-a4b1697f-f956-e651-5f8e-e4072166408c",
"metadata": "Additional information",
"skip_aggregation": true
}
}'
```
```json theme={null}
{
"member": {
"aggregated_at": null,
"connection_status": "CREATED",
"connection_status_id": 0,
"connection_status_message": "Connecting to Wells Fargo Bank...",
"external_guid": null,
"guid": "MBR-7aa13bdb-2866-ba38-b326-d9fb32268f9b",
"institution_guid": "INS-33a533a9-9ead-540c-d17d-bdc92c96be17",
"is_being_aggregated": false,
"is_managed_by_user": false,
"is_manual": false,
"is_user_created": false,
"metadata": "Additional information",
"most_recent_job_guid": "JOB-cc7ac3f1-351a-667f-be7c-93a484df6ebf",
"name": "Wells Fargo Bank",
"needs_updated_credentials": false,
"revision": 0,
"successfully_aggregated_at": null,
"user_guid": "USR-d2219ed6-7d5d-2fad-c332-17fb9bafcefa"
}
}
```
## 7. Verify a member
The verify `member` endpoint begins a verification process for an already-existing member. Use this endpoint when normal aggregation does not return account and routing numbers for the `member`.
The verification workflow is similar to that shown above: Start the verification, poll the member, answer MFA if necessary by using the list member MFA challenges endpoint and the update member endpoint, poll the status again, then read the member's account numbers.
```shell theme={null}
curl -i -X POST https://int-data.moneydesktop.com/members/MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa/verify \
-H 'MD-SESSION-TOKEN: :session_token' \
-H 'Content-Type: application/vnd.mx.nexus.v1+json' \
-H 'Accept: application/vnd.mx.nexus.v1+json'
```
```json theme={null}
{
"member": {
"aggregated_at": null,
"connection_status": "CREATED",
"connection_status_id": 0,
"connection_status_message": "Connecting to Wells Fargo Bank...",
"external_guid": null,
"guid": "MBR-c6536f4c-61dc-a047-5c45-ee38b8ba812a",
"institution_guid": "INS-a4b1697f-f956-e651-5f8e-e4072166408c",
"is_being_aggregated": true,
"is_managed_by_user": false,
"is_manual": false,
"is_user_created": false,
"metadata": "Additional information",
"most_recent_job_guid": "JOB-7f321d2b-399e-2fb4-d2b1-eaea87ec29d7",
"name": "Wells Fargo Bank",
"needs_updated_credentials": false,
"revision": 2,
"successfully_aggregated_at": null,
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
}
}
```
## 8. Check the member's verification status
Several fields on the `member` give important information about the state of the verification including `connection_status`, `is_being_aggregated`, `successfully_aggregated_at`. These fields are also used for standard aggregation jobs, hence the reference in their names.
A connection status of `CONNECTED` means that the `member` was successfully authenticated and verification has begun. The `is_being_aggregated` field will tell you whether the verification job has completed; the field will be true while verification is taking place and returns to `false` when verification is complete. The `successfully_aggregated_at` field will tell you the exact time that the verification job has completed.
You may need to repeatedly poll this endpoint until either an end state or an actionable state is reached.
```shell theme={null}
curl -i https://int-data.moneydesktop.com/members/MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa \
-H 'MD-SESSION-TOKEN: CWforZl1Vn2vC_v6H4rnQRT1DoWpDouJAV-_5TBmiQRAtA8rsOG_BoajTiOSsL0A3bd-bmHXlA-eQzc9ywItKg' \
-H 'Content-Type: application/vnd.mx.nexus.v1+json' \
-H 'Accept: application/vnd.mx.nexus.v1+json'
```
```json theme={null}
{
"member": {
"aggregated_at": "2022-07-01T16:52:07+00:00",
"background_aggregation_is_disabled": "false",
"connection_status": "CONNECTED",
"connection_status_id": 6,
"connection_status_message": "Connected to MX Bank.",
"external_guid": null,
"guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
"institution_code": "mxbank",
"institution_guid": "INS-1572a04c-912b-59bf-5841-332c7dfafaef",
"is_being_aggregated": false,
"is_managed_by_user": true,
"is_manual": false,
"is_oauth": false,
"is_user_created": true,
"metadata": "Additional information",
"most_recent_job_guid": "JOB-d6bb804b-6d12-44f1-b0ad-403441c03372",
"name": "MX Bank",
"needs_updated_credentials": false,
"revision": 1412,
"successfully_aggregated_at": "2022-07-01T16:52:11+00:00",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
}
}
```
## 9. Get MFA challenges
```shell theme={null}
curl -i https://int-data.moneydesktop.com/members/MBR-7aa13bdb-2866-ba38-b326-d9fb32268f9b/challenges \
-H 'MD-SESSION-TOKEN: CWforZl1Vn2vC_v6H4rnQRT1DoWpDouJAV-_5TBmiQRAtA8rsOG_BoajTiOSsL0A3bd-bmHXlA-eQzc9ywItKg' \
-H 'Content-Type: application/vnd.mx.nexus.v1+json' \
-H 'Accept: application/vnd.mx.nexus.v1+json'
```
```json theme={null}
{
"challenges": [
{
"type": "TEXT",
"field_name": "What city were you born in?",
"guid": "CRD-22f1b144-dde6-4c80-9d98-ca3c4900d173",
"label": "What city were you born in?"
}
]
}
```
### Update member with answers to challenges
Updating a `member` will kick off an automatic standard aggregation. Set the `skip_aggregation` parameter to true in your request body to prevent this.
```shell theme={null}
curl -i -X PUT https://int-data.moneydesktop.com/members/MBR-7aa13bdb-2866-ba38-b326-d9fb32268f9b \
-H 'MD-SESSION-TOKEN: CWforZl1Vn2vC_v6H4rnQRT1DoWpDouJAV-_5TBmiQRAtA8rsOG_BoajTiOSsL0A3bd-bmHXlA-eQzc9ywItKg' \
-H 'Content-Type: application/vnd.mx.nexus.v1+json' \
-H 'Accept: application/vnd.mx.nexus.v1+json' \
-d '{
"member": {
"credentials": [
{
"credential_guid": "CRD-18cd14ce-2628-5eb6-ae17-b11f89d0b667",
"value": "user-entered-value"
}
],
"metadata": "Additional information",
"skip_aggregation": true
}
}'
```
```json theme={null}
{
"member": {
"aggregated_at": "null",
"connection_status": "UPDATED",
"connection_status_id": 15,
"connection_status_message": "Connecting to Wells Fargo Bank...",
"external_guid": null,
"guid": "MBR-7aa13bdb-2966-ba39-b326-d9fb32269f9b",
"institution_guid": "INS-33a533a9-9ead-540c-d17d-bdc92c96be17",
"is_being_aggregated": true,
"is_managed_by_user": false,
"is_manual": false,
"is_user_created": true,
"metadata": "Additional information",
"most_recent_job_guid": "JOB-cc7ac3f1-351a-667f-be7c-93a494df6ebf",
"name": "Wells Fargo Bank",
"needs_updated_credentials": false,
"revision": 2,
"successfully_aggregated_at": "null",
"user_guid": "USR-d2219ed6-7d5d-2fad-c332-17fb9bafcefa"
}
}
```
### Check the member status again for completion
```shell theme={null}
curl -i https://int-data.moneydesktop.com/members/MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa \
-H 'MD-SESSION-TOKEN: CWforZl1Vn2vC_v6H4rnQRT1DoWpDouJAV-_5TBmiQRAtA8rsOG_BoajTiOSsL0A3bd-bmHXlA-eQzc9ywItKg' \
-H 'Content-Type: application/vnd.mx.nexus.v1+json' \
-H 'Accept: application/vnd.mx.nexus.v1+json'
```
```json theme={null}
{
"member": {
"aggregated_at": "2022-07-01T16:52:07+00:00",
"background_aggregation_is_disabled": "false",
"connection_status": "CONNECTED",
"connection_status_id": 6,
"connection_status_message": "Connected to MX Bank.",
"external_guid": null,
"guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
"institution_code": "mxbank",
"institution_guid": "INS-1572a04c-912b-59bf-5841-332c7dfafaef",
"is_being_aggregated": false,
"is_managed_by_user": true,
"is_manual": false,
"is_oauth": false,
"is_user_created": true,
"metadata": "Additional information",
"most_recent_job_guid": "JOB-d6bb804b-6d12-44f1-b0ad-403441c03372",
"name": "MX Bank",
"needs_updated_credentials": false,
"revision": 1412,
"successfully_aggregated_at": "2022-07-01T16:52:11+00:00",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
}
}
```
## 10. Read the member's account numbers
```shell theme={null}
curl -i https://int-data.moneydesktop.com/members/MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa/account_numbers \
-H 'MD-SESSION-TOKEN: :session_token' \
-H 'Content-Type: application/vnd.mx.nexus.v1+json' \
-H 'Accept: application/vnd.mx.nexus.v1+json'
```
```json theme={null}
{
"account_numbers": [
{
"account_guid": "ACT-82ac32b4-06e6-48a9-8440-17e49bb3d720",
"account_number": "1174165092",
"guid": "ACN-e72d3448-0c58-4a9d-a236-f89bdca7eabb",
"institution_number": null,
"member_guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
"passed_validation": true,
"routing_number": "998007868",
"transit_number": null,
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
}
]
}
```
## Testing Verification
For the most robust end-to-end testing of verification, MX will need to set up test accounts for a partner. Please contact MX to perform this kind of testing.
However, MX provides simple, static-data test endpoints for verification.
In order to use these test endpoints, you must:
1. **Make requests through the MX integration environment; test endpoints will not function in the production environment.**
2. **Use the following Nexus session token: test\_session.**
3. **Use the following Nexus endpoint paths:**
* Get account numbers (no data exists): `GET /members/unverified/account_numbers/`
* Get account numbers (data does exist): `GET /members/test_nexus_member/account_numbers`
* Verify: `POST /members/test_nexus_member/verify`