ChangeAccountHolderDetail

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

  • Update account information for existing accounts.

    • Name (first, last, salutation)

    • Residence (country, state, street_1, city, postal_code)

    • Identification (ID Document, IssuingCountry, citizenship, LegalResidenceState)

    • TaxResidencies (tin, country)

    • EmploymentType

    • EmployerDetails (occupation, employer_business, employer, employer_address)

    • NumDependents

    • MaritalStatus

  • HTTP Request Type POST

  • Fully Disclosed Client (Individual, Joint, Retirement, Org, Trust)

  • Advisor Client (Individual, Joint, Retirement, Org, Trust)

  • Non-Disclosed- NonQI Client (Individual, Joint, Org, Trust)

  • Fully-Disclosed and Advisor Clients: Takes 1-2 business day to be processed and reviewed by our compliance team.

  • Use /getAmRequestStatus to check the status of the request.

  • Provide applicant data within the NewAccountHolderDetail node

    • If the information included within the NewAccountHolderDetail node does not match with what IBKR has on file, the information will be updated.

    • If multiple requests are submitted for single account; the new request will override the existing pending request.

  • For Dual Language applications, details in both Native and Translated are required.

  • ChangeAccountHolderDetails requests are only supported for accounts that are open OR Pending/New application IF 9974 is assigned. If request is submitted for Pending/New application and 9974 is not assigned, the request will not be accepted.

    • If account information needs to be updated for a Pending/New account, a new application with the updated information will need to be submitted.

      • To avoid duplicate accounts, please use ‘AbandonAccount’ via /updateto delete the existing application with incorrect data.

      • When submitting a new application, a new unique external ID will need to be included. To submit a new application using the original external ID, (UpdateExternalId) for the existing account.

      • Once updated, your team can resubmit the application for the applicant using the original external ID that was used to create the original account.

        • New IBKR account ID will be generated once the application has been resubmitted.

          • You cannot resubmit application for an external_id that had already been processed unless the external_id has been delinked (UpdateExternalId) from the original account.

XSD

Copy 
<xsd:complexType name="ChangeAccountHolderDetail">
<xsd:sequence>
 <xsd:attribute name="reference_account_id" type="xsd:string" use="required">
</xsd:sequence>
<complexType name="NewAccountHolderDetail"> 
<xsd:attribute name="external_id" type="External ID associated with the account (specified during account creation)" use="Optional" />
 <xsd:attribute name="same_mail_address" type="Boolean" use="Optional" />
<xsd:attribute name="is_translated" type="Boolean" use="Only Required IF input_language="Zh-Hans" and has_translation ="true" minOccurs="0" maxOccurs="1" />
</xsd:sequence>
<xsd:element name="Name" use="Required" minOccurs="1" maxOccurs="1" />
<xsd:sequence>
 <xsd:attribute name="first" type="String" use="Optional" />
 <xsd:attribute element name="middle" type="String" use="Optional" />
 <xsd:attribute name="last" type="String" use="Optional" />
 <xsd:attribute name="salutation" type="salutation" use="Optional" />
</xsd:sequence>
<xsd:element name="DOB" type="YYYY-MM-DD" use="Required" minOccurs="1" maxOccurs="1" />
<xsd:element name="Residence" max use="Required" minOccurs="1" maxOccurs="1" /> 
<xsd:sequence>
 <xsd:attribute name="country" type="country" use="Required"/>
 <xsd:attribute name="state" type="state" use="Optional" />
 <xsd:attribute name="postal_code" type="String" use="Optional" />
 <xsd:attribute name="city" type="String" use="Optional" />
 <xsd:attribute name="street_1" type="String" use="Optional" />
 <xsd:attribute name="street_2" type="String" use="Optional" />
</xsd:sequence>
<xsd:element name="NumDependents" max use="Required" minOccurs="1" maxOccurs="1" />
<xsd:ComplexType  name="Phones" type="Phone" use="Required" minOccurs="1" maxOccurs="1" />
 <xsd:element  name="Phone" use="Required" minOccurs="1" maxOccurs="5" />
  <xsd:sequence>
   <xsd:attribute name="type" type="type" use="Optional" />
   <xsd:attribute name="number" type="String" use="Optional" />
   <xsd:attribute name="country" type="country" use="Optional" />
  </xsd:sequence>
<xsd:element name="Identification" use="Optional" />
<xsd:sequence>
 <xsd:attribute name="citizenship" type="citizenship" use="Optional" />
 <xsd:attribute name="<ID_Type>" type="String" use="Optional" />
 <xsd:attribute name="IssuingCountry" type="IssuingCountry" use="Required" minOccurs="1" maxOccurs="1" />
</xsd:sequence>
<xsd:complexType name="TaxResidencies" use="Required" minOccurs="1" maxOccurs="1" />
<xsd:sequence>
<xsd:element name="TaxResidency" use="required" minOccurs="1" maxOccurs="5" />
<xsd:attribute name="TINType" type="TINType" use="required" />
<xsd:attribute name="country" type="country" use="Optional" />
<xsd:attribute name="TIN" type="String" use="Optional" />
</xsd:sequence>
<xsd:complexType name="EmploymentDetails" use="Required IF EMPLOYED OR SELFEMPLOYED" minOccurs="0" maxOccurs="1" /> 
 <xsd:attribute name="is_duplicate_stmt_required" type="Boolean" use="Optional"  minOccurs="0" maxOccurs="1"  />
  <xsd:sequence>
   <xsd:element name="employer" type="String" use="Required"/> 
   <xsd:element name="occupation" type="String" use="Required"/> 
   <xsd:element name="employer_business" type="String" use="Required"/> 
   <xsd:element name="employer_address" type="employer_address" use="Required"/> 
   </xsd:sequence>
   <xsd:element name="employer_address" use="Required"/> 
    <xsd:sequence>
    <xsd:attribute name="country" type="country" use="Required"/> 
    <xsd:attribute name="state" type="state" use="Required"/> 
    <xsd:attribute name="postal_code" type="String" use="Required"/> 
    <xsd:attribute name="city" type="String" use="Required"/> 
    <xsd:attribute name="street_1" type="String" use="Required"/> 
  </xsd:sequence>

Attributes

Name

Type

Description

reference_account_id

String

IB account ID of the advisor/broker client account SYEP is unenrolled for.

same_mail_address

true
false

Indicate if the Mailing Address is the Same as the Residence address.

external_id String

external_id associated with the individual. associated with the user. ID can be obtained from <Entities> section of response file for account creation. If there are multiple individuals on an account, each individual will have a unique external_id.

salutation

Mr.

Mrs.

Ms.

Dr.

Salutation of the account holder

first

String

First name of the account holder.

last

String

Last name of the account holder.

middle

String

Middle name of the account holder.

DOB

YYYY-MM-DD

Date of birth of the account holder.

NumDependents

Non-negative integer

Number of dependents the account holder has.

state

ISO Code

State/Province which the account holder resides.

city

String; Max characters 100

City which the account holder resides.

Name

Type

Description

postal_code

String; Max characters 20

Postal / Zip code.

For countries that do not provide postal code, please enter “00000”

street_1

String; Max characters 200

Street which account holder resides

street_2

String; Max characters 200

Street which account holder resides. Optional

number

String

Phone Number of the account holder.

type

Mobile

Home

Phone number type.

MaritalStatus

S

M

W

D

C

Marital Status of the account holder.

S= Single

M= Married

W= Widowed

D= Divorced

C= Common law partner

country

ISO Code

State/Province which the account holder resides.

citizenship

ISO Code

Citizenship of the account holder. 

IssuingCountry

ISO Code

Country which the <ID_Type> was issued

<ID_Type>

PANNumber

SIN

NationalCard

DriversLicense

AlienCard

Passport

ID Document for account holder.

TINType

NonUS_NationalId

For Non-U.S. Applicants, if the applicant does not have a Foreign Tax ID, then this can be excluded.

 

country

ISO Code

Country where the applicant pays taxes.

Name

Type

Description

TIN

String

Tax Identification Number.

  • United States citizens and Residents: This is required. Provide SSN of the applicant.

All other countries: if the applicant does not have a Foreign Tax ID, then this can be excluded.

employer

String; max characters 128

Name of the employer 

employer_business

String; max characters 200

See ECA_Enumerations.xlsx > employer_business & occupation tab

occupation

String; max characters 200

Occupation of the applicant. See ECA_Enumerations.xlsx > employer_business & occupation tab

country

ISO Code

Country which the employer is located. 

state

ISO Code

State/Province which the employer is located.

city

String; Max characters 100

City which the employer is located.

postal_code

String; Max characters 20

Postal / Zip code.

For countries that do not provide postal code, please enter “00000”

street_1

String; Max characters 200

Street which employer is located.

Sample

Copy 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AcctMgmtRequests xmlns="http://www.interactivebrokers.com/schemas/IBCust_import">
    <ChangeAccountHolderDetail reference_account_id="U123456" >
        <NewAccountHolderDetail same_mail_address="false" external_id="TestTester" >
            <Name suffix="" middle="P" last="Smith" first="John" salutation="Ms."/>
            <DOB>1968-04-01</DOB>
            <MaritalStatus>D</MaritalStatus>
            <NumDependents>1</NumDependents>
            <Residence street_1="1 Wallabee Way" postal_code="46958" country="USA" city="New York" state="NY"/>
            <MailingAddress street_1="1 Wallabee Way"  postal_code="12121" country="USA" city="New York" state="NY"/>
            <Phone type="Mobile" number="2034228988" country="USA" />
            <Email email="tester@test.com"/>
            <Identification SSN="123456789" IssuingState="NY" citizenship="USA" citizenship_2="MEX" />
            <EmploymentType>Employed</EmploymentType>
            <EmploymentDetails>
                <employer>Test Inc.</employer>
                <occupation>Test Marketing</occupation>
                <employer_business>Boomerang Test</employer_business>
                <employer_address street_2="Big Red Park" street_1="121 Platypus Drive" postal_code="10023" country="USA" city="New York" state="NY"/>
            </EmploymentDetails>
            <Ownership percentage="100"/>
            <TaxResidencies>
                <TaxResidency country="USA" TIN="123456789" TIN_Type="SSN" />
            </TaxResidencies>
        </NewAccountHolderDetail>
    </ChangeAccountHolderDetail>
</AcctMgmtRequests>

Name

Type

Description

Execution_Date

YYYY/MM/DD HH:MM:SS

Date/Time which the file was processed by IBKR.

Process_File

FirmName_YYYY-MM-DD_######.xml

File name of the request file.

Client

FirmName

Name of the Counterparty

Client_Master_Acct

String

Master account number
ChangeAccountHolderDetail String Status of the request
reference_account_id String IBKR account ID of the advisor/broker client account which the request is being submitted for
request_status

PROCESSED

ERROR

PENDING

 Status of the request
message String Status of the request.
request_id Non-negative integer Unique ID which IBKR assigns to the request. The ID can be used to query status request at a later time using //getAmRequestStatus endpoint
message String Includes details on the status of the request IF status=”PENDING" or "PROCESSED "
Pending_Tasks <Tasks> Includes pending tasks associated with the info change request IF status=”PENDING"
Errors String Includes error message if status=”ERROR”

Sample

Copy
Success
<?xml version='1.0' encoding='UTF-8'?>
<Process>
  <Execution ECA_XML_Schema_Version="15-Nov-2018">
    <Execution_Date>2020/02/20 00:44:38</Execution_Date>
    <Process_File>TesterFA_2020-02-20_124438885_761126.xml</Process_File>
    <Client>TesterFA</Client>
    <Client_Master_Acct>F1234567</Client_Master_Acct>
  </Execution>
   <ChangeAccountHolderDetail reference_account_id="U2088007" request_status="PROCESSED" message="Status of the request" request_id="50813"/>
</Process>
Copy
Error
<?xml version='1.0' encoding='UTF-8'?>
<Process>
  <Execution ECA_XML_Schema_Version="15-Nov-2018">
    <Execution_Date>2020/02/20 00:44:38</Execution_Date>
    <Process_File>TesterFA_2020-02-20_124438885_761126.xml</Process_File>
    <Client>TesterFA</Client>
    <Client_Master_Acct>F1234567</Client_Master_Acct>
  </Execution>
   <ChangeAccountHolderDetail reference_account_id="U2088007" request_status="ERROR" request_id="50813">
    <Error>Error Message Here</Error>
  </ChangeAccountHolderDetail>
</Process>