Application XML Guide

October 2017

© 2017 Interactive Brokers LLC. All Rights Reserved

Any symbols displayed within these pages are for illustrative purposes only, and are not intended to portray
any recommendation.
 Contents

Contents

Application XML 3

What is Application XML? 3

What We Provide 4

Accessing the Agreements and Disclosures at Our FTP Site 6

How to Get Started 6

About the XML Sample Files 7

Advisor Client Types - Sample Files 7

Application XML Summary 8

How to Set Up Application XML 10

1. Preliminary Steps 10

2. Build and Test Your User Interface 11

3. Rules for Submitting Files 11

4. Testing Phase 14

5. Production Phase 16

Frequently Asked Questions 18

Application XML Guide i

ii
 Application XML

Application XML
The Interactive Brokers Application XML is available for Registered Advisors and Fully Disclosed Brokers
who want to develop their own version of the Interactive Brokers account application for their clients.

Note: Application XML is intended for Advisors and Brokers who either have working knowledge
of XML or have access to support staff with working knowledge of XML

What is Application XML?

Application XML is a process that lets Registered Advisors and Fully Disclosed Brokers provide their
clients with their own customized Interactive Brokers account application experience based on IB's
Application XML Schema. In Application XML, you use our schema as the basis for your own client account
application, collect all of the required information about your client applicants, and then return all of the
client information back to us in XML documents for processing. For example, an Advisor may want his
clients to complete an IB account application on his or her own website instead of using Interactive Brokers'
electronic client account application.

You can control the look and feel of your client account applications, as long you submit that information to
us as properly formatted XML files.

Application XML Guide 3

What We Provide

What We Provide
IB provides everything you need to program your own XML-based client account application solution:

Application XML Agreement - You must sign the Application XML Agreement and return it to us via
email for approval by our Compliance Department.

Once we have approved your signed Application XML Agreement, we will provide the following supporting
documents via email:

IB Application XML Schema - The Application XML Schema is described in two XML Schema Defin-
ition (.XSD) files: IBCust_import.xsd and IBCustEnumerations.xsd. The .XSD files describe the struc-
ture and data types for the XML documents that contain your clients' application information.
Application XML Schema Documentation - This is a zipped online help system automatically gen-
erated from the .XSD files that completely documents the Application XML Schema, including all ele-
ments, data types, attributes and values. Once you download and unzip this file, open the index.html in
your browser to open the documentation.

Note: The Application XML Schema Documentation includes information about five elements:
AcctMgmtRequests, AllDVPInstructions, Applications, ExtPositionsTransfers and
Synchronization. Use ONLY the Applications element and ignore the other elements.

Application XML Response File Schema - This is the file you use to format your custom client
application profile to send back to Interactive Brokers.
XML Samples - Application XML currently supports Individual, Joint, and IRA client accounts for an
Advisor or Fully Disclosed Broker account, so we provide a group of sample files for the most common
client account types and sample response files. Your programming or technical resources can use the
XML samples as models for the XML files that you will send back to us.
ACAT Broker ID/Name List - This Excel spreadsheet (file name ACAT Broker Entries.xls) lists all
brokers who are eligible for ACATS transfers. Refer to this spreadsheet for any clients that using
ACATS to fund their accounts.
EmployeeTrack Company IDs - This Excel spreadsheet (file name ET_Company_ID.xls) lists IDs
that correspond to our internal EmployeeTrack company IDs. Refer to this spreadsheet for any clients

Application XML Guide 4

 What We Provide

who are employed by a broker/dealer with an IB EmployeeTrack account.

Note: This is related to the Affiliation regulatory question.

Financial Ranges - Net Worth, Liquid Net Worth, Annual Net Income and Total Assets are required
attributes in the Financial Information section of your client account applications. We allow either abso-
lute values or ranges of values for these four attributes. The Financial_Ranges.xls Excel spreadsheet
lists ranges of values and their corresponding IDs. If you choose to use financial ranges instead of abso-
lute values for these attributes, include the IDs for the appropriate financial range from this spread-
sheet.
Bundle Based/Capability Based Guidelines for Trading Permissions - We provide three text
files (BundleBased.txt, CapabilityBased-Country.txt and CapabilityBased-State-Country.txt) that list
the form numbers of disclosures, agreements and acknowledgments that are required to support dif-
ferent trading permissions for your client applicants. The actual forms are located in the out-
going/Forms folder on our anonymous FTP site and are listed by the form numbers included in these
three text files.
Trading Permission Codes - This Excel spreadsheet, (file name TradingPermissions.xlsx), lists all of
the available trading permission codes that identify the asset classes and countries that your clients
want to trade. You use these codes to indicate requested trading permissions in the XML files con-
taining your clients' application information that you send back to us. For example, a trading permission
code of US-Sec means that a client is requesting permission to trade US Stocks.
Country Codes - This comma-separated values file, (file name Country_Codes.csv), lists all available
countries. See FAQ 10 for more information.

Application XML Guide 5

Accessing the Agreements and Dis-
closures at Our FTP Site

Broker Client Market Data Service IDs - For Fully Disclosed Brokers only, this Excel spreadsheet
(filename IBrokerClient_MarketDataServices.xls) lists all market data subscription and their Service
IDs, along with the price and currency of each subscription. When sending us your client applicant
data, use this spreadsheet to find the correct Service ID for each requested market data subscription,
and include the Service IDs in the MDServices element in the client application XML file.
Interactive Brokers Public PGP Key - When you submit your client application information and
signed forms and agreements in XML and zip files, you will need IB's public PGP key. The file name is
IBKR_CI.PubKey.asc.
ECA XML Processing - Outlines PGP exchange and signature signing.
List of acceptable documents for Proof of ID and Address

Accessing the Agreements and Disclosures at Our FTP Site

All of the agreements and disclosures that you will need are located at our anonymous FTP site. Use the
following information to access the FTP site. Note that we use anonymous FTP, which means that you can
access the forms using your web browser.

FTP Site Information

Agreements and Disclosures Location:
ftp://ftp.interactivebrokers.com/outgoing/Forms

How to Get Started

1. Learn more about the XML Sample Files that we will provide via email.
2. Read the Summary to familiarize yourself with the main steps involved in the Application XML pro-
cess.
3. Go to How to Set Up Application XML and follow all of the detailed steps to initiate the process, pre-
pare and test your XML files, and complete the delivery of your final XML files.

Application XML Guide 6

 About the XML Sample Files

About the XML Sample Files

Read this section to learn more about the XML sample files that we provide.

Application XML currently supports Individual, Joint and IRA clients for an Advisor or Fully Disclosed
Broker account. Once we have approved your signed Application XML Agreement, we will provide the
XML sample files via email. Your programming or technical resources can use the XML samples as models
for the XML documents containing your clients' application information that you send back to us.

Advisor Client Types - Sample Files

The sample files include XML application data and required PDF forms for the following types of client
accounts:

Note: Additional non-US samples files (dual language) are also included.

Individual - Individual_US_Sample.zip
Joint - Joint_Sample.zip
IRA - Traditional Rollover - TraditionalRolloverIRA_Sample.zip
IRA - Roth - RothIRA_Sample.zip

Application XML Guide 7

Application XML Summary

Application XML Summary

Here is a summary of the steps required to complete the Application XML process. Read this section if you
would like to familiarize yourself with the overall process before you begin.

Note: You can skip this section and go directly to the detailed steps in How to Set Up Application
XML if you prefer.

1. Send a request to implement Application XML to [email protected].

2. We will send you our XML Agreement. Sign and send the agreement back to us at the email
provided above. We will submit it to our Compliance Department for approval, which typically can
take 3-5 days. Once you are approved, we will email you with details about our secure FTP site.
3. Once approved, we will send you the supporting documents and IB hosted FTP details via email,
and then you can build your user interface to collect client data and sign agreements, and then pre-
pare XML files with sample data for testing.
4. You will collect all general data about your client applicants, including name, address, employment
and other information, and get those applicants to sign Interactive Brokers’ agreements and dis-
closures on your own website. Use the XML Samples as models for the XML files that you send us,
or use the All-In-One zip file, which includes both an example XML file and signed agreements and
disclosures.
5. You will work with the sales engineering team to test the process.
6. Upload all applicant data, funding notifications and electronic signatures in XML files along with cop-
ies of the required PDF forms in an encrypted zip file to the secure FTP site.
7. We retrieve and process the files and then post encrypted response XML files to the secure FTP
site. The response files will have a status of Success or Error. You correct any errors and then resub-
mit the corrected XML files to the secure FTP site.
8. If no additional documentation is needed, the account will be submitted for approval.
9. As Advisor or Broker, you are responsible for providing the account numbers, usernames and tem-
porary passwords to your clients.
10. Each client must log in to reset his or her password to access Account Management once his or her
client account has been approved and opened.

Application XML Guide 8

 Application XML Summary

Note: Temporary passwords do not expire; however, all clients MUST reset their temporary
passwords upon logging in for the first time.

Application XML Guide 9

How to Set Up Application XML

How to Set Up Application XML

The following steps describe how a Registered Advisor or Introducing Broker initiates the application XML
process, what details are required in the application XML files, and details about delivery methods. The
entire process is presented here in the following sections:

1. Preliminary Steps
2. Build and Test Your User Interface
3. Rules for Submitting Files
4. Testing Phase
5. Production Phase

1. Preliminary Steps
1. Send a request to implement Application XML to [email protected].
2. We will send you our XML Agreement. Sign and send the agreement back to us at the email
provided above. We will submit it to our Compliance Department for approval, which typically can
take 3-5 days.
3. Once you are approved, we will send you all supporting documentation, files and XML samples via
email. You can download the agreements and disclosure forms from the Forms folder on our
anonymous FTP site.
4. The supporting documentation that we email you will include our public PGP key. You will need this
to encrypt files that you submit to IB later. The file name of the public PGP key is IBKR_
CI.PubKey.asc.
5. Later, during the testing and production steps of the process, you will upload the zip files containing
the Application XML and PDF forms to the FTP site provided by IB and retrieve our encrypted
response XML files from the same FTP site. Once your initial agreement has been approved, we will
email you with details about how to access this secure FTP site , including your own unique login cre-
dentials.
6. Provide us with your PGP key so that you will be able to retrieve our XML response files from the
secure FTP site.
7. Review all supporting documents and files and email any questions you may have to us at salesen-
[email protected].

Application XML Guide 10

 2. Build and Test Your User Interface

Note: See What We Provide for more information about the supporting documentation, files and
samples.

2. Build and Test Your User Interface

1. Build the user interface that you plan to use to collect client application data and prompt clients to
sign agreements. You and your programming team can use the XML schema documentation and
other supporting files as reference while you build your interface.
2. Test your user interface with sample data.

3. Rules for Submitting Files

IB will provide you with the expected file naming convention prefix. You will need this information to
prepare and submit both test XML files and final production XML files. Note that the same secure
FTP site is used for both testing and production.

To submit client applicant information, upload one or more XML files along with copies of the accom-
panying PDF agreement and disclosure forms in an encrypted zip file. This method lets you submit the
XML application information and PDF forms for one or multiple clients together in a single, encrypted
zip file. The zip file must be encrypted with IB's PGP key and signature signed. Note that you can
upload multiple zip files if you prefer, as long as each zip file contains both XML files and PDF forms,
and each zip file is encrypted wtih IB's PGP key.

Application XML Guide 11

3. Rules for Submitting Files

You must follow this naming convention for your zip file(s):
Tester_YYYY-MM-DD_HHMMSS.zip.gpg
where the first segment is the same prefix as your xml files, the second segment is the date (YYYY-
MM-DD) and the third segment is the time (HHMMSS). The file name extension must be .zip.gpg.
For example, Tester_2015-07-29_125345.zip.gpg

Note: If you are not sure how to name your zip files, Interactive Brokers will provide you with the
proper file name prefix.

Do not upload individual XML files without the accompanying PDF forms because this will delay pro-
cessing.
Do not upload encrypted XML files with PDF forms in a zip file. The zip file must be encrypted, NOT the
individual XML file(s).
If there are two accounts (U101/U102) sending three agreements (A1/A2/A3), it is acceptable to have
only three PDF files (A1.pdf; A2.pdf; and A3.pdf). In this case, the XML file should specify the same file
names for each account. No specific naming convention is needed for the PDF files. Avoid using
spaces and special characters in the PDF file names because they tend to create problems.

Application XML Guide 12

 3. Rules for Submitting Files

Important Information About Regulatory Information AFFILIATION Status

In the XML file, there is a section about Regulatory Information which includes the RegulatoryDetails
code "AFFILIATION." In your XML file, this is the line that reads <RegulatoryDetails
status="true" code="AFFILIATION" />. For clients for whom the value of this code is set to true,
you have two options:

Option 1: For EmployeeTrack Accounts

Reference the ET_Company_ID Excel spreadsheet. For example, modify the code in your XML file
to read as follows:

<AffiliationDetails>
<affiliation_relationship>Wife is Employee</affiliation_relationship>
<person_name>Jane Nueman</person_name>
<company_id>14</company_id>
</AffiliationDetails>

Option 2: Not an EmployeeTrack Account

For example, modify the code in your XML file to read as follows:

<AffiliationDetails>
<affiliation_relationship>Self</affiliation_relationship>
<person_name>Karl Gustav Martin Eriksson</person_name>
<company>Covestor</company>
<company_mailing_address postal_code="02110" country="United States"
state="MA" city="Boston" street_1="175 Federal street, suite 825"/>
<company_phone>18668253005</company_phone>
</AffiliationDetails>

Application XML Guide 13

4. Testing Phase

4. Testing Phase
When you are ready, we will test the sample data in your XML files in our QA environment and work with
you to correct any errors. Here are the detailed steps in the testing process:

1. Prepare your XML files with sample client information. Use the sample XML files and Application
XML Schema online documentation as guides.

Your Application XML files (for testing and production) must include:

o All required client information.

o Each client account application must include a unique external ID, which we use to identify the
account. Specify the external ID in the external_id attribute in the XML for the client. We can-
not process two applications with the same external ID. Note that you can use your own user ID
as the external ID.
o While funding (deposit notification) information is not required in your XML files, we encourage
you to include it.
o Interactive Brokers agreements and disclosures, which must contain:

l Electronic signatures (in our XML schema, this is the element Signed By, which is a child
of the element Document);
l The file name of each agreement or disclosure form sent, with each form sent separately in
PDF format by account;
l File length in number of bytes;
l SHA1 checksum
l Two timestamps: exec_login_ts, which represents the moment that the client logged in to
your system; and exec_ts, the time at which the client effectively signed.

Note: The PDF agreements and disclosures are locked; there is no reason for you to have to edit
these files because actual client signatures are not required in the PDF forms that you send us.
They ARE required in the XML file as indicated above.

2. Save the XML files and their accompanying PDF agreement and disclosure forms in a zip file encryp-
ted with IB's public PGP key as described in Rules for Submitting Files.
3. Upload the zip file(s) to the applications/incoming folder on our secure FTP site.

Application XML Guide 14

 4. Testing Phase

If you know that you uploaded a file that contains errors and we have not yet processed the file, let us
know, and then delete the incorrect file from the secure FTP site, correct the errors, and replace it
with the corrected file.

4. We retrieve the files that you uploaded and process them in our QA environment, and then we post
encrypted test response XML files to our secure FTP site.
5. Download the test response files and ensure that you can decrypt them using your PGP key.
Response file names follow this naming convention:

Prefix_yyyy-mm-dd_HHMMS.xml.report.asc
where the first segment is the same prefix as the xml files that you submitted, the second segment is
the date (YYYYMMDD) and the third segment is the time (HHMMSS).

6. Once you decrypt and open the test response files, you will be able to see their contents:

o The status of your application: Success or Error.

o Details of any errors.

If the status is Success (there are no errors), the response file will include the Interactive Brokers
account number, username, temporary password and accepted or pending agreements and
disclosures.

If the status is Error, you must correct the errors and then resubmit your file(s). When you resubmit
the corrected XML files, you can continue to use the same external ID for each client application.

Application XML Guide 15

5. Production Phase

5. Production Phase
When you have successfully loaded several test accounts, let us know that you are ready to prepare and
submit your client applications for production. The steps for preparing and uploading XML files and
PDF forms and retrieving response files are nearly identical to the steps in the testing phase. The only
difference is now you will be submitting actual client applications instead of sample applications.

Note: Your application must be reviewed and approved by compliance prior to switching to
production.

Follow these steps:

1. Collect the real data from your applicants (your clients) via the user interface that you built.
2. Ensure that your XML files adhere to the guidelines listed in Step 1 in the section Testing Phase
above.
3. Prepare one zip file for a single client account application for upload according to the guidelines listed
in the section Rules for Submitting Files above. Make sure the zip file is encrypted, NOT the XML file
contained therein.
4. Upload the zip file to our secure FTP site.
5. We will process the file. Files are processed only once; files that have been already processed are
ignored.
6. Check the secure FTP site for our XML response file. Decrypt the response file. If there are any
errors, correct them and resubmit the file. See Steps 5-6 in the section Testing Phase above for
details.
7. If you need to update a client application that you have already submitted (for example, the client's
marital status changed), and the application has not yet been successfully processed, you must
resubmit the XML file using the same external ID as the original (resubmit the updated XML file
along wit the PDF forms in an encrypted zip file). If the application you need to update and resubmit
has already been successfully processed, you must resubmit the XML file using a new external ID,
and then delete the incorrect client application using the Manage Clients > Dashboard page in
Account Management.
8. If you forget to submit all of the required agreements and disclosure forms, you can submit a special
XML file as described in the FAQs section.

Application XML Guide 16

 5. Production Phase

9. Once that first file has been verified as being completely error-free, we will begin automatically check-
ing the secure FTP site every 15 minutes from 03:00 AM EST to 16:10 PM EST (default). You can
prepare and upload additional zip files for your client account applications.
10. Retrieve the response files from our secure FTP site.
11. Correct any errors indicated in the response files, and resubmit your files.

o If we ask for additional documents (i.e. Proof of Address or Proof of Identity), email them to:
[email protected]. Be sure to include only the new Interactive Brokers
account number in the subject line.
o If no additional documentation is required, each client account will be submitted for approval. You
can check the status of each account application on the Manage Clients > Dashboard page in
Account Management.

12. As Advisor or Broker, you are responsible for providing the account numbers, usernames and tem-
porary passwords to your clients.
13. Each client must log in to reset his or her password to access Account Management once his or her
client account has been approved and opened.

Note: Temporary passwords do not expire; however, all clients MUST reset their temporary
passwords upon logging in for the first time.

Application XML Guide 17

Frequently Asked Questions

Frequently Asked Questions

1. How do I submit XML files in Unicode (dual language encoding)?

Currently Chinese is the only non-English language we support in Application XML.

In ASCII, one character is coded with 1 byte, but in Unicode (UTF-8), up to 4 bytes are allowed per
character to represent non-ASCII range characters such as Chinese symbols.

If you are submitting XML files with Unicode (non-ASCII) characters in Chinese, you must include the
following in your XML files:

Indicate that you are using UTF-8 encoding by including the line <?xml version="1.0" encod-
ing="UTF-8" standalone="yes"?> in the standard header of the XML file(s).
Specify your language in the Application element by adding input_language = '<lan-
guage>[-<script>]' to the element where
<language> represents the shortest ISO 639 code (2 or 3 characters)
<script> represents the ISO 15924 code (4 characters).

For example, for Simplified Chinese, your Application element with input_language would look
like this (not case sensitive):

<Application input_language = 'zh-Hans'> .

If you do not indicate UTF=8 encoding, encoding is defaulted to ASCII. If the input_languge attribute is
missing, then the default value en (for English) is used.

2. What is the External ID?

The external ID is a unique identifier that is represented in the XML file by the attribute external_id.
The external ID must be unique for each account application; we cannot process two applications with the
same external ID. You can use your own user ID in this field.

The external_id is an attribute of the following complex types in the XML file:

Customer
Individual

Application XML Guide 18

 Frequently Asked Questions

Account
User

The external IDs can be the same for all four unless there are multiple individuals. If there are multiple
individuals in an application (i.e., secondary holder in a joint account or IRA beneficiaries), then the external
ID must be unique for each individual.

The user external ID would be the same ID as the account holder.

Individual Example:

Customer external_ID= ANAGY001

Individual (account holder) external_ID= ANAGY001
Account external_ID= ANAGY001
User external_ID= ANAGY001

IRA Example:

Customer external_ID= ANAGY002

Individual (account holder) external_ID= ANAGY002
Individual (beneficiary) external_ID= ANAGY00248
Account external_ID= ANAGY002
User external_ID= ANAGY002

3. Which funding methods can I use to fund new accounts?

Only ACATS (full or partial), ATON, ACH (initiated by bank only), wire and check deposits are supported.

Note: If you are submitting a wire deposit notification in Hong Kong Dollars (HKD), ask sales
engineering for more information.

4. What is the minimum deposit required to open a client account?

5,000 USD.

5. What are the rules for account usernames?

Application XML Guide 19

Frequently Asked Questions

Usernames are eight or nine characters long and must contain five or six lower-case letters and three
numbers. You only need to provide the five lowercase letters; Interactive Brokers will append three or four
numbers to complete the username.

6. What format do I use for Advisor Fees using Percent of Net Liquidation Value (%NLV)?

Enter your %NLV using the following example:

For 2%, enter 2, not 0.02.

Note: You can set the advisor fee or use an existing fee template in the XML application.

7. What do I use for the Identification element?

For US: Social Security Number (SSN attribute).

For non-US, one of the following:

License (DriversLicense attribute)

National ID (NationalCard attribute)
Passport (Passport attribute)
Alien ID (AlienCard attribute).

8. Which XML element do I use for a new application?

The only XML element you will use is Applications. Disregard all other XML elements.

9. For the AccreditedInvestorInformation complex type, there are five unnamed

booleans == q1,q2,q3,q4,q5. What do these do?

You can ignore these obsolete items.

Application XML Guide 20

 Frequently Asked Questions

10. What values are allowed in the country attribute?

The full country name as shown in the NAME column of the Country_Codes.csv file or the 3 character ISO
code, part of the supporting documentation that we email you.

Note: The ISO code must be used for states.

11. What happens if I submit a new application with an older timestamp than a previously
submitted application?

The order of application submission has no effect on the Application XML.

12. What time zone should I use for the two timestamps exec_login_ts and exec_ts?

All of our times are based in New York (EST or EDT).

13. What encryption options are available?

PGP only.

14. What if I forget to submit specific required agreements or disclosures?

You can submit them by uploading an XML file to our FTP site. Name your file submit_additional_docs.xml
and use the following sample as a guide:

<?xml version="1.0" encoding="US-ASCII" standalone="yes"?>

<AcctMgmtRequests xmlns="http://www.interactivebrokers.com/schemas/IBCust_import">
<DocumentSubmission reference_account_id="U1110000">
<Document form_no="3007" exec_ts="20140620165825" exec_login_
ts="20140620195825">
<SignedBy>Test Tester</SignedBy>
<AttachedFile file_name="3007.pdf" file_length="10896" sha1_
checksum="d3da37913817130fa62479905267361bffd090c7" />
</Document>
</DocumentSubmission>
</AcctMgmtRequests>

Application XML Guide 21

Frequently Asked Questions

15. What happens if exactly the same file name gets submitted for two separate clients - for
example, two clients open accounts at the same time and we generate one xml file per client - at
the exact same time (hour-minute-seconds)?

If both files have exactly the same file name, the second file will overwrite the first. The file names must be
different.

Application XML Guide 22