---
title: "How do I master an instrument?"
slug: "how-do-i-master-an-instrument"
tags: ["instrument", "create instrument", "instrument master"]
updated: 2024-12-18T11:18:28Z
published: 2024-12-18T11:18:28Z
canonical: "support.lusid.com/how-do-i-master-an-instrument"
---

> ## 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 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](/v1/docs/what-instruments-does-lusid-support).
- A currency (should you need to augment the [prepopulated basket of currencies](/v1/docs/how-do-i-create-a-currency)).

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](https://www.openfigi.com/id/view/BBG000C05BD1), but we recommend examining the [supported instrument documentation](/v1/docs/what-instruments-does-lusid-support) for more complex asset classes.

## Using the LUSID REST API

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

1. [Obtain an API access token](/v1/docs/how-do-i-obtain-and-use-a-short-lived-api-access-token-from-okta).
2. Call the LUSID [UpsertInstruments](https://www.lusid.com/docs/api#operation/UpsertInstruments) API for your LUSID domain, passing in your API access token, optionally an [instrument scope](/v1/docs/understanding-instrument-scopes) and, for each:

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

```json
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](/v1/docs/what-is-a-lusid-instrument-id-or-luid) for the instrument, an internal identifier automatically generated by LUSID that is guaranteed to be unique and never change, in this case `LUID_00003D5C`:

```json
{
    "values": {
        "upsert-request-1": {
            "href": "https://<your-domain>.lusid.com/api/api/instruments/LusidInstrumentId/LUID_00003D5C",
            "scope": "mysecretscope",
            "lusidInstrumentId": "LUID_00003D5C",
            ...
```
  - An ephemeral ID (to track errors in the response).
  - A friendly `name`.
  - A set of `identifiers` (you must specify at least one [unique identifier](/v1/docs/understanding-instrument-identifiers), for example a FIGI).
  - An economic `definition` appropriate to the type of asset. The `instrumentType` must be one of the [supported instrument types](/v1/docs/what-instruments-does-lusid-support).

### **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:

```json
"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](https://support.lusid.com/docs/readwrite-lusid-investment-data-lusid#instruments).

## Using the LUSID web app

1. Sign in to the [LUSID web app](https://www.lusid.com/app) using the credentials of a LUSID administrator.
2. From the left-hand menu, select **Data Management > Instruments** and click the **Create instrument** button.
3. Enter a unique **Instrument name** for the instrument and add at least one unique **Instrument identifier**, for example a FIGI: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image(426).png?sv=2026-02-06&spr=https&st=2026-11-04T02%3A02%3A12Z&se=2026-11-04T03%3A02%3A12Z&sr=c&sp=r&sig=RmJWB%2BxBxzX31Ocw4NQ8NyFXJ65dX3WBQGhWHp7f8hU%3D)

If the request is successful, LUSID automatically generates a [LUSID Instrument ID](/v1/docs/what-is-a-lusid-instrument-id-or-luid), 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: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image(427).png?sv=2026-02-06&spr=https&st=2026-11-04T02%3A02%3A12Z&se=2026-11-04T03%3A02%3A12Z&sr=c&sp=r&sig=RmJWB%2BxBxzX31Ocw4NQ8NyFXJ65dX3WBQGhWHp7f8hU%3D)