Understanding instrument identifiers

When you create an instrument in LUSID, you must specify at least one identifier. See a list of available identifiers.

Note: If an identifer you use or need is not in our list, contact us to add it to your LUSID domain.

Each identifier maps the instrument to a particular security identification scheme, whether this is to an open standard such as FIGI or PermID, an industry scheme such as ISIN, CUSIP or SEDOL, or to your own internal security database. When data is loaded into LUSID from different sources—each likely referencing the same financial asset using a different identifier—it can be automatically resolved to the same, correct instrument, thereby guaranteeing a consistent economic impact but without transforming ingested data in any way, so it remains meaningful to the originating system.

Identifiers are classed as either unique or non-unique within an instrument scope. You must specify at least one unique identifier when you master an instrument. In addition, LUSID automatically generates a LUSID Instrument ID (or LUID), an internal identifier that is guaranteed to be unique and never change. You can specify as many other identifiers of either class as you like; the more you add, the more successful LUSID will be at consolidating data from different systems.

For example, imagine you are creating a instrument to model a simple equity such as BP PLC $0.25 shares traded in London. You could assign the following identifiers to the instrument:

• A FIGI of BBG000C05BD1

• A SEDOL of 0798059

• An ISIN of GB0007980591

• A ClientInternal of bp-plc-ldn (this represents your internal security database for demonstration purposes)

When transactional or other data items identifying BP PLC $0.25 shares using any of the above values are loaded into LUSID, they can be automatically resolved to the correct instrument. 

Note: If LUSID cannot resolve a data item, it is mapped to the unknown instrument. This prevents the data load operation failing, but you should take steps to manually resolve unknown instruments.

You can call the LUSID UpsertInstruments API to create an instrument with a set of identifiers, for example:

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"},
      "Sedol": {"value": "0798059"}
      "Isin": {"value": "GB0007980591"},
      "ClientInternal": {"value": "bp-plc-ldn"}
      },
    "definition": {
      "instrumentType": "Equity",
      "domCcy": "GBP",
      }
  }
}'

Note the response reveals the automatically-generated LUID:

{
    "values": {
        "upsert-request-1": {
            "href": "https://<your-domain>.lusid.com/api/api/instruments/LusidInstrumentId/LUID_00003D5C",
            "lusidInstrumentId": "LUID_00003D5C",
            "version": {
                "effectiveFrom": "0001-01-01T00:00:00.0000000+00:00",
                "asAtDate": "2021-11-23T10:14:07.7454320+00:00"
            },
            "name": "BP $0.25 LDN",
            "identifiers": {
                "Figi": "BBG000C05BD1",
                "ClientInternal": "bp-plc-ldn",
                "LusidInstrumentId": "LUID_00003D5C",
                "Sedol": "0798059",
                "Isin": "GB0007980591"
            },
            ...
        }
    },
}

You can address an instrument in subsequent API calls using any of its identifiers. For the BP PLC $0.25 instrument, this would be:

Note the following:

• As mentioned above, identifiers are classed as either unique or non-unique within a particular instrument scope. You cannot assign a unique identifier to more than one instrument in the same scope; conversely, a non-unique identifier can match more than one instrument in a scope. You must specify at least one unique (market) identifier for an instrument (that is, in addition to the automatically-generated LUID).

• An identifier is given a 3-stage key (like custom properties), where the first stage is the scope (Instrument), the second is the code (default, which means internal to LUSID), and the third is the identifier name. You use this key to address the instrument in several places, notably when upserting transactions.

• In the real world, it's possible for certain identifiers to change or be recycled. If this happens, you can delete an identifier from one instrument and add it to another.