--- title: "How do I add a property to an entity?" slug: "how-do-i-add-a-property-to-an-entity" tags: ["property", "metricValue", "labelValue", "unit"] 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://.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/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://.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/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?sv=2026-02-06&spr=https&st=2026-11-04T01%3A47%3A15Z&se=2026-11-04T02%3A47%3A15Z&sr=c&sp=r&sig=CneZj%2Bj837dMPSFeDPFzqOK5dd4FiFQ%2Fp4HoP2zelTw%3D) 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?sv=2026-02-06&spr=https&st=2026-11-04T01%3A47%3A15Z&se=2026-11-04T02%3A47%3A15Z&sr=c&sp=r&sig=CneZj%2Bj837dMPSFeDPFzqOK5dd4FiFQ%2Fp4HoP2zelTw%3D) 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?sv=2026-02-06&spr=https&st=2026-11-04T01%3A47%3A15Z&se=2026-11-04T02%3A47%3A15Z&sr=c&sp=r&sig=CneZj%2Bj837dMPSFeDPFzqOK5dd4FiFQ%2Fp4HoP2zelTw%3D) 5. Provide values for your chosen properties and select **Run**: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image(99).png?sv=2026-02-06&spr=https&st=2026-11-04T01%3A47%3A15Z&se=2026-11-04T02%3A47%3A15Z&sr=c&sp=r&sig=CneZj%2Bj837dMPSFeDPFzqOK5dd4FiFQ%2Fp4HoP2zelTw%3D)