How do I add a property to an entity?

Providing you have suitable access control permissions, you can add a property to most types of entity and specify a single value. See how to add a multi-value property.

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

• Using the LUSID REST API

• Using the LUSID web app

• If you have a Luminesce license, by writing a SQL query.

Note the following:

• The property value must conform to the data type specified by the underlying property type.

• The data type of the property type determines whether property values must be created as label values or metric values.

• The maximum number of characters is 1024 unless the data type of the property type is unindexedText. More information.

• A time-variant 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 a property at any time. If you no longer need a property, you can delete 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), 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.

• If an entity type has a Create* API (for example CreatePortfolio), you can add properties when you create entities. Subsequently, you must use a dedicated property API, for example 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.

Creating a property value as a label value

If the property type mandates a property value as a label value (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:

1. Obtain an API access token.

2. Call the UpsertInstruments API for your LUSID domain, passing in your API access token and appending a property to the properties collection:

   • key must be a 3-stage property key in the Instrument domain.

   • 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:

   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"
         }
       ]
     }
   }'

Creating a property value as a metric value

If the property type mandates a property value as a metric value (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:

1. Obtain an API access token.

2. Call the UpsertInstruments API for your LUSID domain, passing in your API access token and appending a property to the properties collection:

   • key must be a 3-stage property key in the Instrument domain.

   • value must be a metricValue object consisting of a numeric value and, if the underlying unit schema 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:

   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"
         }
       ]
     }
   }'

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.

2. Use the left-hand menu to navigate to Data Management > Instruments:
   

3. Choose one or more instruments to add the properties to. Then, select Options icon > Edit:

   

4. Choose one or more properties to add to your chosen instruments:
   

5. Provide values for your chosen properties and select Run: