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

Create an ACH Pull Deposit

Description

This request creates an ACH transfer to pull funds into the brokerage account by using a bank link set up on the brokerage account.


Notes

  • Please note that there are numerous restrictions related to deposits into different types of brokerage accounts based upon account and user characteristics (e.g., no contributions into a beneficiary IRA or any IRA when the account owner is over 70½ years old, 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 contribution year is the current year UNLESS the deposit occurs between 01/01/ 12:00:00am and 04/15 23:59:59 in which case the contribution year could be the current or previous year.
  • The system will reject transactions without a contribution year created on IRA accounts.
  • The system will reject attempts to create transactions after the 12:00:00pm the current date. If the current time is after 12:00:00, the transactions must be future dated.
  • The system will enforce deposit limits for the target account. The default system limit is $100,000.00.
  • 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 $00.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.
  • 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 is allowed.
  • In terms of the error messages, process date equals request date.

Error Codes

This section captures the error codes returned by the API.
Code Description
transaction.rule.validation.error Internal validation error for request. Possible causes range from bad account number in request URL to exceeding the deposit limits. The precise causes will be returned in the response body.
uri.matching.rule Occurs when the account provided in the uri doesn't match the account passed via the request body JSON.
transaction.ira.account.owner.has.turned.seventy.and.one.half.and.cannot.deposit.into.account The account owner age is older than 70.5 and is no longer eligible to deposit into account.
transaction.deposit.account.limit.has.been.reached The monthly deposit limit has been reached.

Error Code Details: transaction.rule.validation.error

The "transaction.rule.validation.error" series of errors are generated when the system encounters errors that would prevent the successful creation of a transaction. Before the system attempts to persist a transaction, it performs a series of validations on a CashTransaction object that has been created based on data passed to the CashTransactionService. The service may return one or more validation errors encountered during the creation call.

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.

Message Text Cause Internal(Y/N)
The process date cannot be on a settlement holiday. Week-ends and most holidays cannot be used for the request date. What API users know as "request date" is known internally, to us, as "process date". N
The transaction amount should be greater than $0.00. Amounts must be greater than $0.00. N
The transaction amount is greater than the maximum allowed. The system will not process any transaction amount greater than $2,000,000.00. This option is configurable on a firm by firm basis. N
The process date must be equal or after [current date in format MM/dd/yyyy]. Transaction can be same day or later before 12:00pm N
The process date must be equal or after [current day + 1 in format MM/dd/yyyy]. Transaction must be tomorrow or later if system time is after 12:00pm. N
You cannot deposit into this account: [Account number here], transactionOid:
[transaction oid here] because of the [Restriction code here] restriction.
Attempt to deposit into a restricted account N
The creator does not have the appropriate access to the selected source account. The entity attempting to create the transaction doesn't have "money mover" or better permission N
The contribution year attribute must be set for deposits into IRA accounts. Contribution year for IRA was not provided. N
The selected target account for transaction: [Transaction oid here]
is of type: [Registration type here] does not support deposit transactions.
The system does not allow deposits into Beneficiary, Model, Watch, 401K or Proxy accounts. The system does not allow deposits into Rollover or Traditional IRA accounts for which the owner is older than 70.5. N
The deposit amount of: [$0,000.00 (formatted dollar amount)] exceeds the deposit limit of [$0,000.00 (formatted dollar amount)]." 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
You cannot use: [year] as the contribution year. The previous year can only be used during tax season 1/1 to 4/15. 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
The selected banklink is disabled. Attempting to use a deleted banklink to create a transaction. N
Target account doesn't appear to have any banklinks. The Folio account for the deposit doesn't have banklinks. N
Account and banklink are unrelated and cannot be used together. The Folio account and banklink not associated in the system. N
The target is null. The system must have a valid Folio Account. The target(Folio Account) is null. Y
The contribution year is of: [year as string] has an invalid format. System tried to convert string into int and failed. Y
The contribution year: [contribution year] is invalid. Internal contribution year is invalid. Y
Funds Hold Amount must be greater than $0.00 A funds hold is a hold placed on deposits before they are available for withdrawal. The system creates a hold when it creates a deposit transaction. The amount of the hold should be equal to the amount of the deposit Y
The Deposit target account and Funds Hold account must be the same account. A deposit was made for account A, but the hold was created for account B, resulting in a mismatch. This mismatch has been flagged as an error. Y
The hold expiration date must be equal to or after [processDate (what API consumers know as "request date"]. The expiration date cannot be earlier than the process date("request date") of the deposit. Y
Funds Hold Exemption must have valid bank account number. The funds hold exemption is missing the bank account number Y
Funds Hold exemption must have valid routing number The funds hold exemption is missing the routing number. Y
The source is null. The system must have a valid Banklink The source(banklink) is null. Y
The selected banklink is not yet available for use. The creation time of the banklink is later than the request date(internally known as "process date"). Y
The request date must be [current date in format MM/dd/yyyy]. Request date is current date. Internally, the request date is the day the transaction was created(requested). What API users know as "request date", the system internally calls "process date". Y
The banklink type is invalid. It is [banklinktype] and should be an ACH. Attempt to use non-ACH banklink for an EFT transaction. Y

Request URL

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

Request Data Fields

Field Required? Description
amount Yes The amount of the requested deposit, ie, 0.00. The amount of the ACH transfer request. Default limit is $100,000.00 over a thirty day period.
banklinkOid Yes The unique identifier for the bank link on an account.
requestDate Yes The date this transfer should initiate. Must follow ISO-8601 formatting.
contributionYear Depends The contribution year of the deposit. Required if the account is IRA, ignored otherwise.

Request Example


POST /restapi/accounts/RA1234ABCD/cashtransfers/achdeposits HTTP/1.1
Content-Type: application/json
{
  "amount" : "123.45",
  "banklinkOid" : "828282828282828",
  "requestDate" : "2014-02-27T00:00:00.000-05:00"
  "contributionYear" : "2015"
}

Response Example 1: Successful Deposit Creation

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 200 OK
X-Powered-By: Servlet/2.5
Server: Sun GlassFish Enterprise Server v2.1.1
Location: http://api.uat.foliofn.com/restapi/accounts/RA0024900G/cashtransfers/achdeposits/2017612635063278223
Content-Type: application/json
Transfer-Encoding: chunked
Date: Sat, 05 Jul 2014 13:06:39 GMT

Response Example 2: Failure due to deposit request with non-settlement date of 11/11/2015 (Veterans's Day) and $0.00 amount 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
X-Powered-By: Servlet/2.5
Server: Sun GlassFish Enterprise Server v2.1.1
Location: https://api.uat.foliofn.com/restapi/accounts/RA1234ABCD/cashtransfers/achdeposits
Content-Type: application/json
Transfer-Encoding: chunked
Date: Sat, 05 Jul 2014 13:06:39 GMT
[
	 {
	  "type":"VALIDATION_RULE",
	  "errorCode":"transaction.rule.validation.error",
	  "message":"Error: processDate:The process date cannot be on a settlement holiday."
	  },
	  {
	    "type":"VALIDATION_RULE",
	    "errorCode":"transaction.rule.validation.error",
	    "message":"Error: amount:The transaction amount should be greater than $0.00."
	  }
]



Change Log

05/13/2016

  1. Added additional info about the transaction.rule.validation.error series of errors.
  2. Fixed typo of word "banklink".

10/21/2015

  1. Added Change Log
  2. Error codes section
  3. Description header
  4. Added Notes section

Getting Started

REST APIs

Resources