Depending on applicable regulations or business limitations, specific API requests may not be available for your use.
Create a Folio Order
This request places trades, also known as security orders, in a folio (i.e., a folio order).
Trades may only be placed in a folio. See Create a Folio for more information about folios.
When placing an order, there are different order types that can be specified and several order parameters that need to be set, as described below, that differ from the order types and parameters available from most other brokerage firms.
Orders on the Folio brokerage platform take place at the folio level and can include one or more securities in the same order (i.e., a folioOrder object contains one or more securityOrders that are for a single folio). A security order placed with us generally specifies the folio into which the securities should be bought or from which they should be sold, though for certain order types you can specify the tax lots to be sold even if those tax lots are not in the folio for which the order is being placed, as tax lots are maintained at the account level.
Request URL
Syntax | POST /restapi/accounts/{accountnumber}/folios/{folionumber}/orders?orderconfig={option} |
---|---|
Example URL | https://api.uat.foliofn.com/restapi/accounts/RA1234ABCD/folios/RA1234ABCD/orders?orderconfig=ds |
Query Parameters
Name | Required? | Values | Description |
---|---|---|---|
orderconfig | No | “c”, Custom Modify, default “b”, Easy Buy “s”, Easy Sell “sa”, Sell All “r”, Rebalance “r-mt”, Rebalance to Model Target Weights “sor”, Sell-Only Rebalance “sor-mt”, Sell-Only Rebalance to Model Target Weights “bor”, Buy-Only Rebalance “bor-mt”, Buy-Only Rebalance to Model Target Weights “sar”, Sell & Rebalance “sar-mt”, Sell & Rebalance to Model Target Weights “bar”, Buy & Rebalance “bar-mt”, Buy & Rebalance to Model Target Weights “dca”, Dollar Cost Average “dm”, Direct Market Order “dl”, Direct Limit Market Order “ds”, Direct Stop Market Order “dsl”, Direct Stop-Limit Market Order “sync”, Sync to Model Current Weights “sync-mt”, Sync Model Target to Model Target Weights “bas”, Buy and Sync to Model Current Weights “bas-mt”, Buy and Sync to Model Target Weights “sas”, Sell and Sync to Model Current Weights “sas-mt”, Sell and Sync to Model Target Weights |
A flag to indicate the type of order to create. |
Note: Buy security orders within sync folio orders may be adjusted during window evaluation if sell proceeds will not cover buys as originally generated.
Request Data Fields
Fields required dependent on order type. Please refer to request examples for details of each order type.
Field | Description |
---|---|
folioNumber | The number(id) of the folio into which the order will be placed. This field is optional in the message body since the URL determines the folio into which the order will be placed. A folioNumber here that does not match the URL will fail validation and generate an error. |
accountNumber | The number(id) of the account into which the order will be placed. This field is also optional in the message body since the URL determines the account into which the order will be placed. An accountNumber here that does not match the URL will fail validation and generate an error. |
dollarShareBasedIndicator | “S” – Share-based. Place this trade by specifying the amount of shares to buy/sell. This order type is only available for custom modify or direct
orders and requires the usage of securityOrders.requestedShareAmount. “D” – Dollar-based. Place this trade by specifying the amount of dollars to buy/sell. Not available for direct orders, and will generate an error if used when not applicable. |
orderType | “W” – Window. Place a window order. “D” – Direct. Place an order for immediate execution. Only allowed for direct limit, direct stop, direct stop-limit orders, and will generate an error if used when not applicable. |
term | Only allowed for direct limit, direct stop, direct stop-limit orders “0” – Day. The order is good only for the day. The requested dollar amount to buy. This field should only be used with non-custom modify window orders, not with rebalance orders, and not used in conjunction with requestedSellDollarAmount, and will generate an error if used when not applicable. |
requestedBuyDollarAmount | The smallest order we can accept is the larger of 0.00001 shares or $0.01 dollars, which is $0.01 for securities priced at $1,000.00 or less. The largest buy amount is the amount of Cash Available for Trading, and any order request for a number of dollars or shares that is greater than the current Cash Available for Trading will be rejected. |
requestedSellDollarAmount |
The requested dollar amount to sell. This field should only be used with non-custom modify window orders, not with sell all orders, not with rebalance orders, and not used in conjunction with requestedBuyDollarAmount, and will generate an error if used when not applicable. The smallest order we can accept is the larger of 0.00001 shares or $0.01 dollars, which is $0.01 for securities priced at $1,000.00 or less. The largest sell amount is a Sell All, and any order request for a number of dollars or shares that is greater than the current holdings will be rejected. |
taxlotReliefMethod | See Tax Lot Relief Methods for available methods and explanations. Average Cost (AVGC) is the only choice for non-taxable accounts and it is not available for taxable accounts, and will generate an error if used when not applicable. Not specifying a value here will cause the trade to default to the default setting for the specified account. |
longTermTaxRate | Long-term tax rate of the owner of the account. This is an input when using the “WLFS” or “WGFS” strategies, and will generate an error if used when not applicable. |
shortTermTaxRate | Short-term tax rate of the owner of the account. This is an input when using the “WLFS” or “WGFS” strategies, and will generate an error if used when not applicable. |
discretionary | “true” or “false”. An order giving the investment representative the ability to determine execution parameters for a trade. This discretion can be exercised through control over the side (buy/sell), timing (time of placement of a market order, for instance), price (through use of a limit or stop price) , or life (Day versus Good 'Til Canceled/GTC) of the order. If such ability was granted to the investment representative, the order should be marked as having discretion exercised. If the investment professional is entering the order on behalf of the client according to the client’s explicit instruction, or the client is entering the order directly, no discretion has been exercised. |
solicited | “true” or “false”. An order should be marked as solicited if the investment representative has initiated contact with the client to recommend and affect a security transaction within their account. An order should be marked as unsolicited if the security transaction has been initiated by the client directly. This could be the order being placed by the client, or contact made by the client to the investment professional to affect an order on their behalf within their account. |
reasonForTrade | “ADJUSTMENT_TO_GUIDELINES(AG)”, “CLIENT_REQUEST(CR)”, “NOT_SPECIFIED(NS)”, “RAISE_CASH(RC)”, “STRATEGY_CHANGE(SC)”, “TAX_LOSS_SELLING(TL)”. See Reasons For Trade for a full explanation. |
applySecurityExclusions | “true” or “false”. Apply security exclusions rule as defined for the specified account. This field is also optional, and the default value is “true”. |
securityOrders | A list of individual securities to buy/sell. This should only be used for direct or custom modify orders. |
securityOrders.side | “1” – Buy “2” – Sell “Z” – Sell All |
securityOrders.security | The security to buy or sell. |
securityOrders.security.ticker | The ticker of the security to buy or sell. |
securityOrders.requestedDollarAmount |
The requested dollar amount to trade for this security. This should be used in conjunction with a dollar-based indicator, and will generate an error if used when not applicable. The smallest order we can accept is the larger of 0.00001 shares or $0.01 dollars, which is $0.01 for securities priced at $1,000.00 or less. The largest buy amount is the amount of Cash Available for Trading, and any order request for a number of dollars or shares that is greater than the current Cash Available for Trading will be rejected. When securityOrders.side = 'Z', requestedDollarAmount is only used as an estimate. The security order will be converted to a share-based order during processing to sell the entire share amount. |
securityOrders.requestedShareAmount |
The requested share amount to trade for this security. This should be used in conjunction with a share-based indicator, and will generate an error if used when not applicable. The smallest order we can accept is the larger of 0.00001 shares or $0.01 dollars, which is $0.01 for securities priced at $1,000.00 or less. The largest buy amount is the amount of Cash Available for Trading, and any order request for a number of dollars or shares that is greater than the current Cash Available for Trading will be rejected. |
securityOrders.limitPrice | The limit price to execute at. This is only applicable to Limit and Stop-Limit orders. |
securityOrders.stopPrice | The stop price to execute at. This is only applicable to Stop and Stop-Limit orders. |
securityOrders.dollarShareBasedIndicator | “S” – Share-based. Place this trade by specifying the amount of shares to buy/sell. This order type is only available for custom modify
or direct orders and requires the usage of securityOrders.requestedShareAmount. All security order dollarShareBasedIndicator should match the folioOrder dollarShareBasedIndicator. |
securityOrders.taxLotSelections | The list of tax lots to relieve with a sell. |
securityOrders.taxLotSelections.taxLotId | The ID of the tax lot. |
securityOrders.taxLotSelections.shareQuantity | The number of shares to relieve. |
Order Examples
Order Type | Dollar-Based Custom Modify |
---|---|
Description | Specify each security and dollar amounts individually. These are window orders only. |
Example |
|
Order Type | Share-Based Custom Modify |
---|---|
Description | Specify each security and share amounts individually. These are window orders only and tax lots may be specified for sell orders. |
Example |
|
Order Type | Easy Buy |
---|---|
Description | Buy into all current positions of the folio based on their current weighting. Unfunded folios cannot use this order type as there are no current weights. |
Example |
|
Order Type | Easy Sell |
---|---|
Description | Sell all current positions of the folio based on their current weighting. |
Example |
|
Order Type | Sell All |
---|---|
Description | Liquidate all positions of the folio. |
Example |
|
Order Type | Rebalance |
---|---|
Description | Rebalance the folio based on the target weights of the folio. Both Buy and Sell orders may be placed. Folios subscribed to models will use the model current weights for the target weights. Folio subscribed to Ready-to-Go folios will use the target weights associated with the subscription. |
Example |
|
Order Type | Rebalance to Model Target Weights |
---|---|
Description | Rebalance the folio based on the subscribed model's target weights. Both Buy and Sell orders may be placed. Used only for folios subscribed to a model. |
Example |
|
Order Type | Sell Only Rebalance |
---|---|
Description | Sell positions in the folio, which will attempt to realign the positions to the target weights without placing any buys. This may not take the folio to target weights if there isn’t a large enough amount sold. Folios subscribed to models will use the model current weights for the target weights. Folios subscribed to Ready-to-Go folios will use the target weights associated with the subscription. |
Example |
|
Order Type | Sell Only Rebalance to Model Target Weights |
---|---|
Description | Sell positions in the folio, which will attempt to realign the positions to the subscribed model's target weights without placing any buys. This may not take the folio to target weights if there isn’t a large enough amount sold. Used only for folios subscribed to a model. |
Example |
|
Order Type | Buy Only Rebalance |
---|---|
Description | Buy positions in the folio, which will attempt to realign the positions to the target weights without placing any sells. This may not take the folio to target weights if there isn’t a large enough amount bought. Folios subscribed to models will use the model current weights for the target weights. Folios subscribed to Ready-to-Go folios will use the target weights associated with the subscription. This order type can be used to fund a new folio subscribed to a model. |
Example |
|
Order Type | Buy Only Rebalance to Model Target Weights |
---|---|
Description | Buy positions in the folio, which will attempt to realign the positions to the subscribed model's target weights without placing any sells. This may not take the folio to target weights if there isn’t a large enough amount bought. Used only for folios subscribed to a model. This order type can be used to fund a new folio subscribed to a model. |
Example |
|
Order Type | Sell and Rebalance |
---|---|
Description | Sell positions in the folio to raise proceeds while rebalancing to target weights. Both Buy and Sell orders may result. Folios subscribed to models will use the model current weights for the target weights. Folios subscribed to Ready-to-Go folios will use the target weights associated with the subscription. |
Example |
|
Order Type | Sell and Rebalance to Model Target Weights |
---|---|
Description | Sell positions in the folio to raise proceeds while rebalancing to subscribed model's target weights. Both Buy and Sell orders may result. Used only for folios subscribed to a model. |
Example |
|
Order Type | Buy and Rebalance |
---|---|
Description | Buy positions in the folio while rebalancing to target weights. Both Buy and Sell orders may result. Folios subscribed to models will use the model current weights for the target weights. Folio subscribed to Ready-to-Go folios will use the target weights associated with the subscription. |
Example |
|
Order Type | Buy and Rebalance to Model Target Weights |
---|---|
Description | Buy positions in the folio while rebalancing to subscribed model's target weights. Both Buy and Sell orders may result. Used only for folios subscribed to a model. |
Example |
|
Order Type | Dollar Cost Average |
---|---|
Description | Similar to an easy buy, but at the target weights instead of the current weights. |
Example |
|
Order Type | Direct Market Order |
---|---|
Description | Place a single security order for immediate execution. |
Example |
|
Order Type | Limit Order |
---|---|
Description | Place a single security limit order. Please note that if a security is part of the tick size pilot program, and a limit price is not in a $0.05 increment, you will receive an error for an invalid price. |
Example |
|
Order Type | Stop Order |
---|---|
Description | Place a single security stop order. Please note that if a security is part of the tick size pilot program, and a stop price is not in a $0.05 increment, you will receive an error for an invalid price. |
Example |
|
Order Type | Stop-Limit Order |
---|---|
Description | Place a single security stop-limit order. Please note that if a security is part of the tick size pilot program, and a stop or limit price is not in a $0.05 increment, you will receive an error for an invalid price. |
Example |
|
Order Type | Sync to Model Current Weights |
---|---|
Description | Sync the folio based on the target weights of the folio. Both Buy and Sell orders may be placed. Folios subscribed to models will use the model current weights for the target weights. Folio subscribed to Ready-to-Go folios will use the target weights associated with the subscription. |
Example |
|
Order Type | Sync to Model Target Weights |
---|---|
Description | Sync the folio based on the subscribed model's target weights. Both Buy and Sell orders may be placed. Used only for folios subscribed to a model. |
Example |
|
Order Type | Buy and Sync to Model Current Weights |
---|---|
Description | Buy positions in the folio, which will attempt to realign the positions to the target weights without placing any sells. This may not take the folio to current target weights if there isn?t a large enough amount bought. Folios subscribed to models will use the model current weights. Folios subscribed to Ready-to-Go folios will use the target weights associated with the subscription. This order type can be used to fund a new folio subscribed to a model. |
Example |
|
Order Type | Buy and Sync to Model Target Weights |
---|---|
Description | Buy positions in the folio, which will attempt to realign the positions to the subscribed model's target weights without placing any sells. This may not take the folio to target weights if there isn?t a large enough amount bought. Used only for folios subscribed to a model. This order type can be used to fund a new folio subscribed to a model. |
Example |
|
Order Type | Sell and Sync to Model Current Weights |
---|---|
Description | Sell positions in the folio to raise proceeds while syncing to target weights. Both Buy and Sell orders may result. Folios subscribed to models will use the model current weights for the target weights. Folios subscribed to Ready-to-Go folios will use the target weights associated with the subscription. |
Example |
|
Order Type | Sell and Sync to Model Target Weights |
---|---|
Description | Sell positions in the folio to raise proceeds while syncing to subscribed model's target weights. Both Buy and Sell orders may result. Used only for folios subscribed to a model. |
Example |
|
Response Examples
Responds with links to the resources (orders) created in the header.
Successful request
HTTP/1.1 201 Created
Date: Tue, 13 Sep 2016 16:27:02 GMT
Location: https://api.uat.foliofn.com/restapi/accounts/RB1234ABCD/folios/RB1234ABCD03/orders/216172782282243860
Content-Length: 0
Content-Language: en
Unsuccessful request
HTTP/1.1 400 Bad Request
Date: Tue, 13 Sep 2016 16:28:24 GMT
Transfer-Encoding: chunked
Content-Type: application/json
[{"type":"VALIDATION_RULE","errorCode":"open.orders.rule","message":"You already have an open window order for this folio. Folios may have only one open order at a time. This order may be placed after the open order is executed.\n"}]
Notes
Orders in Folios
Orders cannot be placed in any folios with the folioNumber ending in “01” as this is the folio reserved for Cash. Only direct orders for whole shares (market, limit, stop, and stop-limit) may be placed in the Non-Folio Holdings folio (i.e., no window trades, no fractional share or dollar-based order in folios ending in 02).
Window vs. Direct
-
Window Orders
Window orders that are sent to us will queued for processing in the NEXT trading window - you cannot specify the trading window into which you would like an order placed.
Only one window order can be placed for the same folio for the same window (i.e., a second order for the same folio will be rejected if the previous order has not already executed in a trading window).
Window orders may be share or dollar-based and can include fractional shares in either type.
Trading windows are currently executed at 11 a.m. and 2 p.m. Eastern Time on days that the U.S. stock markets are open for a full day of trading. This is subject to change.
Type, limit, stop, and other terms applicable to direct orders cannot be applied to window orders.
Window orders cannot be placed in a folio with the folioNumber ending in 02 as this is reserved for Non-Folio Holdings.
-
Direct Orders
Orders that are immediately sent to market (or queued for when the market opens), such as market, limit, stop and stop-limit orders.
These orders can only be placed in whole-shares.
Direct orders are more expensive than window orders.
A term of Good-'Til Canceled (GTC) (term:1) or Day (term:0) must be specified for a direct stop, direct limit, or direct stop-limit order.
Only direct orders for whole shares may be placed in any folios with the folioNumber ending in 02, as this is reserved for Non-Folio Holdings (i.e., no window trades, no fractional share or dollar-based order in folios ending in 02).
Dollar vs. Share
-
Dollar-Based
Specify the amount to buy (side:1) or sell (side:2) by a dollar amount. A sell all (side:Z) may be specified to liquidate a position, and should include a requestedDollarAmount that is only treated as an estimate. Dollar-based orders are converted to share-based orders at the time of execution based on the current price of the security. Dollar-Based is not a parameter that can be used in conjunction with a direct trade. Tax lots may NOT be specified for relief when selling with a Dollar-Based order.
-
Share-Based
Specify the amount to buy (side:1) or sell (side:2) by a share quantity. Tax lots may be specified for relief when selling with a Share-Based order.
Change Log
08/29/2019
- Added new orderconfig Types: sync, sync-mt, bas, bas-mt, sas, sas-mt
08/08/2019
- Added new Request Data Field: applySecurityExclusions
12/09/2016
- Corrected custom modify request example sell all to include requestedDollarAmount
- Updated notes on Dollar vs. Share orders
09/23/2016
- Added new order types - r-mt, bor-mt, sor-mt, bar-mt, sar-mt
- Added dl, ds, dsl notes about tick size pilot program
- Added response examples
- Moved sections
07/22/2016
- Updated text
- Moved sections
04/29/2016
- Added Change Log
- Updated Query Parameters table
- Updated Dollar Cost Average order type