> This page is for TWS API.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://ibkrcampus.com/docs/llms.txt.

# Groups and Profiles

## Introduction

Financial Advisors are able to manage their allocation groups from the TWS API.

> **Info**
>
> Modifications made through the API will affect orders placed through TWS, the TWS API, Client Portal, and the Web API.

---

## Request FA Groups and Profiles

`EClient.requestFA(faDataType)`

Requests the FA configuration as set in TWS for the given [FA Data Type](#requestfa-fa-data-types).

**`faDataType`** `integer`

The configuration to retrieve. See FA Data Types table below.

---

\


#### Python

```python
self.requestFA(1)
```

#### Java

```java
client.requestFA(1);
```

#### C++

```cpp
m_pClient->requestFA(1);
```

#### C\#

```csharp
client.requestFA(1);
```

#### VB.NET

```vbnet
client.requestFA(1)
```

### requestFA FA Data Types

| Type Code | Type Name       | Description                                                                                                          |
| --------- | --------------- | -------------------------------------------------------------------------------------------------------------------- |
| 1         | Groups          | Offer traders a way to create a group of accounts and apply a single allocation method to all accounts in the group. |
| 3         | Account Aliases | Let you easily identify the accounts by meaningful names rather than account numbers.                                |

---

## Receive FA Groups and Profiles

`EWrapper.receiveFA(faDataType, faXmlData)`

Receives the Financial Advisor's configuration available in the TWS.

**`faDataType`** `integer`

The [faDataType](#requestfa-fa-data-types) value specified in the `requestFA` call.

---

**`faXmlData`** `string`

The xml-formatted configuration.

---

\


#### Python

```python
def receiveFA(self, faData: FaDataType, cxml: str):
	print("Receiving FA: ", faData)
	open('log/fa.xml', 'w').write(cxml)
```

#### Java

```java
@Override
public void receiveFA(int faDataType, String xml) {
	System.out.println("Receiving FA: " + faDataType + " - " + xml);
}
```

#### C++

```cpp
void TestCppClient::receiveFA(faDataType pFaDataType, const std::string& cxml) {
    std::cout << "Receiving FA: " << (int)pFaDataType << std::endl << cxml << std::endl;
}
```

#### C\#

```csharp
public virtual void receiveFA(int faDataType, string faXmlData)
{
	Console.WriteLine("Receing FA: "+faDataType+" - "+faXmlData);
}
```

#### VB.NET

```vbnet
Public Sub receiveFA(faDataType As Integer, faXmlData As String) Implements IBApi.EWrapper.receiveFA
  Console.WriteLine("Receing FA: " & faDataType & " - " & faXmlData)
End Sub
```

---

## Replace FA Allocations

`EClient.replaceFA(reqId, faDataType, xml)`

Replaces the FA configuration for the given FA Group or Profile.

To confirm that FA changes were saved, wait for the `EWrapper.replaceFAEnd` callback which provides the corresponding `reqId`. After saving, it is advised to verify the new FA setup via `EClient.requestFA`. If called before changes are fully saved, you may receive an error such as error 10230.

**`reqId`** `integer`

Request identifier used to track data.

---

**`faDataType`** `integer`

The configuration structure to change. Set to 1 (Groups). Passing other values may trigger [error 585](/docs/tws-api/doc/error/messages).

---

**`xml`** `string`

XML configuration for the allocation group. See the Allocation Method XML Format section below for details.

---

\


#### Python

```python
self.replaceFa(reqId, 1, xml)
```

#### Java

```java
client.replaceFa(reqId, 1, xml);
```

#### C++

```cpp
m_pClient->replaceFa(reqId, 1, xml);
```

#### C\#

```csharp
client.replaceFa(reqId, 1, xml);
```

#### VB.NET

```vbnet
client.replaceFa(reqId, 1, xml)
```

### replaceFA FA Data Types

| Type Code | Type Name       | Description                                                                                                          |
| --------- | --------------- | -------------------------------------------------------------------------------------------------------------------- |
| 1         | Groups          | Offer traders a way to create a group of accounts and apply a single allocation method to all accounts in the group. |
| 2         | Account Aliases | Let you easily identify the accounts by meaningful names rather than account numbers.                                |

### EWrapper.replaceFAEnd

`EWrapper.replaceFAEnd(reqId, text)`

Marks the end of the `replaceFA` reception.

**`reqId`** `integer`

Request identifier used to track data.

---

**`text`** `string`

The message text.

---

\


#### Python

```python
def replaceFAEnd(self, reqId: int, text: str):
    super().replaceFAEnd(reqId, text)
    print("ReplaceFAEnd.", "ReqId:", reqId, "Text:", text)
```

#### Java

```java
@Override
public void replaceFAEnd(int reqId, String text) {
        System.out.println(EWrapperMsgGenerator.replaceFAEnd(reqId, text));
}
```

#### C++

```cpp
void TestCppClient::replaceFAEnd(int reqId, const std::string& text) {
    printf("Replace FA End. Request: %d, Text:%s\n", reqId, text.c_str());
}
```

#### C\#

```csharp
public virtual void replaceFAEnd(int reqId, string text)
{
    Console.WriteLine("Replace FA End. ReqId: " + reqId + ", Text: " + text + "\n");
}
```

#### VB.NET

```vbnet
Public Sub replaceFAEnd(reqId As Integer, text As String) Implements IBApi.EWrapper.replaceFAEnd
    Console.WriteLine("replaceFAEnd. ReqId: {0}, Text: {1}", reqId, text)
End Sub
```

---

## Allocation Methods and Groups

A number of methods for account allocations are available with Financial Advisor and IBroker account structures to specify how trades should be distributed across multiple accounts.

Allocation Groups can be created or modified in the Trader Workstation directly as described in [TWS: Allocations and Transfers](https://www.ibkrguides.com/tws/usersguidebook/financialadvisors/create%20an%20account%20group%20for%20share%20allocation.htm).

Alternatively, allocation groups can be created or modified through the `EClient.replaceFA` method in the API.

Interactive Brokers supports two forms of allocation methods: allocation methods with calculations completed by Interactive Brokers, and a set of allocation methods calculated by the user and then specified.

**IB-computed allocation methods**

* Available Equity
* Equal Quantity
* Net Liquidation Value

**User-specified allocation methods** (formerly known as Allocation Profiles)

* Cash Quantity
* Percentages
* Ratios
* Shares

Allocation methods for financial advisor allocation groups are defined using an XML format. The examples below show how each supported allocation method is structured.

### Available Equity

Requires you to specify an order size. This method distributes shares based on the amount of available equity in each account. The system calculates ratios based on the Available Equity in each account and allocates shares based on these ratios.

**Example:** You transmit an order for 700 shares of stock XYZ. The account group includes three accounts, A, B and C with available equity in the amounts of \$25,000, \$50,000 and \$100,000 respectively. The system calculates a ratio of 1:2:4 and allocates 100 shares to Client A, 200 shares to Client B, and 400 shares to Client C.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<ListOfGroups>
  <Group>
    <name>MyTestProfile2</name>
    <defaultMethod>AvailableEquity</defaultMethod>
    <ListOfAccts varName="list">
      <Account>
        <acct>DU6202167</acct>
      </Account>
      <Account>
        <acct>DU6202168</acct>
      </Account>
    </ListOfAccts>
  </Group>
</ListOfGroups>
```

### Monetary Amount

The Monetary Amount method calculates the number of units to be allocated based on the monetary value assigned to each account.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<ListOfGroups>
  <Group>
  <name>MyTestProfile2</name>
  <defaultMethod>MonetaryAmount</defaultMethod>
  
  <ListOfAccts varName="list">
  <Account>
    <acct>DU6202167</acct>
    <amount>1000.0</amount>
  </Account>
  <Account>
    <acct>DU6202168</acct>
    <amount>2000.0</amount>
  </Account>
  </ListOfAccts>
  </Group>
</ListOfGroups>
```

### Equal Quantity

Requires you to specify an order size. This method distributes shares equally between all accounts in the group.

**Example:** You transmit an order for 400 shares of stock ABC. If your Account Group includes four accounts, each account receives 100 shares. If your Account Group includes six accounts, each account receives 66 shares, and then 1 share is allocated to each account until all are distributed.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<ListOfGroups>
  <Group>
    <name>MyTestProfile2</name>
    <defaultMethod>Equal</defaultMethod>
    <ListOfAccts varName="list">
      <Account>
        <acct>DU6202167</acct>
      </Account>
      <Account>
        <acct>DU6202168</acct>
      </Account>
    </ListOfAccts>
  </Group>
</ListOfGroups>
```

### Net Liquidation Value

Requires you to specify an order size. This method distributes shares based on the net liquidation value of each account. The system calculates ratios based on the Net Liquidation value in each account and allocates shares based on these ratios.

**Example:** You transmit an order for 700 shares of stock XYZ. The account group includes three accounts, A, B and C with Net Liquidation values of \$25,000, \$50,000 and \$100,000 respectively. The system calculates a ratio of 1:2:4 and allocates 100 shares to Client A, 200 shares to Client B, and 400 shares to Client C.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<ListOfGroups>
  <Group>
    <name>MyTestProfile2</name>
    <defaultMethod>NetLiq</defaultMethod>
    <ListOfAccts varName="list">
      <Account>
        <acct>DU6202167</acct>
      </Account>
      <Account>
        <acct>DU6202168</acct>
      </Account>
    </ListOfAccts>
  </Group>
</ListOfGroups>
```

### Percentages

This method will split the total number of shares in the order between listed accounts based on the percentages you indicate.

**Example:** Assume an order for 300 shares of stock ABC is transmitted. Account A is set to have 60.0 percentage while Account B is set to have 40.0 percentage. Account A should receive 180 shares and Account B should receive 120 shares.

**Note:** Do not specify an order size. Since the quantity is calculated by the system, the order size is displayed in the Quantity field after the order is acknowledged. This method increases or decreases an already existing position. Positive percents will increase a position, negative percents will decrease a position. For example, to fully close out a position, specify a percentage of -100.

|                |                    |                    |
| -------------- | ------------------ | ------------------ |
| **BUY ORDER**  | *Positive Percent* | *Negative Percent* |
| Long Position  | Increases position | No effect          |
| Short Position | No effect          | Decreases position |

|                |                    |                    |
| -------------- | ------------------ | ------------------ |
| **SELL ORDER** | *Positive Percent* | *Negative Percent* |
| Long Position  | No effect          | Decreases position |
| Short Position | Increases position | No effect          |

```xml
<?xml version="1.0" encoding="UTF-8"?>
<ListOfGroups>
  <Group>
  <name>MyTestProfile2</name>
  <defaultMethod>Percent</defaultMethod>
  <ListOfAccts varName="list">
  <Account>
    <acct>DU6202167</acct>
    <amount>60.0</amount>
  </Account>
  <Account>
    <acct>DU6202168</acct>
    <amount>40.0</amount>
  </Account>
  </ListOfAccts>
  </Group>
</ListOfGroups>
```

### Ratios

This method calculates the allocation of shares based on the ratios you enter.

**Example:** Assume an order for 300 shares of stock ABC is transmitted. A ratio of 1.0 and 2.0 is set to Account A and Account B. Account A should receive 100 shares and Account B should receive 200 shares.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<ListOfGroups>
  <Group>
  <name>MyTestProfile2</name>
  <defaultMethod>Ratio</defaultMethod>
  
  <ListOfAccts varName="list">
  <Account>
    <acct>DU6202167</acct>
    <amount>1.0</amount>
  </Account>
  <Account>
    <acct>DU6202168</acct>
    <amount>2.0</amount>
  </Account>
  </ListOfAccts>
  </Group>
</ListOfGroups>
```

### Contracts or Shares

This method allocates the absolute number of shares you enter to each account listed. If you use this method, the order size is calculated by adding together the number of shares allocated to each account in the profile.

**Example:** Assume an order for 300 shares of stock ABC is transmitted. Account A is set to receive 100.0 shares while Account B is set to receive 200.0 shares. Account A should receive 100 shares and Account B should receive 200 shares.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<ListOfGroups>
  <Group>
  <name>MyTestProfile2</name>
  <defaultMethod>ContractsOrShares</defaultMethod>
  
  <ListOfAccts varName="list">
  <Account>
    <acct>DU6202167</acct>
    <amount>100.0</amount>
  </Account>
  <Account>
    <acct>DU6202168</acct>
    <amount>200.0</amount>
  </Account>
  </ListOfAccts>
  </Group>
</ListOfGroups>
```