How do I master an instrument?

You can master:

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.

Using the LUSID REST API

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

Obtain an API access token.
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 Luminesce

You can use the instrument type-specific Lusid.Instrument.*.Writer providers. More information.

Using the LUSID web app

Sign in to the LUSID web app using the credentials of a LUSID administrator.
From the left-hand menu, select Data Management > Instruments and click the Create instrument button.
Enter a unique Instrument 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 to filter the instrument master and examine the LUSID Instrument ID column: