Updating or deleting properties

You can add properties to entities at the same time as you create those entities using APIs specific to the entity type.

Consider the following example of a call to the UpsertInstruments API to master a new instrument with three properties:

• CountryCode is a single-value perpetual property.
• TraderName is a multi-value perpetual property.
• AnalystRating is a time-variant property.

curl -X POST "https://<your-domain>.lusid.com/api/api/instruments"
  -H "Authorization: Bearer <your-API-access-token>"
  -H "Content-Type: application/json"
  -d '{"upsert-request-1": {
   "name": "BP $0.25 LDN",
   "identifiers": {"Figi": {"value": "BBG000C05BD1"}},
   "definition": {"instrumentType": "Equity", "domCcy": "GBP"},
   "properties": [
     {
       "key": "Instrument/BBG/CountryCode",
       "value": {"labelValue": "UK"}
     },
     {
       "key": "Instrument/BBG/TraderName",
       "value": {
         "labelValueSet": {
           "values": ["Joe Bloggs","Jane Doe","Matt Smith"]
         }
       }
     },
     {
       "key": "Instrument/BBG/AnalystRating",
       "value": {"labelValue": "AAA"},
       "effectiveFrom": "2021-01-01"
     }
   ]
 }
}'

You can subsequently update these properties using either the same UpsertInstruments API or the dedicated UpsertInstrumentProperties API. Whichever you use, note the following principles apply:

• If you omit a property in the update request, the existing value is unchanged.
• If you include a property in the update request and provide a value, the existing property is updated. Note that:
  • For a multi-value property, the existing set is replaced by the new set, so if you want to retain existing values, include them in the new set.
  • For a time-variant property, the new value supersedes the existing value from the effectiveFrom provided; the existing value's effectiveUntil date is automatically truncated. The new value is valid until the end of time unless an explicit effectiveUntil date is provided. See how to retrieve values as a time-series.
• If you include a property in the update request but explicitly null the value, the existing property is deleted. More information.

For example, consider the following subsequent call to the UpsertInstruments API for the same instrument:

curl -X POST "https://<your-domain>.lusid.com/api/api/instruments"
  -H "Authorization: Bearer <your-API-access-token>"
  -H "Content-Type: application/json"
  -d '{"upsert-request-1": {
   "name": "BP PLC",
   "identifiers": {"Figi": {"value": "BBG000C05BD1"}},
   "definition": {"instrumentType": "Equity", "domCcy": "GBP"},
   "properties": [
     {
       "key": "Instrument/BBG/TraderName",
       "value": {
         "labelValueSet": {
           "values": ["Joe Bloggs","Jane Doe","John Doe"]
         }
       }
     },
     {
       "key": "Instrument/BBG/AnalystRating",
       "value": {"labelValue": "BB"},
       "effectiveFrom": "2022-01-01"
     }
   ]
 }
}'

This request:

• Changes the name entity data field from BP $0.25 LDN to BP PLC.
• Retains the CountryCode property value of UK (the property is omitted from the request).
• Changes the set of TraderName property values from Joe Bloggs,Jane Doe,Matt Smith to Joe Bloggs,Jane Doe,John Doe.
• Sets the AnalystRating property value to BB from 1 January 2022. The original AAA value remains valid from 1 January 2021 until 1 January 2022. Without an explicit effectiveUntil, BB is set to be valid until the end of time.

Deleting properties

Perpetual properties

You can call a dedicated API for many types of entity, for example DeleteInstrumentProperties. 

Alternatively, you can call an Upsert* API and explicitly null a property value. For example, to delete a CountryCode property for an instrument you could call either the UpsertInstruments API (shown below) or the UpsertInstrumentProperties API:

curl -X POST "https://<your-domain>.lusid.com/api/api/instruments"
  -H "Authorization: Bearer <your-API-access-token>"
  -H "Content-Type: application/json"
  -d '{"upsert-request-1": {
   "name": "BP PLC",
   "identifiers": {"Figi": {"value": "BBG000C05BD1"}},
   "definition": {"instrumentType": "Equity", "domCcy": "GBP"},
   "properties": [
     {
       "key": "Instrument/BBG/CountryCode",
       "value": null
     }
   ]
 }
}'

Note you pass None instead of null to the equivalent method in the Python SDK: 

properties = [
    lusid.models.ModelProperty(
        key = "Instrument/BBG/CountryCode",
        value = None
    )
]

Time-variant properties

A time-variant property is likely to have multiple values valid during different time periods. Consider the following history of values for an AnalystRating property:

To delete an individual value, call the DeleteInstrumentProperties API and supply an effectiveAt with the inception date of the value to delete, for example 2021-01-01 to delete the AAA value. The BB and AAB values remain valid for their respective date ranges.

To delete all the values and remove the AnalystRating property entirely, call either the UpsertInstruments API (shown below) or the UpsertInstrumentProperties API and explicitly null the property value, supplying effectiveFrom and effectiveUntil parameters encompassing all of time, for example:

curl -X POST "https://<your-domain>.lusid.com/api/api/instruments"
  -H "Authorization: Bearer <your-API-access-token>"
  -H "Content-Type: application/json"
  -d '{"upsert-request-1": {
   "name": "BP PLC",
   "identifiers": {"Figi": {"value": "BBG000C05BD1"}},
   "definition": {"instrumentType": "Equity", "domCcy": "GBP"}
   "properties": [
     {
       "key": "Instrument/BBG/AnalystRating",
       "value": null,
       "effectiveFrom": "0001-01-01",
       "effectiveUntil": "9999-12-31"
     }
   ]
 }
}'

Note deleting an instrument's AnalystRating property entirely means it is no longer returned by a call to the ListInstruments, GetInstruments, GetInstrument, ListInstrumentProperties or GetInstrumentProperties APIs. However, the history of the time-series is still available by calling the GetInstrumentPropertyTimeSeries API.