REST API (1.0.1)

Welcome to the Integral REST API reference.

Our REST API is for less latency-sensitive participants and has resource-oriented URLs, accepts JSON-encoded requests, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Contact Integral’s account management team to get connection details and credentials for access.

Authentication options

You can choose between two authentication methods:

Token-based authentication

An ID and password will be issued to you to generate and refresh/renew an access token. All REST API calls should pass this token to access authenticated services.

Get token

Users should use /v2/sso/login to get an access token. The access token is in SSO_TOKEN of the response header. Your token is valid for a limited time.

Pass token

The token should be sent in SSO_TOKEN of request headers.

Renew token

To keep your session alive, you can renew your token with /sso/tokens/renew. If your token is expired, you are issued a new token.

HMAC authentication

In this authentication method, you must sign each API request with a 'secret'. The 'secret' and 'userId' are issued to you during set up.

All REST requests must contain following header information:

Header attribute Description
AuthorizationThe base64-encoded signature.
DateA date and time as standard UTC string.
DigestSHA-256=base64(sha256(<body>)) If there is no request body, Digest should be set to the digest of a body of 0 length.
typeSet to hmac.

You must send an authorization header with the following parameterization:

credentials := "hmac" params
params := userId "," algorithm ", " headers ", " signature
userId := "username" "=" plain-string
algorithm := "algorithm" "=" DQUOTE (hmac-sha256) DQUOTE
headers := "headers" "=" plain-string
signature := "signature" "=" plain-string
plain-string   = DQUOTE *( %x20-21 / %x23-5B / %x5D-7E ) DQUOTE

Signature parameters

Parameter Description
usernameThe ID of the credential.
algorithmDigital signature algorithm used to create the signature. You should use hmac-sha256.
headersList of HTTP header names, separated by a single space character, used to sign the request.
signatureBase64 encoded digital signature generated by the client.

Sample authorization header

Authorization: hmac userId="user2@XCN1139",
  algorithm="hmac-sha256",
  headers="date content-type content-length",
  signature="XWL1oxJsbC4z3UvO6ZfvgjMvfj249WXSb7Gl/+t/Ql0="

Signature string construction

To generate the string that is signed with a secret, the client must take the values of each HTTP header specified by headers in the order they appear.

  1. If the header name is not request-line, then append the lowercase header name followed with an ASCII colon : and an ASCII space ' '.
  2. If the header name is request-line, then append the HTTP request line (in ASCII format), otherwise append the header value.
  3. If the value is not the last value, then append an ASCII newline \n. The string must not include a trailing ASCII newline.

API tracing

You can set X-Request-ID on the request's HTTP header to trace each API call. The system echos back this header in the response.

Status and error codes

All Integral REST APIs use the following general status codes. See endpoints for specific codes.

HTTP code HTTP statusMeaning
200OKSuccessful submission.
202ACCEPTEDRequest accepted by the system. You are expected to make another API call. Refer to individual API sections and endpoints for subsequent action.
400BAD REQUESTThere is an issue with request parameters. May have a message body that indicates the error. Refer to individual API sections and endpoints for specific errors.
401UNAUTHORIZEDYour IntegralAPI user is not authorized. May have a message body that indicates the error.
404NOT FOUNDThe endpoint could not be found. Either your valid request did not return any results or your request was malformed. May have a message body that indicates the error. Refer to individual API endpoints to confirm that the endpoint URL and parameters are correct.
500INTERNAL SERVER ERRORStop trading immediately and contact Integral Business Support with a complete error message and full details of the HTTP request and response. May have a message body that indicates the error.

4xx and 5xx status codes may return a JSON response body with the message parameter.

Reason codes

You determine the status of any call with a combination of:

  • Status code from the messaging technology (for example, REST/HTTP codes 200 and 404).
  • The reason code for the server. Not all responses include a reason code.

Use the following codes to interpret and act on status responses.

Reason code Description
RequestValidationError.amountOrder size is invalid.
RequestValidationError.CoIdNotSpecifiedClient order ID not specified.
RequestValidationError.DuplicateOrderOrder already exists for the given client order ID.
RequestValidationError.TypeNotSpecifiedOrder type not specified.
RequestValidationError.TIFNotSpecifiedTime in force not specified.
RequestValidationError.SideNotSpecifiedOrder side (buy or sell) not specified.
RequestValidationError.CurrencyNotSpecifiedOrder dealt currency not specified.
RequestValidationError.InvalidDealtCcyDealt currency is neither base currency nor term currency.
RequestValidationError.SymbolNotSpecifiedSymbol not specified.
RequestValidationError.InvalidCurrencyPairSymbol not valid or not supported by the system.
RequestValidationError.SizeNotSpecifiedOrder size not specified.
RequestValidationError.InvalidOrderQtyOrder size not valid.
RequestValidationError.InvalidPriceAccepted price invalid. Zero is invalid price.
RequestValidationError.BuySellMismatchBuy/Sell side of the accepted price is incorrect.
RequestValidationError.InvalidQuoteIDThe rateId of the previously quoted (PQ) order is invalid.
RequestValidationError.LegalEntitySetIncorrectlyAccount field incorrect.
RequestValidationError.OrderTypeNotSupportedOrder type not supported.
RequestValidationError.PriceMismatchAccepted price not the same as previously quoted price.
RequestValidationError.QuoteExpiredRate associated with the rateId not found. It has expired. Price is no longer valid.
RequestValidationError.tradingDisabledTrading is disabled.
Overview
License Integral
Languages
Servers
Mock server
https://docs.fxinside.net/_mock/openapi/integral-api-reference/rest/
https://3ac93db9-6290-458d-9482-0dc0a0e9607a.remockly.com/

Authentication API

Endpoints to login with token-based authentication.

Operations

Market data

Endpoints to get prices, indicative rates, benchmark rates, and trade ticker rates.

Operations

Orders

Place, cancel, and query orders.

Operations

Trades

Trade operations (book, query, amend, roll, allocate, cancel). Also query orders for fills.

Only brokers and sales dealers can amend, roll, and allocate by default. Customer organizations can be configured to allocate trades (work with your Integral Technical Account Manager).

Operations

RFS/RFQ

The RFS/RFQ endpoints provides API access to two trading workflows:

  • Request for Stream (RFS): a stream of firm quotes from liquidity providers against your quote request for a symbol, tenor, amount, and direction for a given price type.
  • Request for Quote (RFQ): a single quote good for a duration you request. The server must be configured to enable the RFQ workflow. Please contact your Technical Account Manager to discuss settings.

You receive responses against your RFS and RFQ requests using the Query request response API and can choose to either accept the quote, withdraw your quote request, or you can allow the your request or quote to expire.

Request for Stream (RFS) workflow:

  1. Send your request:
    • Set the symbol, tenor, amount, and buy/sell direction.
    • Set the rfq parameter to false.
    • Set the expiry parameter to the expiration time of your stream request.
  2. Query the state of your request.
  3. Do one of the following:
    • Accept the quote.
    • Withdraw your quote request.
    • Let your quote request expire.

Request for Quote (RFQ) workflow:

  1. Send your request:
    • Set the symbol, tenor, amount, and buy/sell direction.
    • Set the rfq parameter to true.
    • Set the expiry parameter to your requested duration of the quote.
  2. Query the state of your request.
  3. Do one of the following:
    • Accept the quote.
    • Withdraw your quote request.
    • Let your quote request expire.
Operations

Request quote

Request

Send a quote request to receive firm quotes from liquidity providers for the specified symbol, tenor, amount, and direction (bid, ask, two-way) for a given price type.

After the initial success response REQUEST_RECEIVED, you must query the status of your request to receive the latest quotes and status (see Query quote request (server ID) and Query quote request (client ID)).

Bodyapplication/json
clOrderIdstring<= 60 charactersrequired

RFS reference ID assigned by you.

symbolstring<= 35 charactersrequired

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

amountnumber(double)required
  • Spot, outright, NDF: dealt amount.
  • Swap: near leg dealt amount.
dealtCurrencystring<= 17 charactersrequired

Dealt currency. Must one of the instruments in symbol.

expiryinteger(int64)[ 30 .. 86400 ]required

The definition of this property depends on the rfq property (rfq):

  • rfq=false (RFS workflow) Request expiry time in seconds when when the request is received. The expiration also depends on the server expiry configuration. Typical expiration time is 120 seconds.
  • rfq=true (RFQ workflow) Duration time in seconds for a single quote. Minimum 30 seconds. Maximum 86400 seconds (24 hours). The server must be configured to enable the RFQ workflow. Please contact your Technical Account Manager to discuss settings.

This parameter can override an expiry/duration default set on the server. The lesser of the expiry value on your request or server default value is applied.

rfqboolean

Quote workflow of the request:

  • false=RFS workflow: request a stream of quotes. The (expiry) property specifies the expiry time of the request.
  • true=RFQ workflow: request a single quote that is valid for a duration specified by the (expiry) property. The server must be configured to enable the RFQ workflow. Please contact your Technical Account Manager to discuss settings.

In both workflows, a default expiry/duration can be set on the server. The lesser of the expiry value on your request or server default value is applied.

nearValueDatestring<= 20 charactersrequired

Tenor or broken date in the format YYYY-MM-DD

  • Spot, outright: value date.
  • Swap: near leg value date.
  • NDF: value date if fixingDate not specified.
farDealtAmountnumber(double)

Required for swaps, fwd/fwds, NDF swaps. Far leg dealt amount.

farValueDatestring<= 20 characters

Required for swaps, fwd/fwds, NDF swaps. Tenor or broken date in the format YYYY-MM-DD.

  • Swap, fwd/fwd: far leg value date.
  • NDF swap: value date required if farFixingDate not specified.
fixingDatestring<= 20 characters

NDF fixing date, tenor or broken date in the format YYYY-MM-DD. Required if nearValueDate not specified.

farFixingDatestring<= 20 characters

NDF swap far leg fixing date, tenor or broken date in the format YYYY-MM-DD. Required if farValueDate not specified.

sidestring<= 10 charactersrequired

BUY, SELL, or TWO_WAY from the requester’s perspective and always for the dealt currency.

priceTypestring<= 32 charactersrequired
  • Spot
  • Outright
  • NDF
  • Swap
  • FwdFwd
  • NDFSwap
customerAccountstring<= 30 charactersrequired

ID of the legal entity for which quote request is being executed.

customerOrgstring<= 30 charactersrequired

ID of the organization for which quote request is being executed.

priceViewTypeinteger[ 0 .. 1 ]

Whether quotes from all liquidity providers are collected into a single response (recommended) or each provider quote is sent as separate response:

  • 1=quotes collected into a single response (recommended).
  • 0 or any positive integer=non aggregated view, each liquidity-provider quote is sent as a separate response.
depthinteger>= 1

Requested depth-of-book starting with the top of the book. For example, if set to 5, you receive a maximum of 5 quotes on each side (buy/sell) is 5 as long as providers respond with 5 or more quotes.

providersArray of strings

List of provider IDs to receive the request. If not specified, the server sends the request to all eligible providers.

application/json
{ "clOrderId": "view1MultiLP5", "symbol": "EUR/USD", "amount": 1000000, "dealtCurrency": "EUR", "expiry": 140, "nearValueDate": "1W", "farDealtAmount": 1000000, "farValueDate": "2W", "side": "TWO_WAY", "priceType": "FwdFwd", "customerAccount": "pfOrgLE", "customerOrg": "pfOrg", "providers": [ "ProvA", "ProvB", "ProvC" ] }

Responses

Confirmation with your request ID clOrderId, the server request ID requestId, and request status in the event field.

Bodyapplication/json
requestIdstring<= 255 characters

ID assigned to your request by the server. Use this ID to accept a quote. You need to use this ID or your ID clOrderId to query your request to get quotes and status.

clOrderIdstring<= 60 characters

ID assigned by you from your request. You need to use this ID or the server ID requestId to query your request to get quotes and status.

eventstring<= 50 characters

REQUEST_RECEIVED Indicates the request is received for processing. You need to query your request for get quotes and status of your request.

Response
application/json
{ "clOrderId": "view1MultiLP5", "requestId": "G4796976d517b17818a0021e", "event": "REQUEST_RECEIVED" }

Query quote request (client ID)

Request

Query the state of quote request by the RFS ID clOrderId assigned by you when you sent the request. The response can include quotes, trades, and state of the Quote request.

Query
clOrderIdstring<= 255 charactersrequired

The ID assigned by you when you submitted the request. Sent in the clOrderId field of the request.

Example: clOrderId=view1MultiLP5
No request payload

Responses

A JSON object with the quote status. May include quotes and trades.

Bodyapplication/json
clOrderIdstring<= 60 characters

ID assigned by you from your request. You need to use this ID or the server ID requestId to query your request to get quotes and status.

requestIdstring<= 255 characters

Request ID assigned by Integral. Use this ID to accept a quote. You need to use this ID or your ID clOrderId to query your request to get quotes and status. Returned in requestId of Request quote.

transactionIdstring<= 255 characters

Request transaction ID assigned by Integral. Not used by you.

ttlnumber(int32)

Originating RFS request expiry time.

eventstring<= 50 characters

QUOTE: a quote in response to your request for quote.

Discriminator
quotesArray of objects(quote)

Collection of quotes.

Response
application/json
{ "clOrderId": "rjv_566", "requestId": "G4796976d5_228bd_19587256c877", "transactionId": "FXI9445344076", "ttl": 7200, "event": "QUOTE", "quotes": [ {} ] }

Query quote request (server ID)

Request

Query the state of quote request by the RFS ID assigned by Integral. The response can include quotes, trades, and state of the Quote request.

Path
requestIdstring<= 255 charactersrequired

Request ID assigned by Integral. Returned in requestId of the response to Request quote.

Example: G4796976d517b1786e1fa242
No request payload

Responses

A JSON object with the quote status. May include quotes and trades.

Bodyapplication/json
clOrderIdstring<= 60 characters

ID assigned by you from your request. You need to use this ID or the server ID requestId to query your request to get quotes and status.

requestIdstring<= 255 characters

Request ID assigned by Integral. Use this ID to accept a quote. You need to use this ID or your ID clOrderId to query your request to get quotes and status. Returned in requestId of Request quote.

transactionIdstring<= 255 characters

Request transaction ID assigned by Integral. Not used by you.

ttlnumber(int32)

Originating RFS request expiry time.

eventstring<= 50 characters

QUOTE: a quote in response to your request for quote.

Discriminator
quotesArray of objects(quote)

Collection of quotes.

Response
application/json
{ "clOrderId": "rjv_566", "requestId": "G4796976d5_228bd_19587256c877", "transactionId": "FXI9445344076", "ttl": 7200, "event": "QUOTE", "quotes": [ {} ] }

Accept quote

Request

Accept a quote received in response to a quote request to trade with liquidity providers.

Path
requestIdstring<= 255 charactersrequired

Request ID assigned by Integral. Returned in requestId of the response to Request quote.

Example: G4796976d517b1786e1fa242
Bodyapplication/json
quoteIdstring<= 255 charactersrequired

Quote ID from one of the quotes received in response to a Query Request.

sidestring<= 10 charactersrequired

BUY or SELL from the requester's perspective and always for the dealt currency. For multi-leg requests this is the side of far leg.

Example: "BUY"
symbolstring<= 35 charactersrequired

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

dealtCurrencystring<= 17 charactersrequired

Dealt currency.

clOrderIdstring<= 60 charactersrequired

Originating RFS ID assigned by you.

application/json
{ "quoteId": "G-4796976cf-17b1781b062", "side": "BUY", "symbol": "GBP/USD", "dealtCurrency": "USD", "clOrderId": "view1MultiLP5" }

Responses

Quote accepted. Response has no message body.

Withdraw quote request

Request

Withdraw an active quote request.

Path
requestIdstring<= 255 charactersrequired

Request ID assigned by Integral. Returned in requestId of the response to Request quote.

Example: G4796976d517b1786e1fa242
No request payload

Responses

Accepted response with no message body.

Positions

Get open positions.

Operations

Custody

Custody operations.

Operations

STP download

Get executed trades that have not been downloaded before.

To get trades that have been previously downloaded, you must first call the Prepare trades to resend endpoint.

Operations

Reference data

Fundamental business data (such as accounts, assets, and symbols) used by multiple endpoints.

Operations