/** * LUSID API * # Introduction This page documents the [LUSID APIs](https://www.lusid.com/api/swagger), which allows authorised clients to query and update their data within the LUSID platform. SDKs to interact with the LUSID APIs are available in the following languages : * [C#](https://github.com/finbourne/lusid-sdk-csharp) * [Java](https://github.com/finbourne/lusid-sdk-java) * [JavaScript](https://github.com/finbourne/lusid-sdk-js) * [Python](https://github.com/finbourne/lusid-sdk-python) # Data Model The LUSID API has a relatively lightweight but extremely powerful data model. One of the goals of LUSID was not to enforce on clients a single rigid data model but rather to provide a flexible foundation onto which clients can map their own data models. The core entities in LUSID provide a minimal structure and set of relationships, and the data model can be extended using Properties. The LUSID data model is exposed through the LUSID APIs. The APIs provide access to both business objects and the meta data used to configure the systems behaviours. The key business entities are: - * **Portfolios** A portfolio is a container for transactions and holdings (a **Transaction Portfolio**) or constituents (a **Reference Portfolio**). * **Derived Portfolios**. Derived Portfolios allow Portfolios to be created based on other Portfolios, by overriding or adding specific items. * **Holdings** A Holding is a quantity of an Instrument or a balance of cash within a Portfolio. Holdings can only be adjusted via Transactions. * **Transactions** A Transaction is an economic event that occurs in a Portfolio, causing its holdings to change. * **Corporate Actions** A corporate action is a market event which occurs to an Instrument and thus applies to all portfolios which holding the instrument. Examples are stock splits or mergers. * **Constituents** A constituent is a record in a Reference Portfolio containing an Instrument and an associated weight. * **Instruments** An instrument represents a currency, tradable instrument or OTC contract that is attached to a transaction and a holding. * **Properties** All major entities allow additional user defined properties to be associated with them. For example, a Portfolio manager may be associated with a portfolio. Meta data includes: - * **Transaction Types** Transactions are booked with a specific transaction type. The types are client defined and are used to map the Transaction to a series of movements which update the portfolio holdings. * **Properties Types** Types of user defined properties used within the system. ## Scope All data in LUSID is segregated at the client level. Entities in LUSID are identifiable by a unique code. Every entity lives within a logical data partition known as a Scope. Scope is an identity namespace allowing two entities with the same unique code to co-exist within individual address spaces. For example, prices for equities from different vendors may be uploaded into different scopes such as `client/vendor1` and `client/vendor2`. A portfolio may then be valued using either of the price sources by referencing the appropriate scope. LUSID Clients cannot access scopes of other clients. ## Instruments LUSID has its own built-in instrument master which you can use to master your own instrument universe. Every instrument must be created with one or more unique market identifiers, such as [FIGI](https://openfigi.com/). For any non-listed instruments (eg OTCs), you can upload an instrument against a custom ID of your choosing. In addition, LUSID will allocate each instrument a unique \'LUSID instrument identifier\'. The LUSID instrument identifier is what is used when uploading transactions, holdings, prices, etc. The API exposes an `instrument/lookup` endpoint which can be used to lookup these LUSID identifiers using their market identifiers. Cash can be referenced using the ISO currency code prefixed with \"`CCY_`\" e.g. `CCY_GBP` ## Instrument Data Instrument data can be uploaded to the system using the [Instrument Properties](#tag/InstrumentProperties) endpoint. | Field|Type|Description | | ---|---|--- | | Key|propertykey|The key of the property. This takes the format {domain}/{scope}/{code} e.g. \'Instrument/system/Name\' or \'Transaction/strategy/quantsignal\'. | | Value|string|The value of the property. | | EffectiveFrom|datetimeoffset|The effective datetime from which the property is valid. | ## Transaction Portfolios Portfolios are the top-level entity containers within LUSID, containing transactions, corporate actions and holdings. The transactions build up the portfolio holdings on which valuations, analytics profit & loss and risk can be calculated. Properties can be associated with Portfolios to add in additional data. Portfolio properties can be changed over time, for example to allow a Portfolio Manager to be linked with a Portfolio. Additionally, portfolios can be securitised and held by other portfolios, allowing LUSID to perform \"drill-through\" into underlying fund holdings ### Derived Portfolios LUSID also allows for a portfolio to be composed of another portfolio via derived portfolios. A derived portfolio can contain its own transactions and also inherits any transactions from its parent portfolio. Any changes made to the parent portfolio are automatically reflected in derived portfolio. Derived portfolios in conjunction with scopes are a powerful construct. For example, to do pre-trade what-if analysis, a derived portfolio could be created a new namespace linked to the underlying live (parent) portfolio. Analysis can then be undertaken on the derived portfolio without affecting the live portfolio. ### Transactions A transaction represents an economic activity against a Portfolio. Transactions are processed according to a configuration. This will tell the LUSID engine how to interpret the transaction and correctly update the holdings. LUSID comes with a set of transaction types you can use out of the box, or you can configure your own set(s) of transactions. For more details see the [LUSID Getting Started Guide for transaction configuration.](https://support.lusid.com/configuring-transaction-types) | Field|Type|Description | | ---|---|--- | | TransactionId|string|The unique identifier for the transaction. | | Type|string|The type of the transaction e.g. \'Buy\', \'Sell\'. The transaction type should have been pre-configured via the System Configuration API endpoint. If it hasn\'t been pre-configured the transaction will still be updated or inserted however you will be unable to generate the resultant holdings for the portfolio that contains this transaction as LUSID does not know how to process it. | | InstrumentIdentifiers|map|A set of instrument identifiers to use to resolve the transaction to a unique instrument. | | TransactionDate|dateorcutlabel|The date of the transaction. | | SettlementDate|dateorcutlabel|The settlement date of the transaction. | | Units|decimal|The number of units transacted in the associated instrument. | | TransactionPrice|transactionprice|The price for each unit of the transacted instrument in the transaction currency. | | TotalConsideration|currencyandamount|The total value of the transaction in the settlement currency. | | ExchangeRate|decimal|The exchange rate between the transaction and settlement currency. For example if the transaction currency is in USD and the settlement currency is in GBP this this the USD/GBP rate. | | TransactionCurrency|currency|The transaction currency. | | Properties|map|Set of unique transaction properties and associated values to store with the transaction. Each property must be from the \'Transaction\' domain. | | CounterpartyId|string|The identifier for the counterparty of the transaction. | | Source|string|The source of the transaction. This is used to look up the appropriate transaction group set in the transaction type configuration. | From these fields, the following values can be calculated * **Transaction value in Transaction currency**: TotalConsideration / ExchangeRate * **Transaction value in Portfolio currency**: Transaction value in Transaction currency * TradeToPortfolioRate #### Example Transactions ##### A Common Purchase Example Three example transactions are shown in the table below. They represent a purchase of USD denominated IBM shares within a Sterling denominated portfolio. * The first two transactions are for separate buy and fx trades * Buying 500 IBM shares for $71,480.00 * A spot foreign exchange conversion to fund the IBM purchase. (Buy $71,480.00 for £54,846.60) * The third transaction is an alternate version of the above trades. Buying 500 IBM shares and settling directly in Sterling. | Column | Buy Trade | Fx Trade | Buy Trade with foreign Settlement | | ----- | ----- | ----- | ----- | | TransactionId | FBN00001 | FBN00002 | FBN00003 | | Type | Buy | FxBuy | Buy | | InstrumentIdentifiers | { \"figi\", \"BBG000BLNNH6\" } | { \"CCY\", \"CCY_USD\" } | { \"figi\", \"BBG000BLNNH6\" } | | TransactionDate | 2018-08-02 | 2018-08-02 | 2018-08-02 | | SettlementDate | 2018-08-06 | 2018-08-06 | 2018-08-06 | | Units | 500 | 71480 | 500 | | TransactionPrice | 142.96 | 1 | 142.96 | | TradeCurrency | USD | USD | USD | | ExchangeRate | 1 | 0.7673 | 0.7673 | | TotalConsideration.Amount | 71480.00 | 54846.60 | 54846.60 | | TotalConsideration.Currency | USD | GBP | GBP | | Trade/default/TradeToPortfolioRate* | 0.7673 | 0.7673 | 0.7673 | [* This is a property field] ##### A Forward FX Example LUSID has a flexible transaction modelling system, meaning there are a number of different ways of modelling forward fx trades. The default LUSID transaction types are FwdFxBuy and FwdFxSell. Using these transaction types, LUSID will generate two holdings for each Forward FX trade, one for each currency in the trade. An example Forward Fx trade to sell GBP for USD in a JPY-denominated portfolio is shown below: | Column | Forward \'Sell\' Trade | Notes | | ----- | ----- | ---- | | TransactionId | FBN00004 | | | Type | FwdFxSell | | | InstrumentIdentifiers | { \"Instrument/default/Currency\", \"GBP\" } | | | TransactionDate | 2018-08-02 | | | SettlementDate | 2019-02-06 | Six month forward | | Units | 10000.00 | Units of GBP | | TransactionPrice | 1 | | | TradeCurrency | GBP | Currency being sold | | ExchangeRate | 1.3142 | Agreed rate between GBP and USD | | TotalConsideration.Amount | 13142.00 | Amount in the settlement currency, USD | | TotalConsideration.Currency | USD | Settlement currency | | Trade/default/TradeToPortfolioRate | 142.88 | Rate between trade currency, GBP and portfolio base currency, JPY | Please note that exactly the same economic behaviour could be modelled using the FwdFxBuy Transaction Type with the amounts and rates reversed. ### Holdings A holding represents a position in an instrument or cash on a given date. | Field|Type|Description | | ---|---|--- | | InstrumentUid|string|The unqiue Lusid Instrument Id (LUID) of the instrument that the holding is in. | | SubHoldingKeys|map|The sub-holding properties which identify the holding. Each property will be from the \'Transaction\' domain. These are configured when a transaction portfolio is created. | | Properties|map|The properties which have been requested to be decorated onto the holding. These will be from the \'Instrument\' or \'Holding\' domain. | | HoldingType|string|The type of the holding e.g. Position, Balance, CashCommitment, Receivable, ForwardFX etc. | | Units|decimal|The total number of units of the holding. | | SettledUnits|decimal|The total number of settled units of the holding. | | Cost|currencyandamount|The total cost of the holding in the transaction currency. | | CostPortfolioCcy|currencyandamount|The total cost of the holding in the portfolio currency. | | Transaction|transaction|The transaction associated with an unsettled holding. | ## Corporate Actions Corporate actions are represented within LUSID in terms of a set of instrument-specific \'transitions\'. These transitions are used to specify the participants of the corporate action, and the effect that the corporate action will have on holdings in those participants. ### Corporate Action | Field|Type|Description | | ---|---|--- | | CorporateActionCode|code|The unique identifier of this corporate action | | Description|string| | | AnnouncementDate|datetimeoffset|The announcement date of the corporate action | | ExDate|datetimeoffset|The ex date of the corporate action | | RecordDate|datetimeoffset|The record date of the corporate action | | PaymentDate|datetimeoffset|The payment date of the corporate action | | Transitions|corporateactiontransition[]|The transitions that result from this corporate action | ### Transition | Field|Type|Description | | ---|---|--- | | InputTransition|corporateactiontransitioncomponent|Indicating the basis of the corporate action - which security and how many units | | OutputTransitions|corporateactiontransitioncomponent[]|What will be generated relative to the input transition | ### Example Corporate Action Transitions #### A Dividend Action Transition In this example, for each share of IBM, 0.20 units (or 20 pence) of GBP are generated. | Column | Input Transition | Output Transition | | ----- | ----- | ----- | | Instrument Identifiers | { \"figi\" : \"BBG000BLNNH6\" } | { \"ccy\" : \"CCY_GBP\" } | | Units Factor | 1 | 0.20 | | Cost Factor | 1 | 0 | #### A Split Action Transition In this example, for each share of IBM, we end up with 2 units (2 shares) of IBM, with total value unchanged. | Column | Input Transition | Output Transition | | ----- | ----- | ----- | | Instrument Identifiers | { \"figi\" : \"BBG000BLNNH6\" } | { \"figi\" : \"BBG000BLNNH6\" } | | Units Factor | 1 | 2 | | Cost Factor | 1 | 1 | #### A Spinoff Action Transition In this example, for each share of IBM, we end up with 1 unit (1 share) of IBM and 3 units (3 shares) of Celestica, with 85% of the value remaining on the IBM share, and 5% in each Celestica share (15% total). | Column | Input Transition | Output Transition 1 | Output Transition 2 | | ----- | ----- | ----- | ----- | | Instrument Identifiers | { \"figi\" : \"BBG000BLNNH6\" } | { \"figi\" : \"BBG000BLNNH6\" } | { \"figi\" : \"BBG000HBGRF3\" } | | Units Factor | 1 | 1 | 3 | | Cost Factor | 1 | 0.85 | 0.15 | ## Reference Portfolios Reference portfolios are portfolios that contain constituents with weights. They are designed to represent entities such as indices and benchmarks. ### Constituents | Field|Type|Description | | ---|---|--- | | InstrumentIdentifiers|map|Unique instrument identifiers | | InstrumentUid|string|LUSID\'s internal unique instrument identifier, resolved from the instrument identifiers | | Currency|decimal| | | Weight|decimal| | | FloatingWeight|decimal| | ## Portfolio Groups Portfolio groups allow the construction of a hierarchy from portfolios and groups. Portfolio operations on the group are executed on an aggregated set of portfolios in the hierarchy. For example: * Global Portfolios _(group)_ * APAC _(group)_ * Hong Kong _(portfolio)_ * Japan _(portfolio)_ * Europe _(group)_ * France _(portfolio)_ * Germany _(portfolio)_ * UK _(portfolio)_ In this example **Global Portfolios** is a group that consists of an aggregate of **Hong Kong**, **Japan**, **France**, **Germany** and **UK** portfolios. ## Properties Properties are key-value pairs that can be applied to any entity within a domain (where a domain is `trade`, `portfolio`, `security` etc). Properties must be defined before use with a `PropertyDefinition` and can then subsequently be added to entities. ## Schema A detailed description of the entities used by the API and parameters for endpoints which take a JSON document can be retrieved via the `schema` endpoint. ## Meta data The following headers are returned on all responses from LUSID | Name | Purpose | | --- | --- | | lusid-meta-duration | Duration of the request | | lusid-meta-success | Whether or not LUSID considered the request to be successful | | lusid-meta-requestId | The unique identifier for the request | | lusid-schema-url | Url of the schema for the data being returned | | lusid-property-schema-url | Url of the schema for any properties | # Error Codes | Code|Name|Description | | ---|---|--- | | -10|Server Configuration Error| | | -1|Unknown error|An unexpected error was encountered on our side. | | 102|Version Not Found| | | 103|Api Rate Limit Violation| | | 104|Instrument Not Found| | | 105|Property Not Found| | | 106|Portfolio Recursion Depth| | | 108|Group Not Found| | | 109|Portfolio Not Found| | | 110|Property Schema Not Found| | | 111|Portfolio Ancestry Not Found| | | 112|Portfolio With Id Already Exists| | | 113|Orphaned Portfolio| | | 119|Missing Base Claims| | | 121|Property Not Defined| | | 122|Cannot Delete System Property| | | 123|Cannot Modify Immutable Property Field| | | 124|Property Already Exists| | | 125|Invalid Property Life Time| | | 126|Property Constraint Style Excludes Properties| | | 127|Cannot Modify Default Data Type| | | 128|Group Already Exists| | | 129|No Such Data Type| | | 130|Undefined Value For Data Type| | | 131|Unsupported Value Type Defined On Data Type| | | 132|Validation Error| | | 133|Loop Detected In Group Hierarchy| | | 134|Undefined Acceptable Values| | | 135|Sub Group Already Exists| | | 138|Price Source Not Found| | | 139|Analytic Store Not Found| | | 141|Analytic Store Already Exists| | | 143|Client Instrument Already Exists| | | 144|Duplicate In Parameter Set| | | 147|Results Not Found| | | 148|Order Field Not In Result Set| | | 149|Operation Failed| | | 150|Elastic Search Error| | | 151|Invalid Parameter Value| | | 153|Command Processing Failure| | | 154|Entity State Construction Failure| | | 155|Entity Timeline Does Not Exist| | | 156|Event Publish Failure| | | 157|Invalid Request| | | 158|Event Publish Unknown| | | 159|Event Query Failure| | | 160|Blob Did Not Exist| | | 162|Sub System Request Failure| | | 163|Sub System Configuration Failure| | | 165|Failed To Delete| | | 166|Upsert Client Instrument Failure| | | 167|Illegal As At Interval| | | 168|Illegal Bitemporal Query| | | 169|Invalid Alternate Id| | | 170|Cannot Add Source Portfolio Property Explicitly| | | 171|Entity Already Exists In Group| | | 173|Entity With Id Already Exists| | | 174|Derived Portfolio Details Do Not Exist| | | 176|Portfolio With Name Already Exists| | | 177|Invalid Transactions| | | 178|Reference Portfolio Not Found| | | 179|Duplicate Id| | | 180|Command Retrieval Failure| | | 181|Data Filter Application Failure| | | 182|Search Failed| | | 183|Movements Engine Configuration Key Failure| | | 184|Fx Rate Source Not Found| | | 185|Accrual Source Not Found| | | 186|Access Denied| | | 187|Invalid Identity Token| | | 188|Invalid Request Headers| | | 189|Price Not Found| | | 190|Invalid Sub Holding Keys Provided| | | 191|Duplicate Sub Holding Keys Provided| | | 192|Cut Definition Not Found| | | 193|Cut Definition Invalid| | | 194|Time Variant Property Deletion Date Unspecified| | | 195|Perpetual Property Deletion Date Specified| | | 196|Time Variant Property Upsert Date Unspecified| | | 197|Perpetual Property Upsert Date Specified| | | 200|Invalid Unit For Data Type| | | 201|Invalid Type For Data Type| | | 202|Invalid Value For Data Type| | | 203|Unit Not Defined For Data Type| | | 204|Units Not Supported On Data Type| | | 205|Cannot Specify Units On Data Type| | | 206|Unit Schema Inconsistent With Data Type| | | 207|Unit Definition Not Specified| | | 208|Duplicate Unit Definitions Specified| | | 209|Invalid Units Definition| | | 210|Invalid Instrument Identifier Unit| | | 211|Holdings Adjustment Does Not Exist| | | 212|Could Not Build Excel Url| | | 213|Could Not Get Excel Version| | | 214|Instrument By Code Not Found| | | 215|Entity Schema Does Not Exist| | | 216|Feature Not Supported On Portfolio Type| | | 217|Quote Not Found| | | 218|Invalid Quote Identifier| | | 219|Invalid Metric For Data Type| | | 220|Invalid Instrument Definition| | | 221|Instrument Upsert Failure| | | 222|Reference Portfolio Request Not Supported| | | 223|Transaction Portfolio Request Not Supported| | | 224|Invalid Property Value Assignment| | | 230|Transaction Type Not Found| | | 231|Transaction Type Duplication| | | 232|Portfolio Does Not Exist At Given Date| | | 233|Query Parser Failure| | | 234|Duplicate Constituent| | | 235|Unresolved Instrument Constituent| | | 236|Unresolved Instrument In Transition| | | 237|Missing Side Definitions| | | 299|Invalid Recipe| | | 300|Missing Recipe| | | 301|Dependencies| | | 304|Portfolio Preprocess Failure| | | 310|Valuation Engine Failure| | | 311|Task Factory Failure| | | 312|Task Evaluation Failure| | | 313|Task Generation Failure| | | 314|Engine Configuration Failure| | | 315|Model Specification Failure| | | 320|Market Data Key Failure| | | 321|Market Resolver Failure| | | 322|Market Data Failure| | | 330|Curve Failure| | | 331|Volatility Surface Failure| | | 332|Volatility Cube Failure| | | 350|Instrument Failure| | | 351|Cash Flows Failure| | | 352|Reference Data Failure| | | 360|Aggregation Failure| | | 361|Aggregation Measure Failure| | | 370|Result Retrieval Failure| | | 371|Result Processing Failure| | | 372|Vendor Result Processing Failure| | | 373|Vendor Result Mapping Failure| | | 374|Vendor Library Unauthorised| | | 375|Vendor Connectivity Error| | | 376|Vendor Interface Error| | | 377|Vendor Pricing Failure| | | 378|Vendor Translation Failure| | | 379|Vendor Key Mapping Failure| | | 380|Vendor Reflection Failure| | | 390|Attempt To Upsert Duplicate Quotes| | | 391|Corporate Action Source Does Not Exist| | | 392|Corporate Action Source Already Exists| | | 393|Instrument Identifier Already In Use| | | 394|Properties Not Found| | | 395|Batch Operation Aborted| | | 400|Invalid Iso4217 Currency Code| | | 401|Cannot Assign Instrument Identifier To Currency| | | 402|Cannot Assign Currency Identifier To Non Currency| | | 403|Currency Instrument Cannot Be Deleted| | | 404|Currency Instrument Cannot Have Economic Definition| | | 405|Currency Instrument Cannot Have Lookthrough Portfolio| | | 406|Cannot Create Currency Instrument With Multiple Identifiers| | | 407|Specified Currency Is Undefined| | | 410|Index Does Not Exist| | | 411|Sort Field Does Not Exist| | | 413|Negative Pagination Parameters| | | 414|Invalid Search Syntax| | | 415|Filter Execution Timeout| | | 420|Side Definition Inconsistent| | | 450|Invalid Quote Access Metadata Rule| | | 451|Access Metadata Not Found| | | 452|Invalid Access Metadata Identifier| | | 460|Standard Resource Not Found| | | 461|Standard Resource Conflict| | | 601|Person Identifier Already In Use| | | 602|Person Not Found| | | 603|Cannot Set Identifier| | | 617|Invalid Recipe Specification In Request| | | 618|Inline Recipe Deserialisation Failure| | | 619|Identifier Types Not Set For Entity Object| | | 620|Cannot Delete All Client Defined Identifiers| | | 650|The Order requested was not found.| | | 654|The Allocation requested was not found.| | | 655|Cannot build the fx forward target with the given holdings.| | | 656|Group does not contain expected entities.| | | 667|Relation definition already exists| | * * The version of the OpenAPI document: 0.10.1421 * Contact: info@finbourne.com * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). * https://openapi-generator.tech * Do not edit the class manually. */ export class InstrumentSearchProperty { /** * The property key of instrument property to search for. This will be from the \'Instrument\' domain and will take the format {domain}/{scope}/{code} e.g. \'Instrument/system/Isin\' or \'Instrument/MyScope/AssetClass\'. */ 'key': string; /** * The value of the property e.g. \'US0378331005\' or \'Equity\'. */ 'value': string; static discriminator: string | undefined = undefined; static attributeTypeMap: Array<{name: string, baseName: string, type: string}> = [ { "name": "key", "baseName": "key", "type": "string" }, { "name": "value", "baseName": "value", "type": "string" } ]; static getAttributeTypeMap() { return InstrumentSearchProperty.attributeTypeMap; } }