> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom lists (data lists)

> Tenant-owned lists for rules and checks: primary values, search keys, REST lifecycle, and how list UUIDs are referenced in rule conditions.

## Overview

**Data lists** (including **custom** lists with `type: "custom"`) store values your organization uses in **rules** (`in_custom_list`, `not_in_custom_list`, `contains_any_from_custom_list`, and related operators). The public REST surface is under:

```
https://api.gu1.ai/data-lists
```

All calls require a **Bearer API key** (same as [Authentication](/en/api-reference/authentication)). Data is scoped to the **organization** tied to the key.

## Concepts

* **`name` and `description` (list metadata)**: human-readable fields for **your team** only. They are used in the **gu1 dashboard** (list picker, tables, detail headers) and in audit or admin views so operators can recognize lists without opening each UUID. They are **not** matched by rule engines or `check` endpoints; rule logic still uses **list id** and **item** `primaryValue` / `searchKeys`.
* **`primaryValue`**: main value stored for an item (exact match / normalization depends on list type and engine).
* **`searchKeys`**: optional extra strings used for lookup; if omitted on ingest, the API typically defaults to `[primaryValue]`.
* **`itemData` / `metadata`**: optional JSON objects for extra columns or context.
* **List UUID in rules**: for custom-list operators, the condition `value` is the **list id** (UUID) returned when you create or list the list.

See [Rule conditions](/en/api-reference/rules/conditions) for condition syntax.

## Typical client flow

1. **Create** a list with `POST /data-lists` (use `type: "custom"` for a generic list, or another supported type such as `company_blocklist` if it fits your use case).
2. **Add items** with `POST /data-lists/{listId}/items` (batch up to the API limit) or `POST /data-lists/{listId}/items/bulk` for larger payloads.
3. **Verify membership** with `POST /data-lists/{type}/check` (checks across lists of that **type**) or `POST /data-lists/bulk-check` for several lookups at once.
4. **Browse items** with `GET /data-lists/{listId}/items` (`search` query filters by primary value / keys as implemented by the service), or **look up by value** with `POST /data-lists/{listId}/items/find` when you need exact or substring match on **primary + search\_keys** for that list only.
5. **Maintain** lists with `PATCH /data-lists/{id}`, `PATCH /data-lists/{id}/status`, `DELETE /data-lists/{id}`, and per-item `PATCH` / `DELETE` under `/data-lists/{id}/items/{itemId}`.

## Global vs tenant lists

Your tenant may see **global** lists (e.g. shared sanctions data). Only **system administrators** can mutate global lists or their items; normal API keys manage **tenant-owned** lists.

**Marketplace-only** global lists are not exposed through these endpoints (the API returns `403` with a specific error code).

## API Reference

Use the **Custom lists → API Reference** section in the sidebar for endpoint-by-endpoint parameters and examples.