curl --request POST \
--url https://int-api.mx.com/users/{user_guid}/widget_urls \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '{}'import requests
url = "https://int-api.mx.com/users/{user_guid}/widget_urls"
payload = {}
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({})
};
fetch('https://int-api.mx.com/users/{user_guid}/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_guid}/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([
]),
CURLOPT_HTTPHEADER => [
"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_guid}/widget_urls"
payload := strings.NewReader("{}")
req, _ := http.NewRequest("POST", url, payload)
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_guid}/widget_urls")
.header("Authorization", "Basic <encoded-value>")
.header("Content-Type", "application/json")
.body("{}")
.asString();require 'uri'
require 'net/http'
url = URI("https://int-api.mx.com/users/{user_guid}/widget_urls")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{}"
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-jeff-201709221210"
}
}Request widget URL
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.
curl --request POST \
--url https://int-api.mx.com/users/{user_guid}/widget_urls \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '{}'import requests
url = "https://int-api.mx.com/users/{user_guid}/widget_urls"
payload = {}
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({})
};
fetch('https://int-api.mx.com/users/{user_guid}/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_guid}/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([
]),
CURLOPT_HTTPHEADER => [
"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_guid}/widget_urls"
payload := strings.NewReader("{}")
req, _ := http.NewRequest("POST", url, payload)
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_guid}/widget_urls")
.header("Authorization", "Basic <encoded-value>")
.header("Content-Type", "application/json")
.body("{}")
.asString();require 'uri'
require 'net/http'
url = URI("https://int-api.mx.com/users/{user_guid}/widget_urls")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{}"
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-jeff-201709221210"
}
}Authorizations
Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.
Headers
The desired language of the widget.
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
The unique identifier for a user, beginning with the prefix USR-.
Body
The widget url configuration options.
Hide child attributes
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.
"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'.
"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, browser (respects user's browser setting), and dark. Defaults to light.
"light"
To use this parameter, you must also set use_cases in the same request. If connections_use_case_filter is set to true, the Connections Widget will only show connections (members) with the use_cases you set in the same request. For some examples, see Filter Connections.
false
Only use this option if the widget_type is set to connect_widget. Load the widget into the credential view for the specified institution.
"mxbank"
Only use this option if the widget_type is set to connect_widget. Load the widget into the credential view for the specified institution.
"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. current_member_guid takes precedence over current_institution_code and current_institution_guid.
"MBR-7c6f361b-e582-15b6-60c0-358f12466b4b"
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.
false
Only use this option if the widget_type is set to connect_widget. This determines whether the institution search is displayed within the Connect Widget. This option must be used with current_institution_code, current_instituion_guid, or current_member_guid. When set to true, the institution search feature will be disabled and end users will not be able to navigate to it. Defaults to false. If you set disable_institution_search to true, you must also listen for the backToSearch event to intercept the user from navigating back to search during the flow. Don't listen for any Primary Action postMessages when you disable search. All buttons that will take a user to the search institution page are still displayed in the Connect Widget experience and your user can still select them. This may trigger during several steps in the Connect Widget flow, such as Connected, MDV/Microdeposits Verified, Login Error, and Credentials/OAuth (back button).
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.
false
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(aggregationorverification) is aggregating and AOI. - The member connected postMessage event will not be sent until both aggregations are complete.
false
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.
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.
null
An array of strings that filters institutions in the widget by the specified country code. Acceptable codes include US, CA, and MX (Mexico).
["US", "CA"]
This option is for all widget_types. This configures the widget to render in a mobile WebView. JavaScript event postMessages are replaced with URL updates.
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.
null
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.
"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.
"BROWSER"
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.
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.
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, opted in to using this field, and are requesting a widget with a widget_type of connect_widget or connections_widget.
MONEY_MOVEMENT, PFM ["PFM"]
Response
OK
Hide child attributes
Hide child attributes
"connect_widget"
"https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5"
"U-jeff-201709221210"