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
Call the UpsertCustodianAccounts API with the scope and code of the parent portfolio, for example:
curl -X POST 'https://<your-domain>.lusid.com/api/api/transactionportfolios/Equities/Growth/custodianaccounts'
-H 'Content-Type: application/json-patch+json'
-H 'Authorization: Bearer <your-API-access-token>'
-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:
{
"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:
Write a Luminesce SQL query using the Lusid.Portfolio.CustodianAccount.Writer provider and execute it using a tool such as the LUSID web app:
Data fields and properties
This section supplements the API documentation 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 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.
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.
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 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 lifecycle or corporate action events, where the originating holding is (for example) an equity or bond but the cash proceeds/outlay should be assigned to 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 from the CustodianAccount domain.
Subsequent updates
You can update a custodian account at any time by calling the UpsertCustodianAccounts API with the scope and code of the account to change.
For information about updating or deleting properties, see this article.
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/CustodianAccountNameandTransaction/system/CustodianAccountAccountNumber.
For a new portfolio, call the CreatePortfolio API and add the system property to the subHoldingKeys collection. For an existing portfolio, call the PatchPortfolioDetails API to append to the collection rather than overwriting existing SHKs, for example:
curl -X POST 'https://<your-domain>.lusid.com/api/api/transactionportfolios/Equities/Growth/details'
-H 'Authorization: Bearer <your-API-access-token>'
-H 'Content-Type: application/json-patch+json'
-d '[
{
"value": "Transaction/system/CustodianAccountUniqueId",
"path": "/subHoldingKeys/-",
"op": "add"
}
]'Follow the instructions to create a transaction portfolio and, at the bottom of the Details screen, add the system property to the list of SUB HOLDING KEYS, for example:
Deleting custodian accounts
You can either:
Soft-delete a custodian account to set the status to
Inactive. It is still returned by the ListCustodianAccounts API.Hard-delete a custodian account to set the status to
Deleted. It is not returned by theListCustodianAccountsAPI but is by the GetCustodianAccount API.
You can no longer assign new transactions to a deleted custodian account, but LUSID maintains existing holdings.
Call the 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:
curl -X POST 'https://<your-domain>.lusid.com/api/api/transactionportfolios/Equities/Growth/custodianaccounts/$delete?deleteMode=Hard'
-H 'Content-Type: application/json-patch+json'
-H 'Authorization: Bearer <your-API-access-token>'
-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:
Write a Luminesce SQL query using the Lusid.Portfolio.CustodianAccount.Writer provider with a WriteAction of either HardDelete or SoftDelete, and execute it using a tool such as the LUSID web app:
