--- title: "Using reference lists in LUSID" slug: "using-reference-lists-in-lusid" tags: ["reference lists", "compliance"] 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://.lusid.com/api/api/referencelists"  -H "Content-Type: application/json-patch+json"  -H "Authorization: Bearer "  -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?sv=2026-02-06&spr=https&st=2026-11-04T01%3A47%3A07Z&se=2026-11-04T02%3A47%3A07Z&sr=c&sp=r&sig=7hu49T7TR625g%2Fd%2F9D5Sr%2BZL42ct3Xxv0HzEJkPA%2BcM%3D) 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?sv=2026-02-06&spr=https&st=2026-11-04T01%3A47%3A07Z&se=2026-11-04T02%3A47%3A07Z&sr=c&sp=r&sig=7hu49T7TR625g%2Fd%2F9D5Sr%2BZL42ct3Xxv0HzEJkPA%2BcM%3D) 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?sv=2026-02-06&spr=https&st=2026-11-04T01%3A47%3A07Z&se=2026-11-04T02%3A47%3A07Z&sr=c&sp=r&sig=7hu49T7TR625g%2Fd%2F9D5Sr%2BZL42ct3Xxv0HzEJkPA%2BcM%3D) 5. Click the **Create** button to save your reference list.