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.

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.