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

Create a Cash Transaction

This request is used to create a deposit or withdrawal cash transaction to move funds into and out of a Folio account.

  • Please note that there are numerous restrictions related to deposits/withdrawals into different types of Folio accounts based upon account and user characteristics (e.g., no contributions into a traditional IRA or rollover IRA when the account owner is over 70½ years old; certain states have defined minimum withholdings from IRA accounts; etc.) which will be checked when sent through this API and or when the funds are received at Folio. Learn more in the Folio Institutional Help Center.
  • The system will reject attempts to create transactions after the 12:00:00pm EDT for the current date. If the current time is after 12:00:00, the transactions must be future dated.
  • The system will reject transactions that fall on non-settlement days (holidays or weekends),
  • The system will reject attempts to create transactions with account restrictions.
  • The system will allow transactions to be created on unverified banklinks. However, the system will not process those transactions until the banklinks are verified, request date notwithstanding.
  • The system will reject attempts to create transactions with amounts less than $0.01.
  • The system will reject attempts to create transactions using deleted banklinks.
  • The system will reject attempts to create transactions where the banklink is newer than the transaction. In other words, the transaction request date cannot precede the banklink creation date.
  • The system will reject attempts to create transactions using banklinks with no explicit relationship with the account.
  • In terms of the error messages, process date equals request date.

Deposit

  • The contribution year is the current year UNLESS the deposit occurs between 01/01/ 12:00:00am EDT and 04/15/ 11:59:59pm EDT in which case the contribution year could be the current or previous year. For 2018, the contribution year can be the previous year until 04/17/2018 11:59:59pm.
  • The ira contribution year is required for one-time ira deposits. The system will reject deposits without a contribution year provided with the transaction request.
  • The ira contribution year SHOULD NOT be sent with recurring ira deposit requests.
  • The system will enforce deposit limits for the target account. The default system limit is $100,000.00.
  • The system will reject attempts to create transactions for IRA accounts where the amount exceeds IRA contribution limits.
  • The system WILL NOT enforce yearly IRA contribution limits. Five $4000.00 Traditional IRA contributions are allowed.

Withdrawal

  • The system will perform an immediate cash availability check on a transaction if the request date is the current date prior to 12:00pm EDT, otherwise, the cash availability check occurs on the requested date.
  • The system will enforce withdrawal limits for the target account. The default system limit is $200,000.00 over a 30 day period.
  • The system requires that withholding information is provided if the withdrawal is from non-ROTH IRA account.
  • The withholding types can be represented as fixed dollar('D') or percentage('P'). If you select those options, the witholding amounts MUST be greater than 0.00.
  • To elect not to withhold, option NONE('N') must be used. Withholding amounts of 0.00 can then be used.
  • Withholding types can be mixed and match. For example, state withholding can be a percentage, while fed can be a fixed dollar amount.
  • The sum of state and fed withholding amounts cannot exceed the requested withdrawal amount.
  • Different states can have different withholding amounts. Distributions from your IRA are subject to state taxes which vary by state. See State Income Tax table for more information. The system will verify state withholding amoutns in accordance with that state's tax rules.

Request URL

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

Request Data Fields

Field Required Description
transactionType Yes The type of transaction to be created. “AHD” -- ACH Deposit, “AHW” -- ACH Withdrawal, “CRW” - Check Regular Withdrawal, “COW” - Check Overnight Withdrawal, “WIW” - Wire Withdrawal.
sourceId Depends The source of the funds for the transaction, banklinkoid for deposit; Folio accountnumber for withdrawal. Required for deposit transaction.
targetId Depends The destination of the funds for the transaction, banklinkoid for withdrawal; Folio accountnumber for deposit. Required for withdrawal transaction.
amount Yes Amount of the transaction. The default system limit for deposit is $100,000.00; the default system limit for withdrawal is $200,000.00 over a 30 day period
repeatType Required The frequency type of repeating transaction, “O” - One-time, “W” - Weekly, “M” - Monthly, “Y” -- Yearly.
processDate Yes The process date of the transaction. It can also act as the start date of a repeating transaction. Follows ISO-8601 formatted date.
repeatInterval Depends The multiple of time for the frequency repeat type, ie, every 2 wks or 3 months. Required if it is a repeatable transaction, return validation error otherwise.
repeatOffset Depends The day of the transaction based on the frequency, ie, 3 for monthly would be third day of month. Required if it is a repeatable transaction, return validation error otherwise.
endDate Depends The date after which the repeating transactions should stop. Follows ISO-8601 formatted date. Required if it is a repeatable transaction and endDateChoice is "transfersEndDate", return validation error otherwise.
endDateChoice Depends The type of end date option selected, "transfersInfinite" -- no end date; "transfersMaxNumOf" -- endDate will be derived based on max number of repeated transfers; "transfersEndDate" -- explicit end date provided. Required if it is a repeatable transaction, return validation error otherwise.
iraContributionYear Depends The year that a deposit into an IRA account occurred. Required if it is a deposit transaction and the account is IRA, return validation error otherwise.
The format is YYYY.
distributionReasonCode Depends The reason assigned to a distribution. Valid reasons are "N" -- Normal; "P" -- Premature; "S" -- SEP_72T; and "E" -- Death. Required if it is a withdrawal transaction and the account is IRA, return validation error otherwise.
fedWithholdType Depends The type of Fed withholding selected, "P" -- Percent amount, "D" -- Fixed Dollar amount, "N" -- No withholding. Required if it is a withdrawal transaction and the account is IRA, return validation error otherwise.
fedWithholdAmount Depends The amount or percentage to withhold. Required if it is a withdrawal transaction and the account is IRA and fedWithholdType is not "N", return validation error otherwise.
stateWithholdType Depends The type of State withholding selected, "P" -- Percent amount, "D" -- Fixed Dollar amount, "N" -- No withholding. Required if it is a withdrawal transaction and the account is IRA, return validation error otherwise.
stateWithholdAmount Depends The amount or percentage to withhold. Required if it is a withdrawal transaction and the account is IRA and stateWithholdType is not "N", return validation error otherwise.
doAlertFlag No Need permission to use this field. Default value is "true", set to "false" to silence the alert.
maxRepeatTimes Depends Max number of repeat times. Required if it is a repeatable transaction and endDateChoice is "transfersMaxNumOf", return validation error otherwise.

Request Example: Successful Deposit Creation


POST /restapi/accounts/RA1234ABCD/cashtransactions HTTP/1.1
Content-Type: application/json
{
	"amount" : "250",
	"processDate" : "2016-11-09T15:07:38.360-05:00",
	"repeatType" : "0",
	"sourceId" : "2594073385611396851",
	"targetId" : "RA1234ABCD",
	"transactionType" : "AHD"
}


Response Example 1: Successful Deposit Creation

If the deposit success, the system will return a '201 Created' with location information.


HTTP/1.1 201 Created
Date: Wed, 20 Jul 2016 20:18:30 GMT
Location: http://api.uat.foliofn.com/restapi/accounts/RA1234ABCD/cashtransactions/2017612635063278223
Content-Length: 0
Content-Language: en


Response Example 2: Failure due to deposit request with 0.0 transfer amount

If the deposit attempt fails, the system will return a '400 Bad Request' with information regarding the nature of the error in the response body.
The error code is returned in the 'errorCode' field, while the 'message' field contains information about the actually error.


HTTP/1.1 400 Bad Request
Date: Fri, 29 Jul 2016 15:10:59 GMT
Location: https://api.uat.foliofn.com/restapi/accounts/RA1234ABCD/cashtransactions
Content-Type: application/json
Transfer-Encoding: chunked
[
	 {
	  "type":"VALIDATION_FIELD",
	  "field":"amount",
	  "errorCode":"1003",
	  "message":"Invalid field value"
	  }
]


Response Example 3: Failure due to deposit request with non-settlement date of 07/30/2016 (Saturday) and amount exceeds maximum amount limit in request body

If the deposit attempt fails, the system will return a '400 Bad Request' with information regarding the nature of the error in the response body.
The error code is returned in the 'errorCode' field, while the 'message' field contains information about the actually error.


HTTP/1.1 400 Bad Request
Date: Fri, 29 Jul 2016 15:10:59 GMT
Location: https://api.uat.foliofn.com/restapi/accounts/RA1234ABCD/cashtransactions
Content-Type: application/json
Transfer-Encoding: chunked
[
	 {
	  "type":"VALIDATION_RULE",
	  "errorCode":"",
	  "message":""
	  },
	  {
	  "type":"VALIDATION_RULE",
	  "errorCode":"",
	  "message":""
	  }
]


Error Codes

This section captures the error codes returned by the API.

It should be noted that some errors are strictly internal errors that API consumers are never expected to encounter during the course of normal operations. They are most likely caused by a bug in the API or some other internal issue. For those errors, the only solution is to contact apisupport@folioinstitutional.com.

Code Decription Internal(Y/N)
1001 Field cannot be null for these fields, transactionType, sourceOid, targetOid, amount, processDate. If it is a repeatable transaction, repeatInterval and repeatOffset can not be null. N
1002 Field have to be null for these fields, repeatInterval and repeatOffset if it is not a repeatable transaction (repeatType value is empty). N
1003 Invalid field value for: 1. the value is less or equal to 0 for these fields, sourceOid, targetOid, amount, fedWithholdAmount, stateWithholdAmount, oid; 2. with invalid enumeration value for these fields, transactionType, endDateChoice, distributionReasonCode, fedWithholdType, stateWithholdType, status, cancelReasonCode. N
1004 Invalid field value length for these fields, iraContributionYear (must be 4), cancelReason (max 255) N
9000 The process date for current transaction cannot be a past date. N
9001 The process date for current transaction cannot be a non-settlement date. N
9002 For same day transaction, the request time must before 12pm. N
9003 Request transaction amount cannot exceed the maximum transaction amount limit. N
9004 Cash transaction source cannot be null. Y
9005 Cash transaction target cannot be null. Y
9006 The system cannot find the targetoid. N
9007 The system cannot find the sourceoid. N
9008 The transaction type is unsupported. N
9009 Contribution year cannot be null for a one time transaction with a IRA account. N
9010 The system will only allow the contribution year to be one year earlier than the request date year if the request date month and day fall between 1/1 and 4/15. N
9011 The system doesn't support ACH deposit for current account type. N
9012 ACH deposit disabled. N
9013 Missing firm attribute information. N
9016 The system will enforce transaction limits for the EFT deposit. The default system limit is $100,000.00. N
9017 The system will enforce transaction limits for the EFT withdrawal. The default system limit is $200,000.00. N
9018 The source account is unrelated to the target EFT bank link. N
9019 Attempting to use a deleted banklink to create transaction. N
9020 Account has no banklinks. N
9021 The creation time of the banklink is later than the request date(internally known as "process date"). N
9022 The system could not find banklink based on give banklinkoid. N
9023 The system has issue to retrieve transaction limit for target account. Y
9024 The system has limits on the amount of deposits allowed per month. Please contact apisupport@folioinstitutional.com to get the limits for your firm. N
9025 Attempt to use non-ACH banklink for an EFT transaction. N
9026 Missing IRA config information. Y
9027 The entity attempting to create the transaction doesn't exist in the system. N
9028 The withholding type can only be on of 'P', 'D', 'N'. N
9029 Invalid amount for given withholding type. N
9030 The withholding type can only be on of 'P', 'D', 'N'. N
9031 Invalid amount for given withholding type. N
9032 The distribution reason code is invalid for current user. N
9033 Invalid IRA config entity oid Y
9034 Null creator oid is not allowed. Y
9035 Null creatorOid type is not allowed. Y
9036 Null modifier oid is not allowed. Y
9037 Null modifierOid type is not allowed. Y
9038 Invalid request data fields. N
9039 The source account doesn't have any associated address. N
9040 The source account is unrelated to the target address. N
9041 The source account is unrelated to the target wire bank link. N
9042 Cash transaction repeat template's end date cannot be earlier than process date. N
9043 Missing one or multiple required parameters for creating a repeating cash transaction. Y
9044 Unsupported frequency type for repeating cash transaction. N
9045 Invalid frequency offset for repeating cash transaction. N
9046 The start date(request date of the first transaction in the repeat template) of the repeat transaction doesn't the match the frequency offset. N
9051 No permission to set cash transaction alert flag. N
9055 Withholding amount cannot exceed the cash transaction requested amount. N
9056 Account number does not exist or mismatch with associated transaction. N
9057 Request transaction amount invalid. Provide amount with proper minor units. N
9058 Active Funds Hold is in place. N
9060 ACH amount exceed IRA contribution limit. N

Change Log

09/26/2019

  1. Added timezone info and date format.

05/30/2019

  1. 9060 Error code added to the list.

05/11/2018

  1. 9058 Error code added to the list.

02/02/2018

  1. Updated Deposit information related to ira deposits.
  2. 9057 Error code added to the list.

12/02/2016

  1. Use accountnumber for folio accounts for either source or target Id.
  2. Rename sourceOid & targetOid to sourceId & targetId
  3. Require that frequency always be specified, including for one-time
  4. Updated supported transactionType
  5. Updated supported repeatType

10/07/2016

  1. Request Data Fields, Request Example and Error Codes updated

09/09/2016

  1. Created page

Getting Started

REST APIs

Resources