--- title: "Updating or deleting properties" slug: "updating-or-deleting-properties" tags: ["properties", "update", "updating", "delete", "deleting"] updated: 2024-08-19T12:28:55Z published: 2024-08-19T12:28:55Z canonical: "support.lusid.com/updating-or-deleting-properties" --- > ## 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. # 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](/v1/docs/how-do-i-add-a-property-to-an-entity#using-the-lusid-rest-api). Consider the following example of a call to the [UpsertInstruments](https://www.lusid.com/docs/api#operation/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](/v1/docs/what-is-bitemporal-data#perpetual-time-variant) property. ```json curl -X POST "https://.lusid.com/api/api/instruments"  -H "Authorization: Bearer "  -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](https://www.lusid.com/docs/api#operation/UpsertInstrumentsProperties) 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](/v1/docs/how-do-i-retrieve-a-time-variant-property-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](/v1/docs/updating-or-deleting-properties#deleting-properties). For example, consider the following subsequent call to the `UpsertInstruments` API for the same instrument: ```json curl -X POST "https://.lusid.com/api/api/instruments"  -H "Authorization: Bearer "  -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](https://www.lusid.com/docs/api#operation/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: ```json curl -X POST "https://.lusid.com/api/api/instruments"  -H "Authorization: Bearer "  -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: ```sql 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: | **Value** | **Effective from** | **Effective until** | | --- | --- | --- | | `AAA` | 2021-01-01 | 2022-01-01 | | `BB` | 2022-01-01 | 2023-01-01 | | `AAB` | 2023-01-01 | 9999-12-31 | 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: ```json curl -X POST "https://.lusid.com/api/api/instruments"  -H "Authorization: Bearer "  -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.