Web API Account Management

Account Registration functionality is available to Advisor and Broker clients.

Eligible clients must first be configured by our Sales Engineering team in order to access the features described below.

A POST request to /api/v1/accounts is used to submit the contents of a new customer application.

This request requires a JSON body, which contains the details of the new client account to be created in your account structure. Required fields will vary substantially according to the nature of your account structure, the new client account being opened, and other factors.

Example:

POST https://api.ibkr.com/gw/api/v1/accounts

{
  "Applications": {
    "Application": {
      "Customer": {
        "-email": "new_client@email.com",
        "-external_id": "your_id_for_new_client",
        "-legal_residence_country": "USD",
        "-meets_aml_standard": "true",
        "-user_namex": "abcd123456",
        "-prefix": "ctx",
        "-type": "INDIVIDUAL",
        "AccountHolder": {
          "AccountHolderDetails": {
            "-same_mail_address": "true",
            "-external_id": "your_id_for_new_client-95256423",
            "Name": {
              "-first": "PERSON",
              "-last": "SURNAME"
            },
            "DOB": "1990-01-01",
            "Residence": {
              "-street_1": "123 ROAD ST",
              "-postal_code": "987654",
              "-country": "AUS",
              "-city": "CITY TOWN",
              "-state": "AU-NSW"
            },
            "Email": {
              "-email": "new_client@email.com"
            },
            "Identification": {
              "-citizenship": "AUS"
            },
            "TaxResidencies": {
              "TaxResidency": {
                "-country": "AUS",
                "-TINType": "NonUS_NationalId"
              }
            },
            "W8Ben": {
              "-explanation": "TIN_NOT_DISCLOSED"
            }
          },
          "FinancialInformation": {}
        }
      },
      "Users": {
        "User": {
          "-external_user_id": "your_id_for_new_client-95256423",
          "-prefix": "ctx"
        }
      },
      "Documents": {},
      "Accounts": {
        "Account": {
          "-alias": "your_id_for_new_client",
          "-base_currency": "AUD",
          "-external_id": "your_id_for_new_client",
          "-margin": "Margin",
          "-multicurrency": "true",
          "-property_profile": "Standard",
          "-migration": "true",
          "-source_acct_id": "654321",
          "TradingPermissions": {
            "TradingPermission": [
              {
                "-country": "UNITED STATES",
                "-product": "STOCKS"
              }
            ]
          },
          "Capabilities": {
            "Capability": {
              "-code": "CLP"
            }
          },
          "Fees": {
            "-template_name": "PLUS - default"
          }
        }
      }
    }
  }
}

A successful submission of a new account creation request will return a requestId identifier for the application submission, and a timestamp of its receipt:

{
  "requestId": 5678,
  "executedAt": "YYYY-MM-DD HH:MM:SS"
}

Test

Account Funding and Transfer functionality is available to Advisor and Broker clients.

Eligible clients must first be configured by our Sales Engineering team in order to access the features described below.

A new banking instruction can be sent to Interactive Brokers via a POST request to the /gw/api/v1/banking-instructions endpoint.

Currently this endpoint supports creation of wire, ACH, and Hong Kong eDDA bank instructions.

This endpoint requires a JSON body that identifies the instruction type and delivers the content of the instruction. The keys required for the instruction content will vary by instruction type. Please consult our Reference Material for examples of all supported instruction types.

The following is an example of a new ACH bank instruction:

POST https://api.ibkr.com/gw/api/v1/bank-instructions

{
  "instructionType": "ach_instruction",
  "instruction": {
    "clientInstructionId": "1012983",
    "bankInstructionCode": "ACHUS",
    "achType": "DEBIT_CREDIT",
    "bankInstructionName": "TestInstr",
    "currency": "USD",
    "accountId": "U223454",
    "clientAccountInfo": {
      "bankRoutingNumber": "202012983",
      "bankAccountNumber": "101267576983",
      "bankName": "JPM Chase",
      "accountTypeCode": 999
    }
  }
}

A successful submission of this bank instruction will yield an instructionId and the new instruction’s status:

{
  "instructionResult": 
  {
    "clientInstructionId": 80009,
    "instructionType": "ach_instruction",
    "instructionStatus": "PENDING",
    "instructionId": 43092478
  },
  "instructionSetId": 2487,
  "status": 202
}

Values needed:

• The identifier (“clientInstructionId”) you previously submitted for the instruction
• The IB account to which the instruction pertains
• The “bankInstructionCode” string value used during instruction creation

Details of previously submitted bank instructions, including their status, may be retrieved via a POST request to the /gw/api/v1/banking-instructions/query endpoint.

This endpoint requires a JSON body that identifies the nature of the query (for a single bank instruction, or for a recurring event) and provides identifiers of the requested instruction:

• clientInstructionId: The identifier you previously assigned to the requested bank instruction
• accountId: The IB account to which the instruction pertains
• bankInstructionMethod: The all-caps instruction type identifier submitted as bankInstructionCode during the instruction’s creation

An example request to query for details of wire bank instruction:

POST https://api.ibkr.com/gw/api/v1/bank-instructions/query

{
  "instructionType": "get_bank_instruction_details",
  "instruction":
  {
    "clientInstructionId": "1012983",
    "accountId": "DU123456",
    "bankInstructionMethod": "WIRE"
  }
}

If successful, the query returns:

{
  "instructionResult": {
    "accountId": "DU123456",
    "bankInstructionMethod": "WIRE",
    "instructionDetails": [
      {
        "bankInstructionName": "foreignBank",
        "type": "FOREIGN_BANK",
        "currency": "USD"
      },
      {
        "bankInstructionName": "farawayBroker",
        "type": "FOREIGN_BROKER",
        "currency": "CHF"
      }
    ],
    "ibReferenceId": 0,
    "clientInstructionId": 1012983,
    "instructionType": "GET_INSTRUCTION_NAME",
    "instructionStatus": "PROCESSED",
    "instructionId": 43094187
  },
  "instructionSetId": 3771,
  "status": 202
}

The /gw/api/v1/internal-cash-transfers endpoint is used to transfer cash within IB. Internal cash transfers may be instantaneous, to be carried out synchronously, or scheduled to occur in the future.

An example instantaneous (synchronous) internal cash transfer request:

POST https://api.ibkr.com/gw/api/v1/internal-cash-transfers

  {
    "intructionType": "internal_cash_transfer",
    "instruction": {
      "clientInstructionId": "1012983",
      "sourceAccountId": "U46377",
      "targetAccountId": "U15667",
      "amount": 123.45,
      "currency": "GBP"
    }
  }

A successful instantaneous request yields a 201 status code and a response indicating immediate processing:

  {
    "instructionResult": {
      "clientInstructionId": 1013032,
      "instructionType": "internal_cash_transfer",
      "instructionStatus": "PROCESSED",
      "instructionId": 43091814,
      "ibReferenceId": 132123
    },
    "instructionSetId": 1703,
    "status": 201
  }

A scheduled (asynchronous) internal cash transfer request also includes a dateTimeToOccur value:

POST https://api.ibkr.com/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"
    }
  }

And a successful scheduled request yields a 202 status code and a response indicating that processing is pending:

  {
    "instructionResult": {
      "clientInstructionId": 1013031,
      "instructionType": "internal_cash_transfer",
      "instructionStatus": "PENDING",
      "instructionId": 43091814
    },
    "instructionSetId": 1703,
    "status": 202
  }

The /gw/api/v1/internal-asset-transfers endpoint is used to conduct transfers of assets within IB.

Example request:

POST https://api.ibkr.com/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"
      }
    }
  }

A successful request yields a 202 status code indicating that the transfer is pending:

  {
    "instructionResult": {
      "clientInstructionId": 7008152,
      "instructionType": "internal_position_transfer",
      "status": "PENDING",
      "instructionId": 43092590
    },
    "instructionSetId": 2614,
    "httpStatusCode": 202
  }

The /gw/api/v1/external-cash-transfers endpoint is used to conduct deposits and withdrawals of cash to and from IB accounts.

Example deposit request:

POST https://api.ibkr.com/gw/api/v1/external-cash-transfers

  {
    "instructionType": "deposit_funds",
    "instruction": {
      "clientInstructionId": 7013045,
      "accountId": "U46377",
      "currency": "USD",
      "amount": 100,
      "bankInstructionMethod": "WIRE",
      "sendingInstitution": "Sending Institution name",
      "identifier": "indentifier",
      "specialInstruction": "U46377",
      "bankInstructionName": "Instruction",
      "fromAccountNumber": "U46377",
      "senderInstitutionName": "Senders Institution name"
    }
  }

Successful response, with 202 status code indicating that the deposit is pending:

  {
    "instructionResult": {
      "clientInstructionId": 7008143,
      "instructionType": "deposit_funds",
      "instructionStatus": "PENDING",
      "instructionId": 43092468
    },
    "instructionSetId": 2480,
    "status": 202
  }

Example withdrawal request:

POST https://api.ibkr.com/gw/api/v1/external-cash-transfers

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

Successful response, with 202 status code indicating that the withdrawal is pending:

  {
    "instructionResult": {
      "clientInstructionId": 12000862,
      "instructionType": "withdrawal",
      "instructionStatus": "PROCESSED",
      "instructionId": 43092641,
      "ibReferenceId": 132123
    },
    "instructionSetId": 2719,
    "status": 202
  }

The /gw/api/v1/external-asset-transfers endpoint is used to conduct transfers of positions into and out of IB accounts.

Example asset transfer request into an IB account:

POST https://api.ibkr.com/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"
      }
    }
  }

Successful response, with 202 status code indicating that the transfer is pending:

  {
    "instructionResult": {
      "clientInstructionId": 1013031,
      "instructionType": "fop",
      "instructionStatus": "PENDING",
      "instructionId": 43091814
    },
    "instructionSetId": 1703,
    "status": 202
  }

Example ACATS transfer request out of an IB account:

POST https://api.ibkr.com/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": "sample signature"
    }
  }

Successful response, with 202 status code indicating that the transfer is pending:

  {
    "instructionResult": {
      "clientInstructionId": 7008998,
      "instructionType": "external_position_transfer",
      "instructionStatus": "PENDING",
      "instructionId": 43094000,
      "code": "",
      "description": ""
    },
    "instructionSetId": 3700,
    "status": 202
  }

The /gw/api/v1/statements can be used to retrieve statements in HTML, PDF, and compressed (gzip) HTML.

Example request:

POST https://api.ibkr.com/gw/api/v1/statements

{
    "accountId": "UXXXX",
    "startDate": "20230101",
    "endDate": "20230101",
    "mimeType": "text/html"
}
}

Successful response, where value delivers the requested statement data:

{
    "data": {
      "dataType": "string",
      "encoding": "string",
      "value": "string",
      "mimeType": "string"
    }
}