Transfer Configuration

The transfer field on a createAccount journey adds a 3rd-party holdings transfer step — moving assets from another institution into the new account. When set, the customer authorizes and configures the transfer as part of account opening. Set transfer to null to omit the step entirely.

enforce — "required" means the customer must complete the transfer step; "optional" means they can skip it.

accounts — each entry describes one source account at the custodian. accountNumber: null means the customer enters it; a provided value is readonly. When accountNumber is set, sourceAccountType must be a single-entry array.

Output fields (defaultUnitsOutput, balanceOutput, untransferableUnitsOutput) each accept an array of either a single entry — which locks the behavior — or multiple entries, which let the customer choose:

• cash — sell and transfer as cash
• units — transfer as fund units
• ignore — leave on the source account

instruments — list specific holdings to handle explicitly. Anything not in this list falls back to defaultUnitsOutput.

allowInstrumentSelection — when true, the customer can add instruments to the transfer in addition to those listed.

The customer enters the account number. One specific fund is transferred as units in full. All other holdings and the cash balance are left on the source account. Account is not closed.

{
  "enforce": "required",
  "transfers": [
    {
      "custodian": "<institutionId>",
      "accounts": [
        {
          "accountNumber": null,
          "sourceAccountType": ["isk"],
          "required": true,
          "allowInstrumentSelection": false,
          "defaultUnitsOutput": ["ignore"],
          "balanceOutput": ["ignore"],
          "closeAccountAndSavingsplans": false,
          "untransferableUnitsOutput": ["ignore"],
          "instruments": [
            {
              "id": "<fundId>",
              "unitType": ["full"],
              "outputType": ["units"]
            }
          ]
        }
      ]
    }
  ]
}

Account number is known and readonly. All fund units transfer as units, the cash balance transfers as cash, and the source account and savings plans are closed after completion. Any untransferable units are sold to cash.

{
  "enforce": "required",
  "transfers": [
    {
      "custodian": "<institutionId>",
      "accounts": [
        {
          "accountNumber": "5311145347",
          "sourceAccountType": ["isk"],
          "required": true,
          "allowInstrumentSelection": false,
          "untransferableUnitsOutput": ["cash"],
          "defaultUnitsOutput": ["units"],
          "balanceOutput": ["cash"],
          "closeAccountAndSavingsplans": true
        }
      ]
    }
  ]
}

The transfer step is optional and the customer controls all output choices: how to handle each holding type, the cash balance, and untransferable units. They can also select specific instruments to transfer. closeAccountAndSavingsplans: null lets the customer decide. Additional custodians can be appended to the transfers array alongside the one shown.

{
  "enforce": "optional",
  "transfers": [
    {
      "custodian": "<institutionId>",
      "accounts": [
        {
          "accountNumber": "1234567890",
          "sourceAccountType": ["isk"],
          "required": false,
          "allowInstrumentSelection": true,
          "untransferableUnitsOutput": ["cash", "ignore"],
          "defaultUnitsOutput": ["cash", "units", "ignore"],
          "balanceOutput": ["cash", "ignore"],
          "closeAccountAndSavingsplans": null
        }
      ]
    }
  ]
}