---
title: "How do I add a property to an entity?"
slug: "how-do-i-add-a-property-to-an-entity"
updated: 2026-03-16T10:40:08Z
published: 2026-03-16T10:40:08Z
canonical: "support.lusid.com/how-do-i-add-a-property-to-an-entity"
---

> ## 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.

# How do I add a property to an entity?

You can add a property to most types of entity and specify a single value. [Adding a multi-value property](/v1/docs/how-do-i-add-a-multi-value-property-to-an-entity).

For example, you could add an `Instrument/BBG/AnalystRating` property to an instrument and give it the value `AAA`. Note the following:

- The property value must conform to the data type specified by the underlying [property type](/v1/docs/how-do-i-create-a-property-type).
- The data type of the property type determines whether property values must be created as [label values or metric values](/v1/docs/label-values-and-metric-values).
- The maximum number of characters is 1024 unless the data type of the property type is `unindexedText`. [More information](/v1/docs/storing-large-amounts-of-information-in-properties).
- A [time-variant](/v1/docs/what-is-bitemporal-data#understanding-perpetual-and-time-variant-data-items) property can have a different value during different time periods. You should specify an effective from 'start date'; it is effective until the start date of the next value.

Once added, you can [update](/v1/docs/updating-or-deleting-properties) a property value at any time. If you no longer need a property, you can [delete](/v1/docs/updating-or-deleting-properties) it.

## Using the LUSID REST API

Each entity type adheres to a specific methodology for adding properties to entities:

- If an entity type has an `Upsert*` API (for example [UpsertInstruments](https://www.lusid.com/docs/api#operation/UpsertInstruments)), you can add properties when you create or update entities (that is, at any time). There may be a dedicated property API that you can use independently if you want, for example [UpsertInstrumentProperties](https://www.lusid.com/docs/api#operation/UpsertInstrumentsProperties).
- If an entity type has a `Create*` API (for example [CreatePortfolio](https://www.lusid.com/docs/api#operation/CreatePortfolio)), you can add properties when you create entities. Subsequently, you must use a dedicated property API, for example [UpsertPortfolioProperties](https://www.lusid.com/docs/api#operation/UpsertPortfolioProperties).

Depending on the data type of the property type, you create a property value as either a label value or as a [metric value](/v1/docs/how-do-i-add-a-property-to-an-entity#creating-a-property-value-as-a-metric-value).

### Adding a property as a label value

If the property type [mandates a property value as a label value](/v1/docs/label-values-and-metric-values#creating-a-property-type-that-mandates-metric-values) (typically this is strings, datetimes and booleans), you must specify a `labelValue` object.

For example, to add an `Instrument/BBG/AnalystRating` string property with a value of `AAA` to an instrument when you master it, call the `UpsertInstruments` API and append to the `properties` collection:

- The `key` must be a 3-stage property key in the `Instrument` domain.
- The `value` must consist of a `labelValue` and the actual value as a string (that is, in quotes).
- `effectiveFrom` is nominally optional but for a time-variant property sets the 'start date' for the value; it must be a [valid date](/v1/docs/what-date-formats-are-accepted).

REST APIPython SDK

```bash
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/AnalystRating",
        "value": {
          "labelValue": "AAA"
        },
        "effectiveFrom": "2022-06-18T09:00:00.0000000+00:00"
      }
    ]
  }
}'
```

```python
instruments_api = lusid_api_factory.build(lusid.api.InstrumentsApi)

instruments_request = {
    "upsert_request_1": lusid.models.InstrumentDefinition(
        name = "BP $0.25 LDN",
        identifiers = {
            "Figi": lusid.models.InstrumentIdValue(value = "BBG000C05BD1"),
        },
        definition = lusid.models.Equity(
            instrument_type = "Equity", 
            dom_ccy = "GBP",
        ),
        properties = [
            lusid.models.ModelProperty(
                key = "Instrument/BBG/AnalystRating",
                value = lusid.models.PropertyValue(
                    label_value = "AAA"
                ),
                effective_from=datetime.datetime(2022, 1, 1, 9, 0, 0, tzinfo=datetime.timezone.utc)
            )
        ],
    )
}

try:
    instruments_response = instruments_api.upsert_instruments(
        request_body = instruments_request
    )
except lusid.ApiException as e:
    print(e)
```

### Adding a property as a metric value

If the property type [mandates a property value as a metric value](/v1/docs/label-values-and-metric-values#creating-a-property-type-that-mandates-metric-values) (typically this is numbers), you must specify a `metricValue` object.

For example, to add an `Instrument/Ibor/Fee` numeric property with a value of £30 to an instrument when you master it, call the `UpsertInstruments` API and append to the `properties` collection:

- The `key` must be a 3-stage property key in the `Instrument` domain.
- The `value` must be a `metricValue` object consisting of a numeric `value` and, if the [underlying unit schema](/v1/docs/label-values-and-metric-values#creating-a-property-type-that-mandates-metric-values) is `Iso4217Currency`, a string `unit` that complies with the schema's allowed values.
- `effectiveFrom` is nominally optional but for a time-variant property sets the 'start date' for the value; it must be a [valid date](/v1/docs/what-date-formats-are-accepted).

REST APIPython SDK

```bash
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/Ibor/Fee",
        "value": {
          "metricValue": {
            "value": 30,
            "unit": "GBP"
          }
        },
        "effectiveFrom": "2022-06-18T09:00:00.0000000+00:00"
      }
    ]
  }
}'
```

```python
instruments_api = lusid_api_factory.build(lusid.api.InstrumentsApi)
instruments_request = {
    "upsert_request_1": lusid.models.InstrumentDefinition(
        name = "BP $0.25 LDN",
        identifiers = {
            "Figi": lusid.models.InstrumentIdValue(value = "BBG000C05BD1"),
        },
        definition = lusid.models.Equity(
            instrument_type = "Equity", 
            dom_ccy = "GBP",
        ),
        properties = [
            lusid.models.ModelProperty(
                key = "Instrument/Ibor/Fee",
                value = lusid.models.PropertyValue(
                    metric_value=lusid.models.MetricValue(
                        value = 30,
                        unit = "GBP"
                    )
                ),
                effective_from=datetime.datetime(2022, 1, 1, 9, 0, 0, tzinfo=datetime.timezone.utc)
            )
        ],
    )
}
try:
    instruments_response = instruments_api.upsert_instruments(
        request_body = instruments_request
    )
except lusid.ApiException as e:
    print(e)
```

## Using Luminesce

You must first ‘inline’ properties into entity providers before you can add properties to entities using Luminesce. [More information](/v1/docs/how-do-i-configure-luminesce-entity-providers-to-readwrite-properties).

## Using the LUSID web app

You can use the LUSID web app to add a property to a particular instrument, or add several properties in bulk to many instruments.

For example, to add an `Instrument/BBG/AnalystRating` string property with a value of AAA and an `Instrument/Ibor/Fee` numeric property with a value of £30 to an instrument:

1. Sign in to the [LUSID web app](https://www.lusid.com/app/home).
2. Use the left-hand menu to navigate to **Data Management > Instruments**: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image(92).png)
3. Choose one or more instruments to add the properties to. Then, select **Options icon >** **Edit**:

![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image(93).png)
4. Choose one or more properties to add to your chosen instruments: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image(98).png)
5. Provide values for your chosen properties and select **Run**: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image(99).png)