---
title: "Updating or deleting properties"
slug: "updating-or-deleting-properties"
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://<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](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://<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](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://<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:

```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://<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.