Interactive Brokers

Statements & Trade Confirmations

PDF
Create a PDF of this page to save or print.

Flex Queries - Flex Web Service

Our Flex Web Service allows IB customers to access pre-configured Flex Queries via the HTTPS protocol, without logging into Account Management. This feature enables customers to write automated client software in their preferred language which can request previously defined FlexStatement queries in real-time.

There are currently two versions of the Flex Web Service available: Version 2 and Version 3. Version 3 allows you to specify which version you are using and returns more meaningful error messages. Both versions are described below.


1. Enabling the Flex Web Service

To enable the FlexWeb Service for an account, log in to Account Management and click on the link labeled "Flex Web Service" under the Report Management menu. Clicking this link will enable the Flex Web Service for the account.

Before obtaining a token, it is important to check that the Service Status is Active. If the status is set to Suspended, simply click the link to reactivate.

2. Obtaining the token

You will receive a token on the same screen confirming that the Flex Web Service has been enabled. This token will be used to:

  1. Initiate a Flex request, and
  2. Retrieve a Flex report

The token is valid for a 6 hour period by default, after which time you must obtain a new token through Account Management. You have the option of increasing the time frame for which a Flex Token is valid. The token can also be attached to a specific IP address for greater security.

3. Initiating an automated Flex Web Service request

To initiate a Flex automated request you will need the following information:

  1. Initial URL: https://www.interactivebrokers.com/Universal/servlet/FlexStatementService.SendRequest
  2. Token: Obtained above
  3. Flex Query ID: The ID generated when creating a Flex query.

Note: Programmatic access requires the User-Agent HTTP header to be set. Accepted values are: Blackberry or Java.


Version 2 Query Format

https://www.interactivebrokers.com/Universal/servlet/FlexStatementService.SendRequest?t=TOKEN&q=QUERY_ID&v=2

TOKEN: the token that you already obtained
QUERY_ID: the Flex Query ID generated when you created the Flex Query
v=2: specifies that you are using Flex Web Service Version 2. Note that if you do not specify a Version, the system will use Version 2.


Version 2 XML Response

You will recieve an XML response from IB, which containing the following information:

  • Reference Code - If the request was successful, the XML response will contain a numeric reference code. This code will be used to retrieve the generated Flex query. If the request was unsuccessful, you will receive an error message as the code.
  • Response URL - This is the URL to be used to retrieve the Flex report.

Version 2 Sample XML Response

If successful:

If an error occurred:


Version 3 Query Format

https://www.interactivebrokers.com/Universal/servlet/FlexStatementService.SendRequest?t=TOKEN&q=QUERY_ID&v=3

TOKEN: the token that you already obtained
QUERY_ID: the Flex Query ID generated when you created the Flex Query
v=3: specifies that you are using Flex Web Service Version 3. Note that if you do not specify a Version, the system will use Version 2.


Version 3 XML Response

You will receive an XML response from IB, which containing the following information:

  • Status - If the request was successful, Status will be Success. If the request was unsuccessful, Status will be Fail.
  • Reference Code - If the request was successful, the XML response will contain a numeric reference code. This code will be used to retrieve the generated Flex query.
  • Response URL - This is the URL to be used to retrieve the Flex report.

Version 3 Sample - Successful XML Response

If the request was unsuccessful, the response will contain the following parameters:

  • <Status>Fail</Status>.
  • <ErrorCode>XXXX</ErrorCode> (where XXXX = a numeric error code)
  • <ErrorMessage>TEXT</ErrorMessage> (where TEXT is a text description of the specific error)

Version 3 Sample - Unsuccessful XML Response

4. Retrieving the Flex Report

In order to retrieve the Flex data you will need the following information:

  • Response URL: This is the URL you received as part of the response when you placed the request.
  • Reference Code: This is the code you received as part of the response when you placed the request.
  • Token: This will be the same validation token used to initiate the Flex request.
  • Version: Set to 2 or 3.

Note: If statements are still being generated when you submit your request to retrieve them, do NOT re-initiate the Flex request. Instead, just keep trying to retrieve the statement.


Query Format

https://www.interactivebrokers.com/Universal/servlet/FlexStatementService.GetStatement?q=REFERENCE_CODE&t=TOKEN&v=VERSION

REFERENCE_CODE: the code you received as part of the response when you placed the request.
TOKEN: the token that you already obtained
VERSION: 2 or 3, the Flex Web Service Version you are using. Note that if you do not specify a Version, the system will use Version 2.

You will receive the Flex data as the response if the request was successful. Otherwise, you will receive a XML based response informing you that the request was invalid.


Version 2 Sample XML Response if the Request was Unsuccessful


Version 3 Sample XML Response if the Request was Unsuccessful

Error Codes

The following table lists all of the error codes and error descriptions returned in the ErrorCode and ErrorMessage parameters.


ErrorCode ErrorMessage
1001 Statement could not be generated at this time. Please try again shortly.
1003 Statement is not available.
1004 Statement is incomplete at this time. Please try again shortly.
1005 Settlement data is not ready at this time. Please try again shortly.
1006 FIFO P/L data is not ready at this time. Please try again shortly.
1007 MTM P/L data is not ready at this time. Please try again shortly.
1008 MTM and FIFO P/L data is not ready at this time. Please try again shortly.
1009 The server is under heavy load. Statement could not be generated at this time. Please try again shortly.
1010 Legacy Flex Queries are no longer supported. Please convert over to Activity Flex.
1011 Service account is inactive.
1012 Token has expired.
1013 IP restriction.
1014 Query is invalid.
1015 Token is invalid.
1016 Account is invalid.
1017 Reference code is invalid.
1018 Too many requests have been made from this token. Please try again shortly.
1019 Statement generation in progress. Please try again shortly.
1020 Invalid request or unable to validate request.
1021 Statement could not be retrieved at this time. Please try again shortly.

http://www.interactivebrokers.com/en/index.php?f=asr_statements_tradeconfirmations&p=flexqueries4