Account Management API

Introduction

Copy Location

Interactive Brokers (IBKR) Account Management API is available for Registered Advisors and Introducing Brokers that would like to customize IBKR’s Registration System and Client Portal or control client experience.

The Account Management API can be used in parallel or as a replacement to the IBKR Portal which is our out of the box solution available to registered advisors and introducing brokers free of cost.

Audience

Copy Location

Service is available by request only to advisors/brokers that are registered in a FATF Country. See Setup Process for instructions on how to get started.

Connectivity

Copy Location

IBKR’s Web API implementation follows standard HTTP verbs for communication. It employs a range of HTTP status codes and JSON-formatted messages to convey operation status and error information. To ensure secure communication, all API requests must use HTTPS. Authorization and Authentication for IBKR’s Web API is managed using OAuth 2.0.

Authentication

Copy Location

IBKR only supports private_key_jwt client authentication as described in RFC 7521 and RFC 7523.

• Client authenticates against the authorization server by presenting a signed JWT token called a client_assertion which the authorization server validates against the public key(s) provided by the client during registration.

• This scheme is considered safer than the standard client id/client secret authentication scheme used in early OAuth 2.0 integrations given that it prevents the client from having to pass the client secret in back-end requests.

Data Transmission

Copy Location

User requests will be sent to IBKR in JSON format using HTTPS.

• [POST] and [PATCH] gw/api/v1/accounts, the payload includes archive (zip) file, encoded in base64.
• All other [POST] and [PATCH] requests, the payload will include JSON file that is encoded in base64.

System Availability

Copy Location

System Status: https://www.interactivebrokers.com/en/software/systemStatus.php

Rate Limiting

Copy Location

For the Account Management Web API, Interactive Brokers currently enforces a global request rate limit of 10 requests per endpoint. If rate limit is exceeded, the API will return a 429 code.

Support

Copy Location

IBKR has a designated API team that is available for 24/5 support via email and will be primary point of contact during the integration process.

• Account Management API: dam@ibkr.com
• Trading API: api@ibkr.com

What We Provide

Copy Location

Figuring out where to begin start is the hardest part. To assist with getting started, we have created guides and API references which include everything you need to program your interface for Client Registration, Account Maintenance, Trading, and Portfolio Management. Your designated integration manager will be available for weekly calls throughout the integration process and up to 3 months after going live.

Resources

Copy Location

To help better understand the API endpoints, we suggest installing postman and install our postman collection. To receive a copy of the postman collection, contact dam@ibkr.com.

Setup Process

Copy Location

IBKR’s account registration system and client portal are carefully engineered to meet our requirements; any request to outsource application workflow requires additional approval. We have summarized steps involved to use API for registration and funding in sequential order.

Preliminary

Copy Location

1. Download and complete DAM Request Form.
2. Send completed form to dam@ibkr.com with your IBKR account number.
   • A representative from our API integration team will setup a 30-minute call to review the completed form.
   • Team is available Monday-Friday between 3am EST to 5pm EST.
3. After the preliminary call, IBKR will provide service agreement(s) needed to use API service(s).
   • Return signed copy to dam@ibkr.com. IBKR API Integration Team will review request with IBKR Compliance.
     • Approval process cannot be started until IBKR master account is opened.
     • Approval process can take 3-5 business days.

Build and Test

Copy Location

IBKR will create QA instance reflective of your intended account structure which can be used to safely test our API solutions.

1. To setup the QA (sandbox) environment, provide the following to dam@ibkr.com:
   • RSA key (RSA-3072 or RSA-4096)
     • What is ssh-keygen & How to Use It to Generate a New SSH Key?
     • Generate RSA Key Pair on Windows (ibkrguides.com)
   • IP Addresses (CIDR format)
2. IBKR will share QA credential (Client ID).
3. Build user interface which will be used to collect and manage client data.
4. Test user interface
   • Suggested test cases can be found here.

Go Live

Copy Location

1. If all development work is complete and your team is ready to go live with the API integration, complete following:
   • Provide IBKR with RSA Key for production using the IBKR message center.
     • RSA key for production cannot be same as key that is used for QA
   • Contact your API integration manager with the following:
     • Web ticket number associated with RSA Key
     • Summary of services which will be offered within platform
       • Example: Hybrid registration, account deposits, single sign on for client portal, add trading permissions
     • Instructions to access application interface in QA
     • Screenshots of registration journey in sequential order (PDF)
     • Signed Services Agreement (if this was not done during preliminary steps).
2. IBKR will review and test interface.
   • This process can take 3-5 business days
   • During this period, IBKR can provide feedback on changes that are needed to go live.
3. IBKR will send email with approval status of interface. If approved, IBKR will provide production credentials (Client ID) to your team using the IBKR message center.
4. Test connectivity with the production credentials. If successful, provide following to your IBKR API integration manager:
   • URL address to the application in the Production Environment.
   • Contacts for Production (operations and maintenance).
5. Launch to Production

Client Registration

Copy Location

The accounts endpoint can be used to create a brokerage account with IBKR using the API. For client registration using the API, we offer two options:

• Full Integration: Hosting firm provides all data and forms required to create IBKR brokerage account via API.

• Hybrid: Submit partial application data to IBKR via API to create the account. User will enter remaining application data via the IBKR White Branded application. The application will be prefilled with data that was passed via the API.
  • Connect user to IBKR White Branded Registration using Single Sign On. Alternatively, provide user with login URL to access IBKR Portal. Upon accessing IBKR Portal, user will be prompted to complete registration journey.

_{Available registration options at IBKR including IBKR hosted solutions can be found here.}

Full Integration versus Hybrid

Copy Location

It is important to determine which option your team will use for client registration before starting the the technical integration. If you are just getting started or development team has limited capacity, we suggest using our Hybrid option and transition to Full Integration in later phase (if desired).

The table below includes the differences between Full Integration and Hybrid for client registration.

Data for Client Registration

Copy Location

Required data to create client account via the API is dependent on the following factors:

1. Customer Type 
   • FD= Fully-Disclosed Introducing Broker
   • FA= Registered Investment Advisor
   • OWD= One Way Disclosed Introducing Broker
   • NonQI= Non-Disclosed Introducing Broker ; Non Qualified Intermediary
   • QI with Trading= Non-Disclosed Introducing Broker; Qualified Intermediary where clients have access to trading
   • QI with No Trading= Non-Disclosed Introducing Broker; Qualified Intermediary where clients do not have access to trading via IBKR system (eg. Trades will be placed via FIX).
2. Registration Type
   • Hybrid
   • Full Integration
3. Account Type
   • Retail = Individual, Joint, Retirement, ISA
   • Entity = SMSF, Trust, Organization
4. IBKR Entity Driven by entity which master account is associated with. While accounts are accepted from citizens or residents of all countries except citizens or residents of those countries that are prohibited by the US Office of Foreign Assets Control, advisors/brokers may be limited from opening accounts for applicants that reside in the following countries:
   • United States: Available to U.S. based IB-LLC brokers and advisors only.
   • Canada: Available to IB-CAN brokers and advisors only.
   • Hong Kong: Available to IB-HK brokers and advisors only.
   • Australia: Available to IB-AU brokers and advisors only.
   • Japan: Available to IBLLC brokers and advisors that are FSA Registered only.
   • United Kingdom: Available to IB-UK brokers only.
   • Singapore: Available to IB-SG brokers and advisors only.
   • EEA: Available to IB-IE or IB-CE brokers and advisors only.

Expand each section to see specific field requirements by Customer Type.

_{*Required for Hybrid; else optional. If provided for Hybrid, data will be prefilled.}

KYC Documents

Copy Location

Identity and Address Verification

Copy Location

Real-time Trulioo verification is processed upon account creation for select countries. If Trulioo is verification is not successful, OR Trulioo verification is not supported or the country which the applicant resides in, Identity and Address verification is required for approval.

Trulioo is supported for applicants that reside in following countries

Other countries

• Identity and Address verification will always be required for approval.

Options for Identity and Address Verification

Option 1: Traditional Verification

Collect Proof of ID and Proof of Address documents from the client and submit documents to IBKR documentSubmission.

Processing Time: IBKR has a ‘follow the sun’ model with operators located globally and constantly reviewing and processing supporting documents for new applications. Documents typically processed within 24 hours. Meaning, accounts are approved/opened within 24 hours of the supporting documents being accepted by IBKR.

• Causes for delays could be unsupported doc type is submitted or image received is blurry/too dark

Registration Tasks

• 8001: Proof of Identity (POI)
• 8002: Proof of Address (POA)
  Important to note: For IB-HK Non-Disclosed (QI and NonQI) clients, we only require Proof of Identity (8001).
  
  • Important to note: For IB-HK Non-Disclosed (QI and NonQI) clients, we only require Proof of Identity (8001).

Option 2: Instant Verification

Opt to allow clients to verify using Au10tix (third-party application used to verify client’s identity /geo location).

• If Trulioo is NoMatch, IBKR will pass unique URL which can be used to connect user to Au10Tix to complete verification. The URL is valid for 24 hours. If more than 24 hours, a new URL will need to be generated using /api/v1/accounts/{{accountId}}/kyc endpoint.

Workflow:

• Embed Au10Tix URL or provide a QR code with Au10Tix URL within application.
• User accesses Au10Tix URL and will be prompted to complete consent message verifying they are OK for Au10Tix to capture Biometric information.
  • If user consents, they will be prompted to take photos of the front and back of their ID’s and take a selfie.
  • Au10Tix will process information and complete ID verification.
  • If Au10Tix verification fails; user will be required to complete ‘Traditional Verification) and Provide a Proof of Address and Proof of Identity Document.
• If user declines consent, they will be prompted to complete Traditional Verification

Processing Time: Real-Time verification is completed- if Au10Tix verification passes; account will be approved/opened (Real-Time).

Registration Tasks:

• 8137: Au10Tix Identity and Address Verification
• 8437: Au10Tix Identity

Account Statuses

Copy Location

The status of an account can be one of the following:

The status can change from:

Close Account

Copy Location

The /gw/api/v1/accounts/close can be used to close an opened account based on the accountId. Requests are processed between 8am EST to 11am EST. Requests received outside of these hours will be processed the following day.

• Accounts eligible to be closed must have current status of O or Q.
• If status Q account is closed, status will move to R (rejected)

If an account is funded at the time of the closure request, withdrawalInfo with bankInstructionName and bankInstructionMethod will need to be set. IBKR will send excess funds to this instruction once the account is closed.

POST /gw/api/v1/accounts/close

{
  "instructionType": "account_close",
  "instruction": {
    "clientInstructionId": "1012983",
    "accountId": "U46377",
    "closeReason": "not required",
    "withdrawalInfo": {
      "bankInstructionName": "test instruction",
      "bankInstructionMethod": "WIRE"
    }
  }
}

Cancel Application

Copy Location

The abandonAccount can be used to delete/cancel a pending application based on the accountId. Once the request is processed, the account will no longer appear in IBKR’s CRM as a PENDING account.

• Accounts eligible to be abandoned must have current status of P or N.

PATCH /gw/api/v1/accounts

{
    "accountManagementRequests": {
        "abandonAccount" : [
            {
                "referenceAccountId" : "U12345"
            }   
        ]
    }
}

Reset Application

Copy Location

The resetAbandonedAccount can be used to reset application that was previously marked abandoned based on the accountId. Accounts eligible to be reset must have current status of A and be less than 6 months old. Once the account has been reset, user can proceed with registration process.

PATCH /gw/api/v1/accounts

{
    "accountManagementRequests": {
        "resetAbandonedAccount" : [
            {
                "referenceAccountId" : "U12345"
            }   
        ]
    }
}

View Status by Account

Copy Location

The /gw/api/v1/accounts/{accountId}/status can be used to query the status by account. In addition to the status of the account, the response will include the following information:

View Status for Group of Accounts

Copy Location

The /gw/api/v1/accounts/status can be used to filter custom group of accounts associated with masterAccountId based on the following criteria:

Queries returning more than 10,000 results will trigger a timeout error, Implement pagination using ‘limit‘ and ‘offset‘ parameter to manage large result sets.

Registration Tasks

Copy Location

Registration tasks represent tasks required to activate or maintain a brokerage account at IBKR.

• Tasks include steps in the application sequence, client agreements and disclosures, tax form, supporting documents for approval, and additional verification tasks (Enhanced Due Diligence).
• Tasks can be used to track the lifecycle of an account and identify if client action is required to proceed with approval process.

The following attributes will be returned when viewing registration tasks associated with an account:

View Registration Tasks

Copy Location

IBKR will include the status of registration tasks in response file that is returned when creating an account via the API.

documents: Represents tasks that were included and processed when creating account via the API.

pendingTasks: Represents tasks that are required for account approval. Hosting firm is responsible for communicating pending tasks required for approval to the end user.

The gw/api/v1/accounts/{accountId}/tasks can be used to view registration tasks which are associated with an account after an account has been created.

IBKR segregates tasks into two types:

type=pending: View pending (incomplete) registration tasks which are required for account approval.

• If a registration task is assigned to a pending account and the task is not required for account approval, the task will not be returned in response.
• If registration task is assigned to an opened account and the task is required for an account upgrade, the task will not be returned in response.

type=registration :View all tasks associated with an account irrespective of the account status or state of the registration task.

• View date/time which user completed specific registration task.
• View registration tasks which the client needs to complete in order to trade or maintain account with IBKR.

Complete Registration Tasks

Copy Location

The [PATCH]/api/v1/accounts/ can be used to complete registration tasks for an existing account.

PATCH /api/v1/accounts/

{"accountManagementRequests": {        "documentSubmission": [
            {
                "documents": [
                    {
                        "signedBy": [
                            "Jane Doe"
                        ],
                        "attachedFile": {
                            "fileName": "ProofOfId.pdf",
                            "fileLength": 9508,
                            "sha1Checksum": "b6e3235d3d21dc999da2fa24c7009ad0815e7330"
                        },
                        "formNumber": 8001,
                        "validAddress": true,
                        "execLoginTimestamp": 20210929123113,
                        "execTimestamp": 20210929123113,
                        "proofOfIdentityType": "Drivers License"
                    }
                ],
                "referenceAccountId":"U123456,
                "inputLanguage": "en",
                "translation": false
            }
        ]
    }

Account Information

Copy Location

The /api/v1/accounts/{{accountId}}/details can be used to view account information based on the accountId.

The endpoint returns same data that is returned in IBKR’s end of day Acct_Status including:

• Profile Information (Name, Address, Contact Information, Employment Information)
• Fee Configuration
• Trading Capabilities (requested, approved, activated)
• Application Information (Date Started, Date Approved, Date Opened, Status, Date Funded)
• Account Configuration (Base Currency, Permissions, Special Programs)
• Market Data Subscriptions
• Financial Information (Net Worth, Income, Sources of Wealth)
• Risk Score
• Last Login
• User (Username, Last Login, Two Factor Authentication)

Update Information

Copy Location

The [PATCH]/api/v1/accounts/ can be used to manage user-level and account-level settings.

• Changes applied at the user level will be applied to all accounts associated with the user.
• Updates are only supported for accounts that are opened.
• Alternatively, information changes can be initiated within the IBKR Portal.

User

Copy Location

PATCH /gw/api/v1/accounts

{
    "accountManagementRequests": {
        "changeAccountHolderDetails": [
            {
                "newAccountHolderDetails": [
                    {
                        "id": "172032379"
   {
            "name": {
              "salutation": "Ms.",
              "first": "Jane",
              "last": "Smith"
            },
                "referenceUserName": "joesm123",
                "inputLanguage": "en",
                "translation": false
            }
        ]
    }
}

PATCH /gw/api/v1/accounts

{
    "accountManagementRequests": {
        "addMiFirData": [
            {
                "referenceAccountId": "U12345",
                "title": "ACCOUNT_HOLDER",
                "identifications": [
                    {
                        "citizenship": "Liechtenstein",
                        "passport": "A11111",
                        "alienCard": "AlienCard",
                        "expire": false
                    }
                ]
            }
        ]
    }
}

PATCH /gw/api/v1/accounts

"accountManagementRequests": {
    "updateCredentials": [
        {
            "referenceUserName": "ctest9751",
            "updateEmail": {
             "email": "abqa@ibkr.com",
             "token": "12345",                
            "access": true
            }
        }
    ]
  }
}

PATCH /gw/api/v1/accounts

{
  "accountManagementRequests": {
    "updateWithholdingStatements": [
        {
            "referenceAccountId": "U12345",
            "treatyCountry": "CHN",
            "fatcaCompliantType": "FATCA_COMPLIANT",
            "effectiveDate": "2020-01-02",
            "certW8Imy": true,
            "usIncomeTax": true
        }
    ]
  }
}

PATCH /gw/api/v1/accounts

{
    "accountManagementRequests": {
        "updateTaxForms": [
            {
                "referenceAccountId": "U12345",                "entityId": "123456",
                "externalId": "Test12346",
                "documents": [
                    {
                        "formNumber": "5001",
                        "execTimestamp": "20161221123500",
                        "execLoginTimestamp": "20161221123500",
                        "signedBy": [
                            "John Doe"
                        ],
                        "attachedFile": {
                            "fileName": "Form5001.pdf",
                            "fileLength": "67700",
                            "sha1Checksum": "D8AA699678D12DE6AC468A864D4FAE7999AA904B"
                        }
                    }
                ],
                "w8Ben": {
                    "name": "John Doe",
                    "explanation": "TIN_NOT_REQUIRED",
                    "part29ACountry": "CAN",
                    "cert": true,
                    "blankForm": true,
                    "taxFormFile": "Form5001.pdf",
                    "proprietaryFormNumber": "5001"
                }
            }
        ]
    }
}

Account

Copy Location

PATCH /gw/api/v1/accounts

{
    "accountManagementRequests": {
        "accountConfiguration" : [
            {
                "referenceAccountId" : "U12345",
                "type" : "LiteExecution",
                "value" : "true"
            }   
        ]
    }
}

PATCH /gw/api/v1/accounts

{
  "accountManagementRequests": {
    "accreditedInvestors": [
        {
            "referenceAccountId": "U12345",
            "status": true,
            "signedBy": [
                "Test Test"
            ],
            "qualifiedPurchaser": {
                "status": true,
                "qualifiedPurchaserDetails": [
                    {
                        "code": "InvestmentCompanyAct",
                        "status": true
                    },
                    {
                        "code": "DiscretionaryBasis",
                        "status": true
                    }
                ]
            },
            "eligibleContractParticipant": {
                "status": true,
                "eligibleContractParticipantDetails": [
                    {
                        "code": "HighRisk",
                        "status": true
                    },
                    {
                        "code": "DiscretionaryBasis",
                        "status": false
                    }
                ]
            }
        }
    ]
  }
}

PATCH /gw/api/v1/accounts

{
    "accountManagementRequests": {
        "addCLPCapabilities" : [
            {
                "referenceAccountId" : "U12345"
            }   
        ]
    }
}

PATCH /gw/api/v1/accounts

{
    "accountManagementRequests": {
        "addLevFxCapabilities" : [
            {
                "referenceAccountId" : "U12345"
            }   
        ]
    }
}

PATCH /gw/api/v1/accounts

{
  "accountManagementRequests": {
    "addTradingPermissions": [
      {
        "tradingPermissions": [
          {
            "assetClass": "STK",
            "exchangeGroup": "EU-IBET",
            "country": "BELGIUM",
            "product": "STOCKS"
          }
        ],
        "referenceAccountId": "U123456"
      }
    ]
  }
}

PATCH /gw/api/v1/accounts

{
    "accountManagementRequests": {
        "addTradingPermissions": [
            {
                "tradingPermissions": [
                    {
                        "assetClass": "STK",
                        "exchangeGroup": "EU-IBET",
                        "country": "BELGIUM",
                        "product": "STOCKS"
                    }
                ],
                "documentSubmission": {
                    "documents": [],
                    "referenceAccountId":"U123456",
                    "inputLanguage": "en",
                    "translation": false
                },
                "referenceAccountId":"U123456"
            }
        ]
    }
}

PATCH /gw/api/v1/accounts

{
    "accountManagementRequests": {
        "changeBaseCurrencies": [
            {
                "referenceAccountId": "U12345",
                "newBaseCurrency": "USD"
            }
        ]
    }
}

PATCH /gw/api/v1/accounts

{
    "accountManagementRequests": {
    "changeFinancialInformation": [
        {
          "referenceAccountId": "U12345",
          "newFinancialInformation": {
            "investmentExperience": [
              {
                "assetClass": "BILL",
                "yearsTrading": 2,
                "tradesPerYear": 5,
                "knowledgeLevel": "Extensive"
              }
            ],
            "investmentObjectives": [
              "Trading",
              "Growth",
              "Speculation",
              "Hedging",
              "Preservation",
              "Income"
            ],
            "additionalSourcesOfIncome": [
                {
                    "sourceType": "CONSULTING",
                    "percentage": 4,
                    "description": "from Spouse"
                },
                {
                    "sourceType": "INHERITANCE",
                    "percentage": 10,
                    "description": "father property"
                }
            ],
            "sourcesOfWealth": [
                {
                    "sourceType": "SOW-IND-Allowance",
                    "percentage": 25,
                    "usedForFunds": false,
                    "description": "Allowance from spouse"
                },
                {
                    "sourceType": "SOW-IND-Disability",
                    "percentage": 50,
                    "usedForFunds": false,
                    "description": "Allowance from spouse"
                },
                {
                    "sourceType": "SOW-IND-Inheritance",
                    "percentage": 23,
                    "usedForFunds": true,
                    "description": "Allowance from spouse"
                }
            ],
            "netWorth": 1700000,
            "liquidNetWorth": 120000,
            "annualNetIncome": 210000,
            "totalAssets": 173000,
            "sourceOfFunds": "string",
            "translated": false
          }
        }
      ]
    }
}

PATCH /gw/api/v1/accounts

{
    "accountManagementRequests": {
       "changeMarginTypes": ["referenceAccountId": "U12345",
                "newMargin": "Margin"
            }
        ]
    }
}

PATCH /gw/api/v1/accounts

{
    "accountManagementRequests": {
       "changeMarginTypes": [
            {
                "documentSubmission": {
                    "documents": [
                        {
                            "signedBy": [],
                            "validAddress": true,
                            "execTimestamp": 10,
                            "documentType": "Certified Proof of Address",
                            "expirationDate": "2033-11-22"
                        }
                    ],
                    "referenceAccountId": "U12345",
                    "inputLanguage": "en",
                    "translation": false
                },
                "referenceAccountId": "U12345",
                "newMargin": "xMargin"
            }
        ]
    }
}

PATCH /gw/api/v1/accounts

{
    "accountManagementRequests":{
        "enrollInDRIP":{
            "referenceAccountId": "U12345",
        }
    }
}

PATCH /gw/api/v1/accounts

{
    "accountManagementRequests":{
        "leaveDRIP":{
            "referenceAccountId": "U12345",
        }
    }
}

PATCH /gw/api/v1/accounts

{
    "accountManagementRequests":{
        "leaveSYEP":{
            "referenceAccountId": "U12345",
        }
    }
}

PATCH /gw/api/v1/accounts

{
    "accountManagementRequests": {
       "removeTradingPermissions": [
            {
                "tradingPermissions": [
                    {
                        "assetClass": "STK",
                        "exchangeGroup": "AUS-OPT",
                        "country": "BELGIUM",
                        "product": "STOCKS"
                    }

PATCH /gw/api/v1/accounts

{
    "accountManagementRequests": {
        "updateAccountAliases": [
            {
                "referenceAccountId": "U12345",
                "accountAlias": "U111"
            }
        ]
    }
}

PATCH /gw/api/v1/accounts

{
  "accountManagementRequests": {
    "updateAccountRepresentatives": [
        {
            "referenceAccountId": "U12345",
            "representativeDetails": [
                {
                    "representativeId": "ajd0318a",
                    "percentage": 100
                }
            ]
        }
    ]
  }
}

PATCH /gw/api/v1/accounts

{
  "accountManagementRequests": {
    "updateBcan": [
        {
            "referenceAccountId": "U12345",
            "bcan": "1125",
            "ceNumber": "BNO808"
        }
    ]
  }
}

Client Fees

Copy Location

IBKR provides ability for advisors and brokers to charge fee for their services. Advisors/brokers can configure fees on an account by account basis OR manage fees using a client fee template. The API can be used to view and manage fee templates for existing accounts.

• Client fee templates make it easy to maintain client fee schedule for multiple accounts. Fee templates can be created and updated directly within Portal > Administration & Tools > Fees & Invoicing > Fee Templates.
  • Advisor Fees
  • Brokers

View Fee Template for Account

Copy Location

The /gw/api/v1/fee-templates/query endpoint can be used to view fee template that is currently assigned by accountId. FEE_TEMPLATE_NOT_FOUND response will be returned IF no fee template is applied OR if fee configuration applied is not defined by template.

POST /gw/api/v1/fee-templates/query

{
  "instructionType": "get_fee_template",
  "instruction": {
    "clientInstructionId": "1012983",
    "accountId": "U46377"
  }
}

Set Fees for Account

Copy Location

The /gw/api/v1/fee-templates endpoint can be used to assign a predefined fee template to an existing account. Within the body of the request, define the accountId and the templateName. The templateName represents name of fee template to be applied, the data is case sensitive and must match exact name of template that exists in portal.

• For broker clients, fee changes submitted before 17:00 ET are processed on the same day and will take effect starting from midnight on the following business day.
• For advisor-clients, if the fee is increased or fee type is changed, the client will need to verify/acknowledge the fee increase directly in Account Management/Client Portal.
  • Fee templates acknowledged by the client prior to 5:45PM ET will be processed on the same day.
  • Fee templates acknowledged by the client after 5:45PM ET will be processed on the following business day.
  • If the fee is decreased, the fee will be automatically processed (no client acknowledgement is needed).

POST /gw/api/v1/fee-templates

{
  "instructionType": "apply_fee_tempate",
  "instruction": {
    "clientInstructionId": "1012983",
    "accountId": "U46377",
    "templateName": "Test template"
  }
}

Login Messages

Copy Location

If client action is required post account creation, IBKR will assign a login message to the user. Once login message is assigned, user will be prompted to complete login message upon accessing IBKR Portal.

Scenarios which IBKR will assign a login message:

• Expired tax form
• Update CRS form
• Verify Account Information
• Email Bounced

With exception of tax form updates, completion of login messages are only supported within IBKR Portal (not via API).

View Login Messages by Account

Copy Location

The /gw/api/v1/accounts/{accountId}/login-messages can be used to view login messages assigned to a specific account.

View Login Messages for Group of Accounts

Copy Location

/gw/api/v1/accounts/login-messages can be used to filter list of accounts with login messages assigned.

• Filter list of accounts with specific login message assigned.
• Filter list of accounts created within certain time range.

Queries returning more than 10,000 results will trigger a timeout error, Implement pagination using ‘limit‘ and ‘offset‘ parameter to manage large result sets.

Funds and Banking

Copy Location

When submitting a funding requests using the API, a clientInstructionId will be set within body of the request. The clientInstructionId is a unique identifier associated with the request which is set by the hosting firm; this value cannot be reused. IBKR’s preference is that the clientInstructionId is established in sequential order ie 1, 2, 3, 4  or 100, 101, 102, 103 not 777, 589, 123. The maximum value is 20 digits.

Status of Request

Copy Location

IBKR returns response within 30 seconds of funding request being submitted. The response will return one of the following status’

• PROCESSED: Request has been processed.
• PENDING: Pending Processing
• REJECTED: IBKR unable to process the request.

The /gw/api/v1/client-instructions/{clientInstructionId} endpoint can be used to poll for status of previously uploaded funding request based on the clientInstructionId associated with the request.

Cancel Request

Copy Location

Cancel transaction that is currently in a PENDING status, this includes active recurring transaction that are scheduled for future date. The /gw/api/v1/instructions/cancel can be used to cancel a transaction; within the body of the request, include the instructionId that is associated with request that needs to be canceled.

POST /gw/api/v1/instructions/cancel

{
  "intructionType": "CANCEL_INSTRUCTION",
  "instruction": {
    "clientInstructionId": "12001810",
    "instructionId": 43085477,
    "reason": "Testing"
  }
}

Get Transaction History

Copy Location

The /gw/api/v1/instructions/query endpoint can be used to view information about historical transactions including cash deposits, cash withdrawals, inbound and outbound position transfers and internal transfers by accountId. The daysToGoBack attribute will be used to set lookback period and can be maximum of 30 days. Optionally, include transactionType to filter for a specific transaction.

POST /gw/api/v1/instructions/query

{
  "instructionType": "QUERY_RECENT_INSTRUCTIONS",
  "instruction": {
    "clientInstructionId": "7009001",
    "accountId": "U139838",
    "transactionHistory": {
      "daysToGoBack": 3
    }
  }
}

Available Cash for Withdrawal

Copy Location

The /gw/api/v1/external-cash-transfers/query can be used to view the available cash for withdrawal with and without margin loan based on an accountId AND currency. For non-disclosed clients, this endpoint will return available cash to transfer between master and sub account.

Response will return following values:

• withdrawableAmount: Cash Amount available for withdrawal (assuming margin loan). Only applicable for Fully-Disclosed and Advisor Clients.
• withdrawableAmountNoBorrow: Cash Amount available for withdrawal (without margin loan). Only applicable for Fully-Disclosed and Advisor Clients.
• allowedTransferAmountToMaster: Allowed Transfer Amount to Master assuming margin loan. Only applicable for Non-Disclosed Clients.
• allowedTransferAmountToMasterNoBorrow: Allowed Transfer Amount(no_borrow) to Master. Only applicable for Non-Disclosed Clients.
• withdrawableBalanceWithoutOriginHold: The amount available for withdrawal without origination hold.

POST /gw/api/v1/external-cash-transfers/query

{
  "instructionType": "QUERY_WITHDRAWABLE_FUNDS",
  "instruction": {
    "clientInstructionId": "7009005",
    "accountId": "U87440",
    "currency": "USD"
  }
}

Bank Instructions

Copy Location

In this section we will review how to create, view, and delete banking instructions using the Web API. Please be advised options available using the API are limited in comparison to methods that are supported using the IBKR Hosted Application.

Add Bank Instructions

Copy Location

The /gw/api/v1/bank-instructions endpoint can be used to add banking instructions to an existing IBKR brokerage account. The banking instructions can be used to facilitate future fund transfers.

POST /gw/api/v1/bank-instructions

{"instructionType": "ACH_INSTRUCTION",
"instruction": 

{
"clientInstructionId": "1012983",
"bankInstructionCode": "USACH",
"achType": "DEBIT_CREDIT",
"bankInstructionName": "TestInstr",
"currency": "USD",
"accountId": "U223454",
"clientAccountInfo": {
"bankRoutingNumber": "202012983",
"bankAccountNumber": "101267576983",
"bankName": "JPM Chase",
"bankAccountTypeCode": 1
}
}
}

POST /gw/api/v1/bank-instructions

{
"instructionType": "TRADITIONAL_BANK_INSTRUCTION_VERIFICATION",
"instruction": {
"clientInstructionId": 7013057,
"bankInstructionCode": "USACH",
"bankInstructionName": "ACH-Tst1Random172",
"accountId": "U117717",
"pendingInstructionId": 43086786,
"creditAmount1": 0.32,
"creditAmount2": 0.46
}
}

POST /gw/api/v1/bank-instructions

{
"instructionType": "EDDA_INSTRUCTION",
"instruction": {
"clientInstructionId": 7012743,
"bankInstructionName": "My EDDA Instructions",
"currency": "CNH",
"accountId": "U8072517",
"bankBranchCode": "003",
"bankAccountNumber": "132456",
"bankClearingCode": "003",
"debtorIdentificationDocumentType": "hkId"
}

POST /gw/api/v1/bank-instructions

{
"instructionType": "PREDEFINED_DESTINATION_INSTRUCTION",
"instruction": {
"clientInstructionId": 7013053,
"bankInstructionName": "Test Wire Instructions",
"bankInstructionMethod": "WIRE",
"accountId": "U123456",
"currency": "USD",
"financialInstitution": {
"name": "Test Bank",
"branchCode": "",
"identifier": "SBIN001000",
"identifierType": "BIC",
"clientAccountId": "132456789"
}
}
}

View Saved Bank Instructions

Copy Location

When initiating deposit or withdrawal, the user can save the banking information, also referred to as the bankInstructionName. If banking information is saved, the user can reference the bank information for future funding requests rather than re-entering the banking information. The /gw/api/v1/bank-instructions/query endpoint can be used to view list of saved banking instructions on file by accountId and bankInstructionMethod. The response will return the corresponding bankInstructionName and, currency last 4 digits of the bankAccountNumber (if applicable).

POST /gw/api/v1/bank-instructions/query

{
  "instructionType": "QUERY_BANK_INSTRUCTION",  "instruction": {
    "clientInstructionId": "1012983",
    "accountId": "U46377",
    "bankInstructionMethod": "ACH"
  }
}

Delete Bank Instructions

Copy Location

The /gw/api/v1/bank-instructions can be used to delete banking instructions (bankInstructionName) for an existing account by bankInstructionName, currency, and bankInstructionMethod. Users are limited to 6 active banking instructions at a single time.

POST /gw/api/v1/bank-instructions

{
  "instructionType": "DELETE_BANK_INSTRUCTION",
  "instruction": {
    "clientInstructionId": 7013055,
    "accountId": "U46377",
    "bankInstructionName": "Test Delete",
    "bankInstructionMethod": "WIRE",
    "currency": "USD"
  }
}

Cash Transfer

Copy Location

With support for over 20 + currencies, IBKR provides clients the flexibility to make deposits or withdrawals in base and non-base currency balances. Specific currency restrictions may apply, this is determined based on individuals country of residence and the selected funding method. Available currencies can be found here.

The /gw/api/v1/external-cash-transfers can be used to manage cash transfers between external bank account and the IBKR brokerage account. Transfer details including method (ACH and WIRE), transaction type (DEPOSIT or WITHDRAWAL), currency, and amount will be defined within the body of the request.

To supplement the sample requests found in the API reference documentation, we’ve provided a details breakdown of body parameters and their usage in the section that follows.

Deposit Funds

Copy Location

Deposit cash into the brokerage account for trading. The funding process and time for funds to arrive will vary based on the method. Please be advised that methods available via the Web API are limited in comparison to options that are supported within the IBKR Hosted Portal.

Wire Deposit

Copy Location

Wire deposit is the quickest method to fund the brokerage account. Wire deposits arrive immediately to four business days, depending on your bank. Non-U.S. banks are generally at the longer end of the range. Credit to account is immediate upon arrival.

• Fees: Determined by your bank, generally fees do apply.
• Trading Hold: Funds are immediately available for trading after arriving at IBKR.
• Withdrawal Hold: Funds are available for withdrawal after three business days.

A two-step process is used to complete a bank wire:

Step 1: Create deposit notification so that IBKR is aware of the incoming funds. This important step helps ensure the proper routing of your funds if we do not receive your IBKR account number / account title from the wire template you setup at your bank.

Step 2: Contact bank to request bank wire and supply the bank with IBKR’s wiring instructions.

• IBKR wire instructions will vary based on the currency AND IB-Entity which the account is associated with. Contact your API representative to for list of IBKR Wire Instructions.

POST /gw/api/v1/external-cash-transfers
{
  "instructionType": "DEPOSIT",
  "instruction": {
    "clientInstructionId": 7013045,
    "accountId": "U46377",
    "currency": "USD",
    "amount": 100,
    "bankInstructionMethod": "WIRE",
    "sendingInstitution": "Chase Bank",
    "identifier": "123456",
    "specialInstruction": "My Deposit",
    "bankInstructionName": "Instruction",
  }
}

ACH Deposit

Copy Location

U.S. residents with linked bank account can seamlessly deposit funds to their IBKR brokerage account using ACH initiated at IBKR.

• Fees: Free
• Trading Hold: For initial deposit, the first deposit is available to trade four business days after initiating the deposit in Client Portal. Subsequent deposits may be available immediately (depending on tenure, deposit history and account balance). Otherwise, four business days to trade.
• Withdrawal Hold: Funds are available for withdrawal to the originating bank account after five business days. If you wish to withdraw the funds to an account other than the originating bank account, the hold period is 44 business days.

More information on ACH can be found here.

POST /gw/api/v1/external-cash-transfers
{
  "instructionType": "DEPOSIT",
  "instruction": {
    "clientInstructionId": 7013045,
    "accountId": "U46377",
    "currency": "USD",
    "amount": 100,
    "bankInstructionMethod": "ACH",
    "bankInstructionName": "My Checking Account",
  }
}

Withdraw Funds

Copy Location

Withdrawal requests can be initiated via the Web API if standing bank instructions are on file.

• Withdrawal limit is 100K USD. Withdrawal requests for more than 100K USD will need to be summited via the IBKR hosted portal.
• IBKR allows one free withdrawal request per calendar month. After the first withdrawal (of any kind), IBKR will charge the fees listed below for any subsequent withdrawal.
• Information on processing time and fees can be found here.

Wire Withdrawal

Copy Location

At the present, IBKR infrastructure only supports creation of wire withdrawal instructions within IBKR Hosted (not via API). Once instructions have been created, ongoing withdrawal requests can be submitted for standing instruction using the API.

Add Wire Instructions via IBKR Portal

• Advisors and brokers enrolled in Streamlined program can create manage banking instructions on behalf of client within IBKR Portal Broker.
• End user can create banking instructions directly within IBKR Portal under Transfer & Pay > Transfer Funds. Alternatively, connect user to IBKR Portal using Single Sign On (SSO) and set deep link.

POST /gw/api/v1/external-cash-transfers

{ "instructionType": "WITHDRAWAL", 
 "instruction": {    "clientInstructionId": 7013048,
    "accountId": "U46377",
    "bankInstructionName": "Test Withdrawal",
    "bankInstructionMethod": "WIRE",
    "amount": "123.45",
    "currency": "USD",
    "dateTimeToOccur": "2023-11-20T09:12:13Z"
  }

ACH Withdrawal

Copy Location

U.S. residents with linked bank account can seamlessly withdraw funds from IBKR brokerage account to bank account via ACH.

POST /gw/api/v1/external-cash-transfers

{
  "instructionType": "WITHDRAWAL",
  "instruction": {
    "clientInstructionId": 7013048,
    "accountId": "U46377",
    "bankInstructionName": "Test Withdrawal",
    "bankInstructionMethod": "ACH",
    "amount": "500.12",
    "currency": "USD",
    "dateTimeToOccur": "2023-11-20T09:12:13Z"
  }
}

Recurring Transactions

Copy Location

When initiating a deposit or withdrawal request, include recurDetail with transaction details to configure recurring transaction.

• instruction_name: This is the name of the saved recurring transaction and will be displayed within Client Portal under ‘Recurring Transactions’ page.
• frequency: Schedule the transaction to recur at monthly, quarterly or annual intervals.
• start_date: Entered in the format YYYY-MM-DD, this indicates the first date that the recurring transaction should be processed.
• end_date: The end_date is optional and indicates the last date that the recurring transaction should be processed. If null, the transaction will recur indefinitely canceled.

The transaction information entered will be saved and the transaction will recur at the frequency and on the start_date which was entered. In the event the transaction falls on a US non-business day under normal circumstances, we will process the request on the business day prior to the recurring transaction date. In the even this processing leads to multiple withdrawals during the same month, the account holder will be assessed withdrawal fees.

POST /gw/api/v1/external-cash-transfers

{
  "instructionType": "DEPOSIT",
  "instruction": {
    "clientInstructionId": 7013047,
    "accountId": "U46377",
    "currency": "USD",
    "amount": 100,
    "bankInstructionMethod": "WIRE",
    "sendingInstitution": "Sending Institution name",
    "recurDetail": {
      "instruction_name": "Arkansas-Test-Instr",
      "start_date": "2023-10-16",
      "frequency": "MONTHLY"
    }
  }
}

Cancel Recurring Transaction

Copy Location

Recurring transactions that are initiated using the API can be canceled by calling /gw/api/v1/instructions/cancel endpoint. Within the body of the request, include the instructionId of the recurring transaction to be canceled. The instructionId is a unique value assigned by IBKR at creation of the recurring transaction.

Optionally, instructions can be managed within IBKR Portal under Transfer & Pay > Saved Information.

POST /gw/api/v1/instructions/cancel

{
  "intructionType": "cancel_instruction",
  "instruction": {
    "clientInstructionId": "12001810",
    "instructionId": 43085477,
    "reason": "Testing"
  }
}

View Recurring Instructions

Copy Location

The /gw/api/v1/bank-instructions/query endpoint can be used to view active recurring instruction details by accountId. Details include type, method, amount, currency, frequency, start date, and end date.

POST /gw/api/v1/bank-instructions/query 

{
  "instructionType": "get_bank_instruction_details",
  "instruction": {
    "clientInstructionId": "1012983",
    "accountId": "U399192"
  }
}

View Recurring Transactions

Copy Location

View historical transactions associated with a recurring instruction. The look back period is set by numberOfTransactions. Response will include the recurring instruction details and status of the individual recurringTransactionStatus.

POST /gw/api/v1/bank-instructions/query 

{
  "instructionType": "QUERY_RECURRING_EVENTS",
  "instruction": {
    "clientInstructionId": "1012983",
    "ibReferenceId": 206603050,
    "numberOfTransactions": 100
  }
}

Internal Transfer

Copy Location

Internally transfer cash/positions between IBKR accounts based on eligibility.

Processing Time: Our system does not allow internal transfers on Saturdays (any time), Sundays before 3PM EST, and on any evening between 11:45PM-12:30AM EST. Requests submitted outside of these times are processed in real-time.

Transfer Cash Internally

Copy Location

The /gw/api/v1/internal-cash-transfers can be used to transfer cash internally between IBKR accounts based on eligibility.

• Non-Disclosed: Transfer cash between Non-Disclosed Master and Non-Disclosed Sub.
• Fully-Disclosed: Transfer cash from Fully-Disclosed master to sub account.
• All Accounts: Internal transfers supported between existing IBKR accounts IF both source and destination account have matching account titles, country of residence, tax ID, and are associated with the same IB Entity.

Requests submitted outside of downtime are processed in real-time and will be immediate (max of 15 seconds), if request is unable to be processed in 15 seconds, the request will move to a PENDING status. Optionally, include dateTimeToOccur to schedule transaction for set time in the future.

POST /gw/api/v1/internal-cash-transfers

{
  "intructionType": "INTERNAL_CASH_TRANSFER",
  "instruction": {
    "clientInstructionId": "1012983",
    "sourceAccountId": "U46377",
    "targetAccountId": "U15667",
    "amount": 123.45,
    "currency": "GBP",
    "dateTimeToOccur": "2018-03-20T09:12:13Z"
  }
}

Transfer Positions Internally

Copy Location

The /gw/api/v1/internal-asset-transfers can be used to transfer positions internally between IBKR accounts based on eligibility.

• All Accounts: Internal transfers supported between existing IBKR sub accounts IF both source and destination account have matching account titles, country of residence, tax ID, and are associated with the same IB Entity.
• Non-Disclosed and Omnibus: Internal transfer supported between sub accounts that are linked to the same master account.

POST /gw/api/v1/internal-asset-transfers
{
  "instructionType": "INTERNAL_POSITION_TRANSFER",
  "instruction": {
    "clientInstructionId": 7013044,
    "sourceAccountId": "U399192",
    "targetAccountId": "U87440",
    "position": 106,
    "transferQuantity": 6,
    "tradingInstrument": {
      "tradingInstrumentDescription": {
        "securityIdType": "ISIN",
        "securityId": "459200101",
        "assetType": "STK"
      },
      "currency": "USD"
    }
  }
}

POST /gw/api/v1/internal-asset-transfers

{
  "instructionType": "INTERNAL_POSITION_TRANSFER",
  "instruction": {
    "clientInstructionId": 7013043,
    "sourceAccountId": "U399192",
    "targetAccountId": "U87440",
    "position": 106,
    "transferQuantity": 6,
    "tradingInstrument": {
      "conId": 21323,
      "currency": "USD"
    }
  }
}

Position Transfers

Copy Location

Transfer positions between IBKR brokerage account and external account using the /gw/api/v1/external-asset-transfers endpoint. Transfer methods available will vary based on country of residence and currency of assets being transferred.

POST /gw/api/v1/external-asset-transfers

{
  "instructionType": "FOP",
  "instruction": {
    "clientInstructionId": 7013039,
    "direction": "IN",
    "accountId": "U46377",
    "contraBrokerAccountId": "12345678A",
    "contraBrokerDtcCode": "534",
    "quantity": 1000,
    "tradingInstrument": {
      "tradingInstrumentDescription": {
        "securityIdType": "ISIN",
        "securityId": "459200101",
        "assetType": "STK"
      },
      "currency": "USD"
    }
  }
}

POST /gw/api/v1/external-asset-transfers

{
  "instructionType": "fop",
  "instruction": {
    "clientInstructionId": 7013038,
    "direction": "IN",
    "accountId": "U46377",
    "contraBrokerAccountId": "12345678A",
    "contraBrokerDtcCode": "534",
    "quantity": 1000,
    "tradingInstrument": {
      "conId": 12123,
      "currency": "USD"
    }
  }
}

POST /gw/api/v1/external-asset-transfers

{
  "instructionType": "DWAC",
  "instruction": {
    "clientInstructionId": 7013036,
    "direction": "IN",
    "accountId": "U1001095",
    "contraBrokerAccountId": "12345678A",
    "contraBrokerTaxId": "123456789",
    "quantity": 1000,
    "accountTitle": "Special Company Holding LLC",
    "referenceId": "refId",
    "tradingInstrument": {
      "conId": 12123,
      "currency": "USD"
    }
  }
}

POST /gw/api/v1/external-asset-transfers

{
  "instructionType": "EXTERNAL_POSITION_TRANSFER",
  "instruction": {
    "clientInstructionId": 7013060,
    "type": "FULL",
    "subType": "ACATS",
    "brokerId": "0226",
    "brokerName": "Wall Street Financial Group",
    "accountAtBroker": "SOL12345",
    "sourceIRAType": "RO",
    "accountId": "U1225448",
    "signature": "John Tester"
  }
}

POST /gw/api/v1/external-asset-transfers

{
  "instructionType": "EXTERNAL_POSITION_TRANSFER",
  "instruction": {
    "clientInstructionId": 7013060,
    "type": "FULL",
    "subType": "ATON",
    "brokerId": "3265",
    "brokerName": "Wall Street Financial Group",
    "accountAtBroker": "SOL12345",
    "accountId": "U1225448",
    "signature": "John Tester"
  }
}

POST /gw/api/v1/external-asset-transfers

{
  "instructionType": "COMPLEX_ASSET_TRANSFER",
  "instruction": {
    "clientInstructionId": 7013040,
    "direction": "IN",
    "accountId": "U399192",
    "quantity": 10,
    "contraBrokerInfo": {
      "accountType": "ORG",
      "brokerName": "JP MORGAN",
      "depositoryId": "1234",
      "brokerAccountId": "as3456567678578N",
      "country": "United States",
      "contactName": "as",
      "contactEmail": "a@gmail.com",
      "contactPhone": "2039126155"
    },
    "tradingInstrument": {
      "conId": 12123,
      "currency": "USD"
    }
  }
}

POST /gw/api/v1/external-asset-transfers

{
  "instructionType": "COMPLEX_ASSET_TRANSFER",
  "instruction": {
    "clientInstructionId": 7013042,
    "direction": "IN",
    "accountId": "U399192",
    "quantity": 10,
    "contraBrokerInfo": {
      "accountType": "ORG",
      "brokerName": "JP MORGAN",
      "depositoryId": "1234",
      "brokerAccountId": "as3456567678578N",
      "country": "United States",
      "contactName": "as",
      "contactEmail": "a@gmail.com",
      "contactPhone": "2039126155"
    },
    "tradingInstrument": {
      "tradingInstrumentDescription": {
        "securityIdType": "ISIN",
        "securityId": "459200101",
        "assetType": "STK"
      },
      "currency": "USD"
    }
  }
}

POST /gw/api/v1/external-asset-transfers

{
  "instructionType": "complex_asset_transfer",
  "instruction": {
    "clientInstructionId": 7013041,
    "direction": "IN",
    "accountId": "U399192",
    "quantity": 10,
    "contraBrokerInfo": {
      "accountType": "ORG",
      "brokerName": "JP MORGAN",
      "depositoryId": "1234",
      "brokerAccountId": "as3456567678578N",
      "country": "United States",
      "contactName": "as",
      "contactEmail": "a@gmail.com",
      "contactPhone": "2039126155"
    },
       "tradingInstrument": {
      "conId": 12123,
      "currency": "USD"
    },
    "nonDisclosedDetail": {
      "tradeDate": "2018-03-20T09:12:13Z",
      "settleDate": "2018-03-20T09:12:13Z",
      "psetBic": "OCSDATWWXXX",       
      "reagDeagBic": "TMBECH22XXX",
      "buyerSellBic": "TMBECH22XXX",
      "memberAccountId": "OCSD212100",
      "safeKeepingAccountId": "OCSD212100"
    }
  }
}

POST /gw/api/v1/external-asset-transfers
{
  "instructionType": "complex_asset_transfer",
  "instruction": {
    "clientInstructionId": 7013041,
    "direction": "IN",
    "accountId": "U399192",
    "quantity": 10,
    "contraBrokerInfo": {
      "accountType": "ORG",
      "brokerName": "JP MORGAN",
      "depositoryId": "1234",
      "brokerAccountId": "as3456567678578N",
      "country": "United States",
      "contactName": "as",
      "contactEmail": "a@gmail.com",
      "contactPhone": "2039126155"
    },
    "tradingInstrument": {
      "tradingInstrumentDescription": {
        "securityIdType": "ISIN",
        "securityId": "459200101",
        "assetType": "STK"
      },
      "currency": "USD"
    },
    "nonDisclosedDetail": {
      "tradeDate": "2018-03-20T09:12:13Z",
      "settleDate": "2018-03-20T09:12:13Z",
      "psetBic": "OCSDATWWXXX",       
      "reagDeagBic": "TMBECH22XXX",
      "buyerSellBic": "TMBECH22XXX",
      "memberAccountId": "OCSD212100",
      "safeKeepingAccountId": "OCSD212100"
    }
  }
}

Statements

Copy Location

IBKR provides comprehensive activity statements which include net asset value, PnL data and transaction details. The API can be used to view available statements and generate statements in PDF format.

Available Statements

Copy Location

The gw/api/v1/statements/available can be used to query list of available statements based on accountId. The endpoint will return available statements for up to 2 years and year to date for daily, monthly and annual statements.

• Statements are available from date which account is funded.
• The reporting window closes at 5:15PM EST for commodities and 8:20PM EST for securities. Statements will be available around midnight (EST).

For daily, response will return first date available to last date available.

GET gw/api/v1/statements/available?accountId=U123456

{
    "data": {
        "dataType": "String",
        "value": {
            "daily": {
                "endDate": "20241007",
                "startDate": "20220101"
            },
            "monthly": [
                "202201",
                "202202",
                "202203",
                "202204",
                "202205",
                "202206",
                "202207",
                "202208",
                "202209",
                "202210",
                "202211",
                "202212",
                "202301",
                "202302",
                "202303",
                "202304",
                "202305",
                "202306",
                "202307",
                "202308",
                "202309",
                "202310",
                "202311",
                "202312",
                "202401",
                "202402",
                "202403",
                "202404",
                "202405",
                "202406",
                "202407",
                "202408",
                "202409"
            ],
            "annual": [
                "2022",
                "2023"
            ]
        }
    }
}

Generate Statements

Copy Location

The gw/api/v1/statements can be used to generate standard statements in PDF format for given time period. The startDate and endDate will be used to set the time period.

• Maximum range is 365 days per request.
• Statements are only available from date which account is funded.

Additional formats (Excel, CSV, HTML) and Custom Statements are available for download within IBKR Portal.

Single Sign On

Copy Location

The /api/v1/sso-browser-sessions endpoint can be used to create Single Sign On (SSO) session to seamlessly connect user to the IBKR Client Portal. The IBKR Client Portal is a browser based interface where users can view portfolio information, manage account settings, manage orders, initiate funding, and access account statements. The portal will reflect hosting firms branding (logo, company name, color theme) IF white branding is configured.

Workflow

Copy Location

1. Hosting firm will call the /api/v1/sso-browser-sessions and provide credential and ip of the end user.
   • ip: Static IP is required and must be the actual customer’s computer (their IP-REMOTE_ADDR).
   • credential: IBKR username associated with the user.
2. IBKR returns a response with unique URL which can be used to access the client portal.
   • The unique URL is only valid for 60 seconds and can only be accessed from the IP which was included in the original request. This means an error will be triggered IF unique URL is accessed more than once, unique URL is accessed after 60 seconds, OR if IP which unique URL is accessed from is different from IP that was passed in the original request to create single sign on session.
3. Hosting firm invokes the unique URL into the users browser, new window opens and the user lands in IBKR Portal. See details here to set landing page.

Example Request

POST /api/v1/sso-browser-sessions 

{ "ip": "206.106.137.230", "credential": "potest123"}

Example Response with Landing Page Set for Statements

https://www.clientam.com/sso/resolver?ACTION=Statement&SID=<asdfsadfsdfsadfsdf>

Limitations

Copy Location

• SSO is only supported for browsers (Desktop or Mobile Browser). SSO is not supported for natively installed mobile applications.
• When an account is initially created, IBKR will assign a temporary password to the account. One time setup where the user is required to reset the temporary password after the account has been created.
• Authentication using the IBKR credential (username) and password is required when adding withdrawal instructions and initiating withdrawal requests using the IBKR hosted portal.

Define Landing Page

Copy Location

By default, when creating SSO session for an opened account, the user will land on the Client Portal home page. Direct user to specific landing page by adding the ACTION to the start call.

• Data for landing page is case and space sensitive
  • ACTION (is always uppercase)
  • SID (start call is always upper case)

Commonly used Landing Pages

Copy Location

Callback Notifications

Copy Location

IBKR will send notifications via RESTful Web API when status of a request changes. The notifications provided via the callback service have the same format as polling for a status (ie. /gw/api/v1/accounts/{accountId}/status) . Notifications are available for Client Registration, Account Information Changes, and Funding Requests that originate using Account Management API and IBKR Portal.

Application Schema

Copy Location

This section outlines the schema for client registration along with validations and required attributes.

Additionally, the /api/v1/enumerations/{enumerationType} can be used to query list of enumerations for attributes included within extPositionsTransfers, occupation, employerBusiness, financialInformation, affiliationDetails, tradingPermissions, etc.

Types include:

• acats: Query most up to date values for brokerId and brokerName. Used if funding via US ACATS extPositionsTransfers.
• aton: Query most up to date values for brokerId and brokerName. Used if funding via ATON Canada extPositionsTransfers.
• business-occupation: List of occupation AND employerBusiness for employmentDetails.
• edd-avt: Query questions associated with EDD (Enhanced Due Diligence) or AVT (Additional Verification) tasks assigned to an account.
• employee-plans: View EPA that are linked to master account (applicable IF offering SEP IRA accounts).
• employee-track: Query most up to date companyId for account. For affiliationDetails, if company has an existing IBKR Employee Track account.
• exchange-bundles: Query most up to date list of exchangeGroup for TradingPermissions.
• fin-info-ranges:  Query most up to date range IDs by currency  for annualNetIncome, netWorth, liquidNetWorth.
• market-data: View list of market data subscriptions.
• prohibited-country: View list of prohibited countries. Applicants that reside in prohibited country are restricted from opening an account with IBKR. Error will be thrown IF legalResidenceCountry, OR country (included within Residence, mailingAddress and employerAddress, taxResidency node) is a prohibited country.
• quiz-questions: Obtain list of questions associated with IBKR knowledge assessment.
• security-questions: Obtain list of questions supported for IBKR security questions.

AssociatedIndividual

Copy Location

AssociatedIndividual represents data for individuals that are associated with the account. Required fields for the individual fill vary based on the association and account type.

• Individual: customer > accountHolder > accountHolderDetails
• Retirement:
  • customer > accountHolder > accountHolderDetails
  • accounts> iraBeneficiaries > primaryBeneficiaries AND contingentBeneficiaries
• Joint: customer > jointHolder > firstHolderDetails and secondHolderDetails
• Trust: customer > trust > grantors AND beneficiaries
• Organization: customer > organization > associatedEntities > associatedIndividuals AND associatedEntities

Required

Copy Location

Dependent on type

Copy Location