How do I master an instrument?

Providing you are a LUSID user with sufficient privileges, you can master an instrument to model a real-world financial asset in the LUSID Security Master.

Note: If you are the LUSID domain owner, you are automatically assigned the built-in lusid-administrator role, which has all the permissions necessary to perform the operations in this article.

You can model:

• A simple instrument such as an Equity.
• A complex OTC or exchange-traded contract such as a Future, FxForward, Bond, Swap, Option and more.
• A currency (should you need to augment the prepopulated basket of currencies).

The precise instructions are highly dependent on the type of asset you want to model. The examples on this page model a simple equity, BP PLC $0.25 shares traded in London, but we recommend examining the supported instrument documentation for more complex asset classes.

There are several ways in which you can create an instrument:

• Using the LUSID REST API
• Using the LUSID web app
• You can search the LUSID instrument master and the OpenFIGI database simultaneously, using results from the latter to populate the former.
• If you have a Luminesce license, you can write a SQL query to populate the LUSID instrument master from an internal database or market vendor.

Using the LUSID REST API

You can create up to 2000 instruments in a single API request.

1. Obtain an API access token.
2. Call the LUSID UpsertInstruments API for your LUSID domain, passing in your API access token, optionally an instrument scope and, for each:
   • An ephemeral ID (to track errors in the response).
   • A friendly name.
   • A set of identifiers (you must specify at least one unique identifier, for example a FIGI).
   • An economic definition appropriate to the type of asset. The instrumentType must be one of the supported instrument types.

   Note that a new instrument is created if all the unique identifiers you specify in the API request do not match an instrument in the specified instrument scope (or in the built-in default scope if you do not specify one). Otherwise, an existing instrument is updated.

   For example, to create a new instrument representing BP PLC $0.25 shares traded in London in mysecretscope:

   curl -X POST "https://<your-domain>.lusid.com/api/api/instruments?scope=mysecretscope"
      -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"
         }
     }
   }'

   If the request is successful, the response reveals the LUSID Instrument ID for the instrument, an internal identifier automatically generated by LUSID that is guaranteed to be unique and never change, in this case LUID_00003D5C:

   {
       "values": {
           "upsert-request-1": {
               "href": "https://<your-domain>.lusid.com/api/api/instruments/LusidInstrumentId/LUID_00003D5C",
               "scope": "mysecretscope",
               "lusidInstrumentId": "LUID_00003D5C",
               ...

Examining a summary report

Since you can upsert so many instruments at once it can be difficult to judge the success of the operation. You can examine the metadata/actions section of the response to the UpsertInstruments API call to see lists of instruments created, updated or unchanged:

"metadata": {
  "actions": [
    {
      "type": "UpdatedInstruments",
      "description": "The request identifiers of Updated Instruments",
      "identifierType": "RequestId",
      "identifiers": [
        "upsert-request-2"
      ]
    },
    {
      "type": "CreatedInstruments",
      "description": "The request identifiers of Created Instruments",
      "identifierType": "RequestId",
      "identifiers": [
        "upsert-request-1"
      ]
    },
    {
      "type": "UnchangedInstruments",
      "description": "The request identifiers of Unchanged Instruments",
      "identifierType": "RequestId",
      "identifiers": [
        "upsert-request-3"
      ]
    }
  ]
},

Using the LUSID web app

1. Sign in to the LUSID web app using the credentials of a LUSID administrator.
2. From the left-hand menu, select Data Management > Instruments:
   
3. On the Instruments dashboard, click the Create instrument button.
4. Enter a unique Name for the instrument and add at least one unique Instrument Identifier, for example a FIGI:
   

   If the request is successful, LUSID automatically generates a LUSID Instrument ID, an internal identifier that is guaranteed to be unique and never change. To see what this is, enter the Name on the Instruments dashboard to filter the instrument master, and examine the LUSID Instrument ID column: