Account Management API

Account Management 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] will include JSON request that is encoded in base64.
• Maximum request size is 20MB
• There is no restriction on maximum response size

System Availability

Copy Location

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

Rate Limiting

Copy Location

Interactive Brokers enforces a global request rate limit for the Account Management Web API:

• 10 requests per second per endpoint
• 600 requests per minute per master account (10 requests × 60 seconds)

Authentication Scope

Authentication for the Account Management API operates at the master account level, distinguishing it from the trading API’s user-level authentication structure.

Exceeding Rate Limits

If your application exceeds these established rate limits, the API will respond with a 429 HTTP status code (Too Many Requests).

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: am-api@interactivebrokers.com
• Trading API: api@interactivebrokers.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 and environment.

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. Send an email to api-solutions@interactivebrokers.com with the following:
   • Firm Name
   • Firm Role (ie. Introducing Broker, Financial Advisor OR Third Party Service Provider)
   • API Services which you are interested in using (ie. Registration, Funding, Single Sign On, View Portfolio Data, Trading, Reporting)
   • Describe intended usage (1-2 sentences)
2. A rep from our API team will provide link to complete an integration questionnaire (electronically).
3. Upon completing the questionnaire, a representative from our API solutions team will reach out to schedule an introductory call to assess needs and determine services required for a successful integration.

Build and Test

Copy Location

Access to QA environment will be granted upon agreement of the integration requirements.

1. To setup the QA (sandbox) environment for Registration and Funding API, provide the following to am-api@interactivebrokers.com:
   • RSA key
     • Size: 3072 or 4096
     • Format: PEM
     • IP Addresses (CIDR Format)
   • Signed Services Agreement
2. IBKR will provide QA credential which can be used to access QA.
3. Build interface and test IBKR’s APIS.
   • Developers tool kit includes quick start guide
   • Suggested test cases

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.
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

The information necessary to establish a client account through our API varies based on several key 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 data requirements by Customer Type. Refer to schema for structure of the JSON.

_{*Required for Hybrid; otherwise optional if coordinated with the API Solutions team. 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 selected countries. If Trulioo 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

Copy Location

Option 1: Traditional Verification

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

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).}

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

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

_{Important: While partners may implement Traditional Verification as their primary verification method, in certain risk-based scenarios determined by IBKR compliance, Au10Tix verification may be required even if Traditional Verification was initially assigned or completed. This requirement is non-negotiable and is triggered by IBKR’s internal risk assessment protocols. Failure to implement support for both verification methods may result in users being unable to complete the account opening process in certain scenarios. All partners are expected to support both verification paths either through direct API implementation or SSO fallback capability.}

Agreements and Disclosures

Copy Location

Fully-Disclosed and Advisor clients are required to sign IBKR customer agreements and disclosures.

• Full Integration: Hosting firm will display IBKR agreements and disclosures within interface and collect electronic signature.
• Hybrid: End use signs IBKR agreements via the IBKR White Branded Platform

This section covers handling agreements and disclosures for clients using Full Integration.

Download IBKR Agreements and Disclosures

Copy Location

• Option 1: Download from public FTP: ftp://ftp2.interactivebrokers.com/outgoing/Forms/
• Option 2: Pull using the /gw/api/v1/forms endpoint.

Submit Agreements and Disclosures

Copy Location

The /gw/api/v1/accounts/documents endpoint provides mechanism to submit Agreements and Disclosures to IBKR once a day instead of with each application. We store these documents on the servers and will use them for new application requests submitted that day.

• Documents will need to be submitted once a day (before the Applications are submitted). PDFs will be displayed and submitted as is- no changes/edits will be made to the actual PDF files.
• This end-point will not process any Tax Form Documents. Tax Form document should be submitted with every application
• If submitted in the morning, you only need to include the Tax Form attachment for each applicant. Otherwise, you will need to include PDFs with each application (Create Account).

{
        "processDocuments":
            {
                "documents": [
                    {
                        "attachedFile": {
                            "fileName": "Form3024.pdf",
                            "fileLength": 432177,
                            "sha1Checksum": "03D899BA757F617C907A1F021D7046AC1DAC8707"
                        },
                        "payload": {
                            "mimeType": "application/pdf",
                            "data": pm.collectionVariables.get('form3024')
                        },
                        "formNumber": 3024,
                        "execLoginTimestamp": 20210929123113,
                        "execTimestamp": 20210929123113
                    }
                ],
                "inputLanguage": "en",
                "translation": false
            }
    }

Processing of IBKR Agreements and Disclosures

Copy Location

• Hosting firm will display IBKR agreements and disclosures within interface and collect electronic signature.
  • Collect a signature for each form OR display all forms on a single page with a single signature box at the bottom and pass that signature within the documents section for each form.
  • Example of IBKR’s Application as a reference
• The signature, which is collected will be included in the signedBy section of the documents.
• Hosting firm will provide copy of the IBKR agreements which were presented to user in the application payload that is submitted to IBKR for client registration.
  • No changes should be made to the PDF (We validate the forms using sha1checksum if alterations have been made, error will be triggered and the form will not be accepted.
• If a form is updated, hosting firm has a 7-calendar day grace period to update the form.

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 accountClose can be used to close an opened account based on the accountId. Within the body of the request, include reason for account closure (closeReason).

• Accounts eligible to be closed must have current status of O or Q and must have a cleared balance. If an account is funded at the time which the closure request is submitted, the request will be rejected.
• If status Q account is closed, status will move to R (rejected)

Requests are processed between 8am EST to 11am EST. Requests received outside of these hours will be processed the following day.

POST /gw/api/v1/accounts/close

{
  "accountManagementRequests": {
   "accountClose": {
      "accountId": "U1233457",
      "closeReason": "time to go"
    }
  }
 

Reopen Account

Copy Location

The reopenAccount can be used to reopen an opened account based on the accountId.

• The following accounts are eligible for reopening:
  • Fully-Disclosed and Advisor subs that originate using Hybrid
  • Current status of C (Closed)

Once the reopen request has been submitted, the end user must log into the IBKR Portal to review application information and sign updated agreements and disclosures. The request will not be processed until this step is completed.

PATCH /gw/api/v1/accounts

{
  "accountManagementRequests": {
   "reopenAccount": {      
   "accountId": "U1233457"
    }
  }
 

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": {
            "accountId": "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": {
            "accountId": "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.

Account Status Scenarios

Copy Location

The endpoint will return both a “status” and “state” that indicate where the account is in the account setup process. The below table will help you understand what these values mean and what actions need to be taken.

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",
                        "payload": {
                         "mimeType": "application/pdf",
                         "data": "<DocumentEncodedInBase64>"         }

                    }
                ],
                "accountId":"U123456,
                "inputLanguage": "en",
                "translation": false
            }
        
    }

PATCH /api/v1/accounts/{
{
    "accountManagementRequests": {
        "questionnaires": {
            "accountId": "U123456",
            "questionnaire": [
                {
                    "formNumber": 9943,
                    "answers": [
                        {
                            "detail": "description",
                            "id": 2396,
                            "questionId": 1620
                        }
                    ]
                }
            ]
        }
    }
}

PATCH /api/v1/accounts/
{
"accountManagementRequests": {
"quizQuestionnaires": {
"questionnaire": [
{
"answers": [
{
"id": 4,
"questionId": 1
},
{
"id": 4,
"questionId": 2
},
{
"id": 4,
"questionId": 3
},
{
"id": 4,
"questionId": 4
},
{
"id": 4,
"questionId": 5
},
{
"id": 4,
"questionId": 6
},
{
"id": 4,
"questionId": 7
},
{
"id": 4,
"questionId": 8
},
{
"id": 4,
"questionId": 9
},
{
"id": 4,
"questionId": 10
}
],
"formNumber": 2430
},
{
"answers": [
{
"id": 4,
"questionId": 1
},
{
"id": 4,
"questionId": 2
},
{
"id": 4,
"questionId": 3
},
{
"id": 4,
"questionId": 4
},
{
"id": 4,
"questionId": 5
},
{
"id": 4,
"questionId": 6
},
{
"id": 4,
"questionId": 7
},
{
"id": 4,
"questionId": 8
},
{
"id": 4,
"questionId": 9
},
{
"id": 4,
"questionId": 10
}
],
"formNumber": 2438
},
{
"answers": [
{
"id": 4,
"questionId": 1
},
{
"id": 4,
"questionId": 2
},
{
"id": 4,
"questionId": 3
},
{
"id": 4,
"questionId": 4
},
{
"id": 4,
"questionId": 5
},
{
"id": 4,
"questionId": 6
},
{
"id": 4,
"questionId": 7
},
{
"id": 4,
"questionId": 8
},
{
"id": 4,
"questionId": 9
},
{
"id": 4,
"questionId": 10
}
],
"formNumber": 2432
}
],
"accountId": "U1111111",
"task": [
{
"formNumber": 2431,
"status": false
},
{
"formNumber": 2439,
"status": false
},
{
"formNumber": 2433,
"status": false
}
]
}
}
}

{
  "accountManagementRequests": {
    "prohibitedCountryQuestionnaire": {
      "accountId": "accountId",
      "entityId": "247519520",
      "prohibitedQuestionnaireDetails": [
        {
          "code": "PASSPORT",
          "details": "Do you hold passport for the following countries"
        },
        {
          "code": "BIRTH",
          "details": "Were you born in the following countries"
        },
        {
          "code": "CITIZENSHIP",
          "details": "Do you hold citizenship in the following countries"
        },
        {
          "code": "BUSINESSDEALINGS",
          "details": "Do you have business dealings in the following countries"
        },
        {
          "code": "FINANCIALACCOUNTS",
          "details": "Do you have financial accounts in the following countries"
        },
        {
          "code": "RESIDENT",
          "details": "Do you plan to reside in the following countries"
        },
        {
          "code": "MULTI",
          "details": "Do you hold citizenship and/or residency details in multiple countries"
        }
      ]
    }
  }
}

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:

• Application Information (Date Started, Date Approved, Date Opened, Status, Date Funded, Applicant Type, External ID )
• Profile Information (Name, Address, Contact Information, Employment Information, Identification Document Information, Accepted Signatures)
• Fee Configuration and Effective Date
• Account Configuration (Base Currency, Permissions, Special Programs including SYEP and DRIP, MIFID Category, Market Data Subscriptions)
• Trading Capabilities (Requested, Approved, Activated, Margin Type, Options Level)
• Financial Information (Net Worth, Income, Sources of Wealth)
• Appropriateness  (Investment Objectives, Knowledge & Experience)
• Risk Score
• User (Username, Last Login, Two Factor Authentication, Last Login)

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": {
        "addMiFirData": {
            "accountId": "U12345",
            "title": "ACCOUNT HOLDER",
            "identifications": [
                {
                    "citizenship": "Liechtenstein",
                    "passport": "A11111",
                    "alienCard": "AlienCard",
                    "expire": false
                }
            ]
        }
    }
}

PATCH /gw/api/v1/accounts

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

PATCH /gw/api/v1/accounts

{
  "accountManagementRequests": {
    "manageMarketDataSubscriptions": {
      "service": [
        460,
        462
      ],
      "referenceUserName": "test12345"
    }
  }
}

PATCH /gw/api/v1/accounts

"accountManagementRequests": {
    "updateCredentials": [
        {
            "referenceUserName": "ctest9751",
            "updateEmail": {
             "email": "newemail@gmail.com", 
            "access": true
            }
        }
    ]
  }
}

PATCH /gw/api/v1/accounts

"accountManagementRequests": {
    "updateCredentials": [
        {
            "referenceUserName": "ctest9751",
            "updateEmail": {
             "email": "newemail@gmail.com", 
            "access": true
            }
        }
    ]
  }
}

PATCH /gw/api/v1/accounts

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

PATCH /gw/api/v1/accounts

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

PATCH /gw/api/v1/accounts

{
  "accountManagementRequests": {
    "updateWithholdingStatement": 
        {
            "accountId": "U12345",
            "treatyCountry": "CHN",
            "fatcaCompliantType": "FATCA_COMPLIANT",
            "effectiveDate": "2020-01-02",
            "certW8Imy": true,
            "usIncomeTax": true
        }
    
  }
}

PATCH /gw/api/v1/accounts

{
    "accountManagementRequests": {
        "updateTaxForm": {
            "accountId": "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" : 
            {
                "accountId" : "U12345",
                "type" : "LiteExecution",
                "value" : "true"
            }   
        
    }
}

PATCH /gw/api/v1/accounts

{
  "accountManagementRequests": {
    "accreditedInvestor": 
        {
            "accountId": "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": {
        "addCLPCapability" : 
            {
                "accountId" : "U12345"
            }   
        
    }
}

PATCH /gw/api/v1/accounts

{
    "accountManagementRequests": {
        "addLevFxCapability" : 
            {
                "accountId" : "U12345"
            }   
        
    }
}

PATCH /gw/api/v1/accounts

{
    "accountManagementRequests": {
        "addTradingPermissions": 
            {
                "tradingPermissions": [
                    {
                        "country": "BELGIUM",
                        "product": "STOCKS"
                    }
                ],
                    "accountId": "U1234",
            }
        
    }
}

PATCH /gw/api/v1/accounts

{
    "accountManagementRequests": {
        "addTradingPermissions": 
            {
                "tradingPermissions": [
                    {
                        "country": "BELGIUM",
                        "product": "STOCKS"
                    }
                ],
                "documentSubmission": {
                    "documents": [],
                    "accountId": "U1234",
                    "inputLanguage": "en",
                    "translation": false
                },
                    "accountId": "U1234",
            }
        
    }
}

PATCH /gw/api/v1/accounts
 {
  "accountManagementRequests": {
   "applyFeeTemplate": {
      "accountId": "U10032411",
      "templateName": "FeePerTradeUnit100"
    }
  }
}

PATCH /gw/api/v1/accounts

{
    "accountManagementRequests": {
        "changeBaseCurrency": {
            "accountId": "U12345",
            "newBaseCurrency": "USD"
        }
    }
}

PATCH /gw/api/v1/accounts

{
    "accountManagementRequests": {
    "changeFinancialInformation": [
        {
          "accountId": "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": {
        "changeMarginType": {
            "accountId": "U12345",
            "newMargin": "Margin"
        }
    }
}

PATCH /gw/api/v1/accounts

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

PATCH /gw/api/v1/accounts

{
    "accountManagementRequests":{
        "enrollInDrip":{
            "accountId": "U12345",
        }
    }
}

PATCH /gw/api/v1/accounts

{
    "accountManagementRequests":{
        "leaveDrip":{
            "accountId": "U12345",
        }
    }
}

PATCH /gw/api/v1/accounts

{
    "accountManagementRequests":{
        "enrollInSyep":{
            "accountId": "U12345",
        }
    }
}

PATCH /gw/api/v1/accounts

{
    "accountManagementRequests":{
        "leaveSyep":{
            "accountId": "U12345",
        }
    }
}

PATCH /gw/api/v1/accounts
{
    "accountManagementRequests": {
        "removeTradingPermissions": [
            {
                "tradingPermissions": [
                    {
                        "assetClass": "STK",
                        "exchangeGroup": "EU-IBET",
                        "country": "BELGIUM",
                        "product": "STOCKS"
                    }
                ]
                "accountId":"U123456"
            }
        ]
    }
}

PATCH /gw/api/v1/accounts

{
    "accountManagementRequests": {
        "updateAccountAlias": [
            {
                "accountId": "U12345",
                "accountAlias": "U111"
            }
        ]
    }
}

PATCH /gw/api/v1/accounts

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

PATCH /gw/api/v1/accounts

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

PATCH /gw/api/v1/accounts

{
    "accountManagementRequests": {
        "updateExternalId" : 
            {
                "accountId" : "U12345",
                "newExternalId" : "Test1234"            }   
        
    }
}

PATCH /gw/api/v1/accounts

{
    "accountManagementRequests": {
        "updatePropertyProfile" : 
            {
                "accountId" : "U12345",
                "propertyProfile" : "Standard"            }   
        
    }
}

PATCH /gw/api/v1/accounts

{
  "accountManagementRequests": {
    "updateUserAccessRights": [
        {
            "accountId": "U12345",
            "repId": "potest123",
            "action": "ADD"
        }
    ]
  }
}

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. Client fees can be set during client registration journey and updated/ The fee schedule will be defined within accounts.

• Advisor Managed: Fee schedule needs to be defined during client registration using advisorWrapFees OR feesTemplateName.
• Broker Clients: feesTemplateName is optional. If no fee template is set during registration, the default client fee template will automatically apply to that account.

Fee configurations are effective starting effective date. The effective date for client fees can be obtained by calling /api/v1/accounts/{{accountId}}/details

• If the account opening date is after the effective date, the fee configurations are effective 1 day after the open date.
• If the request approval date is after the effective date, the fee configurations are effective 1 day after the request approval date.
• Fee computations will not exist until effectiveDate (based on above bullet points) & the account is funded.

Fee Templates

Copy Location

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

Set Fee Template for Existing Account

Copy Location

The applyFeeTemplate 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).

PATCH /gw/api/v1/accounts
 {
  "accountManagementRequests": {
   "applyFeeTemplate": {
      "accountId": "U10032411",
      "templateName": "FeePerTradeUnit100"
    }
  }
}

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

The following login messages can be completed using the API:

• ACK_AGREEMENT_UPDATE (Use DocumentSubmission)
• W8INFO (Use UpdateTaxForm)
• LLC_AGREEMENT_UPDATE (Use DocumentSubmission)

All other login messages will need to be completed 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 7 days. Optionally, include transactionType to filter for a specific transaction.

Rate Limit: 1 request per 10 minutes.

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": "0",
"branchCodetype": "BSB_AUD",
"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, bankRoutingNumber, 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 account ID which the account is associated with. Wire instructions can be obtained using /api/v1/enumerations/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"
  }
}

Wire Instructions

Copy Location

This /api/v1/enumerations/wire-instructions can be used to retrieve the necessary banking details and wire transfer instructions required to deposit funds into your IBKR trading account. The response will include recipient bank information, account details, and any specific reference codes needed to ensure proper crediting of your deposit.

Important Notes:

• Wire instructions are subject to change and will vary based on currency
• It is recommended that you call this endpoint prior to depositing funds to IBKR to ensure you have the most current and accurate wire transfer details

POST /api/v1/enumerations/wire-instructions?currency=USD&accountId=U123456
{
    "enumerationsType": "wire-instructions",
    "jsonData": [
        {
            "currency": "USD",
            "accountNameAndBeneficiary": "Interactive Brokers LLC, One Pickwick Plaza, Greenwich, Connecticut, 06830, United States",
            "accountNumber": "12345678(Account Number)",
            "routingNumber": "12345678(ABA Code)",
            "bankSWIFTCode": "CHASUS33XXX",
            "bankTitleAndAddress": "JPMORGAN CHASE BANK, N.A., 383 Madison Avenue, New York, 10017, United States",
            "alternateAccountInfo": "",
            "paymentReference": "U123456/ IBLLC Test Test Account"
        }
    ]
}

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
  }
}

Open Banking

Copy Location

Our Open Banking integration provides a streamlined way to manage bank connections and transfers between your bank account and your IBKR brokerage account. We partner with Plaid to handle secure bank authentication and connection management.

We offer a hybrid integration approach rather than a full direct API integration:

• Bank connection management is handled by our partner Plaid
• Transfer execution is facilitated through our API endpoints
• Standing instructions are managed within your IBKR account

Add Open Banking Instructions

Copy Location

Connect users to the IBKR portal using Single Sign On to add new Open Banking instructions to their account.

plaintext

Use Case: First-time setup or adding additional bank accounts

Flow:

1. Hosting firm will call the /api/v1/sso-browser-sessions and provide credential and ip of the end user.
2. IBKR returns a response URL with SID (unique token).
   • SID is only valid for 60 seconds and can only be accessed from the IP which was included in the original request.
3. Hosting firm appends ACTION=TransferFunds&type=DEPOSIT&method=OPEN_BANKING&currency=<GBPorEUR> to the URL
4. Hosting firm invokes the URL into the users browser, new window opens and the user lands on IBKR funding page where they can add open banking instructions

https://www.clientam.com/sso/resolver?ACTION=TransferFunds&type=DEPOSIT&method=OPEN_BANKING&currency=<GBPorEUR>&SID=<TokenHere> 

Initiate Open Banking Deposit

Copy Location

Initiate a deposit via Plaid when standing Open Banking instructions are already in place by calling the /gw/api/v1/external-cash-transfers endpoint.

Prerequisites:

• User must have existing standing Open Banking instructions in their IBKR account
• Bank account must be previously connected
• Hosting firm has provided the URI to IBKR API representative.

Flow:

• Hosting firm calls the /gw/api/v1/external-cash-transfers endpoint providing IBKR with deposit details.
• IBKR returns unique URL address
• Hosting firm invokes URL into users browser. User lands in Plaid interface.
• User authenticates and confirms deposit
• Funds transfer is initiated

{
    "instructionType": "DEPOSIT",
    "instruction": {
        "clientInstructionId": 43454545,
        "accountId": "U1234567",
        "currency": "EUR",
        "amount": 1300,
        "bankInstructionMethod": "OPEN_BANKING",
        "openBanking": {
            "serviceProvider": "PLAID",
            "plaidOptions": {
                "linkDisplayName": "Test displayname",
                "completionRedirectUri": "wonderdust://complete"
            }
        },
        "bankInstructionName": "Test Bank"
    }
}

{
    "status": 202,
    "instructionSetId": 882059,
    "instructionResult": {
        "depositDetails": {
            "openBanking": {
                "serviceProvider": "PLAID",
                "providerResponse": {
                    "paymentId": "payment-id-sandbox-dc9f2de9-6c6d-4c04-b09c-c7fb8314afc7",
                    "hostedlinkUrl": "https://secure.plaid.com/hl/ls16p0n6orpq489p4s37o3rr16pqq9n3p2",
                    "linkToken": "link-sandbox-61c5a1be-cd93-4c9f-82b8-ee61cdd4a8c7"
                }
            }
        },
        "ibReferenceId": 320905649,
        "clientInstructionId": 601361111111301,
        "instructionType": "DEPOSIT",
        "instructionStatus": "PENDING",
        "instructionId": 703819361
    }
}

Initiate Withdrawal

Copy Location

When you add Open Banking instructions to your IBKR account, IBKR automatically creates a set of standing withdrawal instructions. This one-time setup enables seamless ongoing transfers. This means withdrawal requests can be submitted without requiring user interaction with Plaid or IBKR.

• bankInstructionMethod will be one of the following:
  • LVP (IB-UK)
  • SEPA

Prerequisites:

• Standing withdrawal instructions must be set up in IBKR account

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

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

_{TIP: 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, bankRoutingNumber, currency last 4 digits of the bankAccountNumber.}

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.

Processing

Copy Location

Our system processes 200 requests every 5 minutes, this is an asynchronous process. If a bulk request of 600 transfer requests submitted. This will take 15 minutes to be processed (total of 3 batches). Users may be subject to additional fee if submitting more than 1000 internal position transfer requests daily.

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"
    }
  }
}

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

{
  "instructionType": "complex_asset_transfer",
  "instruction": {
    "clientInstructionId": 7013041,
    "direction": "IN",
    "accountId": "U399192",
    "quantity": 10,
     "accountIdAtCurrentBroker": "U123456",
    "contraBrokerInfo": {
      "accountType": "ORG",
      "brokerName": "INTERNAL",
      "depositoryId": "1234",
      "brokerAccountId": "as3456567678578N",
      "country": "United States",
      "contactName": "as",
      "contactEmail": "a@gmail.com",
      "contactPhone": "2039126155"
      "accountTitle": "My Account Title"

    },
       "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,    
     "accountIdAtCurrentBroker": "U123456",    
      "contraBrokerInfo": {
      "accountType": "ORG",
      "brokerName": "INTERNAL",
      "depositoryId": "1234",
      "brokerAccountId": "as3456567678578N",
      "country": "United States",
      "contactName": "as",
      "contactEmail": "a@gmail.com",
      "contactPhone": "2039126155",      
       "accountTitle": "My Account Title"},
    "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"
    }
  }
}

Status of Position Transfer Request

Copy Location

For fop AND complexAssetTransfer, the response returned by IBKR will include clearingState AND status. The status returns the overall status of the clearingState reflects stage in the transfer process.

Bulk Transactions

Copy Location

Internal Cash Transfer (Bulk)

Copy Location

The /v1/clients/{client-id}/internal-cash-transfers:bulk can be used to transfer cash internally between IBKR accounts based on eligibility.

• Multiple transfer requests can be included within single instruction set.
• Batch processing every 30-60 seconds unless dateTimeToOccur is specified. Transfer will be processed for dateTimeToOccur. For instant transfers, use internal_cash_transfer.

Internal Position Transfer (Bulk)

Copy Location

The/v1/clients/{client-id}/internal-asset-transfers:bulk can be used to transfer positions internally between IBKR accounts based on eligibility.

• Multiple transfer requests can be included within single instruction set.
• Our system processes 200 requests every 5 minutes, this is an asynchronous process. If a bulk request of 600 transfer requests submitted. This will take 15 minutes to be processed (total of 3 batches). Users may be subject to additional fee if submitting more than 1000 internal position transfer requests daily.

POST /v1/clients/{client-id}/internal-asset-transfers:bulk

{
  "instructionType": "INTERNAL_POSITION_TRANSFER",
  "instructions": [
    {
      "clientInstructionId": 7013005,
      "sourceAccountId": "U399192",
      "targetAccountId": "U87440",
      "transferQuantity": 6,
      "tradingInstrument": {
        "tradingInstrumentDescription": {
          "securityIdType": "ISIN",
          "securityId": "45229200101",
          "assetType": "STK"
        },
      }
    },
    {
      "clientInstructionId": 7013006,
      "sourceAccountId": "U399192",
      "targetAccountId": "U87440",
      "transferQuantity": 6,
      "tradingInstrument": {
        "tradingInstrumentDescription": {
          "securityIdType": "ISIN",
          "securityId": "459200101",
          "assetType": "STK"
        },
        "currency": "USD"
      }
    },
    {
      "clientInstructionId": 7013043,
      "sourceAccountId": "U399192",
      "targetAccountId": "U87440",
      "transferQuantity": 6,
      "tradingInstrument": {
        "tradingInstrumentDescription": {
          "securityIdType": "ISIN",
          "securityId": "45229200101",
          "assetType": "STK"
        },
      },
    }
  ]
}

POST /v1/clients/{client-id}/internal-asset-transfers:bulk

{
  "instructionType": "INTERNAL_POSITION_TRANSFER",
  "instructions": [
    {
      "clientInstructionId": 7013005,
      "sourceAccountId": "U399192",
      "targetAccountId": "U87440",
      "transferQuantity": 6,
      "tradingInstrument": {
        "conid": 21323,
        "currency": "USD"
      }
    },
    {
      "clientInstructionId": 7013006,
      "sourceAccountId": "U399192",
      "targetAccountId": "U87440",
      "transferQuantity": 6,
        "tradingInstrument": {
        "conid": 111222,
        "currency": "USD"
      }
    },
    {
      "clientInstructionId": 7013043,
      "sourceAccountId": "U399192",
      "targetAccountId": "U87440",
      "transferQuantity": 6,
      "tradingInstrument": {
        "conid": 21323,
        "currency": "USD"
      },
    }
  ]
}

Reporting

Copy Location

IBKR offers comprehensive reporting capabilities to meet your business requirements. This section provides detailed guidance on accessing various reports through our API.

• Activity Statements: Activity Statements reflect all account activity including cash transactions, dividends, corporate actions, and trades.
• Tax Forms: Access tax documents for the last 5 years.
• Trade Confirmations: Trade confirmation generated in real-time for all executions.

Activity Statements

Copy Location

Activity statements show summary of account activity for a given time period. This includes 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.

Tax Forms

Copy Location

View available tax forms and generate historical or current tax forms by account ID.

Available Tax Forms

Copy Location

The gw/api/v1/tax-documents/available can be used to query list of available tax forms based on accountId.

• Tax Form availability
  • Form 1099 (Consolidated) will be available February 15 for the immediately preceding year.
  • Form 1099-R for IRA accounts will be available by January 31 for the immediately preceding year.
  • Form 5498 for IRA accounts will be available by May 31 for the immediately preceding year.

For more information on available tax forms, please visit our main website.

GET gw/api/v1/tax-documents/available?accountId=U123456&year=2022

{
"data": {
"dataType": "String",
"value": {
"forms": [
{
"isForm": true,
"taxFormName": "1099",
"formats": [
"PDF"
]
}
]
}
}
}

Generate Tax Documents

Copy Location

The gw/api/v1/tax-documents can be used to generate tax documents in PDF, HTML or CSV format for given tax year.