---
title: "Using reference lists in LUSID"
slug: "using-reference-lists-in-lusid"
updated: 2025-04-22T16:26:12Z
published: 2025-04-22T16:26:12Z
canonical: "support.lusid.com/using-reference-lists-in-lusid"
---

> ## 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.

# Using reference lists in LUSID

A *reference list* in LUSID is a repository of data that can contain:

| **A series of...** | **For example, if you want to...** |
| --- | --- |
| Strings | Store a list of asset classes. |
| Portfolios or portfolio groups | Store a list of portfolios to exclude from a compliance rule. |
| Instruments | Store a list of instruments to exclude from a particular compliance rule. |
| Funds | Store a list of funds to exclude from a compliance rule. |
| Properties or address keys | Store a list of instrument properties that should exist to pass a compliance check. |
| Decimals | Store a list of upper and lower bounds that an order should remain within. |

All reference lists in LUSID have a *scope* and a *code* forming a unique ID. Currently, you can pass one or more reference list IDs into various LUSID [compliance rules](/v1/docs/what-is-compliance-in-lusid) to ensure the rule checks against the values in the list. For example, you can:

- [Set up a compliance rule](/v1/docs/how-do-i-create-a-compliance-rule) that checks orders do not comprise of instruments of a particular set of asset classes.
- Set up a compliance rule that checks orders contain a list of required properties, such as the country of origin.
- Specify a reference list of portfolios within a compliance rule to exclude those in the list from the rule.

You can also use reference lists for other LUSID operations, such as to specify a list of portfolios to create valuation reports for.

## How do I create a reference list?

Providing you are a LUSID user with sufficient privileges, you can create a *reference list* to store a collection of values.

- Method 1: [Using the LUSID REST API](/v1/docs/using-reference-lists-in-lusid#using-the-lusid-rest-api)
- Method 2: [Using the LUSID web app](/v1/docs/using-reference-lists-in-lusid#using-the-lusid-web-app)
- Method 3: [Using the dedicated Luminesce provider](/v1/docs/lusidreferencelistwriter)

### Using the LUSID REST API

Currently, you can create one reference list per API call.

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 [UpsertReferenceList](https://www.lusid.com/docs/api/lusid/endpoints/reference-lists/UpsertReferenceList) API, passing in:
  - A `scope` and `code` that together uniquely identify the reference list.
  - A user-friendly `name` and optional `description` for the reference list.
  - Any `tags` for the reference list.
  - One `referenceListType` out of the following options, and an array of `values` to populate the reference list with:
    - `PortfolioGroupIdList`: takes in an array of `scope` and `code` pairs that uniquely identify [portfolio groups](/v1/docs/what-is-a-portfolio-group).
    - `PortfolioIdList`: takes in an array of `scope` and `code` pairs that uniquely identify [portfolios](/v1/docs/introduction-to-portfolios).
    - `PropertyList`: takes in an array of property `key` and `value` pairs that uniquely identify [properties](/v1/docs/properties).
    - `AddressKeyList`: takes in an array of strings containing keys that uniquely identify a queryable address (such as a [metric](/v1/docs/what-is-a-metric)) in LUSID.
    - `FundIdList`: takes in an array of `scope` and `code` pairs that uniquely identify [funds](/v1/docs/how-do-i-create-a-fund).
    - `InstrumentList`: takes in an array of strings containing [instrument identifiers](/v1/docs/what-are-unique-and-non-unique-identifiers) of any type.
    - `StringList`: takes in an array of strings.
    - `DecimalList`: takes in an array of doubles.

The following example creates (or updates if it already exists) a reference list of portfolios:

```json
curl -X POST 
"https://<your-domain>.lusid.com/api/api/referencelists"
  -H "Content-Type: application/json-patch+json"
  -H "Authorization: Bearer <your-API-access-token>"
  -d "{
  "id": {
    "scope": "Finbourne-Examples",
    "code": "Uk-Portfolios"
  },
  "name": "UkPortfoliosReferenceList",
  "description": "Reference list containing the scope and code of all my UK portfolios",
  "tags": [
    "portfolio",
    "uk"
  ],
  "referenceList": {
    "values": [
      {
        "scope": "Finbourne-Examples",
        "code": "PortfolioUk"
      },
      {
        "scope": "Finbourne-Examples",
        "code": "Uk-Equities"
      }
    ],
    "referenceListType": "PortfolioIdList"
  }
}"
```

Once you have created a reference list, you could include the `scope` and `code` when creating a compliance rule to, for example, exclude the portfolios in the reference list from being checked by a particular rule. [See how to create a compliance rule.](/v1/docs/how-do-i-create-a-compliance-rule)

### 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 top left menu, select **Portfolio Management > Compliance Rules**. ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image(773).png)
3. Select the **Reference Lists** tab and click the **Create reference list** button: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image(774).png)
4. On the **Create Reference List** screen, specify:
  - A unique **Scope** and **Code**.
  - A friendly **Display Name** and **Description**.
  - Any **Tags** for the reference list.
  - A reference **List Type**.
  - A set of items, specific to your **List Type**, to include in your reference list. ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image(776).png)
5. Click the **Create** button to save your reference list.