How does LUSID resolve data to instruments?

When you upsert transactions and other data items to LUSID, you must specify at least one identifier mapping each item to an instrument mastered in LUSID.

For example, a simple equity such as BP PLC $0.25 shares traded in London might have any of the following identifiers:

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

Note: Identifiers are classed as either unique and identify exactly one instrument per instrument scope (for example FIGI), or non-unique and can identify more than one instrument per scope (such as ISIN). More information.

For example, you might upsert transactions into LUSID from a system that identifies BP PLC $0.25 shares using a FIGI:

[
  {
    "transactionId": "txn-upsert-1",
    "type": "StockIn",
    "instrumentIdentifiers": {
      "instrument/default/Figi": "BBG000C05BD1"
    },
    ...

Meanwhile, you might upsert corporate actions from a system that identifies BP PLC $0.25 shares using an ISIN:

"transitions": [
   {
      "inputTransition": {
         "instrumentIdentifiers": {
            "instrument/default/Isin": "GB0007980591"
             ...

LUSID must resolve these data items to the same BP PLC $0.25 instrument mastered in LUSID in order to guarantee a consistent economic impact.

By default, LUSID operates a ‘data load first’ policy, so transactions and other data items are upserted and exceptions flagged for subsequent remediation, without interrupting critical processes. Note you can increase the level of validation to reject transactions that do not resolve to instruments instead.

For each data item you upsert, LUSID examines the instrument identifiers in the API request and performs the following steps in turn until a matching instrument is found:

Step 1: LUSID determines the instrument scope in which to look. If a transaction is booked into a portfolio with a custom instrument scope registered, LUSID performs steps 2 and 3 in that scope. If not, LUSID automatically falls back to the built-in default instrument scope.

Step 2: LUSID examines the unique identifiers specified in the API request in a set order. If the request contains a unique identifier and a matching instrument is found in the instrument scope, LUSID resolves to that instrument.

Step 3: If not, LUSID examines the non-unique identifiers:

1. If the API request has one or more non-unique identifiers and together they match a single instrument exactly, LUSID resolves to that instrument.
2. If no single exact match is found, LUSID cycles through the non-unique identifiers in a set order:
   1. If the non-unique identifier being examined matches a single instrument, LUSID resolves to that instrument.
   2. If the identifier matches either zero instruments or two or more, LUSID ignores it and tries the next non-unique identifier, if there is one.

If a matching instrument cannot be found in a custom instrument scope, LUSID repeats Step 2 and Step 3 in the default scope. If a matching instrument still cannot be found, LUSID maps the data item to the unknown instrument (LUID_ZZZZZZZZ). This is important as it prevents the data load operation failing, but you should take steps to manually resolve unknown instruments.

Note: LUSID does not map unknown cash transactions to the unknown currency.

The following flow diagram summarises the mapping logic for (non-currency) instruments within the default scope: