Depending on applicable regulations or business limitations, specific API requests may not be available for your use.

Create an External Account Transfer

This request allows initiating an incoming Account Transfer, for a specified account number.

Note: If a firm is not eligible for ACAT transfers paperwork will need to be sent to Folio to initiate the transfer. Please see Get Contra Firms for list of firms eligible for ACAT transfers. Not all accounts at a given firm are ACAT eligible and the firm may still require paperwork after attempting an ACAT initiation.


Request URL

Syntax POST /restapi/accounts/{accountnumber}/acatin
Example URL https://api.uat.foliofn.com/restapi/accounts/RB18938005/acatin

Request Data Fields

Field Type Description Required Value
accountNumber String The account number created by Folio REST service. No If null, use the one specified on the URL.
loginId String A unique ID for the member which has been generated when the member is initially created. Yes
cashAmount Double The amount of cash transferred. Only for partial transfer type. No
contraAccountNumber String The account number of the transferred account. Yes
contraAccountType String The type of transferred account. Yes Same as the one referenced by the account number. See Account Types part.
contraFirmName String The name of the firm where the account is transferred from. Yes A valid name as returned by the Get Contra Firms request.
rothFiveYear Integer The Roth Five Year for IRA account type. No Any valid years (4 digits) between 1997 and present.
signatures RestAcatTransferSignature[] Array of account owner(s) signature(s) data. Yes See ACAT Transfer Stock Data Fields part.
signatureImageEncoding String The type of encoding use for the signature(s) data. Yes
  • JPG
  • GIF
  • PNG
  • SVG (preferred)
stocks RestAcatTransferStock[] Array of stock(s) transferred. Only for partial transfer type. No See ACAT Transfer Signature Data Fields part.
transferAllCash Boolean Flag indicate if all Cash is transferred. No
  • true
  • false (default)
transferType String The type of transfer. Yes
  • full
  • partial

Request ACAT Transfer Stock Data Fields

Field Type Description Required Value
ticker String The security identifier code. Yes A valid ticker as returned by the Get A Security or Get All Securities requests.
amount Double The amount of stock to transferred. Only if transferAll is false.
transferAll Boolean Flag indicate if all stock is transferred. No
description String A short description of the stock transferred. No A string less or equals to 35 characters.

Request ACAT Transfer Signature Data Fields

Field Type Description Required Value
loginId String The unique ID for the member which has been generated when the member is initially created. Yes
data String Signature image encoded in Base64. Yes

Account Types (contraAccountType)

This request allows transferring the following account types:

  • 9 – Simple IRA
  • I – Individual
  • J – Joint - Rights of Survivorship
  • K – Joint - Tenants in Common
  • L – Joint - Community Property
  • M – Joint - Tenants by Entirety
  • P – Sep. IRA
  • Q – IRA Rollover
  • R – Traditional IRA
  • S – Roth IRA
  • X – Revocable Trust

All others values will be rejected with status 400 and code “invalid choice”.


Request Example

  • Full Transfer with Individual Account


POST http://api.uat.foliofn.com/restapi/accounts/RD9039000T/acatin HTTP/1.1
Content-Type: application/json

{
	"loginId" : "muserid17625",
	"transferType" : "full",
	"contraAccountType" : "I",
	"contraAccountNumber" : "CACCNB",
	"contraFirmName" : "HSBC Securities (USA) Inc.",
	"signatureImageEncoding" : "SVG",
	"signatures" : [
		{ "loginId" : "muserid17625", "data" : "..." }
	]
}

  • Full Transfer with Joint Account


POST http://api.uat.foliofn.com/restapi/accounts/RD9039000T/acatin HTTP/1.1
Content-Type: application/json

{
	"loginId" : "muserid17625",
	"transferType" : "full",
	"contraAccountType" : "K",
	"contraAccountNumber" : "CACCNB",
	"contraFirmName" : "HSBC Securities (USA) Inc.",
	"signatureImageEncoding" : "SVG",
	"signatures" : [
		{ "loginId" : "muserid17625", "data" : "..." },
		{ "loginId" : "muserid89774", "data" : "..." }
	]
}

  • Transfer All Cash with Individual Account


POST http://api.uat.foliofn.com/restapi/accounts/RD9039000T/acatin HTTP/1.1
Content-Type: application/json

{
	"loginId" : "muserid17625",
	"transferType" : "partial",
	"transferAllCash" : "true",
	"contraAccountType" : "I",
	"contraAccountNumber" : "CACCNB",
	"contraFirmName" : "HSBC Securities (USA) Inc.",
	"signatureImageEncoding" : "SVG",
	"signatures" : [
		{ "loginId" : "muserid17625", "data" : "..." }
	]
}

  • Transfer Cash and Stocks with Individual Account


POST http://api.uat.foliofn.com/restapi/accounts/RD9039000T/acatin HTTP/1.1
Content-Type: application/json

{
	"loginId" : "muserid17625",
	"transferType" : "partial",
	"cashAmount" : "11.5",
	"contraAccountType" : "I",
	"contraAccountNumber" : "CACCNB",
	"contraFirmName" : "HSBC Securities (USA) Inc.",
	"signatureImageEncoding" : "SVG",
	"stocks" : [
		{ "ticker" : "AAPL", "amount" : "1.0" },
		{ "ticker" : "IBM", "transferAll" : "true", "description" : "all" }
	],
	"signatures" : [
		{ "loginId" : "muserid17625", "data" : "..." }
	]
}


Response Example

The Account Transfer identifier code is return on the response location field.


HTTP/1.1 201 Created
Date: XXX
Location:
http://api.uat.foliofn.com/restapi/accounts/RD9039000T/acatin/11HIS3RQ

Responses are the same no matter the request data.


Error Codes

HTTP Code Status Field Code Message Description
403 - - - Specified user is not allowed to use the request.
400 loginId invalid.value - The account number on the request is different from the one specified on the URL.
400 loginId loginId.not.found - The specified loginId is not found on Folio system.
400 contraAccountType cannot.be.null - No value.
400 contraAccountType invalid.values - The specified value is different from the one in the specified account.
400 contraAccountType invalid.choice - The specified value is not supported. See Account Types part.
400 rothFiveYear invalid.value - The specified value is invalid.
400 stocks ${i}.stock.amount.cannot.be.null - The amount for the stocks[i] is null.
400 stocks ${i}.stock.amount.cannot.be.lower.or.equals.to.zero - The amount the stocks[i] is lower or equals to 0.
400 stocks ${i}.stock.ticker.cannot.be.null - The ticket for the stocks[i] is null.
400 stocks ${i}.stock.ticker.not.found - The ticker for the stocks[i] cannot be found on Folio system.
400 stocks ${i}.stock.description.too.long - The description for the stocks[i] is too long.
400 - acat.expected.cashamount.or.stocks.for.partial.transfer - Neither cashAmount nor stocks specified on the request.
400 transferType invalid.choice - Invalid transfer type specified.
400 signatureImageEncoding cannot.be.null - The specified value is null.
400 signatureImageEncoding invalid.choice - Invalid signature image encoding specified.
400 signatures cannot.be.null - No signature specified.
400 signatures acat.signature.invalid.count - The number of specified signature(s) is invalid.
Expected:
  • 2 for joint account
  • 1 for other account
400 signatures ${i}.signature.loginid.cannot.be.null - The login ID for the signatures[i] is null.
400 signatures ${i}.signature.loginid.cannot.be.empty - The login ID for the signatures[i] is empty.
400 signatures ${i}.signature.data.cannot.be.null - The data for the signatures[i] is null.
400 signatures ${i}.signature.data.cannot.be.empty - The data for the signatures[i] is empty.
400 signatures acat.signature.primary.loginid.not.match - The first signature login ID does not match the one registered on the Folio account.
400 signatures acat.signature.secondary.loginid.not.match - The secondary signature login ID does not match the one registered on the Folio account.
400 Accounts.initiateAcatTransfer invalid.value - The specified account does not belong to the specified loginId.
400 contraFirmName acat.brokerage.not.found - The specified contra firm name is not found on Folio system.

Change Log

07/08/2016

  1. Reordered Sections

12/18/2015

  1. New documentation

Getting Started

REST APIs

Resources

Developer Home