--- title: "How do I create and register custodian accounts?" slug: "how-do-i-create-and-register-custodian-accounts" status: "update" updated: 2026-09-04T09:24:10Z published: 2026-09-04T09:24:10Z canonical: "support.lusid.com/how-do-i-create-and-register-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. # How do I create and register custodian accounts? You can create as many custodian accounts as you like within a portfolio. Each account must link to a legal entity already mastered in LUSID. You can then register all the custodian accounts as a special kind of sub-holding key (SHK) for the portfolio in order to segregate holdings in the same way. ## Creating custodian accounts LUSID web appLUSID APILuminesce Call the [UpsertCustodianAccounts](https://www.lusid.com/docs/api/lusid/endpoints/transaction-portfolios/UpsertCustodianAccounts/) API with the scope and code of the parent portfolio, 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": "MyCAs",    "code": "HSBC-Stock",    "accountNumber": "10003786",    "accountName": "HSBC Stock",    "accountingMethod": "FirstInFirstOut",    "currency": "GBP",    "properties": {      "CustodianAccount/default/IsDefault": {        "key": "CustodianAccount/default/IsDefault",        "value": {          "labelValue": "True"        }      },      "CustodianAccount/default/RelatedAccounts": {        "key": "CustodianAccount/default/RelatedAccounts",        "value": {          "labelValueSet": {            "values": [              "MyCAs/HSBC-Cash",              "MyCAs/HSBC-CashMargin"            ]          }        },      }    },    "custodianIdentifier": {      "idTypeScope": "InternationalBanks",      "idTypeCode": "BankId",      "code": "HSBC"    },    "accountType": "Cash"  } ]' ``` Providing the request is successful, LUSID creates the custodian account, resolves the legal entity, and sets the `status` to `Active`: ```json {  "custodianAccounts": [    {      "custodianAccountId": {        "scope": "MyCAs",        "code": "HSBC-Stock"      },      "status": "Active",      "accountNumber": "10003786",      "accountName": "HSBC Stock",      "accountingMethod": "FirstInFirstOut",      "currency": "GBP",      "properties": {        "CustodianAccount/default/IsDefault": {          "key": "CustodianAccount/default/IsDefault",          "value": {            "labelValue": "True"          },          "effectiveFrom": "0001-01-01T00:00:00.0000000+00:00"        },        "CustodianAccount/default/RelatedAccounts": {          "key": "CustodianAccount/default/RelatedAccounts",          "value": {            "labelValueSet": {              "values": [                "MyCAs/HSBC-Cash",                "MyCAs/HSBC-CashMargin"              ]            }          },          "effectiveFrom": "0001-01-01T00:00:00.0000000+00:00"        }      },      "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"          }        },        "relationships": [],      },      "accountType": "Cash"    }  ],  ... } ``` Navigate to **Data Management > Custodian Accounts**, choose a parent portfolio, and click the **Create custodian accounts** button: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-2BXF4K78.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) ### Data fields and properties This section supplements the [API documentation](https://www.lusid.com/docs/api/lusid/endpoints/transaction-portfolios/UpsertCustodianAccounts/) and on-screen help text in the LUSID web app. #### Fields A custodian account is identified within a portfolio by a `scope`, and a `code` that must be unique within that scope. You must specify an `accountName`, `accountNumber` and `currency`, but these fields are informational only and not used by LUSID. You can choose an `accountingMethod` from [this list](/v1/docs/what-are-the-supported-tax-lot-accounting-methods-in-lusid#supported-tax-lot-accounting-methods) that is different to that of the parent portfolio. To inherit the portfolio method, specify `Default`. You must specify a `custodianIdentifier` referencing a legal 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). We recommend specifying an `accountType` to identity the purpose of the custodian account, for example `Stock` or `Cash` or `CashMargin`. LUSID uses this account type in its transaction resolution mechanism. [More information](/v1/docs/how-does-lusid-resolve-transactions-to-custodian-accounts). You have the option to set a custodian account as the default for its `accountType` within the portfolio, so for example `HSBC-Stock` as the default among all `Stock`-type custodian accounts. This helps prevent [resolution failures](/v1/docs/how-does-lusid-resolve-transactions-to-custodian-accounts) if a transaction’s movements are not explicitly assigned. To do this, set the `CustodianAccount/default/IsDefault` system property to `True`. You have the option to nominate a set of *related* custodian accounts, so for example you could specify that `HSBC-Cash` and `HSBC-CashMargin` are related to `HSBC-Stock`. This helps prevent resolution failures for transactions automatically generated by LUSID in response to instrument or corporate action events, where the original holding is (for example) an equity or bond but the cash proceeds/outlay should rest with a `Cash`-type custodian account. To do this, set the `CustodianAccount/default/RelatedAccounts` system property to an array of `<custodian-account-scope>/<custodian-account-code>` identifiers; note related accounts must all have a different `accountType`. #### Properties You can optionally extend the data model of a custodian account by adding custom [properties](https://support.lusid.com/v1/docs/properties) from the `CustodianAccount` domain. ### Subsequent updates You can update a custodian account at any time by calling the [UpsertCustodianAccounts](https://www.lusid.com/docs/api/lusid/endpoints/transaction-portfolios/UpsertCustodianAccounts/) API with the scope and code of the account to change. For information about updating or deleting properties, see [this article](/v1/docs/updating-or-deleting-properties). ## Registering custodian accounts in order to segregate holdings To segregate holdings using custodian accounts, register the `Transaction/system/CustodianAccountUniqueId` system property as a SHK with the parent portfolio. > **Note**: There are two other system properties 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) ## 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)