MX (Open Banking) Getting Started: Account Setup & First API Call

Getting started overview

Getting started with MX (Open Banking) involves a structured process to ensure secure and efficient integration. The primary steps include setting up a developer account, generating the necessary API credentials, and making an initial API call to confirm connectivity. MX provides a sandbox environment for testing integrations before deploying to a production environment. This allows developers to simulate data aggregation and test various API endpoints without affecting live financial data.

The MX platform is designed to facilitate financial data aggregation, data enhancement, and the creation of digital banking experiences. It supports various use cases, including personal financial management (PFM) applications and fraud detection systems. Developers typically interact with the MX API using standard HTTP requests, authenticated with a Client ID and API Key. The platform offers SDKs in languages such as JavaScript, React Native, Android, and iOS to streamline development, alongside comprehensive documentation for direct API interactions according to MX API documentation.

Below is a quick reference table outlining the essential steps to get started:

Create an account and get keys

To begin using MX (Open Banking), the first requirement is to establish a developer account. MX offers custom enterprise pricing models, and access typically starts with engagement through their sales team. You can initiate this process by visiting the MX Contact Sales page. During the signup process, you will provide details about your organization and intended use case, which helps MX configure an appropriate account and access level for you.

Once your account is approved and set up, you will gain access to the MX Developer Dashboard. Within this dashboard, you will find your unique API credentials: a Client ID and an API Key. These keys are fundamental for authenticating all your requests to the MX API. The Client ID identifies your application or organization, while the API Key serves as the secret token that verifies your requests. It is critical to keep your API Key secure and never expose it in client-side code or public repositories. Best practices for API key security often include storing keys as environment variables or using a secrets management service.

MX often provides distinct sets of credentials for their sandbox (development) environment and their production environment. Ensure you are using the correct set of keys for the environment you are targeting. The sandbox environment allows for testing without interacting with real financial data, as described in the MX API reference documentation.

Your first request

After obtaining your Client ID and API Key, you can proceed to make your first API request. This initial call typically targets a basic endpoint in the MX sandbox environment to verify that your credentials are set up correctly and that you can establish a connection to the MX API. A common first request might involve listing supported institutions or checking the status of the API.

MX provides extensive documentation and code examples for various programming languages, including cURL, Ruby, Python, Java, and Node.js. These examples can be found in the MX API reference and are designed to help you quickly construct your first request. Below is an example using cURL, which is a widely supported command-line tool for making HTTP requests and is useful for initial testing. This example demonstrates how to fetch a list of supported institutions from the MX platform:

curl --request GET \
  --url https://base.url/users/{user_guid}/institutions \
  --header 'Accept: application/vnd.mx.api.v1+json' \
  --header 'MX-API-KEY: YOUR_API_KEY' \
  --header 'MX-CLIENT-ID: YOUR_CLIENT_ID'

Note: Replace YOUR_API_KEY and YOUR_CLIENT_ID with your actual credentials. The base.url should correspond to the MX API endpoint for the sandbox environment, which is typically provided in your developer dashboard or MX documentation. The user_guid placeholder would be replaced by a specific user identifier once you begin working with user-specific data, but for a general institutions list, some endpoints may not require it or use a default if available in the sandbox.

Upon successful execution, the API should return a JSON response containing a list of institutions. A 200 OK HTTP status code generally indicates a successful request. If you encounter errors, refer to the troubleshooting section below and the MX API documentation for specific error codes and their meanings.

Common next steps

Once you have successfully made your first API call, you can proceed with further integration steps to build out your application's functionality. The MX platform supports a range of capabilities beyond simple institution listing, including:

• User Management: Creating and managing users within the MX system is essential for linking their financial accounts. This involves generating unique user identifiers and handling user consent for data access, following principles outlined by OAuth 2.0 authorization frameworks.
• Account Aggregation: This is a core feature where you enable users to connect their financial accounts (e.g., bank accounts, credit cards) from various institutions. The MX platform then aggregates transaction and balance data from these accounts.
• Data Enhancement: MX provides services to categorize and cleanse raw transaction data, making it more digestible and useful for end-users. This includes normalizing merchant names, classifying spending, and detecting duplicate transactions.
• Money Experiences: Building features like personal financial management (PFM) tools, budgeting applications, and spending insights using the enhanced data.
• Webhook Configuration: Setting up webhooks allows MX to notify your application in real-time about significant events, such as new transactions, account updates, or connection errors. This reduces the need for constant polling and improves efficiency, as detailed in general webhook implementation guides.
• Production Deployment: After thorough testing in the sandbox, you will work with MX to transition your application to the production environment, which involves using live API keys and real user data.

Each of these steps typically has dedicated sections and code examples within the MX Developer Documentation, guiding you through the implementation details.

Troubleshooting the first call

When making your first API call to MX, you might encounter issues. Here are common problems and troubleshooting steps:

• Incorrect Credentials: Double-check that your MX-API-KEY and MX-CLIENT-ID are correctly copied and pasted into your request. Ensure there are no leading or trailing spaces. Verify you are using the correct keys for the sandbox environment if that's your target.
• Environment URL Mismatch: Confirm that the base URL for your API request matches the MX sandbox API endpoint. Using a production URL with sandbox keys (or vice-versa) will result in authentication failures.
• Missing Headers: Ensure all required HTTP headers, such as Accept: application/vnd.mx.api.v1+json, are included in your request as specified in the MX API reference.
• Network Issues: Verify your internet connection. If you are behind a firewall or proxy, ensure it allows outgoing connections to the MX API endpoints.
• Rate Limiting: While less common for a first call, repeated failed attempts or rapid successive requests could trigger rate limiting. If you suspect this, wait a few minutes before retrying.
• Error Messages: Pay close attention to the HTTP status code and any error messages returned in the API response body. MX error messages are designed to be informative. Common error codes include 401 Unauthorized (credentials issue), 403 Forbidden (permissions issue), or 404 Not Found (incorrect endpoint or resource).
• SDK vs. Raw API: If you are using an MX SDK, ensure it is correctly installed and configured. Sometimes, making a raw cURL request (as shown in the example above) can help isolate if the issue is with your code, the SDK, or the API call itself.
• Documentation Review: Consult the MX Developer Documentation for specific API endpoint requirements, expected parameters, and error code explanations.
• Contact MX Support: If you have exhausted troubleshooting steps and still face issues, reach out to MX support. Provide them with your Client ID, the specific API endpoint you are calling, your request details (excluding your secret API key), and the full error response you are receiving.