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

# Custom Lists Guide

> How to manage tenant-owned screening lists: upload records, publish versions, activate lists per workspace, and control risk rating impact.

export const StorybookFrame = ({storyId, title, version = "20260419-1", height, zoom = 0.7, preferLocalPreview = false}) => {
  const HOSTED_STORYBOOK_BASE_URL = "https://minerva-storybook.s3.ca-central-1.amazonaws.com/iframe.html";
  const isLocalDocsPreview = typeof window !== "undefined" && ["localhost", "127.0.0.1"].includes(window.location.hostname);
  const storybookBaseUrl = preferLocalPreview && isLocalDocsPreview ? "http://localhost:6006/iframe.html" : HOSTED_STORYBOOK_BASE_URL;
  const params = new URLSearchParams({
    id: storyId,
    viewMode: "story",
    singleStory: "true",
    shortcuts: "false",
    toolbar: "0",
    nav: "0",
    panel: "0"
  });
  params.set("v", version);
  const src = `${storybookBaseUrl}?${params.toString()}`;
  const unscaledHeight = `${Math.ceil(height / zoom)}px`;
  const unscaledWidth = `${100 / zoom}%`;
  return <div style={{
    width: "100%"
  }}>
      <div style={{
    height: `${height}px`,
    overflow: "hidden",
    border: "1px solid #e2e8f0",
    borderRadius: "12px",
    backgroundColor: "#ffffff",
    display: "flex",
    justifyContent: "center",
    alignItems: "flex-start"
  }}>
        <iframe src={src} title={title} loading="lazy" style={{
    width: unscaledWidth,
    height: unscaledHeight,
    transform: `scale(${zoom})`,
    border: "0",
    display: "block",
    transformOrigin: "top center",
    flexShrink: 0
  }} allowFullScreen></iframe>
      </div>
    </div>;
};

Custom lists let your organization screen customers against tenant-owned lists — internal watchlists, do-not-onboard registries, or policy-restricted counterparties — alongside Minerva's standard Sanctions, PEP, and News feeds. Records you upload become a versioned, deployable screening source with full audit history.

<Warning>
  <strong>Enterprise feature:</strong> Custom lists are available for enterprise
  customers and must be enabled by Minerva before your organization can use
  them. Contact your Minerva representative or [support@gominerva.com](mailto:support@gominerva.com) to discuss
  enabling custom-list screening for your environments.
</Warning>

**Access:** Requires the <strong>Admin</strong> role or above to create lists, upload records, publish versions, or change workspace activation. Other users can review lists read-only. In the sidebar, go to <strong>Administration</strong> > <strong>Configuration</strong>, then open <strong>Custom Lists</strong> under <strong>Data sources</strong>.

Use this guide when you need to:

* create a custom list and upload records in bulk
* add, edit, or archive individual records
* publish reviewed versions of a list
* activate a list version for a workspace screening feed
* control how list matches affect the Client Risk Rating
* monitor deployment health and roll back to an earlier version

<Info>
  Custom lists are <strong>tenant-owned</strong>, while activation is{" "}
  <strong>workspace-scoped</strong>. The same list can be live in one workspace
  (for example Live) while another workspace (for example Calibration) stays on
  an older version or does not use the list at all.
</Info>

## Key Concepts

| Concept                        | Meaning                                                                                                                                                                         |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <strong>List</strong>          | A tenant-owned collection of records with a name, description, and risk rating impact.                                                                                          |
| <strong>Record</strong>        | One individual or organization on the list, identified by a stable record UID from your source system.                                                                          |
| <strong>Working set</strong>   | The current editable records and list settings. Manual edits and list-setting changes accumulate here until you publish changes; bulk uploads publish in their own review step. |
| <strong>Version</strong>       | An immutable snapshot created by publishing the working set. Only published versions can be activated.                                                                          |
| <strong>Activation</strong>    | The workspace-level choice of which published version screens live traffic, and on which feed category.                                                                         |
| <strong>Feed category</strong> | The screening feed a match is reported under: Internal Risk, Sanctions, PEP, News, Legal, or Criminal.                                                                          |
| <strong>Deployment</strong>    | The background rollout that indexes an activated version and brings it into live screening.                                                                                     |

## How Custom List Screening Works

1. <strong>Create a list</strong> and load records through file uploads or
   manual entry.
2. <strong>Publish</strong> the working set into a new immutable version after
   reviewing the staged changes.
3. <strong>Activate</strong> a published version in the selected workspace on a
   feed category.
4. Minerva <strong>deploys</strong> the version. When the deployment is live,
   screening and ongoing monitoring in that workspace include the list.
5. Matches appear in screening results under the selected feed category with
   the list name, record UID, and your custom fields as evidence, and the
   list's risk rating impact is applied to the profile's Client Risk Rating.

## The Custom List Management Page

The management page shows every list in the tenant with its deployment state, workspace activation, feed category, record count, and latest version.

<StorybookFrame storyId="pages-tenant-config-custom-lists--default" title="Custom List Management Page" height={560} version="20260710-custom-lists" preferLocalPreview />

From this page you can:

* <strong>Create list</strong>: name the list, describe it, and choose its
  default feed category.
* <strong>Download upload templates</strong>: starter CSV or XLSX files with the
  recognized column headers.
* <strong>Open</strong> a list to manage records, uploads, versions, and
  activation on its detail page.
* <strong>Upload</strong> directly into a list from the table row.

## The List Detail Page

Each list has a detail page with four areas: the records table, the risk rating impact control, deployment status, and recent uploads.

<StorybookFrame storyId="pages-tenant-config-custom-lists--list-detail" title="Custom List Detail Page" height={1150} version="20260710-custom-lists" preferLocalPreview />

### Records

The records table is the list's working set. Manual edits become part of the next published version.

* Filter by record status (<strong>Active</strong> or <strong>Archived</strong>).
* Search by record UID prefix.
* <strong>Add record</strong> or <strong>Edit</strong> opens the record form:
  record UID, entity type (individual or organization), name, aliases,
  countries, date of birth or date of incorporation, reason, notes, and custom
  fields.
* <strong>Archive</strong> removes a record from the next published version
  without deleting its history; archived records can be restored.

<Tip>
  Use a stable identifier from your source system (customer number, case ID) as
  the record UID. Uploads match records by UID, so a stable UID is what makes
  re-uploads update records instead of duplicating them.
</Tip>

## Uploading Records in Bulk

Use <strong>Upload records</strong> on the detail page to load a CSV or XLSX file of up to 100MB. Columns can be in any order when the headers are recognizable; start from the downloadable templates if you are building the file for the first time.

Every upload is validated on the server before anything changes:

1. Choose the file and a <strong>merge mode</strong>:
   <strong>Upsert only</strong> keeps records that are missing from the file,
   while <strong>Full replace</strong> archives them.
2. <strong>Validate</strong> parses the file and computes an execution plan —
   adds, updates, unchanged records, and archives — without applying anything.
3. Review the plan, the row preview, and any validation errors.
4. <strong>Publish</strong> applies the batch and creates a new published
   version of the list.

<StorybookFrame storyId="pages-tenant-config-custom-lists--upload-review" title="Upload Review Step" height={760} version="20260710-custom-lists" preferLocalPreview />

If validation reports errors, fix the file and upload it again — nothing from a failed or unreviewed batch reaches screening. In-progress and recent batches stay visible in <strong>Recent Uploads</strong> so another admin can pick up a pending review.

## Publishing Changes

Manual record edits and list-setting changes (name, description, risk rating impact) accumulate as unpublished changes. The list header shows an <strong>Unpublished changes</strong> chip while anything is staged.

<strong>Publish changes</strong> snapshots the working set into a new version
and deploys it where the list is activated. The review dialog summarizes exactly
what will change:

<StorybookFrame storyId="pages-tenant-config-custom-lists--publish-changes" title="Publish Changes Review Dialog" height={720} version="20260710-custom-lists" preferLocalPreview />

* added, updated, and removed record counts, with a sample of affected records
* list configuration changes, such as a new risk rating impact
* the total record count after publish

Use <strong>Discard changes</strong> in the header menu to reset the working set back to the last published version instead.

<Info>
  Publishing does not interrupt screening. The previously active version keeps
  serving until the new version's deployment is live.
</Info>

## Activating a List in a Workspace

Activation controls which published version screens live traffic in the selected workspace. Open <strong>Manage activation</strong> (or <strong>Activate in workspace</strong> for a list that is not active yet).

<StorybookFrame storyId="pages-tenant-config-custom-lists--workspace-activation" title="Workspace Activation Dialog" height={700} version="20260710-custom-lists" preferLocalPreview />

* <strong>Feed category</strong> chooses the screening feed this list
  contributes matches to: Internal Risk, Sanctions, PEP, News, Legal, or
  Criminal.
* <strong>Target version</strong> selects the published version to serve. Draft
  or failed versions cannot be activated.
* <strong>Disable</strong> stops the list from screening in this workspace
  without deleting the list or its versions.

Activation requests a deployment. Screening starts once the deployment status reaches <strong>Live</strong>; the deployment status card on the detail page tracks each step (version published, deployment queued, provisioning and indexing, live) and surfaces failure reasons with retry.

<Warning>
  Activation is per workspace. Activating a new version in Live does not change
  what Calibration serves — switch workspaces and activate there when you are
  ready.
</Warning>

## Risk Rating Impact

The <strong>Risk rating impact</strong> slider (0–100) controls how much a screening match against this list raises the profile's Client Risk Rating: 0 means no risk-rating effect and 100 means a match immediately reads as high risk. The value is saved to the working set and takes effect on screening when you publish changes.

Use higher impacts for lists that represent confirmed adverse decisions (do-not-onboard, exited relationships) and lower impacts for advisory or contextual lists.

## Version History and Rollback

Every publish creates a numbered version with its record count, risk impact, publish time, and deployment state. Open <strong>Version history</strong> from the header menu to review or roll back.

<StorybookFrame storyId="pages-tenant-config-custom-lists--version-history" title="Version History Dialog" height={700} version="20260710-custom-lists" preferLocalPreview />

Activating an older version rolls the workspace back without deleting newer published versions — you can roll forward again at any time. Rollback is also the recovery path when a deployment fails: retry the failed version, roll back to the last good one, or disable the feed while you investigate.

## How Matches Appear in Screening

* Matches from custom lists appear in screening results and ongoing monitoring under the feed category the list is activated on, alongside matches from Minerva's standard data feeds.
* Match evidence includes the list name, the record UID, and the custom fields you uploaded, so reviewers see why the record is on the list.
* The monitoring cadence for the Internal Risk feed is configured on the <a href="/screening-frequencies-guide">Screening frequencies</a> page once custom lists are enabled for the tenant.

## Example Use Cases

| Use case                 | Feed category | Suggested setup                                                                                     |
| ------------------------ | ------------- | --------------------------------------------------------------------------------------------------- |
| Internal watchlist       | Internal Risk | Upsert-only uploads from case management; moderate risk impact; daily-to-weekly monitoring cadence. |
| Do-not-onboard registry  | Internal Risk | Full-replace uploads from the decision system of record; high risk impact.                          |
| Policy sanctions overlay | Sanctions     | Entities restricted by internal policy beyond public programs; high risk impact.                    |
| Litigation exposure      | Legal         | Counterparties in active disputes; low-to-moderate impact for context during review.                |

## Related Guides

* [Screening Guide](/screening-guide)
* [Screening Frequencies Guide](/screening-frequencies-guide)
* [Workspaces Guide](/workspaces-guide)
* [Match Scoring Guide](/match-scoring-guide)