You are here: Application XML > How to Set Up Application XML
  • All Files

 

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 salesengineering@interactivebrokers.com.
  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, download all supporting documentation, files, XML samples and agreements and disclosure forms from our anonymous FTP site. Download the documents, files and samples from the Documents folder on our anonymous FTP site, and download all forms from the Forms folder on our anonymous FTP site.
  4. Download our public PGP key from the Documents folder on our anonymous FTP site. 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 your XML files from a separate, secure FTP site and retrieve our encrypted response XML files from the same secure 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 credentials.
  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 salesengineering@interactivebrokers.com.

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

Familiarize yourself with the following rules about file names and file submission. 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 (NOT the anonymous 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 accompanying 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 (available on our anonymous FTP site). 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.
  • 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
  • Do not upload individual XML files without the accompanying PDF forms because this will delay processing.
  • 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.

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>

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:

  • All required client information.
  • 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 cannot process two applications with the same external ID. Note that you can use your own user ID as the external ID.
  • Interactive Brokers agreements and disclosures, which must contain:
  • Electronic signatures (in our XML schema, this is the element Signed By, which is a child of the element Document);
  • The file name of each agreement or disclosure form sent, with each form sent separately in PDF format by account;
  • File length in number of bytes;
  • SHA1 checksum
  • 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: Actual client signatures are not required on the PDF agreements and disclosures that you send us. They ARE required in the XML file as indicated above.

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

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.

  1. 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.
  2. Download the test response files and ensure that you can decrypt them using your PGP key. Response file names follow this naming convention:

Tester_YYYYMMDD-HHMMS.xml
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).
For example Tester_20160210-094705.xml

  1. Once you decrypt and open the test response files, you will be able to see their contents:
  • The status of your application: Success or Error.
  • 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.

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.

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.
  9. Once that first file has been verified as being completely error-free, we will begin automatically checking the secure FTP site every 15 minutes from 3:00 AM EST to 16:10 PM EST. 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.
  1. As Advisor or Broker, you are responsible for providing the account numbers, usernames and temporary passwords to your clients.
  2. 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 modify their temporary passwords upon logging in for the first time.

  © 2016 Interactive Brokers