MX

MX

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:

  1. The Base URL - for example, https://linkmoney-dev.fingoal.com
  2. The endpoint collection's name - In this case, mx. See each endpoint collection for the collection's name.
  3. The version - each endpoint collection has separate versioning rather than a holistic version control for the entire api - for example, v1.
  4. 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

For the Request

NameLocationDescription
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

For the Request

NameLocationDescription
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

For the Request

NameLocationData TypeDescription
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.
Request BodyQuery Parameters
String
Only institutions whose name contains the appended string will be returned.
Request BodyQuery Parameters
Boolean
Only institutions which support identity will be returned.
Request BodyQuery Parameters
Boolean
Only institutions which offer access to account statements will be returned.
Request BodyQuery Parameters
Boolean
Only institutions which support account verification will be returned.
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

For the Request

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

Endpoints

EndpointRequest MethodDescription
GET
Find a single Institution and return its status.
GET
Listing institution-required credentials returns all credentials for the institutions along with pagination parameters.
GET
Returns a list of institutions based on the specified search term or parameter.
GET
Returns a paginated list containing institutions that have been set as the partner’s favorites, sorted by popularity.
GET
Returns a paginated list of all the merchants in the MX system.
GET
Returns the attributes of the specified merchant.
GET
Returns the specified account resource.
GET
Returns a list of account numbers associated with the specified account.
GET
Returns a list of the last 90 days of transactions associated with the specified account.
GET
Returns a list of all the accounts associated with the specified user.
DELETE
This endpoint is used to delete a specific custom category according to its unique GUID.
GET
Returns a list of account numbers associated with the specified account.
PUT
This endpoint is used to update the attributes of a custom category according to its unique GUID.
GET
This endpoint is used to list all categories associated with a user, including both default and custom categories.
POST
This endpoint is used to list all categories associated with a user, including both default and custom categories.
GET
This endpoint is used to retrieve a list of all the default categories and subcategories offered within the MX Platform API.
GET
Returns all holdings associated with the specified user across all accounts and members.
GET
Returns all holdings associated with the specified account.
GET
This endpoint is used to get an array of available statements.
GET
This endpoint is used to read a JSON representation of the statement.
GET
Use this endpoint to download a specified statement PDF.
DELETE
This endpoint will permanently delete the specified member.
GET
This endpoint returns information about the specified member.
PUT
This endpoint is used to update certain attributes of the specified member.
GET
This endpoint returns a list of account numbers associated with the specified member.
GET
Use this endpoint to check whether identity data is available for a specific member.
PUT
This endpoint allows you to update certain attributes of an account resource.
POST
This endpoint initiates an aggregation event for the member.
GET
Use this endpoint for information on what multi-factor authentication challenges need to be answered in order to aggregate a member.
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.
GET
This endpoint returns an array which contains information on every non-MFA credential associated with a specific member.
POST
Some institutions allow developers to access an extended transaction history with up to 24 months of data associated with a particular member.
POST
Use this endpoint to fetch the statements associated with a particular member.
GET
Returns all holdings associated with the specified member across all accounts.
GET
Returns information about the member’s connection to a financial institution, including crucial information about aggregation.
GET
Returns a list of transactions associated with the specified member, across all accounts associated with that member.
GET
Returns a list of all the members that belong to the specified user.
POST
This endpoint allows you to create a new member.
DELETE
This endpoint permanently deletes a transaction rule based on its unique GUID.
GET
This endpoint is used to read the attributes of an existing transaction rule based on the rule’s unique GUID.
PUT
This endpoint is used to read the attributes of an existing transaction rule based on the rule’s unique GUID.
GET
This endpoint is used to read the attributes of all existing transaction rules belonging to the user.
POST
This endpoint is used to create a new transaction rule.
GET
This endpoint will return the attributes of the specified transaction.
PUT
Use this endpoint to update the description of a specific transaction according to its unique GUID.
GET
Returns a list of transactions associated with the specified user, across all members and accounts associated with that user.
DELETE
This endpoint is used to delete the specified user.
GET
This endpoint will return the details of the specified user.
PUT
This endpoint is used to update the attributes of the specified user.
GET
Returns a list of all your 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

For the Request

NameLocationTypeDescription
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

For the Request

NameLocationDescription
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

For the Request

NameLocationData TypeIs Required ?Description
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

For the Request

NameLocationDescription
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

For the Request

NameLocationData TypeIs Required ?Description
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.
Request Body
Object
Yes
Request Body
String
No
Request Body
String
No
Request Body
String
No
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

For the Request

NameLocationDescription
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

For the Request

NameLocationData TypeIs Required ?Description
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.
Request Body
Object
Yes
Request Body
String
No
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.
Request Body
String
No
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

For the Request

NameLocationDescription
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

For the Request

NameLocationDescription
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

For the Request

NameLocationData TypeIs RequiredDescription
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.
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.
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

Copy of For the Request

NameLocationData TypeIs RequiredDescription
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

For the Request

NameLocationDescription
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

For the Request

NameLocationDescription
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

For the Request

NameLocationData TypeIs RequiredDescription
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.
Request Body
Object
Yes
While no single parameter is required, the category object cannot be empty.
Request Body
String
No
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

Copy of For the Request

NameLocationData TypeIs RequiredDescription
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

For the Request

NameLocationData TypeIs Required ?Description
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.
Request Body
Object
Yes
Request Body
String
No
Request Body
String
Yes
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

Copy of For the Request

NameLocationData TypeIs RequiredDescription
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

For the Request

NameLocationData TypeIs Required ?Description
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.
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.
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

For the Request

NameLocationDescription
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

For the Request

NameLocationData TypeIs Required ?Description
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

For the Request

NameLocationDescription
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

For the Request

NameLocationDescription
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

For the Request

NameLocationData TypeIs Required ?Description
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

For the Request

NameLocationDescription
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

For the Request

NameLocationData TypeIs Required ?Description
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.
Request Body
Boolean
No
This indicates whether background aggregation should be disabled for the member.
Request Body
Array
No
The credentials that you wish to update for this member.
Request Body
String
No
The unique partner-definite identifier for the member.
Request Body
String
No
Additional information you can store on this member.
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

For the Request

NameLocationDescription
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

For the Request

NameLocationDescription
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

For the Request

NameLocationData TypeIs Required ?Description
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.
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

For the Request

NameLocationDescription
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

For the Request

NameLocationData TypeDescription
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.
Query Parameters
String
A non-unique identifier for the question.
Query Parameters
String
A unique identifier for the challenge, defined by MX.
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.
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.
Query Parameters
String
A readable question that is presented to the user.
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.
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

For the Request

NameLocationDescription
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

For the Request

NameLocationDescription
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

For the Request

NameLocationDescription
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

For the Request

NameLocationDescription
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

For the Request

NameLocationData TypeIs Required ?Description
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.
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.
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

For the Request

NameLocationDescription
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

For the Request

NameLocationData TypeIs Required ?Description
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.
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.
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

For the Request

NameLocationDescription
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

For the Request

NameLocationData TypeIs Required ?Description
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.
Request Body
Boolean
No
When set to true, background aggregation will be disabled for this member.
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.
Request Body
String
No
The unique partner-defined identifier for the member.
Request Body
String
Yes
The unique code for the institution to which the member will connect. Defined by MX.
Request Body
String
No
Additional information you can store on this member.
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.
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.
Request Body
Boolean
No
Setting this parameter to true will prevent the member from automatically aggregating when it is created.
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

For the Request

NameLocationData TypeIs Required ?Description
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

For the Request

NameLocationDescription
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

For the Request

NameLocationData TypeIs Required ?Description
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.
Request Body
Object
Yes
Request Body
String
Atleast 1 out the 3
Request Body
String
Atleast 1 out the 3
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

For the Request

NameLocationDescription
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

For the Request

NameLocationData TypeIs Required ?Description
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.
Request Body
Object
Yes
Request Body
String
Yes
Request Body
String
Yes
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

For the Request

NameLocationData TypeIs Required ?Description
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

For the Request

NameLocationData TypeIs Required ?Description
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.
Request Body
Object
Yes
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

For the Request

NameLocationData TypeIs Required ?Description
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.
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.
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

For the Request

NameData TypeIs Required ?Description
Number
No
This specifies the page to be returned. Defaults to 1.
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.

Response

NameDescription
The page delivered by the current response.
The number of records delivered with each page.
The total number of records available.
The total number of pages available.

Example Pagination Object

"pagination": {
  "current_page": 1,
  "per_page": 25,
  "total_entries": 2,
  "total_pages": 1
}URL Construction
🖥️
Developer 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
 to authorize the call.

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:

  • CHALLENGED
  • DENIED
  • EXPIRED
  • IMPAIRED
  • IMPEDED
  • LOCKED
  • PREVENTED
  • REJECTED

Fields for the connection status webhook

NameData TypeDefination
String
This value should always equal CHANGED.
String
This field indicates the state of a member’s aggregation, provided as a string.
Number
This field indicates the state of a member’s aggregation, provided as an integer.
String
A message that can be displayed to the end user to help them navigate the connection and aggregation process.
String
Unique identifier for the member that triggered the webhook. Defined by MX.
String
The type of webhook being delivered.
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.

Fields for the aggregation webhook

NameData TypeDefination
String
The action that triggered the webhook, e.g., member_data_updated.
Number
The date and time at which the process that triggered the webhook was finished. Given in Unix time.
String
The date on which the process that triggered the webhook was finished. Given in ISO 8601 without a timestamp.
String
The unique identifier for the member which has new or updated transaction data. Defined by MX.
Number
The number of newly created transactions.
Number
The number of newly updated transactions.
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.
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.

Fields for the balance webhook

NameData TypeDefination
String
The action that triggered the webhook, e.g., member_data_updated.
Number
The date and time at which the process that triggered the webhook was finished. Given in Unix time.
String
The date on which the process that triggered the webhook was finished. Given in ISO 8601 without a timestamp.
String
The unique identifier for the member which has new or updated transaction data. Defined by MX.
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.
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.

Fields for history webhooks

NameData TypeDefination
String
The action that triggered the webhook, e.g., member_data_updated.
Number
The date and time at which the process that triggered the webhook was finished. Given in Unix time.
String
The date on which the process that triggered the webhook was finished. Given in ISO 8601 without a timestamp.
String
The unique identifier for the member which has new or updated transaction data. Defined by MX.
Number
The number of newly created transactions.
Number
The number of newly updated transactions.
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.
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.

Fields for statement webhooks

NameData TypeDefination
String
The action that triggered the webhook, e.g., member_data_updated.
String
The date and time at which the process that triggered the webhook was finished. Given in Unix time.
Number
The date on which the process that triggered the webhook was finished. Given in ISO 8601 without a timestamp.
String
The unique identifier for the member which has new or updated transaction data. Defined by MX.
String
The number of newly created transactions.
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.
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:

  1. HTTP basic: Provide MX with a username and password for making basic HTTP requests to your chosen URL;
  2. 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;
  3. 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 OK
  • 201 CREATED
  • 202 ACCEPTED
  • 203 NON_AUTHORITATIVE_INFORMATION
  • 204 NO_CONTENT
  • 205 RESET_CONTENT
  • 206 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

‣
Accounts
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"
‣
FinSight 
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.
‣
Transaction
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"
‣
User
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