Place order

Request

Place a new order. You can place various types of order such as limit, market, at best, previously quoted, stop, algo, pegged, and more. Under algo orders you can execute various strategies such as TWAP.

Returns status code 202 if your order is accepted by the system for processing. Use the query order endpoints to get the current status of your order Query order (client ID or all active orders) or Query order (server ID).

You can get all trades associated with an order using Query all trades on an order by ID. Trades contain information like counterparty, settlement date, and amount.

Required request attributes for all order types

All place-order requests must have the following attributes:

coId
type
side
symbol
size
currency

Conditionally required request attributes and values

Your request may require additional attributes based on the order type or attribute values.

For example, if you place an order with timeInForce=GTT (good-til-canceled) you must also specify expiryTime.

Order type	Required attributes and values
Limit(IOC)	`type=Limit`, `timeInForce=IOC`, `price`
Limit(GTC)	`type=Limit`, `timeInForce=GTC`, `price`
Limit(GTT)	`type=Limit`, `timeInForce=GTT`, `expiryTime`, `price`
Market(IOC)	`type=Market`, `timeInForce=IOC`, `price`
At best	`type=AtBest`, `timeInForce=FOK`, `valueDate`
Stop	`type=Stop`, `price`, `stopPrice`, `execFlags=BidTrigger\|OfferTrigger\|MidTrigger`
Previously quoted	`type=PQ`, `timeInForce=FOK`, `price`, `rateId`
Algo (TWAP)	`type=Algo`, `timeInForce=GTC`, `targetStrategy`
On behalf of	`price`, `org`, `account`

Security

SSO_TOKEN

Bodyapplication/json

coIdstring, <= 255 charactersrequired

Client order ID assigned by the API user.

rateIdstring, <= 255 characters

Unique identifier for rate. Required for Previously Quoted Orders.

typestring, <= 20 charactersrequired

Limit
AtBest
Market
Stop
StopLimit
Pegged
Algo
PQ (previously quoted)

sidestring, <= 10 charactersrequired

Buy or Sell from the order placer’s perspective and always for the dealt currency.

symbolstring, <= 35 charactersrequired

Base and term currency separated by a slash / (for example EUR/USD).

sizenumber, (double)required

Order amount.

currencystring, <= 17 charactersrequired

Dealt currency.

pricenumber, (double)

Order’s requested limit price.

priceTypestring, <= 32 characters

Optional for At Best orders.

Spot
Outright
NDF

timeInForcestring, <= 20 characters

GTC
IOC
FOK (required for at-best orders)
GTT (must specify expiryTime)
DAY

orgstring, <= 30 characters

Organization ID in Integral's system. If the order iss placed on behalf of another organization, this parameter contains the other organization's ID.

accountstring, <= 30 characters

The ID of the account (legal entity) for which the order iss placed. Required when placing orders on behalf of another organization.

expiryTimeinteger, (int64)

Expiry time when timeInForce=GTT. In seconds. Max value is one day (86399 seconds).

valueDatestring, <= 20 characters

Value date in the format YYYY-MM-DD. Required for at-best orders.

stopPricenumber, (double)

Order’s stop price (if any).

execFlagsArray of strings

Execution strategy requested with order:

BidTrigger: Stay on bid side
MidTrigger: Mid price
OfferTrigger: Stay on offer side

minQtynumber, (double)

Minimum fill size (if any) in dealt currency.

maxShownumber, (double)

Amount of the order visible to other market participants:

0 (zero) or undefined: Hidden: Order is not visible to other customers.
Equal to size: Display: Full order amount visible to other customers.
Less than size: Iceberg: Only the value of maxShow visible.

targetStrategystring, <= 32 characters

(Algo) The algo or strategy of the order:

Mid
Fixing
Twap
LitSwitch
DarkSwitch

executionStartTimestring, <= 32 characters

(Algo) Relative time at which the strategy should start execution specified in the format HH:MM:SS.sss. If not specified, the strategy starts executing immediately.

executionEndTimestring, <= 32 characters

(Algo) Absolute time in GMT at which the strategy should stop executing. If not specified, the order expires based on the value of its time in force.

pegPriceTypestring, <= 32 characters

The rate the order is pegged to:

Mid: Pegged to mid rate.

pegOffsetValuenumber, (double)

The amount in pips that is added to the price of the peg. Can be positive or negative.

actionOnExpirystring, <= 32 characters

(Algo) Action taken at the end of the algo’s duration if there is an unfilled amount remaining. If not specified, the order is cancelled at expiration. NoAction, FillAtMarket, Twap

sliceSizenumber, (double)

(Algo) The fixed size of each slice.

passiveTimeinteger, (int64)

(Algo) Time for which each slice rests in OCX RiskNet. Specified in milliseconds. Overrides passiveTimeFactor.

passiveTimeFactorPercentagenumber, (double)

(Algo) Determines how long each slice rests in OCX RiskNet, calculated as a percent of the actual slice interval. Required if passiveTime is not set

sliceIntervalinteger, (int64)

(Algo) Interval between slices in milliseconds. If the interval is fixed, this value is the interval duration. If the interval is randomized, this value is the upper boundary of random values.

randomizeSliceSizePercentagenumber, (double)

(Algo) The percentage range that the sliceSize is randomized.

randomizeSliceIntervalPercentagenumber, (double)

(Algo) The percentage range that the sliceInterval is randomized.

tobRangenumber, (double)

(Algo) If sliceSize undefined, the slice size is this percentage of the top-of-book price size.

customParametersobject, <= 3500 characters

Collection of parameters that are unique to your organization. The number of parameters, their keynames, and values are defined by you.

Contact your Integral Technical Account Manager to enable and configure custom parameters.

Your custom parameters are included in API responses and in STP trade download.

Custom parameters sent to Integral via API are stored in the database directly. No validation is performed.

The maximum size of the customParameter property is 3500 characters, including all keys, values, and JSON syntax characters.

POST

/v2/orders

{
  "coId": "8932452311944",
  "type": "Limit",
  "side": "Buy",
  "symbol": "EUR/USD",
  "currency": "EUR",
  "size": 1000000,
  "price": 1.0971678,
  "timeInForce": "IOC"
}

Responses

Order accepted by system.
Response contains an order object with an orderId assigned by the system.
Use Query order (server ID) or Query order (client ID or all active orders) to get the current status of your order.

Bodyapplication/json

coIdstring, <= 255 charactersrequired

Client order ID assigned by the API user.

typestring, <= 20 charactersrequired

Limit
AtBest
Market
Stop
StopLimit
Pegged
Algo
PQ (previously quoted)

timeInForcestring, <= 20 charactersrequired

GTC
IOC
FOK
GTT
DAY

sidestring, <= 10 charactersrequired

Buy or Sell from the order placer’s perspective and always for the dealt currency.

currencystring, <= 17 charactersrequired

Dealt currency.

symbolstring, <= 35 charactersrequired

Base and term currency separated by a slash / (for example EUR/USD).

sizenumber, (double)required

Order amount.

rateIdstring, <= 255 characters

Unique identifier for rate. Required for Previously Quoted Orders.

orgstring, <= 30 characters

Organization ID in Integral's system. If the order was placed on behalf of another organization, this parameter contains the other organization's ID.

accountstring, <= 30 characters

The ID of the account (legal entity) for which the order was placed. Required when placing orders on behalf of another organization.

pricenumber, (double)

Order’s limit price, if any.

priceTypestring, <= 32 characters

Optional for At Best orders.

Spot
Outright
NDF

expiryTimeinteger, (int64)

Expiry time when timeInForce=GTT. In seconds. Max value is one day (86399 seconds).

clientOrderTimestring, <= 32 characters

Time the order was submitted in the format yyyy-MM-dd HH:mm:ss,SSS Z.

tradeChannelstring, <= 128 characters

The app or workflow that originated the order.

targetStrategystring, <= 32 characters

Algo: The algo or strategy of the order:

Mid
Fixing
Twap
LitSwitch
DarkSwitch

originalCoIdstring, <= 255 characters

The original client order ID of the order to be cancelled or replaced by this request.

stopPricenumber, (double)

Order’s stop price (if any).

execFlagsArray of strings

Execution strategy requested with order:

BidTrigger: Stay on bid side
MidTrigger: Mid price
OfferTrigger: Stay on offer side

minQtynumber, (double)

Minimum fill size (if any) in dealt currency.

maxShownumber, (double)

Amount of the order visible to other market participants:

0 (zero) or undefined: Hidden: Order is not visible to other customers.
Equal to size: Display: Full order amount visible to other customers.
Less than size: Iceberg: Only the value of maxShow visible.

averagePricenumber, (double)

Average price of all fills so far. For orders and order types with timeInForce=FOK such as at-best orders, this is the filled price.

cumQtynumber, (double)

Total cumulative amount filled so far.

orderIdstring, <= 60 characters

Order ID assigned by Integral.

valueDatestring, <= 20 characters

Value date in the format YYYY-MM-DD.

tradeDatestring, <= 20 characters

Trade date of fill.

executionTypestring, <= 30 characters

CANCELED
NEW
PARTIAL_FILL
PENDING_NEW
TRADE

leavesQtynumber, (double)

Unfilled amount as of the most recent fill.

counterpartystring, <= 30 characters

Counterparty organization ID.

counterPartyAccountstring, <= 30 characters

Counterparty legal entity ID.

transactTimeinteger, (int64)

UTC time of last event on the order in milliseconds.

userFullNamestring, <= 128 characters

Fully qualified user name of order submitting user, including namespace and organization ID in the format userName@namespace.orgID.

actionstring, <= 32 characters

place
cancel
cancelAll

statusstring, <= 32 characters

RECEIVED: Order received.
NEW: Order has been entered and is working according to the order type and specified execution strategy.
PARTIALLY_FILLED: Trade done that does not completely fill the order.
FILLED: Trade done that completely fills the order.
PENDING_CANCEL: Cancel order request has been received and is in process.
CANCELED: Order has been canceled.
REPLACED: Order has been replaced with a new order.
STOPPED: Price matching has been paused for the order.
REJECTED: Order has been rejected.
EXPIRED: Order expired.
FAILED: Order failed.

reasonstring, <= 128 characters

Orders with status=FAILED or status=REJECTED, the reason for failure or rejection. INTERNAL_SERVER_ERROR indicates a serious error. Stop trading immediately and contact Business Support to resolve the issue.

customerIdstring, <= 30 characters

Customer ID on whose behalf the order is placed.

executionStartTimestring, <= 32 characters

Relative time at which the strategy should start execution specified in the format HH:MM:SS.sss. If not specified, the strategy starts executing immediately.

executionEndTimestring, <= 32 characters

Absolute time in GMT at which the strategy should stop executing. If not specified, the order expires based on the value of its time in force.

pegPriceTypestring, <= 32 characters

The rate the order is pegged to:

Mid: Pegged to mid rate.

pegOffsetValuenumber, (double)

The amount in pips that is added to the price of the peg. Can be positive or negative.

actionOnExpirystring, <= 32 characters

Action taken at the end of the algo’s duration if there is an unfilled amount remaining. If not specified, the order is cancelled at expiration. NoAction, FillAtMarket, Twap

sliceSizenumber, (double)

The fixed size of each slice.

passiveTimeinteger, (int64)

Time for which each slice rests in OCX RiskNet. Specified in milliseconds. Overrides passiveTimeFactor.

passiveTimeFactorPercentagenumber, (double)

Determines how long each slice rests in OCX RiskNet, calculated as a percent of the actual slice interval. Required if passiveTime is not set

sliceIntervalinteger, (int64)

Interval between slices in milliseconds. If the interval is fixed, this value is the interval duration. If the interval is randomized, this value is the upper boundary of random values.