---
title: "Lusid.LegalEntity"
slug: "lusidlegalentity"
updated: 2024-09-23T15:39:53Z
published: 2024-09-23T15:39:53Z
canonical: "support.lusid.com/lusidlegalentity"
---

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

# Lusid.LegalEntity

| **Type** | **Read/write** | **Author** | **Availability** |
| --- | --- | --- | --- |
| [Data provider](/v1/docs/what-are-a-data-provider-and-a-direct-provider) | Read | Finbourne | Provided with LUSID |

The `Lusid.LegalEntity` provider enables you to write a [Luminesce SQL query](/v1/docs/understanding-the-luminesce-sql-query-syntax) that retrieves [legal entities](/v1/docs/representing-institutions-in-lusid-using-legal-entities) defined in LUSID, such as international banks, investment firms, pension companies and so on.

> **Note:** The LUSID user running the query must have sufficient [access control permissions](/v1/docs/creating-policies-to-control-access-to-providers-for-different-luminesce-end-users) to both use the provider *and* read legal entity data stored in LUSID. This should automatically be the case if you are the domain owner.

**See also:** [Luisd.LegalEntity.Writer](/v1/docs/lusidlegalentitywriter)

## Prerequisites

> **Note**: You only need perform the operation in this section once, for both `Lusid.LegalEntity` and [Luisd.LegalEntity.Writer](/v1/docs/lusidlegalentitywriter).

A legal entity must have at least one [user-specified identifier](/v1/docs/representing-institutions-in-lusid-using-legal-entities#understanding-identifiers) from which LUSID can generate a unique internal LUID. Consider the following JSON representation of a legal entity in LUSID:

```json
"displayName": "Acme Bank Inc",
"description": "An international bank",
"lusidLegalEntityId": "LUID_00003D6Y",
"identifiers": {
  "LegalEntity/InternationalBanks/BankId": {
     "key": "LegalEntity/InternationalBanks/BankId",
     "value": {
       "labelValue": "AcmeInc"
     },
     "effectiveFrom": "0001-01-01T00:00:00.0000000+00:00"
   }
}
```

It's important to note that `Lusid.LegalEntity` does not know anything about the `LegalEntity/InternationalBanks/BankId` identifier out-of-the-box. For this reason, a field representing this identifier cannot be listed in the Luminesce catalog by default. In order to retrieve legal entities, you must first run a special SQL query to ['inline' the identifier as a field](/v1/docs/how-do-i-configure-luminesce-entity-providers-to-readwrite-properties) in `Lusid.LegalEntity`, so that it appears in the catalog and can be interacted with:

```sql
@identifiersToCatalog = values
('LegalEntity/InternationBanks/BankId', 'IntBankId', True, 'An identifier for this legal entity as an international bank');

@config = select column1 as [Key], column2 as Name, column3 as IsMain, column4 as Description from @identifiersToCatalog;

select * from Sys.Admin.Lusid.Provider.Configure
where Provider = 'Lusid.LegalEntity'
and Configuration = @config;
```

You can now use `Lusid.LegalEntity` in the normal way to retrieve legal entity fields, including the newly-added identifier field (which is listed in the catalog as `IntBankID`).

## Basic usage

```sql
select * from Lusid.LegalEntity where <filter-expression>
```

## Query parameters

`Lusid.LegalEntity` has parameters that enable you to filter or refine a query.

To list available parameters, their data types, default values, and an explanation for each, run the following query using a [suitable tool](/v1/docs/what-tools-are-available-to-write-luminesce-queries):

```sql
select FieldName, DataType, ParamDefaultValue, Description from Sys.Field where TableName = 'Lusid.LegalEntity' and FieldType = 'Parameter';
```

## Data fields

By default, `Lusid.LegalEntity` returns a table of data populated with particular fields (columns). You can return a subset of these fields.

> **Note**: The `LEI` field returns the value of the `LegalEntity/default/LEI` [system property](/v1/docs/what-is-a-system-property#legal-entity-system-properties), if populated.

To list fields available to return, their data types, whether fields are considered 'main', and an explanation for each, run the following query using a [suitable tool](/v1/docs/what-tools-are-available-to-write-luminesce-queries):

```sql
select FieldName, DataType, IsMain, IsPrimaryKey, SampleValues, Description from Sys.Field where TableName = 'Lusid.LegalEntity' and FieldType = 'Column';
```

> **Note:** Fields marked 'main' are returned by queries that select a caret character, for example `select ^ from Lusid.LegalEntity`.

## Examples

> **Note:** For more example Luminesce SQL queries, visit our [Github repo](https://github.com/finbourne/luminesce-examples/tree/master/examples).

### Example 1: Retrieve the first 20 legal entities

```sql
select * from Lusid.LegalEntity Limit 20;
```

### Example 2: Retrieve legal entities with particular names and descriptions

```sql
select * from Lusid.LegalEntity where DisplayName like '%Asset%' and Description like '%City%';
```

### Example 3: Retrieve version information for legal entities created by a particular user

```sql
select AsAtCreated, 
  RequestIdCreated, 
  AsAtModified, 
  UserIdModified, 
  RequestIdModified, 
  AsAtVersionNumber 
from Lusid.LegalEntity 
where UserIdCreated = '00uji4twb4jDcHGjN2p7'  
```