Quickstarts
Link Money Quickstart
FinSight Quickstart
LinkMoney API
Link Money API
Instant Account Verification (IAV)
Switch Kit
Aggregator Guides
MX
Plaid
Yodlee
FinSight API
Calls to Action
Transaction Enrichment
Resources
Base URL Quick Guide
Constellation Digital Partners
Common Errors
Privacy
FinGoal Privacy & Security
Developer Account
Request FinGoal Developer Account
MX Guide
Since FinGoal handles user registration there is no need to add link token creation or exchange. First, you just need to register with the FinSightAPI, then you're ready to send users to the Link Money Gateway with { auth headers } where they'll link their accounts.
Responses from data dumps can be sent via webhooks or you can call for the data manually via the endpoints listed below.
‣
MX Endpoints
The Link Money API exposes numerous endpoints for developers to interact with our data in a variety of ways. Broadly speaking, these endpoints can be divided into a couple of categories.
Some developers who use Link Money API will be coming from another aggregator, MX. Though MX's functionality is similar to what we're offering, it has a different call structure from our own. In order to minimize friction during the migration process, Link Money API provides endpoints that clone the MX structure and receive and return MX data.
URL Construction
Depending on which endpoint collection, you may only need to access certain endpoint collections and not others. Endpoint construction is essentially:
- The Base URL - for example,
https://linkmoney-dev.fingoal.com - The endpoint collection's name - In this case,
mx. See each endpoint collection for the collection's name. - The version - each endpoint collection has separate versioning rather than a holistic version control for the entire api - for example,
v1. - The endpoint, as specified in each endpoint's documentation.
Some examples include:
https://linkmoney-dev.fingoal.com/v1/mx/transactions/get
https://linkmoney-dev.fingoal.com/v2/mx/transactions
https://linkmoney-dev.fingoal.com/v1/mx/configuration‣
Institutions
Institutions are borrowed from the MX terminology. Per their documentation:
"An institution represents a financial institution (FI) like Chase or Wells Fargo. It’s important to point out that many real-world FI will actually have several different institution objects within the MX Platform API. 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."
While the LinkMoney API does not use the item system in its underlying data scheme, it still leverages the term in MX endpoints to help with the transition from the MX platform.
Developers can use the MX Item endpoints to retrieve items from the LinkMoney API. As with MX, these Items will include only data associated with a login from a single institution.
Read institution.
Endpoint: GET /institutions/:institution_code
Find a single Institution and return its status.
Parameters
| Name | Location | Description |
|---|---|---|
access_token | Request BodyHeaders | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X GET /institutions/:institution_code \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \
-d '{}'Response
{
"institution": {
"code": "50025",
"medium_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/INS-a4c142b7-9d52-e9e9-e464-4d00eaa81f76_100x100.png",
"name": "Franklin-Oil Region CU",
"small_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/INS-a4c142b7-9d52-e9e9-e464-4d00eaa81f76_50x50.png",
"supports_account_identification": false,
"supports_account_statement": false,
"supports_account_verification": false,
"supports_oauth": false,
"supports_transaction_history": false,
"url": "www.franklincreditunion.com"
}
}List institution-required credentials.
Endpoint: GET /institutions/:institution_code/credentials
Parameters
| Name | Location | Description |
|---|---|---|
access_token | Request BodyHeaders | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X GET /institutions/:institution_code/credentials \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \
-d '{}'Response
Listing institution-required credentials returns all credentials for the institutions along with pagination parameters
{
"credentials": [
{
"display_order": 1,
"field_name": "LOGIN",
"field_type": "LOGIN",
"guid": "CRD-9f61fb4c-912c-bd1e-b175-ccc7f0275cc1",
"label": "Username"
},
{
"display_order": 2,
"field_name": "PASSWORD",
"field_type": "PASSWORD",
"guid": "CRD-e3d7ea81-aac7-05e9-fbdd-4b493c6e474d",
"label": "Password"
}
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 2,
"total_pages": 1
}
}List institutions
Endpoint: GET /institutions
This endpoint returns a list of institutions based on the specified search term or parameter.
Parameters
| Name | Location | Data Type | Description |
|---|---|---|---|
access_token | Request BodyHeaders | String | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
name | Request BodyQuery Parameters | String | Only institutions whose name contains the appended string will be returned. |
supports_account_identification | Request BodyQuery Parameters | Boolean | Only institutions which support identity will be returned. |
supports_account_statement | Request BodyQuery Parameters | Boolean | Only institutions which offer access to account statements will be returned. |
supports_account_verification | Request BodyQuery Parameters | Boolean | Only institutions which support account verification will be returned. |
supports_transaction_history | Request BodyQuery Parameters | Boolean | Only institutions which offer an extended transaction history will be returned. |
Example Request
curl -X GET /institutions \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \
-d '{}'Response
Response contains a list of institutions based on the specified search term or parameter.
{
"institutions": [
{
"code": "5426",
"medium_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/default_100x100.png",
"name": "Test",
"small_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/default_50x50.png",
"supports_account_identification": false,
"supports_account_statement": false,
"supports_account_verification": false,
"supports_oauth": false,
"supports_transaction_history": false,
"url": "testbankformoneydesktop.com"
},
{
"code": "50025",
"medium_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/INS-a4c142b7-9d52-e9e9-e464-4d00eaa81f76_100x100.png",
"name": "Franklin-Oil Region CU",
"small_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/INS-a4c142b7-9d52-e9e9-e464-4d00eaa81f76_50x50.png",
"supports_account_identification": false,
"supports_account_statement": false,
"supports_account_verification": false,
"supports_oauth": false,
"supports_transaction_history": false,
"url": "www.franklincreditunion.com"
},
...
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 130,
"total_pages": 6
}
}List favorites
Endpoint: GET /institutions/favorites
This endpoint returns a paginated list containing institutions that have been set as the partner’s favorites, sorted by popularity.
You will need to contact MX to set a list of favorites
Parameters
| Name | Location | Description |
|---|---|---|
access_token | Request BodyHeaders | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X GET /institutions/favorites \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \
-d '{}'Response
Response contains a paginated list containing institutions that have been set as the partner’s favorites, sorted by popularity
{
"institutions": [
{
"code": "52726",
"medium_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/default_100x100.png",
"name": "Washington Federal",
"small_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/default_50x50.png",
"supports_account_identification": null,
"supports_account_statement": null,
"supports_account_verification": true,
"supports_oauth": false,
"supports_transaction_history": null,
"url": "www.washingtonfederal.com"
},
{
"code": "capital_one",
"medium_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/default_100x100.png",
"name": "Capital One",
"small_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/default_50x50.png",
"supports_account_identification": null,
"supports_account_statement": null,
"supports_account_verification": false,
"supports_oauth": false,
"supports_transaction_history": null,
"url": "http://www.capitalone.com"
},
...
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 130,
"total_pages": 6
}
}| Endpoint | Request Method | Description |
|---|---|---|
/institutions/:institution_code | GET | Find a single Institution and return its status. |
/institutions/:institution_code/credentials | GET | Listing institution-required credentials returns all credentials for the institutions along with pagination parameters. |
/institutions | GET | Returns a list of institutions based on the specified search term or parameter. |
/institutions/favorites | GET | Returns a paginated list containing institutions that have been set as the partner’s favorites, sorted by popularity. |
/merchants | GET | Returns a paginated list of all the merchants in the MX system. |
/merchants/:merchant_guid | GET | Returns the attributes of the specified merchant. |
/users/:user_guid/accounts/:account_guid | GET | Returns the specified account resource. |
/users/:user_guid/accounts/:account_guid/account_numbers | GET | Returns a list of account numbers associated with the specified account. |
/users/:user_guid/accounts/:account_guid/transactions | GET | Returns a list of the last 90 days of transactions associated with the specified account. |
/users/:user_guid/accounts | GET | Returns a list of all the accounts associated with the specified user. |
/users/:user_guid/categories/:category_guid | DELETE | This endpoint is used to delete a specific custom category according to its unique GUID. |
/users/:user_guid/categories/:category_guid | GET | Returns a list of account numbers associated with the specified account. |
/users/:user_guid/categories/:category_guid | PUT | This endpoint is used to update the attributes of a custom category according to its unique GUID. |
/users/:user_guid/categories | GET | This endpoint is used to list all categories associated with a user, including both default and custom categories. |
/users/:user_guid/categories | POST | This endpoint is used to list all categories associated with a user, including both default and custom categories. |
/users/:user_guid/categories/default | GET | This endpoint is used to retrieve a list of all the default categories and subcategories offered within the MX Platform API. |
/users/:user_guid/holdings | GET | Returns all holdings associated with the specified user across all accounts and members. |
/users/:user_guid/holdings/:holding_guid | GET | Returns all holdings associated with the specified account. |
/users/:user_guid/members/:member_guid/statements | GET | This endpoint is used to get an array of available statements. |
/users/:user_guid/members/:member_guid/statements/:statement_guid | GET | This endpoint is used to read a JSON representation of the statement. |
/users/:user_guid/members/:member_guid/statements/{{statement_guid}}.pdf | GET | Use this endpoint to download a specified statement PDF. |
/users/:user_guid/members/:member_guid | DELETE | This endpoint will permanently delete the specified member. |
/users/:user_guid/members/:member_guid | GET | This endpoint returns information about the specified member. |
/users/:user_guid/members/:member_guid | PUT | This endpoint is used to update certain attributes of the specified member. |
/users/:user_guid/members/:member_guid/account_numbers | GET | This endpoint returns a list of account numbers associated with the specified member. |
/users/:user_guid/members/:member_guid/account_owners | GET | Use this endpoint to check whether identity data is available for a specific member. |
/users/:user_guid/members/:member_guid/accounts/:account_guid | PUT | This endpoint allows you to update certain attributes of an account resource. |
/users/:user_guid/members/:member_guid/aggregate | POST | This endpoint initiates an aggregation event for the member. |
/users/:user_guid/members/:member_guid/challenges | GET | Use this endpoint for information on what multi-factor authentication challenges need to be answered in order to aggregate a member. |
/users/:user_guid/members/:member_guid/check_balance | POST | This endpoint operates much like the aggregate member endpoint except that it gathers only account balance information; it does not gather any transaction data. |
/users/:user_guid/members/:member_guid/credentials | GET | This endpoint returns an array which contains information on every non-MFA credential associated with a specific member. |
/users/:user_guid/members/:member_guid/extend_history | POST | Some institutions allow developers to access an extended transaction history with up to 24 months of data associated with a particular member. |
/users/:user_guid/members/:member_guid/fetch_statements | POST | Use this endpoint to fetch the statements associated with a particular member. |
/users/:user_guid/members/:member_guid/holdings | GET | Returns all holdings associated with the specified member across all accounts. |
/users/:user_guid/members/:member_guid/status | GET | Returns information about the member’s connection to a financial institution, including crucial information about aggregation. |
/users/:user_guid/members/:member_guid/transactions | GET | Returns a list of transactions associated with the specified member, across all accounts associated with that member. |
/users/:user_guid/members | GET | Returns a list of all the members that belong to the specified user. |
/users/:user_guid/members | POST | This endpoint allows you to create a new member. |
/users/:user_guid/transaction_rules/:transaction_rule_guid | DELETE | This endpoint permanently deletes a transaction rule based on its unique GUID. |
/users/:user_guid/transaction_rules/:transaction_rule_guid | GET | This endpoint is used to read the attributes of an existing transaction rule based on the rule’s unique GUID. |
/users/:user_guid/transaction_rules/:transaction_rule_guid | PUT | This endpoint is used to read the attributes of an existing transaction rule based on the rule’s unique GUID. |
/users/:user_guid/transaction_rules | GET | This endpoint is used to read the attributes of all existing transaction rules belonging to the user. |
/users/:user_guid/transaction_rules | POST | This endpoint is used to create a new transaction rule. |
/users/:user_guid/transactions/:transaction_guid | GET | This endpoint will return the attributes of the specified transaction. |
/users/:user_guid/transactions/:transaction_guid | PUT | Use this endpoint to update the description of a specific transaction according to its unique GUID. |
/users/:user_guid/transactions | GET | Returns a list of transactions associated with the specified user, across all members and accounts associated with that user. |
/users/:user_guid | DELETE | This endpoint is used to delete the specified user. |
/users/:user_guid | GET | This endpoint will return the details of the specified user. |
/users/:user_guid | PUT | This endpoint is used to update the attributes of the specified user. |
/users | GET | Returns a list of all your users. |
/users | POST | Use this endpoint to create a new user. |
‣
Merchants
A merchant contains information about the merchant, business, company, or seller associated with a specific transaction. This information includes a name, logo, and website.
Note: Not every transaction will have a merchant_guid assigned to it; this field may be set to null.
List merchants
Endpoint: GET /merchants
This endpoint returns a paginated list of all the merchants in the MX system.
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
access_token | Request BodyHeaders | String | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X GET /merchants \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \
-d '{}'Example Response
For more information about the response, see the model documentation entry on Plaid institutions.
{
"merchants": [
{
"guid": "MCH-ad6d3405-ec03-721d-b0ca-eeceeebcb8b5",
"logo_url": "https://content.mx.com/logos/merchants/MCH-ad6d3405-ec03-721d-b0ca-eeceeebcb8b5.png",
"name": "1-800 Contacts",
"website_url": "https://www.1800contacts.com",
"created_at": "2018-09-17T19:13:53Z",
"logo_updated_at": "2021-08-09T16:19:23Z",
"updated_at": "2021-08-09T16:19:23Z"
},
{
"guid": "MCH-dfef19bb-1af4-bbaa-db41-434b4b1c8f04",
"logo_url": "https://content.mx.com/logos/merchants/MCH-dfef19bb-1af4-bbaa-db41-434b4b1c8f04.png",
"name": "1-800-Flowers.com",
"website_url": "https://www.1800flowers.com",
"created_at": "2018-07-16T16:31:35Z",
"logo_updated_at": "2021-02-19T15:58:10Z",
"updated_at": "2021-02-19T15:58:10Z"
},
{
"guid": "MCH-9559c6fb-c05f-ee9e-bb33-ce23078df1a0",
"logo_url": "https://content.mx.com/logos/merchants/MCH-9559c6fb-c05f-ee9e-bb33-ce23078df1a0.png",
"name": "24 Hour Fitness",
"website_url": "https://www.24hourfitness.com",
"created_at": "2018-04-23T20:23:59Z",
"logo_updated_at": "2021-02-19T16:15:59Z",
"updated_at": "2021-02-19T16:15:59Z"
},
•••
],
"pagination": {
"current_page": 1,
"per_page": 10,
"total_entries": 11443,
"total_pages": 1145
}
}Read merchant
Endpoint: GET /merchants/:merchant_guid
This endpoint returns the attributes of the specified merchant.
Parameters
| Name | Location | Description |
|---|---|---|
access_token | Request BodyHeader | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X GET /merchants/:merchant_guid \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \
-d '{}'Example Response
{
"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"
}
}‣
Users
A user represents an end-user accessing the MX Platform API via your application, be it a mobile app, web app, desktop app, etc.
‣
Delete User
Endpoint: DELETE /users/:user_guid
This endpoint is used to delete the specified user. The response will have a status of 204 No Content without an object.
Parameters
| Name | Location | Data Type | Is Required ? | Description |
|---|---|---|---|---|
access_token | Request BodyHeaders | String | Yes | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X DELETE /users/:user_guid \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \‣
Read User
Endpoint: GET /users/:user_guid
This endpoint will return the details of the specified user.
Parameters
| Name | Location | Description |
|---|---|---|
access_token | Request BodyHeaders | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X GET /users/:user_guid \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}"Response
{
"user": {
"guid": "USR-29eab3cf-6a87-fe97-6279-563b63e75a53",
"id": "098345869540",
"email": "completely.fabricated.user@example.com",
"is_disabled": false,
"metadata": null
}
}‣
Update User
Endpoint: PUT /users/:user_guid
This endpoint is used to update the attributes of the specified user.
Parameters
| Name | Location | Data Type | Is Required ? | Description |
|---|---|---|---|---|
access_token | Request BodyHeaders | String | Yes | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
user | Request Body | Object | Yes | |
user.email | Request Body | String | No | |
user.metadata | Request Body | String | No | |
user.is_disabled | Request Body | String | No | |
user.id | Request Body | String | No |
Example Request
curl -X PUT /users/:user_guid \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-type: application/json' \
-H "Authorization: Bearer {access_token}" \
-d '{
"user": {
"id": "ironman2"
}
}'Response
{
"user": {
"email": "completely.fabricated.user@example.com",
"guid": "USR-29eab3cf-6a87-fe97-6279-563b63e75a53",
"id": "ironman2",
"is_disabled": false,
"metadata": null
}
}‣
List Users
Endpoint: GET /users
This endpoint will return a list of all your users.
Parameters
| Name | Location | Description |
|---|---|---|
access_token | Request BodyHeaders | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X GET /users/:user_guid/transaction_rules \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \Response
{
"users": [
{
"email": null,
"guid": "USR-1b7e650e-095e-0667-d673-dea669e59a41",
"id": "1364598269",
"is_disabled": false,
"metadata": null
},
{
"email": "completely.fabricated.user@example.com",
"guid": "USR-29eab3cf-6a87-fe97-6279-563b63e75a53",
"id": "098345869540",
"is_disabled": false,
"metadata": null
},
{
"email": null,
"guid": "USR-aeed962a-e6b5-cb30-9640-d3f0f0195a0c",
"id": "1368496234",
"is_disabled": false,
"metadata": null
},
{
"email": null,
"guid": "USR-8d819d0e-a720-f437-0be3-03a8783086bd",
"id": "1368544284",
"is_disabled": false,
"metadata": null
}
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 4,
"total_pages": 1
}
}‣
Create a User
Endpoint: POST /users
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
| Name | Location | Data Type | Is Required ? | Description |
|---|---|---|---|---|
access_token | Request BodyHeaders | String | Yes | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
user | Request Body | Object | Yes | |
user.email | Request Body | String | No | |
user.id | Request Body | String | No | None of these parameters are required, but the user object cannot be empty. MX recommends that partners always set the id parameter when creating a user. |
user.metadata | Request Body | String | No | |
user.is_disabled | Request Body | String | No |
Example Request
curl -X POST /users \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \
-d '{
"user": {
"id": "partner-2345",
"is_disabled": false,
"email": "totally.fake.email@notreal.com",
"metadata": "Yada yada yada"
}
}'Response
{
"user": {
"email": "totally.fake.email@notreal.com",
"guid": "USR-3a17a2b1-acbc-48d1-8098-1b8ae8939ab2",
"id": "partner-2345",
"is_disabled": false,
"metadata": "Yada yada yada"
}
}‣
Users / Accounts
A user represents an end-user accessing the MX Platform API via your application, be it a mobile app, web app, desktop app, etc.
Read Account
Endpoint: GET /users/:user_guid/accounts/:account_guid
This endpoint returns the specified account resource.
Parameters
| Name | Location | Description |
|---|---|---|
access_token | Request BodyHeaders | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X GET /users/:user_guid/accounts/:account_guid \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" Response
{
"account": {
"account_number": "5366",
"apr": null,
"apy": null,
"available_balance": null,
"available_credit": 327.01,
"balance": 1872.99,
"cash_balance": null,
"cash_surrender_value": null,
"created_at": "2020-08-04T21:27:47Z",
"credit_limit": null,
"currency_code": "USD",
"day_payment_is_due": null,
"death_benefit": null,
"guid": "ACT-82a93692-f756-534f-9b2e-ad10534f9b2e",
"holdings_value": null,
"id": "104055120",
"imported_at": "2021-08-01T12:00:47Z",
"institution_code": "chase",
"insured_name": null,
"interest_rate": null,
"is_closed": false,
"is_hidden": false,
"last_payment": null,
"last_payment_at": null,
"loan_amount": null,
"matures_on": null,
"member_guid": "MBR-0b2121f5-bf4f-4244-a697-cac64244a697",
"member_id": "1505009123",
"member_is_managed_by_user": true,
"metadata": null,
"minimum_balance": null,
"minimum_payment": null,
"name": "CREDIT CARD",
"nickname": null,
"original_balance": null,
"pay_out_amount": null,
"payment_due_at": null,
"payoff_balance": null,
"premium_amount": null,
"routing_number": null,
"started_on": null,
"subtype": "NONE",
"total_account_value": null,
"type": "CREDIT_CARD",
"updated_at": "2021-01-15T17:09:09Z",
"user_guid": "USR-11a448aa-5e7b-70db-45d6-d6927092043e",
"user_id": "U-107895"
}
}List account numbers by account
Endpoint: GET /users/:user_guid/accounts/:account_guid/account_numbers
This endpoint returns a list of account numbers associated with the specified account.
Parameters
| Name | Location | Description |
|---|---|---|
access_token | Request BodyHeaders | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X GET /users/:user_guid/accounts/:account_guid/account_numbers \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \Response
{
"account_numbers": [
{
"account_guid": "ACT-82a93692-f756-534f-9b2e-ad10a0f38462",
"account_number": "10001",
"guid": "ACN-123",
"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
}
}List transactions by account
Endpoint: GET /users/:user_guid/accounts/:account_guid/transactions
This endpoint returns a list of the last 90 days of transactions associated with the specified account.
Parameters
| Name | Location | Data Type | Is Required | Description |
|---|---|---|---|---|
access_token | Request BodyHeaders | String | Yes | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
from_date | Request BodyQuery Parameters | String | 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 | Request BodyQuery Parameters | String | 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. |
Example Request
curl -X GET /users/:user_guid/accounts/:account_guid/transactions \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \Response
{
"transactions": [
{
"account_guid": "ACT-09c0ee66-51a8-4edf-b977-99534a471134",
"account_id": "account-1040434698",
"amount": 7.94,
"category": "Paycheck",
"check_number_string": null,
"created_at": "2020-03-02T19:11:11Z",
"currency_code": "USD",
"date": "2020-03-02",
"description": "Paycheck",
"guid": "TRN-181ce5d9-d33e-45b9-a9cd-8f8ef9d82d5d",
"id": "transaction-1040434568",
"is_bill_pay": false,
"is_direct_deposit": false,
"is_expense": false,
"is_fee": false,
"is_income": true,
"is_international": null,
"is_overdraft_fee": false,
"is_payroll_advance": false,
"is_recurring": false,
"is_subscription": false,
"latitude": null,
"localized_description": null,
"localized_memo": null,
"longitude": null,
"member_guid": "MBR-3eb08fde-01d5-454c-ae6a-95606ccd1225",
"member_is_managed_by_user": true,
"memo": null,
"merchant_category_code": null,
"merchant_guid": null,
"merchant_location_guid": null,
"original_description": "Payroll",
"posted_at": "2020-03-03T12:00:00Z",
"status": "POSTED",
"top_level_category": "Income",
"transacted_at": "2020-03-02T12:00:00Z",
"type": "CREDIT",
"updated_at": "2020-03-02T19:11:14Z",
"user_guid": "USR-a2e65785-975d-dcbd-fd22-7bbba2581fb0",
"user_id": "user-1040435626"
},
{
"account_guid": "ACT-09c0ee66-51a8-4edf-b977-99534a471134",
"account_id": "account-1040434698",
"amount": 64.77,
"category": "Mobile Phone",
"check_number_string": null,
"created_at": "2020-03-02T19:11:11Z",
"currency_code": "USD",
"date": "2020-03-02",
"description": "Verizon Wirelss",
"guid": "TRN-3f206b3c-0c6a-4c37-bbe9-c8d60dd953c7",
"id": "transaction-123057654",
"is_bill_pay": false,
"is_direct_deposit": false,
"is_expense": true,
"is_fee": false,
"is_income": false,
"is_international": null,
"is_overdraft_fee": false,
"is_payroll_advance": false,
"is_recurring": false,
"is_subscription": false,
"latitude": null,
"localized_description": null,
"localized_memo": null,
"longitude": null,
"member_guid": "MBR-3eb08fde-01d5-454c-ae6a-95606ccd1225",
"member_is_managed_by_user": true,
"memo": null,
"merchant_category_code": null,
"merchant_guid": "MCH-a5252ab5-56bc-a0ea-7d89-e598a4d5ec0e",
"merchant_location_guid": null,
"original_description": "Verizon Wireless",
"posted_at": "2020-03-03T12:00:00Z",
"status": "POSTED",
"top_level_category": "Bills & Utilities",
"transacted_at": "2020-03-02T12:00:00Z",
"type": "DEBIT",
"updated_at": "2020-03-02T19:11:14Z",
"user_guid": "USR-a2e65785-975d-dcbd-fd22-7bbba2581fb0",
"user_id": "user-1040435626"
},
...
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 20,
"total_pages": 1
}
}List accounts
Endpoint: GET /users/:user_guid/accounts
This endpoint returns a list of all the accounts associated with the specified user
Parameters
| Name | Location | Data Type | Is Required | Description |
|---|---|---|---|---|
access_token | Request BodyHeaders | String | Yes | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X GET /users/:user_guid/accounts \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \Response
{
"accounts": [
{
"account_number": "5366",
"apr": null,
"apy": null,
"available_balance": null,
"available_credit": 327.01,
"balance": 1872.99,
"cash_balance": null,
"cash_surrender_value": null,
"created_at": "2020-08-04T21:27:47Z",
"credit_limit": null,
"currency_code": "USD",
"day_payment_is_due": null,
"death_benefit": null,
"guid": "ACT-82a93692-f756-534f-9b2e-ad10a0f3f756",
"holdings_value": null,
"id": "1041424581",
"imported_at": "2021-08-01T12:00:47Z",
"institution_code": "chase",
"insured_name": null,
"interest_rate": null,
"is_closed": false,
"is_hidden": false,
"last_payment": null,
"last_payment_at": null,
"loan_amount": null,
"matures_on": null,
"member_guid": "MBR-0b2121f5-bf4f-4244-a697-ca5925a325a1",
"member_id": "M-1260571",
"member_is_managed_by_user": true,
"metadata": null,
"minimum_balance": null,
"minimum_payment": null,
"name": "CREDIT CARD",
"nickname": null,
"original_balance": null,
"pay_out_amount": null,
"payment_due_at": null,
"payoff_balance": null,
"premium_amount": null,
"routing_number": null,
"started_on": null,
"subtype": "NONE",
"total_account_value": null,
"type": "CREDIT_CARD",
"updated_at": "2021-01-15T17:09:09Z",
"user_guid": "USR-11a448aa-5e7b-70db-45d6-d6927092043e",
"user_id": "U-107895"
},
•••
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 8,
"total_pages": 1
}
}‣
Users / Category(s)
Categories are automatically assigned to a given transaction by the MX system. There are more than a hundred default MX categories and subcategories. The endpoints that follow allow you to list and read those default categories with their attributes.
‣
Delete Category
Endpoint: DELETE /users/:user_guid/categories/:category_guid
This endpoint is used to delete a specific custom category according to its unique GUID. The API will respond with an empty object and a status of 204 No Content.
Parameters
| Name | Location | Description |
|---|---|---|
access_token | Request BodyHeaders | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X DELETE /users/:user_guid/categories/:category_guid \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \‣
Read Category
Endpoint: GET /users/:user_guid/categories/:category_guid
This endpoint returns a list of account numbers associated with the specified account.
Parameters
| Name | Location | Description |
|---|---|---|
access_token | Request BodyHeaders | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X GET /users/:user_guid/categories/:category_guid \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \Response
{
"category": {
"created_at": null,
"guid": "CAT-7829f71c-2e8c-afa5-2f55-fa3634b89874",
"is_default": true,
"is_income": false,
"metadata": null,
"name": "Auto & Transport",
"parent_guid": null,
"updated_at": null
}
}‣
Update a Custom Category
Endpoint: PUT /users/:user_guid/categories/:category_guid
This endpoint is used to update the attributes of a custom category according to its unique GUID.
Parameters
| Name | Location | Data Type | Is Required | Description |
|---|---|---|---|---|
access_token | Request BodyHeaders | String | Yes | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
category | Request Body | Object | Yes | While no single parameter is required, the category object cannot be empty. |
category.name | Request Body | String | No | |
category.metadata | Request Body | String | No |
Example Request
curl -i -X PUT '/users/:user_guid/categories/:category_guid' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \
-d '{
"category": {
"name": "Web shopping"
}
}'Response
{
"category": {
"created_at": "2020-08-26T20:31:41Z",
"guid": "CAT-3684d909-4b77-481c-99bf-8d87c6aa2c62",
"is_default": false,
"is_income": null,
"metadata": null,
"name": "Web shopping",
"parent_guid": "CAT-aad51b46-d6f7-3da5-fd6e-492328b3023f",
"updated_at": "2020-08-26T22:29:03Z"
}
}‣
List all Categories (including custom)
Endpoint: GET /users/:user_guid/categories
This endpoint is used to list all categories associated with a user, including both default and custom categories.
Parameters
| Name | Location | Data Type | Is Required | Description |
|---|---|---|---|---|
access_token | Request BodyHeaders | String | Yes | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X GET /users/:user_guid/categories \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \Response
{
"categories": [
{
"created_at": "2020-08-26T19:56:42Z",
"guid": "CAT-742dcb38-57e9-4c84-a240-48bc6580ea2e",
"is_default": false,
"is_income": null,
"metadata": null,
"name": "Some other insurance",
"parent_guid": "CAT-7829f71c-2e8c-afa5-2f55-fa3634b89874",
"updated_at": "2020-08-26T19:56:42Z"
},
{
"created_at": "2020-08-26T20:31:41Z",
"guid": "CAT-3684d909-4b77-481c-99bf-8d87c6aa2c62",
"is_default": false,
"is_income": null,
"metadata": null,
"name": "New scooter insurance",
"parent_guid": "CAT-7829f71c-2e8c-afa5-2f55-fa3634b89874",
"updated_at": "2020-08-26T22:29:03Z"
},
{
"created_at": null,
"guid": "CAT-7829f71c-2e8c-afa5-2f55-fa3634b89874",
"is_default": true,
"is_income": false,
"metadata": null,
"name": "Auto & Transport",
"parent_guid": null,
"updated_at": null
},
{
"created_at": null,
"guid": "CAT-de7c2dc7-90e6-85a2-6509-5ec10942e887",
"is_default": true,
"is_income": false,
"metadata": null,
"name": "Auto Insurance",
"parent_guid": "CAT-7829f71c-2e8c-afa5-2f55-fa3634b89874",
"updated_at": null
},
...
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 27,
"total_pages": 2
}
}‣
Create a custom Category
Endpoint: POST /users/:user_guid/categories
This endpoint is used to create a new custom category for a specific user.
Parameters
| Name | Location | Data Type | Is Required ? | Description |
|---|---|---|---|---|
access_token | Request BodyHeaders | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. | ||
category | Request Body | Object | Yes | |
category.metadata | Request Body | String | No | |
category.name | Request Body | String | Yes | |
category.parent_guid | Request Body | String | Yes |
Example Request
curl -i -X POST '/users/:user_guid/categories' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \
-d '{
"category": {
"metadata": "Super cool extra info.",
"name": "Online Shopping",
"parent_guid": "CAT-aad51b46-d6f7-3da5-fd6e-492328b3023f"
}
}'Response
{
"category": {
"created_at": "2020-08-26T20:31:41Z",
"guid": "CAT-3684d909-4b77-481c-99bf-8d87c6aa2c62",
"is_default": false,
"is_income": null,
"metadata": "Super cool extra info.",
"name": "Online Shopping",
"parent_guid": "CAT-aad51b46-d6f7-3da5-fd6e-492328b3023f",
"updated_at": "2020-08-26T20:31:41Z"
}
}‣
List default categories (excluding custom categories)
Endpoint: GET /users/:user_guid/categories/default
This endpoint is used to retrieve a list of all the default categories and subcategories offered within the MX Platform API. In other words, each item in the returned list will have its is_default field set to true. There are currently 119 default categories and subcategories.
Parameters
| Name | Location | Data Type | Is Required | Description |
|---|---|---|---|---|
access_token | Request BodyHeaders | String | Yes | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -i '/users/:user_guid/categories/default' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H "Authorization: Bearer {access_token}" \Response
{
"categories": [
{
"created_at": null,
"guid": "CAT-7829f71c-2e8c-afa5-2f55-fa3634b89874",
"is_default": true,
"is_income": false,
"metadata": null,
"name": "Auto & Transport",
"parent_guid": null,
"updated_at": null
},
{
"created_at": null,
"guid": "CAT-de7c2dc7-90e6-85a2-6509-5ec10942e887",
"is_default": true,
"is_income": false,
"metadata": null,
"name": "Auto Insurance",
"parent_guid": "CAT-7829f71c-2e8c-afa5-2f55-fa3634b89874",
"updated_at": null
},
{
"created_at": null,
"guid": "CAT-cb93691a-684d-b326-4c32-f8abaecfde90",
"is_default": true,
"is_income": false,
"metadata": null,
"name": "Auto Payment",
"parent_guid": "CAT-7829f71c-2e8c-afa5-2f55-fa3634b89874",
"updated_at": null
}
...
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 8,
"total_pages": 1
}
}‣
Users / Holdings
Holdings represent a stock, bond, or other type of investment.
List Holdings by User
Endpoint: GET /users/:user_guid/holdings
This endpoint returns all holdings associated with the specified user across all accounts and members.
Parameters
| Name | Location | Data Type | Is Required ? | Description |
|---|---|---|---|---|
access_token | Request BodyHeaders | String | Yes | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
from_date | Query Parameters | String | 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 | Query Parameters | String | 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. |
Example Request
curl -X GET /users/:user_guid/holdings \
-H 'Content-Type: application/json' \
-d '{
"access_token": String
}'Response
{
"holdings": [
{
"account_guid": "ACT-f3a6ddfb-3768-4713-87a0-4ad04f87c396",
"cost_basis": null,
"created_at": "2019-08-02T17:43:22Z",
"currency_code": "USD",
"cusip": "70450Y103",
"daily_change": null,
"description": "PayPal Holdings Inc.",
"guid": "HOL-bd3bc50f-5a70-4226-abef-ae9bb4c1cb1a",
"holding_type": 9,
"id": "holding-8417f306-7113-485f-b209-3864ae82fdd7",
"market_value": 57,
"member_guid": null,
"metadata": null,
"purchase_price": 26,
"shares": 37,
"symbol": "PYPL",
"updated_at": "2020-03-02T19:11:02Z",
"user_guid": "USR-a2e65785-975d-dcbd-fd22-7bbba2581fb0"
},
{
"account_guid": "ACT-f3a6ddfb-3768-4713-87a0-4ad04f87c396",
"cost_basis": null,
"created_at": "2019-08-02T17:43:22Z",
"currency_code": "USD",
"cusip": "99UBAYWG0",
"daily_change": null,
"description": "American Airlines Group Inc.",
"guid": "HOL-813a8b86-0dfd-4e8b-8852-24e9a5a0c688",
"holding_type": 10,
"id": "holding-a3fccf60-9a89-4a90-aaaf-0462a4e40bef",
"market_value": 4,
"member_guid": null,
"metadata": null,
"purchase_price": 60,
"shares": 31,
"symbol": "AAL",
"updated_at": "2020-03-02T19:11:02Z",
"user_guid": "USR-a2e65785-975d-dcbd-fd22-7bbba2581fb0"
},
...
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 10,
"total_pages": 1
}
}Read Holding
Endpoint: GET /users/:user_guid/holdings/:holding_guid
This endpoint returns all holdings associated with the specified account.
Parameters
| Name | Location | Description |
|---|---|---|
access_token | Request BodyHeaders | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X GET /users/:user_guid/holdings/:holding_guid \
-H 'Content-Type: application/json' \
-d '{
"access_token": String
}'Response
{
"holding": {
"account_guid": "ACT-34088d82-dbca-4d99-ae7e-e3176df9c306",
"cost_basis": null,
"created_at": "2019-08-08T16:15:30Z",
"currency_code": "USD",
"cusip": "278642103",
"daily_change": null,
"description": "eBay Inc.",
"guid": "HOL-57ffa88f-f630-4232-991e-4f82a783f24e",
"holding_type": 5,
"id": "holding-f0093b53-3af9-4784-b129-b4ff185614fa",
"market_value": 5,
"member_guid": null,
"metadata": null,
"purchase_price": 24,
"shares": 12,
"symbol": "EBAY",
"updated_at": "2019-08-08T16:15:30Z",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
}
}‣
Users / Members / Statements
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.
List Account Statements available for a Member
Endpoint: GET /users/:user_guid/members/:member_guid/statements
This endpoint is used to get an array of available statements.
Parameters
| Name | Location | Data Type | Is Required ? | Description |
|---|---|---|---|---|
access_token | Request BodyHeaders | String | Yes | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X GET /users/:user_guid/members/:member_guid/statements \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \Response
{
"statements": [
{
"account_guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
"content_hash": "ca53785b812d00ef821c3d94bfd6e5bbc0020504410589b7ea8552169f021981",
"created_at": "2016-10-13T18:08:00Z",
"guid": "STA-737a344b-caae-0f6e-1384-01f52e75dcb1",
"member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
"updated_at": "2016-10-13T18:09:00Z",
"uri": "",
"user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
}
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 1,
"total_pages": 1
}
}Read an Account Statement
Endpoint: GET /users/:user_guid/members/:member_guid/statements/:statement_guid
This endpoint is used to read a JSON representation of the statement.
Parameters
| Name | Location | Description |
|---|---|---|
access_token | Request BodyHeaders | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X GET /users/:user_guid/members/:member_guid/statements/:statement_guid \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \Response
{
"statement": {
"account_guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
"content_hash": "ca53785b812d00ef821c3d94bfd6e5bbc0020504410589b7ea8552169f021981",
"created_at": "2016-10-13T18:08:00Z",
"guid": "STA-737a344b-caae-0f6e-1384-01f52e75dcb1",
"member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
"updated_at": "2016-10-13T18:09:00Z",
"uri": "",
"user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
}
}Download an Account Statement PDF
Endpoint: GET /users/:user_guid/members/:member_guid/statements/{{statement_guid}}.pdf
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://int-api.mx.com or https://api.mx.com) and appended with .pdf.
Parameters
| Name | Location | Description |
|---|---|---|
access_token | Request BodyHeaders | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X GET /users/:user_guid/members/:member_guid/statements/{{statement_guid}}.pdf \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}"‣
Users / Members
A member represents the relationship between a user and an institution. A user may have multiple members, one each for their bank, their mortgage broker, their credit card provider, etc. Aggregation, verification, and many other processes are centered around a member, meaning this is probably the most important type of object you’ll be working with.
Delete Member
Endpoint: DELETE /users/:user_guid/members/:member_guid
Making a request to this endpoint will permanently delete the specified member.
A successful response will have the status 204 No Content.
Note: You should not use the delete member endpoint to resolve aggregation errors.
Parameters
| Name | Location | Data Type | Is Required ? | Description |
|---|---|---|---|---|
access_token | Request BodyHeaders | String | Yes | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X DELETE /users/:user_guid/members/:member_guid \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \Read Member
Endpoint: GET /users/:user_guid/members/:member_guid
This endpoint returns information about the specified member.
Parameters
| Name | Location | Description |
|---|---|---|
access_token | Request BodyHeaders | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X GET /users/:user_guid/members/:member_guid \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \Response
{
"member": {
"aggregated_at": "2019-12-03T18:10:22Z",
"connection_status": "CONNECTED",
"guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
"id": null,
"institution_code": "mxbank",
"is_being_aggregated": false,
"is_managed_by_user": true,
"is_oauth": false,
"metadata": null,
"name": "MX Bank",
"successfully_aggregated_at": "2019-08-08T16:17:51Z",
"user_guid": "USR-151a102b-90b3-1bc3-48d1-c24cad5a2b13",
"user_id": "10405939560"
}
}Update Member
Endpoint: PUT /users/:user_guid/members/:member_guid
This endpoint is used to update certain attributes of the specified member.
Parameters
| Name | Location | Data Type | Is Required ? | Description |
|---|---|---|---|---|
access_token | Request BodyHeaders | String | Yes | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
background_aggregation_is_disabled | Request Body | Boolean | No | This indicates whether background aggregation should be disabled for the member. |
credentials | Request Body | Array | No | The credentials that you wish to update for this member. |
id | Request Body | String | No | The unique partner-definite identifier for the member. |
metadata | Request Body | String | No | Additional information you can store on this member. |
skip_aggregation | Request Body | Boolean | No | Setting this parameter to true will prevent the member from automatically aggregating when it is created. |
Example Request
curl -X PUT /users/:user_guid/members/:member_guid \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \
-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\"}"
}
}'Response
{
"member": {
"aggregated_at": "2020-04-29T20:40:07Z",
"connection_status": "CONNECTED",
"guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
"id": null,
"institution_code": "mxbank",
"is_being_aggregated": true,
"is_managed_by_user": true,
"is_oauth": false,
"metadata": null,
"name": "MX Bank",
"successfully_aggregated_at": "2019-08-08T16:17:51Z",
"user_guid": "USR-151a102b-90b3-1bc3-48d1-c24cad5a2b13",
"user_id": "10405939560"
}
}List Account Numbers by Member
Endpoint: GET /users/:user_guid/members/:member_guid/account_numbers
This endpoint returns a list of account numbers associated with the specified member.
Parameters
| Name | Location | Description |
|---|---|---|
access_token | Request BodyHeaders | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X GET /users/:user_guid/members/:member_guid/account_numbers \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \Response
{
"account_numbers": [
{
"account_guid": "ACT-82a93692-f756-534f-9b2e-ad10a0f38462",
"account_number": "10001",
"institution_number": null,
"member_guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
"routing_number": "68899990000000",
"transit_number": null,
"user_guid": "USR-3a17a2b1-acbc-48d1-8098-1b8ae8939ab2"
}
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 1,
"total_pages": 1
}
}List Account Owners
Endpoint: GET /users/:user_guid/members/:member_guid/account_owners
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 owners of each account associated with the member.
Parameters
| Name | Location | Description |
|---|---|---|
access_token | Request BodyHeaders | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X GET /users/:user_guid/members/:member_guid/account_owners \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \Response
{
"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
}
}Update Account
Endpoint: PUT /users/:user_guid/members/:member_guid/accounts/:account_guid
This endpoint allows you to update certain attributes of an account resource.
Parameters
| Name | Location | Data Type | Is Required ? | Description |
|---|---|---|---|---|
access_token | Request BodyHeaders | String | Yes | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
account | Object | Yes | ||
Boolean | No |
Example Request
curl -X PUT /users/:user_guid/members/:member_guid/accounts/:account_guid \
'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \
-d '{
"account": {
"is_hidden": true
}
}'Response
{
"account": {
"account_number": "5366",
"apr": null,
"apy": null,
"available_balance": null,
"available_credit": 327.01,
"balance": 1872.99,
"cash_balance": null,
"cash_surrender_value": null,
"created_at": "2020-08-04T21:27:47Z",
"credit_limit": null,
"currency_code": "USD",
"day_payment_is_due": null,
"death_benefit": null,
"guid": "ACT-82a63692-f766-534f-9b2e-ad12a0b7001a",
"holdings_value": null,
"id": "104434698",
"imported_at": "2021-08-01T12:00:47Z",
"institution_code": "chase",
"insured_name": null,
"interest_rate": null,
"is_closed": false,
"is_hidden": true,
"last_payment": null,
"last_payment_at": null,
"loan_amount": null,
"matures_on": null,
"member_guid": "MBR-0b2321f5-bf4f-4224-a637-cac69fa051b",
"member_id": "104064688356",
"member_is_managed_by_user": true,
"metadata": null,
"minimum_balance": null,
"minimum_payment": null,
"name": "CREDIT CARD",
"nickname": null,
"original_balance": null,
"pay_out_amount": null,
"payment_due_at": null,
"payoff_balance": null,
"premium_amount": null,
"routing_number": null,
"started_on": null,
"subtype": "NONE",
"total_account_value": null,
"type": "CREDIT_CARD",
"updated_at": "2021-01-15T17:09:09Z",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06c11141024",
"user_id": "104001234"
}
}Aggregate Member
Endpoint: POST /users/:user_guid/members/:member_guid/aggregate
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.
This endpoint can trigger multi-factor authentication. It is therefore important that the end user be present when initiating aggregation.
This endpoint should not be used to perform periodic aggregations; MX automatically attempts to refresh each member approximately every 24 hours.
Parameters
| Name | Location | Description |
|---|---|---|
access_token | Request BodyHeaders | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X POST /users/:user_guid/members/:member_guid/aggregate \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \Response
{
"member": {
"aggregated_at": "2020-04-29T20:40:07Z",
"connection_status": "CONNECTED",
"guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
"id": null,
"institution_code": "mxbank",
"is_being_aggregated": true,
"is_managed_by_user": true,
"is_oauth": false,
"metadata": null,
"name": "MX Bank",
"successfully_aggregated_at": "2019-08-08T16:17:51Z",
"user_guid": "USR-151a102b-90b3-1bc3-48d1-c24cad5a2b13",
"user_id": "10405939560"
}
}List Member Challenges
Endpoint: GET /users/:user_guid/members/:member_guid/challenges
Use this endpoint for information on what multi-factor authentication challenges need to be answered in order to aggregate a member.
The exact fields returned in the challenges object will differ depending on the type of challenge that has been issued. For instance, a challenge with the type OPTIONS includes the options array, whereas one with the type TEXT does not.
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.
Parameters
| Name | Location | Data Type | Description |
|---|---|---|---|
access_token | Request BodyHeaders | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. | |
field_name | Query Parameters | String | A non-unique identifier for the question. |
guid | Query Parameters | String | A unique identifier for the challenge, defined by MX. |
image_data | Query Parameters | 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 | Query Parameters | String | For challenge type IMAGE_OPTIONS, this field represents an array of choices. It will only be present when the challenge type is IMAGE_OPTIONS. |
label | Query Parameters | String | A readable question that is presented to the user. |
options | Query Parameters | Array | For challenge type OPTIONS, this field represents an array of choices. It will only be present when the challenge type is OPTIONS. |
type | Query Parameters | String | The type of challenge. Supported types include TEXT, OPTIONS, TOKEN, IMAGE_DATA, IMAGE_OPTIONS. |
Example Request
curl -X POST /users/:user_guid/members/:member_guid/challenges \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \Response
{
"challenges": [
{
"field_name": "text",
"guid": "CRD-123",
"label": "What is your name",
"type": "TEXT"
},
{
"field_name": "text",
"guid": "CRD-456",
"label": "What is your favorite color?",
"options": [
{
"label": "Blue",
"value": 1
},
{
"label": "Red",
"value": 2
}
],
"type": "OPTIONS"
}
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 2,
"total_pages": 1
}
}Check Balances
Endpoint: POST /users/:user_guid/members/:member_guid/check_balance
This endpoint operates much like the aggregate member endpoint except that it gathers only account balance information; it does not gather any transaction data.
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 that two hours. If made more frequently, a 429 Too Many Requests status will be returned.
Calling this endpoint may result in multi-factor authentication. It is therefore important that the end user be present when initiating a balance request.
Parameters
| Name | Location | Description |
|---|---|---|
access_token | Request BodyHeaders | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X POST /users/:user_guid/members/:member_guid/check_balance \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \Response
{
"member": {
"aggregated_at": "2020-04-29T20:40:07Z",
"connection_status": "CONNECTED",
"guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
"id": null,
"institution_code": "mxbank",
"is_being_aggregated": true,
"is_managed_by_user": true,
"is_oauth": false,
"metadata": null,
"name": "MX Bank",
"successfully_aggregated_at": "2019-08-08T16:17:51Z",
"user_guid": "USR-151a102b-90b3-1bc3-48d1-c24cad5a2b13",
"user_id": "10405939560"
}
}List Member Credentials
Endpoint: GET /users/:user_guid/members/:member_guid/credentials
This endpoint returns an array which contains information on every non-MFA credential associated with a specific member
Parameters
| Name | Location | Description |
|---|---|---|
access_token | Request BodyHeaders | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X GET /users/:user_guid/members/:member_guid/credentials \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \Response
{
"credentials": [
{
"display_order": 1,
"field_name": "LOGIN",
"field_type": "LOGIN",
"guid": "CRD-9f61fb4c-912c-bd1e-b175-ccc7f0275cc1",
"label": "Username"
},
{
"display_order": 2,
"field_name": "PASSWORD",
"field_type": "PASSWORD",
"guid": "CRD-e3d7ea81-aac7-05e9-fbdd-4b493c6e474d",
"label": "Password"
}
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 2,
"total_pages": 1
}
}Extend history
Endpoint: POST /users/:user_guid/members/:member_guid/extend_history
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. If an extended transaction process is already running, a 202 Accepted status will be returned.
If another aggregation-type process is already running — like standard aggregation or verification — a 409 Conflict will be returned.
Parameters
| Name | Location | Description |
|---|---|---|
access_token | Request BodyHeaders | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X POST /users/:user_guid/members/:member_guid/extend_history \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \Response
{
"member": {
"aggregated_at": "2020-04-29T20:40:07Z",
"connection_status": "CONNECTED",
"guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
"id": null,
"institution_code": "mxbank",
"is_being_aggregated": true,
"is_managed_by_user": true,
"is_oauth": false,
"metadata": null,
"name": "MX Bank",
"successfully_aggregated_at": "2019-08-08T16:17:51Z",
"user_guid": "USR-151a102b-90b3-1bc3-48d1-c24cad5a2b13",
"user_id": "10405939560"
}
}Fetch Account Statements for a Member
Endpoint: POST /users/:user_guid/members/:member_guid/fetch_statements
Use this endpoint to fetch the statements associated with a particular member. If a fetch statements process 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.
Parameters
| Name | Location | Description |
|---|---|---|
access_token | Request BodyHeaders | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X POST /users/:user_guid/members/:member_guid/fetch_statements \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \Response
{
"member": {
"aggregated_at": "2020-08-05T16:09:20Z",
"connection_status": "CONNECTED",
"guid": "MBR-0b2121f5-bf4f-4244-a697-cac69160020f",
"id": "M-109876",
"institution_code": "chase",
"is_being_aggregated": true,
"is_managed_by_user": true,
"is_oauth": false,
"metadata": null,
"name": "Chase",
"successfully_aggregated_at": "2020-08-04T21:27:48Z",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
"user_id": "null"
}
}List Holdings by Member
Endpoint: GET /users/:user_guid/members/:member_guid/holdings
This endpoint returns all holdings associated with the specified member across all accounts.
Parameters
| Name | Location | Data Type | Is Required ? | Description |
|---|---|---|---|---|
access_token | Request BodyHeaders | String | Yes | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
from_date | Query Parameters | String | 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 | Query Parameters | String | 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. |
Example Request
curl -X GET /users/:user_guid/members/:member_guid/holdings \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \Response
{
"holdings": [
{
"account_guid": "ACT-f3a6ddfb-3768-4713-87a0-4ad04f87c396",
"cost_basis": null,
"created_at": "2019-08-02T17:43:22Z",
"currency_code": "USD",
"cusip": "70450Y103",
"daily_change": null,
"description": "PayPal Holdings Inc.",
"guid": "HOL-bd3bc50f-5a70-4226-abef-ae9bb4c1cb1a",
"holding_type": 9,
"id": "holding-8417f306-7113-485f-b209-3864ae82fdd7",
"market_value": 57,
"member_guid": null,
"metadata": null,
"purchase_price": 26,
"shares": 37,
"symbol": "PYPL",
"updated_at": "2020-03-02T19:11:02Z",
"user_guid": "USR-a2e65785-975d-dcbd-fd22-7bbba2581fb0"
},
{
"account_guid": "ACT-f3a6ddfb-3768-4713-87a0-4ad04f87c396",
"cost_basis": null,
"created_at": "2019-08-02T17:43:22Z",
"currency_code": "USD",
"cusip": "99UBAYWG0",
"daily_change": null,
"description": "American Airlines Group Inc.",
"guid": "HOL-813a8b86-0dfd-4e8b-8852-24e9a5a0c688",
"holding_type": 10,
"id": "holding-a3fccf60-9a89-4a90-aaaf-0462a4e40bef",
"market_value": 4,
"member_guid": null,
"metadata": null,
"purchase_price": 60,
"shares": 31,
"symbol": "AAL",
"updated_at": "2020-03-02T19:11:02Z",
"user_guid": "USR-a2e65785-975d-dcbd-fd22-7bbba2581fb0"
},
...
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 10,
"total_pages": 1
}
}Read Member Status
Endpoint: GET /users/:user_guid/members/:member_guid/status
This endpoint returns information about the member’s connection to a financial institution, including crucial information about aggregation.
The fields returned here should be interpreted together to get a picture of what is happening with the member.
Parameters
| Name | Location | Description |
|---|---|---|
access_token | Request BodyHeaders | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X GET /users/:user_guid/members/:member_guid/status \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \Response
{
"member": {
"aggregated_at": "2020-05-07T22:01:00Z",
"connection_status": "CONNECTED",
"guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
"is_authenticated": true,
"is_being_aggregated": false,
"successfully_aggregated_at": "2020-05-07T22:01:25Z"
}
}List Transactions by Member
Endpoint: GET /users/:user_guid/members/:member_guid/transactions
Requests to this endpoint return a list of transactions associated with the specified member, across all accounts associated with that member.
Parameters
| Name | Location | Data Type | Is Required ? | Description |
|---|---|---|---|---|
access_token | Request BodyHeaders | String | Yes | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
from_date | Query Parameters | String | 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 | Query Parameters | String | 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. |
Example Request
curl -X GET /users/:user_guid/members/:member_guid/transactions \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \Response
{
"transactions": [
{
"account_guid": "ACT-09c0ee66-51a8-4edf-b977-99534a471134",
"account_id": "account-1040434698",
"amount": 7.94,
"category": "Paycheck",
"check_number_string": null,
"created_at": "2020-03-02T19:11:11Z",
"currency_code": "USD",
"date": "2020-03-02",
"description": "Paycheck",
"guid": "TRN-181ce5d9-d33e-45b9-a9cd-8f8ef9d82d5d",
"id": "transaction-1040434568",
"is_bill_pay": false,
"is_direct_deposit": false,
"is_expense": false,
"is_fee": false,
"is_income": true,
"is_international": null,
"is_overdraft_fee": false,
"is_payroll_advance": false,
"is_recurring": false,
"is_subscription": false,
"latitude": null,
"localized_description": null,
"localized_memo": null,
"longitude": null,
"member_guid": "MBR-3eb08fde-01d5-454c-ae6a-95606ccd1225",
"member_is_managed_by_user": true,
"memo": null,
"merchant_category_code": null,
"merchant_guid": null,
"merchant_location_guid": null,
"original_description": "Payroll",
"posted_at": "2020-03-03T12:00:00Z",
"status": "POSTED",
"top_level_category": "Income",
"transacted_at": "2020-03-02T12:00:00Z",
"type": "CREDIT",
"updated_at": "2020-03-02T19:11:14Z",
"user_guid": "USR-a2e65785-975d-dcbd-fd22-7bbba2581fb0",
"user_id": "user-1040435626"
},
{
"account_guid": "ACT-09c0ee66-51a8-4edf-b977-99534a471134",
"account_id": "account-1040434698",
"amount": 64.77,
"category": "Mobile Phone",
"check_number_string": null,
"created_at": "2020-03-02T19:11:11Z",
"currency_code": "USD",
"date": "2020-03-02",
"description": "Verizon Wirelss",
"guid": "TRN-3f206b3c-0c6a-4c37-bbe9-c8d60dd953c7",
"id": "transaction-123057654",
"is_bill_pay": false,
"is_direct_deposit": false,
"is_expense": true,
"is_fee": false,
"is_income": false,
"is_international": null,
"is_overdraft_fee": false,
"is_payroll_advance": false,
"is_recurring": false,
"is_subscription": false,
"latitude": null,
"localized_description": null,
"localized_memo": null,
"longitude": null,
"member_guid": "MBR-3eb08fde-01d5-454c-ae6a-95606ccd1225",
"member_is_managed_by_user": true,
"memo": null,
"merchant_category_code": null,
"merchant_guid": "MCH-a5252ab5-56bc-a0ea-7d89-e598a4d5ec0e",
"merchant_location_guid": null,
"original_description": "Verizon Wireless",
"posted_at": "2020-03-03T12:00:00Z",
"status": "POSTED",
"top_level_category": "Bills & Utilities",
"transacted_at": "2020-03-02T12:00:00Z",
"type": "DEBIT",
"updated_at": "2020-03-02T19:11:14Z",
"user_guid": "USR-a2e65785-975d-dcbd-fd22-7bbba2581fb0",
"user_id": "user-1040435626"
},
...
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 20,
"total_pages": 1
}
}List Members
Endpoint: GET /users/:user_guid/members
This endpoint returns a list of all the members that belong to the specified user.
Parameters
| Name | Location | Description |
|---|---|---|
access_token | Request BodyHeaders | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X GET /users/:user_guid/members \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \Response
{
"members": [
{
"aggregated_at": "2019-12-03T18:10:22Z",
"connection_status": "CONNECTED",
"guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
"id": null,
"institution_code": "mxbank",
"is_being_aggregated": false,
"is_managed_by_user": true,
"is_oauth": false,
"metadata": null,
"name": "MX Bank",
"successfully_aggregated_at": "2019-08-08T16:17:51Z",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
"user_id": null,
},
{
"aggregated_at": "2019-12-03T18:10:22Z",
"connection_status": "FAILED",
"guid": "MBR-61bfd52c-2e3c-44ef-b747-20797a6f9dc0",
"id": null,
"institution_code": "capital_one",
"is_being_aggregated": false,
"is_managed_by_user": true,
"is_oauth": false,
"metadata": null,
"name": "Capital One ",
"successfully_aggregated_at": null,
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
"user_id": null
},
{
"aggregated_at": "2019-12-03T18:10:23Z",
"connection_status": "DEGRADED",
"guid": "MBR-98ae3e6e-1623-4471-add6-b464bdb4a900",
"id": null,
"institution_code": "paypal",
"is_being_aggregated": false,
"is_managed_by_user": true,
"is_oauth": false,
"metadata": null,
"name": "PayPal",
"successfully_aggregated_at": null,
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
"user_id": null
}
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 3,
"total_pages": 1
}
}Create Member
Endpoint: POST /users/:user_guid/members
This endpoint allows you to create a new member. The API supports both standard members and OAuth members. 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 list institution-required 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.
Parameters
| Name | Location | Data Type | Is Required ? | Description |
|---|---|---|---|---|
access_token | Request BodyHeaders | String | Yes | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
background_aggregation_is_disabled | Request Body | Boolean | No | When set to true, background aggregation will be disabled for this member. |
credentials | Request Body | Array | Yes | 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. |
id | Request Body | String | No | The unique partner-defined identifier for the member. |
institution_code | Request Body | String | Yes | The unique code for the institution to which the member will connect. Defined by MX. |
metadata | Request Body | String | No | Additional information you can store on this member. |
is_oauth | Request Body | Boolean | No | This indicates whether the member uses OAuth authentication or not. OAuth members do not require credentials when being created; instead, the member is created with a PENDING status and the response to the request will contain the oauth_window_uri attribute; the end user authenticates credentials with OAuth. |
referral_source | Request Body | String | No | Must be either BROWSER or APP depending on the implementation. Defaults to BROWSER. This field should not be nested under the member when given in a request body; it can also be sent as a query parameter to the the generate OAuth window URI endpoint. |
skip_aggregation | Request Body | Boolean | No | Setting this parameter to true will prevent the member from automatically aggregating when it is created. |
ui_message_webview_url_scheme | Request Body | String | No | A scheme for routing the user back to the application state they were previously in. This field should not be nested under the member when given in a request body; it can also be sent as a query parameter to the the generate OAuth window URI endpoint. |
Example Request
curl -X POST /users/:user_guid/members/:member_guid/transactions \
-H "Authorization: Bearer {access_token}" \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
"member": {
"credentials": [
{
"guid": "CRD-1ec152cd-e628-e81a-e852-d1e7104624da",
"value": "ExampleUsername"
},
{
"guid": "CRD-1ec152cd-e628-e81a-e852-d1e7104624da",
"value": "Pa$$vv@Rd"
}
],
"institution_code": "mxbank"
}
}'Response
{
"member": {
"aggregated_at": null,
"connection_status": "CREATED",
"guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
"id": null,
"institution_code": "mxbank",
"is_being_aggregated": true,
"is_managed_by_user": true,
"is_oauth": false,
"metadata": null,
"name": "MX Bank",
"successfully_aggregated_at": null,
"user_guid": "USR-151a102b-90b3-1bc3-48d1-c24cad5a2b13",
"user_id": "10405939560"
}
}‣
Users / Transaction Rules
A member represents the relationship between a user and an institution. A user may have multiple members, one each for their bank, their mortgage broker, their credit card provider, etc. Aggregation, verification, and many other processes are centered around a member, meaning this is probably the most important type of object you’ll be working with.
A transaction rule allows partners to specify a match_description and a category; all transactions matching the specified description will be placed in the chosen category.
Transaction rules override the default category MX gives to a transaction. Once a rule is created, all past transactions with a matching cleansed description are placed in the partner-chosen category, and any future transactions will be placed in the chosen category as well.
For example, creating a rule with the match_description “Wal-mart” and the category_guid for “Groceries” will automatically apply that category_guid to any transaction with a matching description, including both existing and future transactions.
Partners may also provide an optional description when creating or updating a transaction_rule. This string will replace all matched transactions’ description value.
Delete a Transaction Rule
Endpoint: DELETE /users/:user_guid/transaction_rules/:transaction_rule_guid
Use this endpoint to permanently delete a transaction rule based on its unique GUID.
Parameters
| Name | Location | Data Type | Is Required ? | Description |
|---|---|---|---|---|
access_token | Request BodyHeaders | String | Yes | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X DELETE /users/:user_guid/transaction_rules/:transaction_rule_guid \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \Read a Transaction Rule
Endpoint: GET /users/:user_guid/transaction_rules/:transaction_rule_guid
This endpoint is used to read the attributes of an existing transaction rule based on the rule’s unique GUID.
Parameters
| Name | Location | Description |
|---|---|---|
access_token | Request BodyHeaders | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X GET /users/:user_guid/transaction_rules/:transaction_rule_guid \
-H 'Content-Type: application/json' \
-d '{
"access_token": String
}'Response
{
"transaction_rule": {
"category_guid": "CAT-b1de2a04-db08-b6ed-f6fe-ca2f5b11c2d0",
"created_at": "2018-10-02T22:00:50Z",
"description": "Walmart",
"guid": "TXR-a080e0f9-a2d4-4d6f-9e03-672cc357a4d3",
"match_description": "Wal-mart",
"updated_at": "2018-10-02T23:54:40Z",
"user_guid": "USR-22fc3203-b3e6-8340-43db-8e50b2f56995"
}
}Update a Transaction Rule
Endpoint: PUT /users/:user_guid/transaction_rules/:transaction_rule_guid
This endpoint is used to update certain attributes of the specified member.
Use this endpoint to update the attributes of a specific transaction rule based on its unique GUID. The API will respond with the updated transaction_rule object. Any attributes not provided will be left unchanged.
Updates to a transaction rule will only be applied to future transactions which match the specified description.
Parameters
| Name | Location | Data Type | Is Required ? | Description |
|---|---|---|---|---|
access_token | Request BodyHeaders | String | Yes | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
transaction_rule | Request Body | Object | Yes | |
transaction_rule.category_guid | Request Body | String | Atleast 1 out the 3 | |
transaction_rule.description | Request Body | String | Atleast 1 out the 3 | |
transaction_rule.match_description | Request Body | String | Atleast 1 out the 3 |
Example Request
curl -X PUT /users/:user_guid/transaction_rules/:transaction_rule_guid \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \
-d '{
"transaction_rule": {
"category_guid": "CAT-b1de2a04-db08-b6ed-f6fe-ca2f5b11c2d0",
"description": "Wal-mart food storage",
"match_description": "Wal-mart"
}
}'Response
{
"transaction_rule": {
"category_guid": "CAT-b1de2a04-db08-b6ed-f6fe-ca2f5b11c2d0",
"created_at": "2018-10-02T22:00:50Z",
"description": "Walmart",
"guid": "TXR-a080e0f9-a2d4-4d6f-9e03-672cc357a4d3",
"match_description": "Wal-mart",
"updated_at": "2018-10-02T23:54:40Z",
"user_guid": "USR-22fc3203-b3e6-8340-43db-8e50b2f56995"
}
}List all Transaction Rules for a User
Endpoint: GET /users/:user_guid/transaction_rules
This endpoint is used to read the attributes of all existing transaction rules belonging to the user.
Parameters
| Name | Location | Description |
|---|---|---|
access_token | Request BodyHeaders | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X GET /users/:user_guid/transaction_rules \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \Response
{
"transaction_rules": [
{
"category_guid": "CAT-b1de2a04-db08-b6ed-f6fe-ca2f5b11c2d0",
"created_at": "2018-10-02T22:00:50Z",
"description": "Walmart",
"guid": "TXR-a080e0f9-a2d4-4d6f-9e03-672cc357a4d3",
"match_description": "Wal-mart",
"updated_at": "2018-10-02T23:54:40Z",
"user_guid": "USR-22fc3203-b3e6-8340-43db-8e50b2f56995"
},
{
"category_guid": "CAT-93ebd80b-4801-cf52-e844-91594ed4c217",
"created_at": "2018-12-19T23:07:36Z",
"description": "Coffee Madness",
"guid": "TXR-37a40e0f-b3e5-4d6f-9e09-672ee357a4de",
"match_description": "Starbucks",
"updated_at": "2018-12-18T23:04:56Z",
"user_guid": "USR-22fc3203-b3e6-8340-43db-8e50b2f56995"
}
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 2,
"total_pages": 1
}
}Create a Transaction Rule
Endpoint: POST /users/:user_guid/transaction_rules
This endpoint is used to create a new transaction rule. The newly-created transaction_rule object will be returned if successful.
Parameters
| Name | Location | Data Type | Is Required ? | Description |
|---|---|---|---|---|
access_token | Request BodyHeaders | String | Yes | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
transaction_rule | Request Body | Object | Yes | |
transaction_rule.category_guid | Request Body | String | Yes | |
transaction_rule.description | Request Body | String | Yes | |
transaction_rule.match_description | Request Body | String | Yes |
Example Request
curl -X POST /users/:user_guid/transaction_rules \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \
-d '{
"transaction_rule": {
"category_guid": "CAT-b1de2a04-db08-b6ed-f6fe-ca2f5b11c2d0",
"description": "Wal-mart food storage",
"match_description": "Wal-mart"
}
}'Response
{
"transaction_rule": {
"category_guid": "CAT-b1de2a04-db08-b6ed-f6fe-ca2f5b11c2d0",
"created_at": "2018-10-02T22:00:50Z",
"description": "Wal-mart food storage",
"guid": "TXR-a080e0f9-a2d4-4d6f-9e03-672cc357a4d3",
"match_description": "Wal-mart",
"updated_at": "2018-10-02T23:54:40Z",
"user_guid": "USR-22fc3203-b3e6-8340-43db-8e50b2f56995"
}
}‣
Users / Transactions
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.
‣
Read Transaction
Endpoint: GET /users/:user_guid/transactions/:transaction_guid
This endpoint will return the attributes of the specified transaction.
Parameters
| Name | Location | Data Type | Is Required ? | Description |
|---|---|---|---|---|
access_token | Request BodyHeaders | String | Yes | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X GET /users/:user_guid/transactions/:transaction_guid \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \Response
{
"transaction": {
"account_guid": "ACT-09c0ee66-51a8-4edf-b977-99534a471134",
"account_id": "account-1040434698",
"amount": 7.94,
"category": "Paycheck",
"check_number_string": null,
"created_at": "2020-03-02T19:11:11Z",
"currency_code": "USD",
"date": "2020-03-02",
"description": "Paycheck",
"guid": "TRN-181ce5d9-d33e-45b9-a9cd-8f8ef9d82d5d",
"id": "transaction-1040434568",
"is_bill_pay": false,
"is_direct_deposit": false,
"is_expense": false,
"is_fee": false,
"is_income": true,
"is_international": null,
"is_overdraft_fee": false,
"is_payroll_advance": false,
"is_recurring": false,
"is_subscription": false,
"latitude": null,
"localized_description": null,
"localized_memo": null,
"longitude": null,
"member_guid": "MBR-3eb08fde-01d5-454c-ae6a-95606ccd1225",
"member_is_managed_by_user": true,
"memo": null,
"merchant_category_code": null,
"merchant_guid": null,
"merchant_location_guid": null,
"original_description": "Payroll",
"posted_at": "2020-03-03T12:00:00Z",
"status": "POSTED",
"top_level_category": "Income",
"transacted_at": "2020-03-02T12:00:00Z",
"type": "CREDIT",
"updated_at": "2020-03-02T19:11:14Z",
"user_guid": "USR-a2e65785-975d-dcbd-fd22-7bbba2581fb0",
"user_id": "user-1040435626"
}
}‣
Update Transaction
Endpoint: PUT /users/:user_guid/transactions/:transaction_guid
Use this endpoint to update the description of a specific transaction according to its unique GUID.
Parameters
| Name | Location | Data Type | Is Required ? | Description |
|---|---|---|---|---|
access_token | Request BodyHeaders | String | Yes | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
transaction | Request Body | Object | Yes | |
transaction.description | Request Body | String | Yes |
Example Request
curl -X PUT /users/:user_guid/transactions/:transaction_guid \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \
-d '{
"transaction": {
"description": "new description"
}
}'Response
{
"transaction": {
"account_guid": "ACT-09c0ee66-51a8-4edf-b977-99534a471134",
"account_id": "account-1040434698",
"amount": 7.94,
"category": "Paycheck",
"check_number_string": null,
"created_at": "2020-03-02T19:11:11Z",
"currency_code": "USD",
"date": "2020-03-02",
"description": "Paycheck",
"guid": "TRN-181ce5d9-d33e-45b9-a9cd-8f8ef9d82d5d",
"id": "transaction-1040434568",
"is_bill_pay": false,
"is_direct_deposit": false,
"is_expense": false,
"is_fee": false,
"is_income": true,
"is_international": null,
"is_overdraft_fee": false,
"is_payroll_advance": false,
"is_recurring": false,
"is_subscription": false,
"latitude": null,
"localized_description": null,
"localized_memo": null,
"longitude": null,
"member_guid": "MBR-3eb08fde-01d5-454c-ae6a-95606ccd1225",
"member_is_managed_by_user": true,
"memo": null,
"merchant_category_code": null,
"merchant_guid": null,
"merchant_location_guid": null,
"original_description": "Payroll",
"posted_at": "2020-03-03T12:00:00Z",
"status": "POSTED",
"top_level_category": "Income",
"transacted_at": "2020-03-02T12:00:00Z",
"type": "CREDIT",
"updated_at": "2020-03-02T19:11:14Z",
"user_guid": "USR-a2e65785-975d-dcbd-fd22-7bbba2581fb0",
"user_id": "user-1040435626"
}
}‣
List Transactions by User
Endpoint: GET /users/:user_guid/transactions
Requests to this endpoint return a list of transactions associated with the specified user, across all members and accounts associated with that user.
Parameters
| Name | Location | Data Type | Is Required ? | Description |
|---|---|---|---|---|
access_token | Request BodyHeaders | String | Yes | Like MX, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
from_date | Query Parameters | String | 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 | Query Parameters | String | 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. |
Example Request
curl -X GET /users/:user_guid/transactions \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \Response
{
"transactions": [
{
"account_guid": "ACT-09c0ee66-51a8-4edf-b977-99534a471134",
"account_id": "account-1040434698",
"amount": 7.94,
"category": "Paycheck",
"check_number_string": null,
"created_at": "2020-03-02T19:11:11Z",
"currency_code": "USD",
"date": "2020-03-02",
"description": "Paycheck",
"guid": "TRN-181ce5d9-d33e-45b9-a9cd-8f8ef9d82d5d",
"id": "transaction-1040434568",
"is_bill_pay": false,
"is_direct_deposit": false,
"is_expense": false,
"is_fee": false,
"is_income": true,
"is_international": null,
"is_overdraft_fee": false,
"is_payroll_advance": false,
"is_recurring": false,
"is_subscription": false,
"latitude": null,
"localized_description": null,
"localized_memo": null,
"longitude": null,
"member_guid": "MBR-3eb08fde-01d5-454c-ae6a-95606ccd1225",
"member_is_managed_by_user": true,
"memo": null,
"merchant_category_code": null,
"merchant_guid": null,
"merchant_location_guid": null,
"original_description": "Payroll",
"posted_at": "2020-03-03T12:00:00Z",
"status": "POSTED",
"top_level_category": "Income",
"transacted_at": "2020-03-02T12:00:00Z",
"type": "CREDIT",
"updated_at": "2020-03-02T19:11:14Z",
"user_guid": "USR-a2e65785-975d-dcbd-fd22-7bbba2581fb0",
"user_id": "user-1040435626"
},
{
"account_guid": "ACT-09c0ee66-51a8-4edf-b977-99534a471134",
"account_id": "account-1040434698",
"amount": 64.77,
"category": "Mobile Phone",
"check_number_string": null,
"created_at": "2020-03-02T19:11:11Z",
"currency_code": "USD",
"date": "2020-03-02",
"description": "Verizon Wirelss",
"guid": "TRN-3f206b3c-0c6a-4c37-bbe9-c8d60dd953c7",
"id": "transaction-123057654",
"is_bill_pay": false,
"is_direct_deposit": false,
"is_expense": true,
"is_fee": false,
"is_income": false,
"is_international": null,
"is_overdraft_fee": false,
"is_payroll_advance": false,
"is_recurring": false,
"is_subscription": false,
"latitude": null,
"localized_description": null,
"localized_memo": null,
"longitude": null,
"member_guid": "MBR-3eb08fde-01d5-454c-ae6a-95606ccd1225",
"member_is_managed_by_user": true,
"memo": null,
"merchant_category_code": null,
"merchant_guid": "MCH-a5252ab5-56bc-a0ea-7d89-e598a4d5ec0e",
"merchant_location_guid": null,
"original_description": "Verizon Wireless",
"posted_at": "2020-03-03T12:00:00Z",
"status": "POSTED",
"top_level_category": "Bills & Utilities",
"transacted_at": "2020-03-02T12:00:00Z",
"type": "DEBIT",
"updated_at": "2020-03-02T19:11:14Z",
"user_guid": "USR-a2e65785-975d-dcbd-fd22-7bbba2581fb0",
"user_id": "user-1040435626"
},
...
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 20,
"total_pages": 1
}
}.
Parameters
| Name | Data Type | Is Required ? | Description |
|---|---|---|---|
page | Number | No | This specifies the page to be returned. Defaults to 1. |
records_per_page | Number | No | This specifies the number of records to be returned on each page. Defaults to 25. The valid range is from 10 to 100. |
| Name | Description |
|---|---|
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
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 2,
"total_pages": 1
}URL ConstructionDeveloper Configuration
‣
MX Webhooks
Link Money API uses webhooks to send updates to developers that lets developer applications know about data changes for new transactions, account balance updates, new account connections, and anything else worth sending a real-time update. This functionality also lets developers who use it skip having to pull data from the Link Money API on regular intervals to keep their applications abreast of the freshest user data.
Different aggregators have different webhook methodologies, schemas, and approaches. Link Money API offers webhooks in a variety of formats to make migrating from another aggregator's webhook system.
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.
‣
Configure a new Webhook Integration
This documentation discusses the options available to developers for configuring webhook flows in Link Money API. Link Money allows for straightforward webhook configuration on the client level.
After setting up a webhook URI through this flow, data will automatically begin to arrive from any of the organizations to which the developer has access. These hooks will continue to flow regardless of whether or not the webhook URI returns a successful (2xx) response.
If your developer ID has not yet been registered with any organizations, please contact FinGoal Support (support@fingoal.com) with the organization you are attempting to access. If you have access to no organizations, you will not receive webhooks.
Setting a Webhook URI
Request
PATCH /v1/webhooks/configuration
Request Headers
Field | Description |
Authorization | A valid Authorization header with a Bearer ${token} using an authentication token generated from Generic Tokens |
Request Body
Field | Description |
webhookUri | A valid webhook URI where you would like to receive data updates. |
Response
Code | Response Body | Description |
201 | The response body consists of a configuration object containing your developer name, callbackUri, and aggregator. | The webhook URL has been successfully updated. |
400 | An error object containing a link to pertinent documentation. | The webhook URI was improperly formatted; Link Money API could not interpret it as a URI. |
You can set up and configure webhooks on the client dashboard.
‣
Connection Status
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:
CHALLENGEDDENIEDEXPIREDIMPAIREDIMPEDEDLOCKEDPREVENTEDREJECTED
| Name | Data Type | Defination |
|---|---|---|
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 | Number | 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
{
"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"
}‣
Aggregation
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.
| Name | Data Type | Defination |
|---|---|---|
action | String | The action that triggered the webhook, e.g., member_data_updated. |
completed_at | Number | 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 | Number | The number of newly created transactions. |
transactions_updated_count | Number | 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
{
"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": "AGGREGATION",
"user_guid": "USR-eaf4ac68-d17d-5e9b-7b46-959a5b315a9e"
}‣
Balance
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.
| Name | Data Type | Defination |
|---|---|---|
action | String | The action that triggered the webhook, e.g., member_data_updated. |
completed_at | Number | 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
{
"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"
}‣
History
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.
| Name | Data Type | Defination |
|---|---|---|
action | String | The action that triggered the webhook, e.g., member_data_updated. |
completed_at | Number | 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 | Number | The number of newly created transactions. |
transactions_updated_count | Number | 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
{
"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"
}‣
Statement
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.
| Name | Data Type | Defination |
|---|---|---|
action | String | The action that triggered the webhook, e.g., member_data_updated. |
completed_at | String | The date and time at which the process that triggered the webhook was finished. Given in Unix time. |
completed_on | Number | 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 | String | 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
{
"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"
}‣
Features
The current version of webhooks in the MX Platform API has the following features:
- Webhooks are delivered via RESTful HTTPS requests to the partner’s listening service;
- Webhooks are triggered when a qualifying event occurs in the MX system;
- Webhooks can make requests to any specified URL;
- Configuration for this is done offline, out of band;
- Each POST request includes a JSON-formatted payload;
- The frequency of request retries diminishes over the course of approximately 24 hours, with no more than 12 total retries after an initial request.
‣
Security
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:
- HTTP basic: Provide MX with a username and password for making basic HTTP requests to your chosen URL;
- Mutual certificate authentication: Both the partner and MX exchange certificates, which are then passed and verified at the time of a request; certificates may be from a commercial certificate authority or custom;
- OAuth 2 bearer token (client credentials) authentication: Provide MX with an id and an access token; these are used to access a URL which provides a bearer token; this bearer token is then used to access the provided webhook URL until the bearer token expires after a pre-determined period of time; MX then repeats the process.
‣
Retries and errors
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.
The schedule of retries incorporates randomness so as to avoid a flood of requests to your system. Retries decrease in frequency with each attempt. You can expect to see a number of retries within the first hour of the initial attempt; gradually, retries will become less frequent.
If the webhook cannot be successfully delivered after 12 successive retries, it will not be delivered.
Partners can signal an error to MX’s webhooks by returning any status code other than those listed below. Any status code returned to MX that is not listed below will be considered an error by the webhook system. The most common error codes are those within the 400 range (something in the request was invalid) or the 500 range (something went wrong on the receiving end).
Successful status codes
200 OK201 CREATED202 ACCEPTED203 NON_AUTHORITATIVE_INFORMATION204 NO_CONTENT205 RESET_CONTENT206 PARTIAL_CONTENT
Setup and testing - To set up and configure webhooks or test an existing webhook, please visit your webhook profile on the client dashboard.
‣
MX Schema
‣
type: object
properties:
account_number:
type: string
description: "The account number associated with the account. This will typically be a masked or partial account number."
example: "5366"
apr:
type: float
description: The annual percentage rate associated with the account.
example: null
apy:
type: float
description: "The annual percentage yield associated with the account."
example: null
available_balance:
type: float
description: "The balance currently available for use in the account. The available balance will normally be a positive value for all account types. The value's sign is determined in the same way as the balance field."
example: null
available_credit:
type: float
description: "The amount of credit currently available for use in the account."
example: 347.01
balance:
type: float
description: "The balance associated with the account. The balance will normally be a positive value for all account types. For instance, 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."
example: 1872.99
cash_balance:
type: float
description: The cash balance of the account.
example: null
cash_surrender_value:
type: float
description: "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."
example: null
created_at:
type: string
description: The date and time at which the account was created on the MX Platform.
example: "2020-08-04T21:27:47Z"
credit_limit:
type: float
description: "The credit limit associated with the account."
example: null
currency_code:
type: string
description: "The three-character ISO 4217 currency code."
example: "USD"
day_payment_is_due:
type: string
description: "The day of the month the payment is due. For example, the 14th is passed as 14."
example: null
death_benefit:
type: integer
description: "The amount paid to the beneficiary of the account upon death of the account owner."
example: null
guid:
type: string
description: "The unique identifier for the account. Defined by MX."
example: "ACT-82a93692-f756-534f-9b2e-ad10a0f38462"
holdings_value:
type: float
description: "The value of the holdings associated with the account."
example: null
id:
type: string
description: "The unique partner-defined identifier for the account."
example: "1040434698"
institution_code:
type: string
description: "A unique identifier for the institution associated with this account. Defined by MX."
example: "chase"
insured_name:
type: string
description: "The name of the insured individual."
example: null
interest_rate:
type: float
description: "The interest rate associated with the account."
example: null
is_closed:
type: boolean
description: "This indicates whether an account has been closed."
example: false
is_hidden:
type: boolean
description: "This indicates whether the account is hidden. Defaults to false."
example: false
last_payment_at:
type: string
description: "The date and time of the most recent payment on the account."
example: null
last_payment:
type: float
description: "The amount of the most recent payment on the account."
example: null
loan_amount:
type: float
description: "The amount of the loan associated with the account."
example: null
matures_on:
type: string
description: "The date on which the account matures."
example: null
member_guid:
type: string
description: "The unique identifier for the member to which the account belongs, assigned by MX."
example: "MBR-0b2121f5-bf4f-4244-a697-cac69160020f"
minimum_balance:
type: float
description: "The minimum balance associated with the account."
example: null
minimum_payment:
type: float
description: "The minimum payment required for an account. This can apply to any debt account. Max length is 10,2."
example: null
name:
type: string
description: "The human-readable name for the account."
example: "CREDIT CARD"
original_balance:
type: float
description: "The original balance associated with the account. This will always be positive."
example: null
pay_out_amount:
type: string
description: "The amount paid out to the insured individual or beneficiary under the conditions of the insurance policy."
example: null
payment_due_at:
type: string
description: "The date and time at which the next payment is due on the account."
example: null
payoff_balance:
type: float
description: "The payoff balance for a debt account. This will normally be a positive number."
example: null
premium_amount:
type: float
description: "The insurance policy's premium amount."
example: null
started_on:
type: string
description: "The date on which a debt account was started."
example: null
subtype:
type: string
description: "The account’s subtype, e.g., PLAN_401_K, MONEY_MARKET, or HOME_EQUITY."
example: "NONE"
total_account_value:
type: float
description: The total value of the account. Max length is 14,2.
example: null
type:
type: string
description: "The general or parent type of the account."
example: "CREDIT_CARD"
updated_at:
type: string
description: "The date and time at which the account was most recently updated."
example: "2021-01-15T17:09:09Z"
user_guid:
type: string
description: "The unique identifier for the user to which the account belongs."
example: "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"‣
type: object
properties:
account_guid:
type: string
description: "The unique identifier for the account associated with the transaction. Defined by MX."
example: "ACT-5ab76520-e0f8-434f-aedf-4f41b8b3ac6f"
amount:
type: number
description: "The monetary amount of the transaction."
example: 4.99
category:
type: string
description: The category of the transaction.
example: Shopping
check_number_string:
type: string
description: The check number for the transaction.
example: "12345"
created_at:
type: string
description: The date and time the transaction was created.
example: "2021-03-03T16:55:23Z"
currency_code:
type: string
description: The three-character ISO 4217 currency code.
example: "USD"
date:
type: string
description: The date the transaction was created, given in ISO 8601 format without a timestamp.
example: "2021-03-03"
description:
type: string
description: A human-readable version of the original_description field described below. This is provided by the MX platform.
example: "Sam's Club"
guid:
type: string
description: The unique identifier for the transaction. Described by MX.
example: "TRN-bb65493f-326c-4364-b79d-50829bd8277b"
id:
type: string
description: The unique partner-defined identifier for the transaction. This field is only returned with partner-managed transactions.
example: "12345"
is_bill_pay:
type: boolean
description: This indicates whether the transaction represents a bill pay.
example: false
is_direct_deposit:
type: boolean
description: This indicates whether the transaction represents a direct deposit.
example: false
is_expense:
type: boolean
description: This indicates whether the transaction represents an expense.
example: true
is_fee:
type: boolean
description: This indicates whether the transaction represents a fee.
example: false
is_income:
type: boolean
description: This indicates whether the transaction represents income.
example: false
is_international:
type: boolean
description: 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.
example: null
is_overdraft_fee:
type: boolean
description: This indicates whether the transaction represents an overdraft fee.
example: false
is_payroll_advance:
type: boolean
description: This indicates whether the transaction represents a payroll advance.
example: false
latitude:
type: number
description: The latitude of the location where the transaction occurred. The number is a signed decimal.
example: 35.689488
localized_description:
type: string
description: A human-readable description of the transaction, provided in a local language.
example: "Sam's Club"
localized_memo:
type: string
description: Additional descriptive information about the transaction, provided in a local language.
example: "Purchase at Sam's club"
longitude:
type: number
description: The longitude of the location where the transaction occurred. The number is a signed decimal.
example: 139.691706
member_guid:
type: string
description: The unique identifier for the member associated with the transaction Defined by MX.
example: "MBR-0b2121f5-bf4f-4244-a697-cac69160020f"
memo:
type: string
description: This field contains additional descriptive information about the transaction.
example: "Purchase at Sam's Club"
merchant_category_code:
type: number
description: The ISO 18245 category code for the transaction.
example: 0780
merchant_guid:
type: string
description: The unique identifier for the merchant associated with this transaction. Defined by MX.
example: "MCH-f07fcd23-1a18-a1a5-b49b-41d2b1076a69"
original_description:
type: string
description: The original description of the transaction as provided by our data feed. See description above for more information.
example: "XXXX0437 PURCHASE SAM'S CLUB ROCH NY 0029"
posted_at:
type: string
description: The date and time the transaction was posted.
example: "2021-03-03T16:55:23Z"
status:
type: string
description: The status of the transaction. This will be either POSTED or PENDING.
example: POSTED
top_level_category:
type: string
description: The parent category assigned to this transaction's category.
example: Shopping
transacted_at:
type: string
description: The date and time the transaction took place.
example: "2021-03-03T16:55:23Z"
type:
type: string
description: The type of transaction. This will be either CREDIT or DEBIT.
example: DEBIT
updated_at:
type: string
description: The date and time the transaction was last updated.
example: "2021-03-03T16:55:23Z"
user_guid:
type: string
description: The unique identifier for the user associated with this transaction. Defined by MX.
example: "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
insight_text:
type: string
description: A short, descriptive test field describing the advice or deal that a fingineer has discovered for this transaction.
insight_ctaurl:
type: string
description: The call to action URL for the advice. Sends the end user to a web page for actionable information to follow the advice.
finsight_image:
type: string
description: A url for a relevant image associated with the advice. Generally, this will be a logo for the merchant FinGoal recommends.
recommendation:
type: string
description: A short title for the Finsight. Generally this will be the name of the merchant that FinGoal recommends.
amountFound:
type: float
description: The amount of "found money" the fingineer estimates this advice will save the end user if it is followed.‣
type: object
properties:
account_guid:
type: string
description: "The unique identifier for the account associated with the transaction. Defined by MX."
example: "ACT-5ab76520-e0f8-434f-aedf-4f41b8b3ac6f"
amount:
type: number
description: "The monetary amount of the transaction."
example: 4.99
category:
type: string
description: The category of the transaction.
example: Shopping
check_number_string:
type: string
description: The check number for the transaction.
example: "12345"
created_at:
type: string
description: The date and time the transaction was created.
example: "2021-03-03T16:55:23Z"
currency_code:
type: string
description: The three-character ISO 4217 currency code.
example: "USD"
date:
type: string
description: The date the transaction was created, given in ISO 8601 format without a timestamp.
example: "2021-03-03"
description:
type: string
description: A human-readable version of the original_description field described below. This is provided by the MX platform.
example: "Sam's Club"
guid:
type: string
description: The unique identifier for the transaction. Described by MX.
example: "TRN-bb65493f-326c-4364-b79d-50829bd8277b"
id:
type: string
description: The unique partner-defined identifier for the transaction. This field is only returned with partner-managed transactions.
example: "12345"
is_bill_pay:
type: boolean
description: This indicates whether the transaction represents a bill pay.
example: false
is_direct_deposit:
type: boolean
description: This indicates whether the transaction represents a direct deposit.
example: false
is_expense:
type: boolean
description: This indicates whether the transaction represents an expense.
example: true
is_fee:
type: boolean
description: This indicates whether the transaction represents a fee.
example: false
is_income:
type: boolean
description: This indicates whether the transaction represents income.
example: false
is_international:
type: boolean
description: 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.
example: null
is_overdraft_fee:
type: boolean
description: This indicates whether the transaction represents an overdraft fee.
example: false
is_payroll_advance:
type: boolean
description: This indicates whether the transaction represents a payroll advance.
example: false
latitude:
type: number
description: The latitude of the location where the transaction occurred. The number is a signed decimal.
example: 35.689488
localized_description:
type: string
description: A human-readable description of the transaction, provided in a local language.
example: "Sam's Club"
localized_memo:
type: string
description: Additional descriptive information about the transaction, provided in a local language.
example: "Purchase at Sam's club"
longitude:
type: number
description: The longitude of the location where the transaction occurred. The number is a signed decimal.
example: 139.691706
member_guid:
type: string
description: The unique identifier for the member associated with the transaction Defined by MX.
example: "MBR-0b2121f5-bf4f-4244-a697-cac69160020f"
memo:
type: string
description: This field contains additional descriptive information about the transaction.
example: "Purchase at Sam's Club"
merchant_category_code:
type: number
description: The ISO 18245 category code for the transaction.
example: 0780
merchant_guid:
type: string
description: The unique identifier for the merchant associated with this transaction. Defined by MX.
example: "MCH-f07fcd23-1a18-a1a5-b49b-41d2b1076a69"
original_description:
type: string
description: The original description of the transaction as provided by our data feed. See description above for more information.
example: "XXXX0437 PURCHASE SAM'S CLUB ROCH NY 0029"
posted_at:
type: string
description: The date and time the transaction was posted.
example: "2021-03-03T16:55:23Z"
status:
type: string
description: The status of the transaction. This will be either POSTED or PENDING.
example: POSTED
top_level_category:
type: string
description: The parent category assigned to this transaction's category.
example: Shopping
transacted_at:
type: string
description: The date and time the transaction took place.
example: "2021-03-03T16:55:23Z"
type:
type: string
description: The type of transaction. This will be either CREDIT or DEBIT.
example: DEBIT
updated_at:
type: string
description: The date and time the transaction was last updated.
example: "2021-03-03T16:55:23Z"
user_guid:
type: string
description: The unique identifier for the user associated with this transaction. Defined by MX.
example: "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"‣
type: object
properties:
email:
type: string
description: The end user's email address.
example: "testuser@gmail.com"
guid:
type: string
description: The unique identifier for the user. Defined by MX.
example: "USR-1114024-90b3-1bce-cac9-c06ced52ab"
id:
type: string
description: A unique, partner-defined, enforced identifier for the user.
example: "12345"
is_disabled:
type: boolean
description: This indicates whether the user has been disabled. Defaults to false.
example: false
metadata:
type: string
description: Additional information you can store about this user. MX recommends using JSON-structured data.
example: null