Merge accounts

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

import requests

url = "https://int-api.mx.com/users/{user_guid}/accounts/merge"

payload = {}
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({})
};

fetch('https://int-api.mx.com/users/{user_guid}/accounts/merge', 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}/accounts/merge",
  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 => [
    "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_guid}/accounts/merge"

	payload := strings.NewReader("{}")

	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_guid}/accounts/merge")
  .header("Accept-Version", "<accept-version>")
  .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}/accounts/merge")

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 = "{}"

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

{
  "account": {
    "account_number": "3331261",
    "account_ownership": "INDIVIDUAL",
    "annuity_policy_to_date": "2025-12-31",
    "annuity_provider": "Metlife",
    "annuity_term_year": 30,
    "apr": 1,
    "apy": 2.35,
    "available_balance": 1000,
    "available_credit": 4000,
    "balance": 1000,
    "cash_balance": 2500,
    "cash_surrender_value": 1000,
    "created_at": "2025-02-13T18:08:00+00:00",
    "credit_limit": 5000,
    "currency_code": "USD",
    "day_payment_is_due": 14,
    "death_benefit": 1000,
    "federal_insurance_status": "INSURED",
    "guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
    "id": "1040434698",
    "imported_at": "2015-10-13T17:57:37.000Z",
    "interest_rate": 3.25,
    "institution_code": "3af3685e-05d9-7060-359f-008d0755e993",
    "insured_name": "Tommy Shelby",
    "is_closed": false,
    "is_hidden": false,
    "is_manual": false,
    "last_payment": 100,
    "last_payment_at": "2023-07-25T17:14:46Z",
    "loan_amount": 1000,
    "margin_balance": 1000,
    "matures_on": "2015-10-13T17:57:37.000Z",
    "member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "member_id": "member123",
    "member_is_managed_by_user": false,
    "metadata": "some metadata",
    "minimum_balance": 100,
    "minimum_payment": 10,
    "name": "Test account 2",
    "nickname": "My Checking",
    "original_balance": 10,
    "pay_out_amount": 10,
    "payment_due_at": "2015-10-13T17:57:37.000Z",
    "payoff_balance": 10,
    "premium_amount": 1,
    "property_type": "VEHICLE",
    "routing_number": "68899990000000",
    "started_on": "2025-10-13T17:57:37.000Z",
    "statement_balance": 1000.5,
    "subtype": "MONEY_MARKET",
    "today_ugl_amount": 1000.5,
    "today_ugl_percentage": 6.9,
    "total_account_value": 1,
    "total_account_value_ugl": 1,
    "type": "CHECKING",
    "updated_at": "2025-02-13T18:09:00+00:00",
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54",
    "user_id": "u-1234"
  }
}

POST

users

{user_guid}

accounts

merge

Merge accounts

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

import requests

url = "https://int-api.mx.com/users/{user_guid}/accounts/merge"

payload = {}
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({})
};

fetch('https://int-api.mx.com/users/{user_guid}/accounts/merge', 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}/accounts/merge",
  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 => [
    "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_guid}/accounts/merge"

	payload := strings.NewReader("{}")

	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_guid}/accounts/merge")
  .header("Accept-Version", "<accept-version>")
  .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}/accounts/merge")

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 = "{}"

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

{
  "account": {
    "account_number": "3331261",
    "account_ownership": "INDIVIDUAL",
    "annuity_policy_to_date": "2025-12-31",
    "annuity_provider": "Metlife",
    "annuity_term_year": 30,
    "apr": 1,
    "apy": 2.35,
    "available_balance": 1000,
    "available_credit": 4000,
    "balance": 1000,
    "cash_balance": 2500,
    "cash_surrender_value": 1000,
    "created_at": "2025-02-13T18:08:00+00:00",
    "credit_limit": 5000,
    "currency_code": "USD",
    "day_payment_is_due": 14,
    "death_benefit": 1000,
    "federal_insurance_status": "INSURED",
    "guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
    "id": "1040434698",
    "imported_at": "2015-10-13T17:57:37.000Z",
    "interest_rate": 3.25,
    "institution_code": "3af3685e-05d9-7060-359f-008d0755e993",
    "insured_name": "Tommy Shelby",
    "is_closed": false,
    "is_hidden": false,
    "is_manual": false,
    "last_payment": 100,
    "last_payment_at": "2023-07-25T17:14:46Z",
    "loan_amount": 1000,
    "margin_balance": 1000,
    "matures_on": "2015-10-13T17:57:37.000Z",
    "member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "member_id": "member123",
    "member_is_managed_by_user": false,
    "metadata": "some metadata",
    "minimum_balance": 100,
    "minimum_payment": 10,
    "name": "Test account 2",
    "nickname": "My Checking",
    "original_balance": 10,
    "pay_out_amount": 10,
    "payment_due_at": "2015-10-13T17:57:37.000Z",
    "payoff_balance": 10,
    "premium_amount": 1,
    "property_type": "VEHICLE",
    "routing_number": "68899990000000",
    "started_on": "2025-10-13T17:57:37.000Z",
    "statement_balance": 1000.5,
    "subtype": "MONEY_MARKET",
    "today_ugl_amount": 1000.5,
    "today_ugl_percentage": 6.9,
    "total_account_value": 1,
    "total_account_value_ugl": 1,
    "type": "CHECKING",
    "updated_at": "2025-02-13T18:09:00+00:00",
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54",
    "user_id": "u-1234"
  }
}

Merge two or more financial accounts that an end user has identified as duplicates. Provide at least two account GUIDs belonging to the same user.

The response will return a single consolidated account. Any other accounts you provided that were not included in the response will be deleted. This is a destructive action and can’t be undone.

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"

Path Parameters

user_guid

string

required

The unique identifier for a user, beginning with the prefix USR-.

Body

application/json

account

object

Hide child attributes

account.account_guids

string[]

required

A list of account GUIDs to merge. Must include at least two GUIDs belonging to the same user.

Example:

[
  "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
  "ACT-e1b1e9e7-9436-4720-a1b5-f02373433bd4"
]

Response

200 - application/json

account

object

Hide child attributes

account.account_number

string | null

The account number associated with the account. This will typically be a masked or partial account number.

Example:

"3331261"

account.account_ownership

enum<string> | null

The type of ownership associated with the account. NULL is returned if not received in the data feed.

Available options:

UNKNOWN,

INDIVIDUAL,

JOINT,

MULTIPLE

Example:

"INDIVIDUAL"

account.annuity_policy_to_date

string | null

The date until which the policy is in effect.

Example:

"2025-12-31"

account.annuity_provider

string | null

The provider of the insurance policy.

Example:

"Metlife"

account.annuity_term_year

integer | null

The effective duration of an insurance policy (one year, five years, etc.).

Example:

30

account.apr

number | null

The annual percentage rate associated with the account.

Example:

1

account.apy

number | null

The annual percentage yield associated with the account.

Example:

2.35

account.available_balance

number | null

The balance that is available for use in asset accounts like checking and savings.

PENDING transactions are typically (not always) taken into account with the available balance.

available_balance will usually be a positive value for all account types, determined in the same way as the balance field.

Example:

1000

account.available_credit

number | null

The amount of credit available for use in liability accounts like credit cards and lines of credit.

PENDING transactions are typically (not always) taken into account with available credit.

available_credit will usually be a positive value for all account types, determined in the same way as the balance field.

Example:

4000

account.balance

number | null

The current balance of the account.

PENDING transactions are typically not taken into account with the current balance, but this may not always be the case.

The balance will usually be a positive value for all account types. 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:

1000

account.cash_balance

number | null

The cash balance of the account.

Example:

2500

account.cash_surrender_value

number | null

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:

1000

account.created_at

string

The date and time the account was created, represented in ISO 8601 format with a timestamp.

Example:

"2025-02-13T18:08:00+00:00"

account.credit_limit

number | null

The credit limit associated with the account.

Example:

5000

account.currency_code

string | null

The three-character ISO 4217 currency code, for example, USD.

Example:

"USD"

account.day_payment_is_due

integer | null

The day of the month the payment is due. For example, the 14th is passed as 14.

Example:

14

account.death_benefit

integer | null

The amount paid to the beneficiary of the account upon death of the account owner.

Example:

1000

account.federal_insurance_status

enum<string> | null

The federal insurance status of the account. Indicates whether the account is insured by the FDIC (banks) or NCUA (credit unions).

Returns an integer (UNKNOWN_INSURED = 0, INSURED = 1, NOT_INSURED = 2).

Available options:

UNKNOWN_INSURED,

INSURED,

NOT_INSURED

Example:

"INSURED"

account.guid

string | null

Unique identifier for the account. Defined by MX.

Example:

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

account.id

string | null

The unique partner-defined identifier for the account.

Example:

"1040434698"

account.imported_at

string | null

The date and time at which the account was last successfully aggregated and received data.

Example:

"2015-10-13T17:57:37.000Z"

account.interest_rate

number | null

The interest rate associated with the account.

Example:

3.25

account.institution_code

string | null

The code identifying a financial institution.

Example:

"3af3685e-05d9-7060-359f-008d0755e993"

account.insured_name

string | null

The name of the insured person.

Example:

"Tommy Shelby"

account.is_closed

boolean

Indicates whether an account has been closed. Closed accounts will no longer update balance or transaction information.

Example:

false

account.is_hidden

boolean | null

Indicates whether the account is hidden. Hidden accounts can still have an active balance and receive transactions. Defaults to false.

Example:

false

account.is_manual

boolean | null

Indicates whether the transaction was manually created or belongs to a manual account.

Example:

false

account.last_payment

number | null

The amount of the most recent payment on the account.

Example:

100

account.last_payment_at

string | null

The date and time when the last payment was made, represented in ISO 8601 format with a timestamp.

Example:

"2023-07-25T17:14:46Z"

account.loan_amount

number | null

The amount of the loan associated with the account.

Example:

1000

account.margin_balance

number | null

Represents the amount of debt the investor owes to the broker for the use of margin. It can be positive or negative, depending on the performance of the investments made with the borrowed funds. A positive margin balance indicates that the securities purchased on margin have increased in value, whereas a negative margin balance signifies that the securities have decreased in value.

Example:

1000

account.matures_on

string | null

The date on which the account matures.

Example:

"2015-10-13T17:57:37.000Z"

account.member_guid

string | null

The unique identifier for the member. Defined by MX.

Example:

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

account.member_id

string | null

The unique, partner-defined, identifier for the member associated with this account.

Example:

"member123"

account.member_is_managed_by_user

boolean | null

This indicates whether the member is managed by the user or the MX partner. Members created with the managed member feature will have this field set to false.

Example:

false

account.metadata

string | null

Additional information you stored about the account.

Example:

"some metadata"

account.minimum_balance

number | null

The minimum balance associated with the account.

Example:

100

account.minimum_payment

number | null

The minimum payment required for an account. This can apply to any debt account.

Example:

10

account.name

string | null

The human-readable name for the resource.

Example:

"Test account 2"

account.nickname

string | null

An alternate name for the account.

Example:

"My Checking"

account.original_balance

number | null

The original balance associated with the account. This will always be positive.

Example:

10

account.pay_out_amount

number | null

The amount paid out to the insured individual or beneficiary under the conditions of the insurance policy.

Example:

10

account.payment_due_at

string | null

The date and time at which the next payment is due on the account.

Example:

"2015-10-13T17:57:37.000Z"

account.payoff_balance

number | null

The payoff balance for a debt account. This will normally be a positive number.

Example:

10

account.premium_amount

number | null

The insurance policy's premium amount.

Example:

1

account.property_type

enum<string> | null

Subtype if the account type is PROPERTY. This field should be ignored unless the type is set to PROPERTY.

Available options:

APPLIANCES,

ART,

COMPUTER,

ELECTRONICS,

FURNITURE,

JEWELRY,

MISCELLANEOUS,

REAL_ESTATE,

SPORTS_EQUIPMENT,

VEHICLE

Example:

"VEHICLE"

account.routing_number

string | null

The routing number for the account.

Example:

"68899990000000"

account.started_on

string | null

The date on which the loan from a debt account started.

Example:

"2025-10-13T17:57:37.000Z"

account.statement_balance

number | null

The balance at the end of the account's last statement period.

Example:

1000.5

account.subtype

string | null

The account's subtype, for example, PLAN_401_K, MONEY_MARKET, or HOME_EQUITY. Each subtype belongs to an account type. For a full list of account subtypes and types, see Accounts.

Example:

"MONEY_MARKET"

account.today_ugl_amount

number | null

The unrealized gain/loss amount for the day for the account.

Example:

1000.5

account.today_ugl_percentage

number | null

The unrealized gain/loss percentage for the date for the account.

Example:

6.9

account.total_account_value

number | null

The sum of the long and short positions, the sweep account and/or cash balance, and any margin debt associated with a particular account. This amount includes the market value of all positions held in the account and is reduced by any debit balance and the amount of short options positions that are "in the money". This may sum to a negative value, and it does not represent an account balance.

Example:

1

account.total_account_value_ugl

number | null

The unrealized gains and losses represent the amount the account has gained or lost based on the purchase price. This is calculated by subtracting the purchase price from the current market value. It does not affect the account until the positions are sold and "realized". This may sum to a negative value, and it does not represent an account balance.

Example:

1

account.type

enum<string> | null

The type of account. Some account types may include subtypes.

Available options:

ANY,

CASH,

CHECKING,

CHECKING_LINE_OF_CREDIT,

CREDIT_CARD,

LOAN,

LINE_OF_CREDIT,

SAVINGS,

INVESTMENT,

MORTGAGE,

INSURANCE,

PREPAID,

PROPERTY

Example:

"CHECKING"

account.updated_at

string | null

The date and time the resource was last updated in ISO 8601 format with a timestamp.

For categories, this field will always be null when is_default is true.

Example:

"2025-02-13T18:09:00+00:00"

account.user_guid

string | null

The unique identifier for the user. Defined by MX.

Example:

"USR-fa7537f3-48aa-a683-a02a-b18940482f54"

account.user_id

string | null

The unique partner-defined identifier for the user.

Example:

"u-1234"