Request widget URL

curl --request POST \
  --url https://int-api.mx.com/users/{user_identifier}/widget_urls \
  --header 'Accept-Version: <accept-version>' \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "widget_url": {}
}
'

import requests

url = "https://int-api.mx.com/users/{user_identifier}/widget_urls"

payload = { "widget_url": {} }
headers = {
    "Accept-Version": "<accept-version>",
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Accept-Version': '<accept-version>',
    Authorization: 'Basic <encoded-value>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({widget_url: {}})
};

fetch('https://int-api.mx.com/users/{user_identifier}/widget_urls', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://int-api.mx.com/users/{user_identifier}/widget_urls",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'widget_url' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Accept-Version: <accept-version>",
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://int-api.mx.com/users/{user_identifier}/widget_urls"

	payload := strings.NewReader("{\n  \"widget_url\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept-Version", "<accept-version>")
	req.Header.Add("Authorization", "Basic <encoded-value>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://int-api.mx.com/users/{user_identifier}/widget_urls")
  .header("Accept-Version", "<accept-version>")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"widget_url\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://int-api.mx.com/users/{user_identifier}/widget_urls")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept-Version"] = '<accept-version>'
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"widget_url\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "widget_url": {
    "type": "connect_widget",
    "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
    "user_id": "u-1234"
  }
}

POST

users

{user_identifier}

widget_urls

Request widget URL

curl --request POST \
  --url https://int-api.mx.com/users/{user_identifier}/widget_urls \
  --header 'Accept-Version: <accept-version>' \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "widget_url": {}
}
'

import requests

url = "https://int-api.mx.com/users/{user_identifier}/widget_urls"

payload = { "widget_url": {} }
headers = {
    "Accept-Version": "<accept-version>",
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Accept-Version': '<accept-version>',
    Authorization: 'Basic <encoded-value>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({widget_url: {}})
};

fetch('https://int-api.mx.com/users/{user_identifier}/widget_urls', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://int-api.mx.com/users/{user_identifier}/widget_urls",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'widget_url' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Accept-Version: <accept-version>",
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://int-api.mx.com/users/{user_identifier}/widget_urls"

	payload := strings.NewReader("{\n  \"widget_url\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept-Version", "<accept-version>")
	req.Header.Add("Authorization", "Basic <encoded-value>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://int-api.mx.com/users/{user_identifier}/widget_urls")
  .header("Accept-Version", "<accept-version>")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"widget_url\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://int-api.mx.com/users/{user_identifier}/widget_urls")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept-Version"] = '<accept-version>'
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"widget_url\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "widget_url": {
    "type": "connect_widget",
    "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
    "user_id": "u-1234"
  }
}

Get an embeddable URL for integrating a widget into your website or app. The URL expires after ten minutes or upon first use, whichever occurs first. You’ll need to obtain a new URL each time the page loads or reloads. Include the widget_type in the request body to specify which widget you want to embed—the Connect Widget, a Personal Financial Management widget, or an Insights widget. Some request parameters are specific to certain widget types. To embed the Connect Widget, set widget_type to connect_widget. For a full list of available widget types, see Widget Types.

Authorizations

Authorization

string

header

required

To authenticate with the Platform API, include your Base64-encoded client_id and api_key in the Authorization header of every request: -H 'Authorization: Basic BASE_64_ENCODING_OF{client_id:api_key}'

Headers

Accept-Version

string

default:v20250224

required

MX Platform API version.

Example:

"v20250224"

Accept-Language

string

The desired language of the widget.

X-CALLBACK-PAYLOAD

string

The base64 encoded string defined in this header will be returned in the Member and Member Data Updated webhooks. This allows you to trace user interactions and workflows initiated externally and internally in the MX Platform. Max 1024 characters.

Path Parameters

user_identifier

string

required

Use either the user id you defined or the MX-defined user guid. See MX-Defined GUIDs vs IDs Defined by You.

Body

application/json

The widget_url configuration options.

Hide child attributes

This determines which widget URL you'll receive.

See Widget Types for a list of potential values. Additional request parameters may only apply to some widget types.

Example:

"connect_widget"

Only use this option if the widget_type is set to connect_widget.

This determines the redirect destination at the end of OAuth when used with is_mobile_webview: true or oauth_referral_source: 'APP'.

Example:

"https://{yoursite.com}"

This option can be passed to any widget_type but will not affect legacy PFM widgets.

Load the widget with the specified color_scheme; options are light, dark, and browser (respects user's browser setting). Defaults to light.

Available options:

light,

browser,

dark

Example:

"light"

Only use this option if the widget_type is set to connect_widget.

Load the widget into the credential view for the specified institution.

Example:

"mx_bank"

Only use this option if the widget_type is set to connect_widget.

Load the widget into the credential view for the specified institution.

Example:

"INS-f1a3285d-e855-b61f-6aa7-8ae575c0e0e9"

Only use this option if the widget_type is set to connect_widget.

Load the widget into a specific member that contains an error or requires multifactor authentication. The widget will determine the best view to load based on the member's current state.

This option takes precedence over current_institution_code and current_institution_guid.

Example:

"MBR-7c6f361b-e582-15b6-60c0-358f12466b4b"

Only use this option if the widget_type is set to connect_widget. This loads the Connect Widget to whichever step the microdeposit process is currently in, which may be the verify amounts step, an error state, and so on. This field is required if attempting to load a specific microdeposit for end users to enter amounts.

Example:

"MIC-1234567890"

Contains a products array that specifies the products you want to aggregate.

Hide child attributes

Contains the products you want to aggregate upon a successful connection. For accepted products, see Defining Products.

Available options:

account_verification,

identity_verification,

transactions,

transaction_history,

statements,

investments,

rewards

Example:

{
  "products": ["transactions", "statements", "investments"]
}

Enables widget-specific behavior.

Hide child attributes

Only use this option if the widget_type is set to spending_widget. When used with the Legacy Spending Widget, used to filter by account. Contains an account_guid (string) optional param.

Example:

"ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1"

Only use this option if the widget_type is set to spending_widget. When used with the Legacy Spending widget, used to filter by date range. Set the date_range using start_date (string) and end_date (string).

Hide child attributes

The start date of the range in YYYY-MM-DD format.

Example:

"2023-01-01"

The end date of the range in YYYY-MM-DD format.

Example:

"2023-12-31"

Only use this option if the widget_type is set to actionable_integration_widget. Launches a deep link integration. Valid value is direct-deposit.

Example:

"direct-deposit"

When used with the Cash Flow, Settings, or Money Dashboard widget, sets the widget's default view. Valid value for Cash Flow or Money Dashboard Widgets is manage_income. Valid values for the Notifications section of the Settings Widget (notifications_settings_widget) are accounts, budgets, or insights.

Example:

"manage_income"

Only use this option if the widget_type is set to master_widget. Launches a specific view in the Master Widget. Valid values are accounts, budgets, cash_flow, debts, finstrong, goals, insights, investments, networth, recurringtransactions, spending, transactions, and trends.

Example:

"budgets"

Only use this option if the widget_type is set to connect_widget. This determines whether background aggregation is enabled or disabled for the member created by the Connect Widget. Defaults to false in aggregation mode and true in verification mode. A global default for all members can be set by reaching out to MX.

Example:

false

Only use this option if the widget_type is set to connect_widget.

Requires one of the following parameters: current_institution_code, current_institution_guid, or current_member_guid.

When set to true, navigating back to the search step triggers the Back to Search event. You must listen for this event and close the widget to avoid trapping the user in the search flow.

Example:

false

Only use this option if the widget_type is set to connect_widget. This indicates whether OAuth app2app behavior is enabled for institutions that support it. Defaults to true. When set to false, the widget will not direct the end user to the institution's mobile application. This setting is not persistent. This setting currently only affects Chase institutions.

Example:

false

Use data_request.products instead to set your products.

Only use this option if the widget_type is set to connect_widget. This determines whether account owner identification data (AOI, previously called "identity verification") aggregates after the data that's specified by the mode finishes aggregating. Defaults to false. This can be set in either aggregation or verification mode. Setting this to true will produce the following behaviors:

The widget will only search for and display institutions that support the data the mode (aggregation or verification) is aggregating and AOI.
The member connected postMessage event will not be sent until both aggregations are complete.

Example:

false

Use data_request.products instead to set your products.

Only use this option if the widget_type is set to connect_widget. This determines whether transaction data are retrieved. Defaults to true in aggregation mode and false in verification mode. This can be set in either aggregation or verification mode. This option does not affect future foreground or background aggregations.

Example:

true

Only use this option if the widget_type is set to pulse_widget. Set this to the insight guid you want to appear at the top of the insights feed.

Example:

null

An array of strings that filters institutions in the widget by the specified country code. Acceptable codes include US, CA, and MX (Mexico).

Example:

["US", "CA"]

This option is for every widget_type. This configures the widget to render in a mobile WebView. JavaScript event postMessages are replaced with URL updates.

Example:

false

Only use this option if the widget_type is set to micro_pulse_carousel_widget. Set this to a unique value for each instance of the Micro Insights Widget. This lets us collect unique data for each instance of the widget.

Example:

null

Sets the language of the widget.

If you're requesting the Connect or Connections Widgets, you must use the Accept-Language header.

Example:

"fr-CA"

Use data_request.products instead to set your products.

Only use this option if the widget_type is set to connect_widget. mode is the most important option for the Connect Widget. This determines what kind of process Connect will run, which affects how you should set many other options. Defaults to aggregation. aggregation mode retrieves account and transaction data; in other words, this runs a standard aggregation. verification mode retrieves account numbers and routing/transit numbers; in other words, it runs an Instant Account Verification (IAV). By default, verification mode does not retrieve transaction data; this default can be modified with secondary options. By default, background aggregation is disabled for all members created in verification mode; this default can be modified with secondary options.

Example:

"aggregation"

Only use this option if the widget_type is set to connect_widget. This determines how MX will respond to the result of an OAuth flow. When set to APP, MX will redirect to the URI specified in the ui_message_webview_url_scheme. When set to BROWSER, MX will send a postMessage but not redirect. If is_mobile_webview is true, this defaults to APP. If false, it defaults to BROWSER.

Example:

"BROWSER"

Contains fields to customize the appearance of a widget.

Hide child attributes

Sets the widget's font. Pass any Google font to change it.

Example:

"Roboto"

This option is for all widget_types. This determines which version of postMessage events are triggered. Defaults to 4. All new implementations must use version 4. Prior versions are deprecated.

Example:

4

Only use this option if the widget_type is set to connect_widget. This is a client-defined scheme used in OAuth redirects in WebViews; also used in URL updates when these replace postMessages in WebViews. Defaults to mx.

Only use this option if the widget_type is set to connect_widget. Load the widget into a view that allows them to update the current member. Optionally used with current_member_guid. This option should be used sparingly. The best practice is to use current_member_guid and let the widget resolve the issue.

Example:

false

The use case that will be associated with any members created through the widget. Valid values are PFM and/or MONEY_MOVEMENT. This is required if you've met with MX and have opted in to using this field.

Available options:

MONEY_MOVEMENT,

PFM

Example:

["PFM"]

Response

200 - application/json

Hide child attributes

This determines which widget URL you'll receive. Additional request parameters may only apply to some widget types.

Available options:

accounts_widget,

mini_accounts_widget,

actionable_integration_widget,

budgets_widget,

mini_budgets_widget,

cash_flow_widget,

mini_cash_flow_widget,

connect_widget,

connections_widget,

debts_widget,

finstrong_widget,

mini_finstrong_widget,

goals_widget,

help_widget,

master_widget,

money_dashboard_widget,

net_worth_widget,

mini_net_worth_widget,

notifications_settings_widget,

recurringtransactions_widget,

mini_recurringtransactions_widget,

settings_widget,

spending_widget,

mini_spending_widget,

spending_plan_widget,

mini_spending_plan_widget,

transaction_rules_widget,

transactions_widget,

trends_widget,

mini_trends_widget

Example:

"connect_widget"

The URL for accessing the widget.

Example:

"https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5"

The unique partner-defined identifier for the user.

Example:

"u-1234"