Account Management Introduction

Copy Location

IMPORTANT DISCLOSURE

Please be advised that DAM API using XML is considered legacy and has been discontinued.

• New clients will exclusively access our services through the Web API with OAuth 2.0 authentication
• Existing clients have the option to transition to the Web API with OAuth 2.0.

This documentation is solely provided to assist existing clients using the legacy API until their transition is complete. For any questions or assistance with this transition, please contact our API support team at am-api@interactivebrokers.com.

Interactive Brokers (IBKR) Digital Account Management (DAM) 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.

Requirements

Copy Location

• Working knowledge and/or support staff with working knowledge of XML and PGP Key Encryption. 
• Application data will be sent to IBKR in XML format via RESTful Web API.
• Only ASCII characters are supported.

Important to note: Data included within the document such as accountIDs, CSID, sha1_checksum is for reference only and do not reflect actual values.

Integration Requirements

Copy Location

This section outlines the technical requirements and specifications for integrating with Interactive Brokers (IBKR) systems for application data transmission via the Digital Asset Management (DAM) Web Service.

XML Structure

Copy Location

All XML requests must begin with a standard XML declaration (XML prolog) in the opening line.

Declaration Components

Copy Location

Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

Data Format

Copy Location

• Supported Characters: ASCII only
• Character Set: Standard ASCII characters (codes 0-127)
• Restrictions:
  • Extended ASCII characters (codes 128-255) are NOT supported
  • Unicode characters are NOT supported
  • Special characters outside ASCII range must be encoded or avoided

Accessibility

Copy Location

Digital AM Web Service will be available on the Web at the following URLs:

Production Instance

• api.ibkr.com (non-China region only)
• www.ibkr.com.cn (Mainland China only)

Quality Instance

• https://qa.interactivebrokers.com

Connectivity

Copy Location

We use a third party provider that offers Global DNS service with live health checks. The third party provider ensures that:

• The domain is served from all our main data centers located globally (United States, Switzerland, Hong Kong).
• User is sent to a data center that is closest to the user.
• If a data center is down, the user is automatically sent to next closest healthy data center.
• Healthchecks continuously performed against the DAM server to determine if data center is healthy.

Availability

Copy Location

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

Health Check

Copy Location

[POST] https://[domain]/ws/<ecaORfb>/healthcheck

The healthcheck endpoint offers you the ability to check overall system availability. The call will need to be done on a per service type (eca OR fb).

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

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 dam@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 dam@interactivebrokers.com:
   • PGP Public Key
   • IP Addresses (CIDR Format)
2. IBKR will provide QA credential which can be used to access QA.
3. Build interface and test IBKR’s APIS.
   • 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:
   • Contact your API integration manager with the following:
     • PGP Public Key (Unique key from QA)
     • IP Addresses (CIDR Format)
     • 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 can take 3-5 business days to be completed).
3. IBKR will send email with approval status of interface. If approved, IBKR will provide production credentials.
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

[POST] https://[domain]/ws/eca/create

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

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

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.
  • Whenever a form is updated, you will be sent an e-mail notification and you will have a 7-calendar day grace period to update the form in your application.
• Hybrid: End use signs IBKR agreements via the IBKR White Branded Platform

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

View/Download Agreements and Disclosures

Copy Location

[POST] https://[domain]/ws/eca/getForms

This endpoint can be used to view and download IBKR agreements and disclosures by form number. It provides access to the original documents as maintained by the server, along with comprehensive metadata.

Functionality:

• Download agreement or disclosure in PDF format
• View meta data including date modified, filename, size, SHA1 checksum

Optionally, agreements and disclosures can be downloaded from public FTP: ftp://ftp2.interactivebrokers.com/outgoing/Forms/

Submit Agreements and Disclosures

Copy Location

[POST] https://[domain]/ws/eca/submitDocuments

This 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).
• When input_language=”zh-Hans” and the Chinese version of the form (when available) must displayed to the client and must be submitted.

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

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 https://[domain]/ws/eca/Au10Tix 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:

View Account Status

Copy Location

[POST] https://[domain]/ws/eca/getAccountStatus

Query status of account(s). The endpoint returns key information including the status of the account, state of the application, date application was started, date opened, and date closed.

• Query by account, custom group of accounts, all accounts associated with master, for accounts created within certain date range, OR status

Close Account

Copy Location

[POST] https://[domain]/ws/fb/new-request | Function: close_account

The close_account function can be used to close an opened account based on the client_ib_acct_id. Within the body of the request, include reason for account closure (close_reason).

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

Reopen Account

Copy Location

[POST] https://[domain]/ws/fb/new-request | Function: reopen_account

• Customer type – Fully Disclosed, Non-Disclosed and Advisor Clients.
• Requests submitted prior to 3pm EST will be processed same day. Requests submitted after 3pm EST will be processed the following business day.
• IBKR may require additional documents (eg Proof of Identity, Proof of Address) for reopen_account requests.
• reopen_account requests are unable to be processed for applications that were started > 3 years ago. Instead, the user must complete a new application. 

Cancel Application

Copy Location

[POST] https://[domain]/ws/eca/update | Function: AbandonAccount

The AbandonAccount can be used to delete/cancel a pending application based on the reference_account_id. 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.

Reset Application

Copy Location

[POST] https://[domain]/ws/eca/update | Function: ResetAbandonAccount

The ResetAbandonAccount can be used to reset application that was previously marked abandoned based on the reference_account_id. 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.

Validations

• Full DAM (Tax Form included in /create request): Applications can only be reset IF the application is less than 6 months old. Meaning, if date_begun > 6 months, an error will be triggered if request to ‘ResetAbandonedAccount’ is submitted.

• DAM Hybrid (Tax form completed in IBKR Portal after account was created): Application can be reset at anytime. Once reset, client will need to re-review application data and submit updated in IBKR Portal (white branded).

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.

Pending Tasks

Copy Location

[POST] https://[domain]/ws/eca/getPendingTasks

View pending (incomplete) registration tasks which are required for account approval. 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.

• Query by account, custom group of accounts, all accounts associated with master, for accounts created within certain date range, OR pending task.
• If supporting document was rejected; response will include rejection reason.

Registration Tasks

Copy Location

[POST] https://[domain]/ws/eca/getRegistrationTasks

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

• Query by account, custom group of accounts, all accounts associated with master, for accounts created within certain date range, OR pending task.
• Pull CIP documents submitted to IBKR for account approval. These CIP documents if required for an account, may include copies of driver’s license, passport, utility bills etc.
• 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

[POST] https://[domain]/ws/eca/update

This section covers how to complete registration tasks for an existing account.

Task Completion Guide

Copy Location

[POST] https://[domain]/ws/eca/getForms

This endpoint can be used to view details associated with a specific task and how to complete the task. Our system supports three main categories of tasks, each with specific requirements and completion methods:

Document Submission Tasks

Copy Location

Criteria: Forms where document_type='Document' and is_uploadable='T'

Requirements:

Copy Location

• Acceptable Documents: Refer to the specific list of acceptable document types for each form
• Action Required: To Submit
• API Support:Copy code{ "apiSupportedTask": { "value": "T", "method": "accountManagementRequests.DocumentSubmission" } }

Questionnaire and Quiz Tasks

Copy Location

Criteria: Forms where document_type='Document' and is_uploadable='F'

EDD Questionnaires:

Copy Location

• Description: Enhanced Due Diligence questionnaires that require detailed responses
• Action Required: To Complete
• API Support:Copy code{ "apiSupportedTask": { "value": "T", "method": "accountManagementRequests.questionnaires" } }

Quiz Questionnaires:

Copy Location

• Description: Knowledge-based questionnaires with specific correct answers
• Action Required: To Complete
• API Support:Copy code{ "apiSupportedTask": { "value": "T", "method": "accountManagementRequests.quizQuestionnaires" } }

Agreement Signing Tasks

Copy Location

Criteria: Forms where document_type='Agreement'

Requirements:

Copy Location

• Action Required: To Sign
• API Support:Copy code{ "apiSupportedTask": { "value": "T", "method": "accountManagementRequests.DocumentSubmission" } }

Account Information

Copy Location

[POST] https://[domain]/ws/eca/getAccountDetail

View account information based on the accountIds. 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)

Client Account Queries

Copy Location

[POST] https://[domain]/ws/eca/getClientData

This service allows you to search and retrieve a list of accounts based on specific criteria to help you find accounts that match your requirements. Query by any data that is returned when calling /getAccountDetails.

Examples include:

• State and/or country of residence
• Fee configuration
• Market data services
• Requested, approved, and/or activated trading capabilities
• Trading permission(s)
• Employment type

Linked Accounts

Copy Location

Additional Account

Copy Location

Allows you to easily create additional accounts of different types for your current clients, which are linked to their existing usernames. This process uses your client’s existing information so you will only be required to provide any account type specific information.

• Individual can create linked account (Individual or Joint).
  • If Joint, first holder will be listed as first holder on the new joint.
• First holder on a joint account can create linked account (Individual OR Joint).
  • If joint, individual will be listed as the first holder on the joint.
• Second holder on joint account cannot create linked account.
  • This user will maintain 2 separate user IDs for each account.

Linked accounts have the following characteristics:

• Clients can access all linked accounts in Client Portal from a single username making management easier.
• Advisors/Brokers can create multiple linked accounts.
• Linked accounts need to be funded independently

There are two options for creating linked accounts:

Option 1: Initiate account linkage request within Portal

Option 2: By request only, create linked account using the API.

Creation of Additional Account via the API

Copy Location

[POST] https://[domain]/ws/eca/update | Function: AddAdditionalAcct

Duplicate Account

Copy Location

Duplicate client accounts are useful for maintaining different trading strategies in different accounts. Duplicate account requests are only supported within Portal, and not via the API.

• Requests need to be submitted within IBKR Portal by the master user.
• Once request has been submitted, client must acknowledge the request within Portal.

Once your request has been processed, the following account settings will be duplicated:

• SMA configuration
• Exchange caps
• Commission
• Flex Queries
• Delivery information
• DVP instructions

Update Information

Copy Location

[POST] https://[domain]/ws/eca/update

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