Add Investments Move to your app
Use Investments Move to streamline brokerage-to-brokerage account transfers
In this guide, we'll start from scratch and walk through how to use Investments Move to get the data required to set up an ACATS transfer. If you are already familiar with using Plaid and are set up to make calls to the Plaid API, make sure to initialize Link with the investments_auth
product; you can then skip ahead to Fetching Investments Move data.
Get Plaid API keys and complete application profile
If you don't already have one, you'll need to create a Plaid developer account. After creating your account, you can find your API keys under the Team Settings menu on the Plaid Dashboard.
You will also need to complete your application profile on the Dashboard. The information in your profile will be shared with users of your application when they manage their connection on the Plaid Portal. Your application profile must be completed before connecting to certain institutions in Production.
Install and initialize Plaid libraries
You can use our official server-side client libraries to connect to the Plaid API from your application:
1// Install via npm2npm install --save plaid
After you've installed Plaid's client libraries, you can initialize them by passing in your client_id
, secret
, and the environment you wish to connect to (Sandbox or Production). This will make sure the client libraries pass along your client_id
and secret
with each request, and you won't need to explicitly include them in any other calls.
1// Using Express2const express = require('express');3const app = express();4app.use(express.json());56const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');78const configuration = new Configuration({9 basePath: PlaidEnvironments.sandbox,10 baseOptions: {11 headers: {12 'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,13 'PLAID-SECRET': process.env.PLAID_SECRET,14 },15 },16});1718const client = new PlaidApi(configuration);
Create an Item in Link
Plaid Link is a drop-in module that provides a secure, elegant authentication flow for each institution that Plaid supports. Link makes it secure and easy for users to connect their bank accounts to Plaid. Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the Link documentation.
Using Link, we will create a Plaid Item, which is a Plaid term for a login at a financial institution. An Item is not the same as a financial institution account, although every account will be associated with an Item. For example, if a user has one login at their bank that allows them to access both their checking account and their savings account, a single Item would be associated with both of those accounts.
First, on the client side of your application, you'll need to set up and configure Link. If you want to customize Link's look and feel, you can do so from the Dashboard.
When initializing Link, you will need to specify the products you will be using in the product array.
Create a link_token
1app.post('/api/create_link_token', async function (request, response) {2 // Get the client_user_id by searching for the current user3 const user = await User.find(...);4 const clientUserId = user.id;5 const request = {6 user: {7 // This should correspond to a unique id for the current user.8 client_user_id: clientUserId,9 },10 client_name: 'Plaid Test App',11 products: ['investments_auth'],12 language: 'en',13 webhook: 'https://webhook.example.com',14 redirect_uri: 'https://domainname.com/oauth-page.html',15 country_codes: ['US'],16 };17 try {18 const createTokenResponse = await client.linkTokenCreate(request);19 response.json(createTokenResponse.data);20 } catch (error) {21 // handle error22 }23});
When using Investments Move, you can also configure options in the /link/token/create
call to allow more brokerage accounts to be added, with the tradeoff that Plaid may not be able to verify all of the information. For details, see Fallback flows.
Install Link dependency
1<head>2 <title>Connect a bank</title>3 <script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>4</head>
Configure the client-side Link handler
1const linkHandler = Plaid.create({2 token: (await $.post('/create_link_token')).link_token,3 onSuccess: (public_token, metadata) => {4 // Send the public_token to your app server.5 $.post('/exchange_public_token', {6 public_token: public_token,7 });8 },9 onExit: (err, metadata) => {10 // Optionally capture when your user exited the Link flow.11 // Storing this information can be helpful for support.12 },13 onEvent: (eventName, metadata) => {14 // Optionally capture Link flow events, streamed through15 // this callback as your users connect an Item to Plaid.16 },17});1819linkHandler.open();
Get a persistent access_token
Next, on the server side, we need to exchange our public_token
for an access_token
and item_id
. The access_token
will allow us to make authenticated calls to the Plaid API. Doing so is as easy as calling the /item/public_token/exchange
endpoint from our server-side handler. We'll use the client library we configured earlier to make the API call.
Save the access_token
and item_id
in a secure datastore, as they’re used to access Item
data and identify webhooks
, respectively. The access_token
will remain valid unless you actively chose to expire it via rotation or remove the corresponding Item via /item/remove
. The access_token
should be stored securely, and never in client-side code. A public_token
is a one-time use token with a lifetime of 30 minutes, so there is no need to store it.
1app.post('/api/exchange_public_token', async function (2 request,3 response,4 next,5) {6 const publicToken = request.body.public_token;7 try {8 const response = await client.itemPublicTokenExchange({9 public_token: publicToken,10 });1112 // These values should be saved to a persistent database and13 // associated with the currently signed-in user14 const accessToken = response.data.access_token;15 const itemID = response.data.item_id;1617 res.json({ public_token_exchange: 'complete' });18 } catch (error) {19 // handle error20 }21});
Fetching Investments Move data
Now that the authentication step is out of the way, we can begin using authenticated endpoints from the Plaid API. For more detailed information on the schema for account information returned, see /investments/auth/get
.
1const request: InvestmentsAuthGetRequest = {2 access_token: accessToken,3};4try {5 const response = await plaidClient.investmentsAuthGet(request);6 const investmentsAuthData = response.data;7} catch (error) {8 // handle error9}
The results of the /investments/auth/get
call return the information you need to submit an ACATS transfer, using verified data derived directly from the brokerage. Example response data is below. For more details on the schema of data returned, see the API Reference.
1{2 "accounts": [3 {4 "account_id": "31qEA6LPwGumkA4Z5mGbfyGwr4mL6nSZlQqpZ",5 "balances": {6 "available": 43200,7 "current": 43200,8 "iso_currency_code": "USD",9 "limit": null,10 "unofficial_currency_code": null11 },12 "mask": "4444",13 "name": "Plaid Money Market",14 "official_name": "Plaid Platinum Standard 1.85% Interest Money Market",15 "subtype": "money market",16 "type": "depository"17 },18 {19 "account_id": "xlP8npRxwgCj48LQbjxWipkeL3gbyXf64knoy",20 "balances": {21 "available": null,22 "current": 320.76,23 "iso_currency_code": "USD",24 "limit": null,25 "unofficial_currency_code": null26 },27 "mask": "5555",28 "name": "Plaid IRA",29 "official_name": null,30 "subtype": "ira",31 "type": "investment"32 }33 ],34 "holdings": [35 {36 "account_id": "xlP8npRxwgCj48LQbjxWipkeL3gbyXf64knoy",37 "cost_basis": 1,38 "institution_price": 1,39 "institution_price_as_of": "2021-05-25",40 "institution_price_datetime": null,41 "institution_value": 0.01,42 "iso_currency_code": "USD",43 "quantity": 0.01,44 "security_id": "d6ePmbPxgWCWmMVv66q9iPV94n91vMtov5Are",45 "unofficial_currency_code": null,46 "vested_quantity": 1,47 "vested_value": 148 },49 {50 "account_id": "xlP8npRxwgCj48LQbjxWipkeL3gbyXf64knoy",51 "cost_basis": 0.01,52 "institution_price": 0.011,53 "institution_price_as_of": "2021-05-25",54 "institution_price_datetime": null,55 "institution_value": 110,56 "iso_currency_code": "USD",57 "quantity": 10000,58 "security_id": "8E4L9XLl6MudjEpwPAAgivmdZRdBPJuvMPlPb",59 "unofficial_currency_code": null,60 "vested_quantity": null,61 "vested_value": null62 },63 {64 "account_id": "xlP8npRxwgCj48LQbjxWipkeL3gbyXf64knoy",65 "cost_basis": 40,66 "institution_price": 42.15,67 "institution_price_as_of": "2021-05-25",68 "institution_price_datetime": null,69 "institution_value": 210.75,70 "iso_currency_code": "USD",71 "quantity": 5,72 "security_id": "abJamDazkgfvBkVGgnnLUWXoxnomp5up8llg4",73 "unofficial_currency_code": null,74 "vested_quantity": 7,75 "vested_value": 6676 }77 ],78 "item": {79 "available_products": [80 "assets",81 "balance",82 "beacon",83 "cra_base_report",84 "cra_income_insights",85 "signal",86 "identity",87 "identity_match",88 "income",89 "income_verification",90 "investments",91 "processor_identity",92 "recurring_transactions",93 "transactions"94 ],95 "billed_products": [96 "investments_auth"97 ],98 "consent_expiration_time": null,99 "error": null,100 "institution_id": "ins_115616",101 "item_id": "7qBnDwLP3aIZkD7NKZ5ysk5X9xVxDWHg65oD5",102 "products": [103 "investments_auth"104 ],105 "update_type": "background",106 "webhook": "https://www.genericwebhookurl.com/webhook"107 },108 "numbers": {109 "acats": [110 {111 "account": "TR5555",112 "account_id": "xlP8npRxwgCj48LQbjxWipkeL3gbyXf64knoy",113 "dtc_numbers": [114 "1111",115 "2222",116 "3333"117 ]118 }119 ]120 },121 "owners": [122 {123 "account_id": "31qEA6LPwGumkA4Z5mGbfyGwr4mL6nSZlQqpZ",124 "names": [125 "Alberta Bobbeth Charleson"126 ]127 },128 {129 "account_id": "xlP8npRxwgCj48LQbjxWipkeL3gbyXf64knoy",130 "names": [131 "Alberta Bobbeth Charleson"132 ]133 }134 ],135 "request_id": "hPCXou4mm9Qwzzu",136 "securities": [137 {138 "close_price": 0.011,139 "close_price_as_of": null,140 "cusip": null,141 "industry": null,142 "institution_id": null,143 "institution_security_id": null,144 "is_cash_equivalent": false,145 "isin": null,146 "iso_currency_code": "USD",147 "market_identifier_code": null,148 "name": "Nflx Feb 01'18 $355 Call",149 "option_contract": null,150 "proxy_security_id": null,151 "sector": null,152 "security_id": "8E4L9XLl6MudjEpwPAAgivmdZRdBPJuvMPlPb",153 "sedol": null,154 "ticker_symbol": "NFLX180201C00355000",155 "type": "derivative",156 "unofficial_currency_code": null,157 "update_datetime": null158 },159 {160 "close_price": 9.08,161 "close_price_as_of": "2024-09-09",162 "cusip": null,163 "industry": "Investment Trusts or Mutual Funds",164 "institution_id": null,165 "institution_security_id": null,166 "is_cash_equivalent": false,167 "isin": null,168 "iso_currency_code": "USD",169 "market_identifier_code": null,170 "name": "DoubleLine Total Return Bond I",171 "option_contract": null,172 "proxy_security_id": null,173 "sector": "Miscellaneous",174 "security_id": "AE5rBXra1AuZLE34rkvvIyG8918m3wtRzElnJ",175 "sedol": "B5ND9B4",176 "ticker_symbol": "DBLTX",177 "type": "mutual fund",178 "unofficial_currency_code": null,179 "update_datetime": null180 },181 {182 "close_price": 42.15,183 "close_price_as_of": null,184 "cusip": null,185 "industry": null,186 "institution_id": null,187 "institution_security_id": null,188 "is_cash_equivalent": false,189 "isin": null,190 "iso_currency_code": "USD",191 "market_identifier_code": null,192 "name": "iShares Inc MSCI Brazil",193 "option_contract": null,194 "proxy_security_id": null,195 "sector": null,196 "security_id": "abJamDazkgfvBkVGgnnLUWXoxnomp5up8llg4",197 "sedol": null,198 "ticker_symbol": "EWZ",199 "type": "etf",200 "unofficial_currency_code": null,201 "update_datetime": null202 },203 {204 "close_price": 1,205 "close_price_as_of": null,206 "cusip": null,207 "industry": null,208 "institution_id": null,209 "institution_security_id": null,210 "is_cash_equivalent": true,211 "isin": null,212 "iso_currency_code": "USD",213 "market_identifier_code": null,214 "name": "U S Dollar",215 "option_contract": null,216 "proxy_security_id": null,217 "sector": null,218 "security_id": "d6ePmbPxgWCWmMVv66q9iPV94n91vMtov5Are",219 "sedol": null,220 "ticker_symbol": null,221 "type": "cash",222 "unofficial_currency_code": null,223 "update_datetime": null224 }225 ]226}