--- title: "Segregating holdings using custodian accounts" slug: "segregating-holdings-using-custodian-accounts" updated: 2026-04-08T15:03:39Z published: 2026-04-08T15:03:39Z canonical: "support.lusid.com/segregating-holdings-using-custodian-accounts" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.lusid.com/llms.txt > Use this file to discover all available pages before exploring further. # Segregating holdings using custodian accounts You have the option to set up any number of *custodian accounts* for a [transaction portfolio](/v1/docs/what-is-a-transaction-portfolio). When you load transactions into the portfolio, you can assign them to particular custodian accounts, or alternatively pro-rate across all accounts. You may simply do this in order to record custodian information for transactions, but you can also use custodian accounts to segregate holdings in the portfolio in the same way as [sub-holding keys](/v1/docs/what-is-a-sub-holding-key-shk) (SHKs). Advantages of custodian accounts over SHKs may be: - LUSID automatically establishes relationships between custodian accounts and [legal entities](/v1/docs/representing-institutions-in-lusid-using-legal-entities) or [person entities](/v1/docs/representing-people-in-lusid-using-person-entities) mastered in LUSID. - Custodian accounts are simpler to manage (create, read, update and delete). - Custodian accounts have their own [tax lot accounting methods](/v1/docs/what-are-the-supported-tax-lot-accounting-methods-in-lusid), so you can manage liquidation strategies at a more granular level. Consider the following scenario: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/CustodianAccounts (1).png) ## Creating custodian accounts LUSID web appLUSID APILuminesce To create one or more custodian accounts, call the [UpsertCustodianAccounts](https://www.lusid.com/docs/api/lusid/endpoints/transaction-portfolios/UpsertCustodianAccounts/) API, specifying the scope and code of the parent portfolio in the URL and, in the body of the request: - A `scope` and `code` that together uniquely identify the custodian account (the latter must be unique within the former). - An `accountNumber` and meaningful `accountName`. - An `accountingMethod` if you want to change the default option of average cost. [See a list](/v1/docs/what-are-the-supported-tax-lot-accounting-methods-in-lusid#supported-tax-lot-accounting-methods). - A `custodianIdentifier` referencing either a legal entity or a person entity already mastered in LUSID. This identifier consists of three parts: `idTypeScope`, `idTypeCode` and `code`. [More information](/v1/docs/representing-institutions-in-lusid-using-legal-entities#understanding-identifiers). - The `currency` of the portfolio. Note this field is informational only and not used by LUSID. - An `accountType` if you want to change the default of `Margin`. Note this field is informational only and not used by LUSID. - Optionally, one or more custom [properties](/v1/docs/properties) from the `CustodianAccount` domain to extend the data model. For example: ```json curl -X POST 'https://.lusid.com/api/api/transactionportfolios/Equities/Growth/custodianaccounts'  -H 'Content-Type: application/json-patch+json'  -H 'Authorization: Bearer '  -d '[  {    "scope": "CustodianAccounts",    "code": "HSBC-FIFO",    "accountNumber": "1234",    "accountName": "HSBC FIFO",    "accountingMethod": "FirstInFirstOut",    "currency": "GBP",    "custodianIdentifier": {    "idTypeScope": "InternationalBanks",      "idTypeCode": "BankId",      "code": "HSBC"    }  } ]' ``` Providing the request is successful, LUSID creates the custodian account, resolves the related entity, and sets the `status` to `Active`: ```json {  "custodianAccounts": [  {    "custodianAccountId": {      "scope": "CustodianAccounts",      "code": "HSBC-FIFO"    },    "status": "Active",    "accountNumber": "1234",    "accountName": "HSBC FIFO",    "accountingMethod": "FirstInFirstOut",    "currency": "GBP",    "accountType": "Margin"    "custodian": {      "displayName": "HSBC",      "description": "An international bank and investment firm"      "lusidLegalEntityId": "LUID_00003DAR",      "identifiers": {        "LegalEntity/InternationalBanks/BankId": {          "key": "LegalEntity/InternationalBanks/BankId",          "value": {            "labelValue": "HSBC"          },          "effectiveFrom": "0001-01-01T00:00:00.0000000+00:00",          "effectiveUntil": "9999-12-31T23:59:59.9999999+00:00"        }      }    }    "properties": {},    "relationships": []    }  ],  ... } ``` Navigate to **Data Management > Custodian Accounts** and click the **Create custodian accounts** button: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-T69IHAIC.png) Write a Luminesce SQL query using the [Lusid.Portfolio.CustodianAccount.Writer](/v1/docs/lusidportfoliocustodianaccountwriter) provider and execute it using a tool such as the LUSID web app: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-IKBB71KP.png) ## Registering custodian accounts in order to segregate holdings To use custodian accounts as SHKs you must register the `Transaction/system/CustodianAccountUniqueId` system property with the parent portfolio. > **Note**: There are two other system properties storing different information that you can use to register custodian accounts instead if you wish: `Transaction/system/CustodianAccountName` and `Transaction/system/CustodianAccountAccountNumber`. LUSID web appLUSID API For a new portfolio, call the [CreatePortfolio](https://www.lusid.com/docs/api/lusid/endpoints/transaction-portfolios/CreatePortfolio/) API and add the system property to the `subHoldingKeys` collection. For an existing portfolio, call the [PatchPortfolioDetails](https://www.lusid.com/docs/api/lusid/endpoints/transaction-portfolios/PatchPortfolioDetails/) API to append to the collection rather than overwriting existing SHKs, for example: ```json curl -X POST 'https://.lusid.com/api/api/transactionportfolios/Equities/Growth/details'  -H 'Authorization: Bearer '  -H 'Content-Type: application/json-patch+json'  -d '[  {    "value": "Transaction/system/CustodianAccountUniqueId",    "path": "/subHoldingKeys/-",    "op": "add"  } ]' ``` Follow the instructions to [create a transaction portfolio](/v1/docs/how-do-i-create-a-transaction-portfolio#using-the-lusid-web-app) and, at the bottom of the **Details** screen, add the system property to the list of **SUB HOLDING KEYS**, for example: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-1ZMJS7I9.png) ## Assigning transactions to custodian accounts and examining holdings LUSID web appLUSID API Call the [BatchUpsertTransactions](https://www.lusid.com/docs/api/lusid/endpoints/transaction-portfolios/BatchUpsertTransactions) API and specify a scope and code in the `custodianAccountId` object, for example: ```json curl -X POST 'https://.lusid.com/api/api/transactionportfolios/Equities/Growth/transactions/$batchUpsert?successMode=Partial'  -H 'Content-Type: application/json-patch+json'  -H 'Authorization: Bearer '  -d '{  "transactionRequest-1": {    "transactionId": "Txn-01",    "type": "StockIn",    "instrumentIdentifiers": {"Instrument/default/Figi": "BBG000C05BD1"},    "transactionDate": "2024-11-01T00:00:00.0000000+00:00",    "settlementDate": "2023-11-03T00:00:00.0000000+00:00",    "units": 1000,    "transactionPrice": {"price": 5, "type": "Price"},    "totalConsideration": {"amount": 5000, "currency": "GBP"},    "custodianAccountId": {      "scope": "CustodianAccounts",      "code": "HSBC-FIFO"    }  } }' ``` Follow the instructions to [book a transaction](/v1/docs/how-do-i-create-or-update-a-transaction) and choose a **Custodian Account**, for example: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-S5IL3N5P.png) You can [examine holdings](/v1/docs/how-do-i-generate-a-holdings-report) and group by the `Transaction/system/CustodianAccountUniqueId` SHK to segregate holdings by custodian account, for example: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image(853).png) ### Prorating transactions across all custodian accounts You can optionally call the [BatchUpsertTransactions](https://www.lusid.com/docs/api/lusid/endpoints/transaction-portfolios/BatchUpsertTransactions) API and set the `Transaction/default/AllocationMetho`system property to `Prorated` *instead* of specifying the `custodianAccountId` object, for example: ```json curl -X POST 'https://.lusid.com/api/api/transactionportfolios/Equities/Growth/transactions/$batchUpsert?successMode=Partial'  -H 'Content-Type: application/json-patch+json'  -H 'Authorization: Bearer '  -d '{  "transactionRequest-1": {    "transactionId": "Txn-05",    "type": "StockIn",    "instrumentIdentifiers": {"Instrument/default/Figi": "BBG000C05BD1"},    "transactionDate": "2024-11-02T00:00:00.0000000+00:00",    "settlementDate": "2023-11-04T00:00:00.0000000+00:00",    "units": 1000,    "transactionPrice": {"price": 4.5, "type": "Price"},    "totalConsideration": {"amount": 4500, "currency": "GBP"},    "properties": {      "Transaction/default/AllocationMethod": {        "key": "Transaction/default/AllocationMethod",        "value": {          "labelValue": "Prorated"        }      }    }  } }' ``` LUSID now distributes the units (1000) and cost (£4,500) proportionally among all custodian accounts with a holding in the underlying instrument that is greater than zero: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image(854).png) ## Valuing a portfolio with holdings segregated by custodian account You can specify the following [metrics](/v1/docs/what-is-a-metric#specifying-metrics-in-valuation-reports) when valuing a portfolio to retrieve more information about custodian accounts: - `CustodianAccount/CustodianAccountId/Scope` - `CustodianAccount/CustodianAccountId/Code` - `CustodianAccount/AccountNumber` - `CustodianAccount/Status` - `CustodianAccount/Name` - `CustodianAccount/AccountingMethod` - `CustodianAccount/Currency` - `CustodianAccount/AccountType` - `CustodianAccount/Custodian/displayName` - `CustodianAccount/Custodian/description` - `CustodianAccount/Custodian/lusidEntityId` For example: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-V79FINPI.png) ## Deleting custodian accounts You can either: - Soft-delete a custodian account to set the status to `Inactive`. It is still returned by the [ListCustodianAccounts](https://www.lusid.com/docs/api/lusid/endpoints/transaction-portfolios/ListCustodianAccounts) API. - Hard-delete a custodian account to set the status to `Deleted`. It is not returned by the `ListCustodianAccounts` API but is by the [GetCustodianAccount](https://www.lusid.com/docs/api/lusid/endpoints/transaction-portfolios/GetCustodianAccount) API. You can no longer assign new transactions to a deleted custodian account, but LUSID maintains existing holdings. LUSID web appLUSID APILuminesce Call the [DeleteCustodianAccounts](https://www.lusid.com/docs/api/lusid/endpoints/transaction-portfolios/DeleteCustodianAccounts/) API, specifying the scope and code of the parent portfolio in the URL, and a `deleteMode` of either `Hard` or `Soft`. In the body of the request, specify the scope and code of one or more custodian accounts, for example: ```json curl -X POST 'https://.lusid.com/api/api/transactionportfolios/Equities/Growth/custodianaccounts/$delete?deleteMode=Hard'  -H 'Content-Type: application/json-patch+json'  -H 'Authorization: Bearer '  -d '[  {    "scope": "CustodianAccounts",    "code": "HSBC-FIFO"  } ]' ``` Currently, the only option is to soft-delete a custodian account. Navigate to **Data Management > Custodian Accounts**, identify the custodian account to delete, and click the **Make inactive** button: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-34E0LQCH.png) Write a Luminesce SQL query using the [Lusid.Portfolio.CustodianAccount.Writer](/v1/docs/lusidportfoliocustodianaccountwriter#example-2-permanently-remove-a-custodian-account-from-a-portfolio) provider with a `WriteAction` of either `HardDelete` or `SoftDelete`, and execute it using a tool such as the LUSID web app: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-NVGKYLM7.png)