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

# Allowlists Guide

> Create an allowlist of cleared customers, turn it on for a workspace, and read how it suppresses or annotates screening matches, end to end with curl.

An allowlist is a [custom list](https://docs.gominerva.com/api-reference/custom-lists-api.md) with `purpose: "allowlist"`. Each entry names one customer you have cleared, such as a payee or a client, and the watchlist records that customer keeps matching without being the listed party. When a later screen of that customer hits only covered records, Minerva marks the match `suppressed` with `suppression_reason: allowlist`, or, in Hint Mode, annotates it and leaves it for review.

An allowlist never raises a hit of its own. It only acts on hits from other feeds, and never on an Internal hit.

This guide covers creating an allowlist, adding entries, turning it on, reading the screening annotations, gating your workflow on them, adding a customer straight from a match, keeping entries in sync, and auditing.

> [!WARNING]
>
> **Enterprise feature:** Allowlists use the custom lists entitlement. Contact
> your Minerva representative or [support@gominerva.com](mailto:support@gominerva.com) to get custom lists
> enabled for your organization.

## Before you start

* Managing allowlists needs an **admin application key**, as every custom-list request does. See [The admin application key](https://docs.gominerva.com/api-reference/custom-lists-api.md#the-admin-application-key).
* Screening calls use your usual workspace API key. The allowlist annotations appear on the same responses you already read.
* An allowlist reduces new alerts. Profiles that are already flagged stay flagged until someone reviews them.
* Billing: an allowlisted Direct API or risk-assessment search is billed like any other search; allowlisting does not change how monitoring and onboarding are billed.

Set these variables first:

```bash theme={null}
export MINERVA_ADMIN_KEY="YOUR_ADMIN_API_KEY"
export MINERVA_API_KEY="YOUR_WORKSPACE_API_KEY"
export ORG_ID="YOUR_ORG_ID"
export WORKSPACE_ID="YOUR_WORKSPACE_ID"
export BASE="https://api.gominerva.com/custom-lists/v2/organizations/$ORG_ID"
```

> [!NOTE]
>
> `admin-api.gominerva.com` is deprecated for API clients. It keeps working for
> now, but new and updated integrations should call `api.gominerva.com`. The
> paths change as well as the host:
>
> * `admin-api.gominerva.com/v2/organizations/{orgId}/custom-lists/…` becomes `api.gominerva.com/custom-lists/v2/organizations/{orgId}/…`
> * `admin-api.gominerva.com/v2/organizations/{orgId}/workspaces/…` becomes `api.gominerva.com/workspaces/v2/organizations/{orgId}/…`
> * `admin-api.gominerva.com/v2/webhooks/screening/…` becomes `api.gominerva.com/webhooks/v2/screening/…`

> [!NOTE]
>
> The requests and responses on this page were captured from a Minerva test
> environment running allowlists. IDs, keys, `record_uid` values, checksums, and
> names are replaced with placeholders, and long responses are shortened to the
> fields this page discusses. The add-from-match response shows the documented
> shape; it was not part of that capture.

## Where the fields appear

| Surface | Endpoint | Match objects | Summary |
| - | - | - | - |
| Synchronous single search | `POST /v1/search-sync` or `GET /v1/search-sync` | `results[i]` | `allowlist_summary` |
| Batch search results | `GET /v1/search/{jobid}` | `results[n].results[i]` | `results[n].allowlist_summary` |
| v2 search | `POST /v2/search` | `entity_matches[k].matches[i]` | `entity_matches[k].metadata.allowlist_summary` |
| Potential matches list | `GET /v2/search/matches` | `matches[i]` | None; filter with `allowlist_status` instead |

Each match can carry:

* `review_status`: `suppressed` when the allowlist suppressed it.
* `suppression_reason`: present only when `review_status` is `suppressed`. `allowlist` means your allowlist suppressed it; `no_material_change` means Minerva's [repeated alert suppression](https://docs.gominerva.com/alert-suppression-guide.md) did, or a reviewer marked it No Material Change. It records why Minerva suppressed the match and is cleared on any later status change. Older responses may omit it; treat that as `no_material_change`.
* `allowlist`: what the allowlist concluded and which entry decided it. It stays on the match after a later review.
* `checklist.hits_info[].allowlist`: the outcome for each watchlist record on the match.

## Reading order

1. Read `allowlist_summary.status`. `off` means the allowlist did not run, and `off_reason` says why (`not_enabled`, `no_active_allowlist`, `mode_off`, or `channel_disabled`). `unavailable` means it could not be checked in time: nothing was suppressed.
2. Gate on `allowlist_summary.alertable`. The entity needs review while `alertable` is greater than 0. It counts every match whose `review_status` is neither `suppressed` nor `false_positive`, so it is safe to use even when the allowlist was `unavailable`. A response without `allowlist_summary` comes from before allowlists; count the matches yourself.
3. For each match, read `review_status`, then `suppression_reason`, then `allowlist.status`.

Allowlisting runs before [Automatic Disposition](https://docs.gominerva.com/api-reference/automatic-disposition-guide.md), so a match the allowlist suppressed carries no disposition.

## Modes

| Mode | Effect on a covered match | `allowlist.status` |
| - | - | - |
| `off` | None. The allowlist does not run. | Absent |
| `hint` | The match stays `unresolved`, annotated with the entry that would suppress it. | `would_suppress` |
| `suppress` | The match is set to `suppressed` with `suppression_reason: allowlist`. | `suppressed` |

Start in `hint`, check the annotations on real traffic, then switch to `suppress`.

## Annotation fields

| `allowlist.status` | Meaning |
| - | - |
| `suppressed` | Every alerting record on the match is covered by a valid entry. |
| `would_suppress` | The same coverage in Hint Mode. The match stays `unresolved`. |
| `partially_covered` | Some records are covered and others are not. `matched_on.records_covered` is less than `records_total`. |
| `subject_not_matched` | The screened name was not accepted. `screened_name_is_record: true` means the screened name is the listed party. |
| `details_not_matched` | The name matched, but a detail such as date of birth differs. See `matched_on.comparison`. |
| `record_not_covered` | A record on the match is outside the entry's known records. |
| `record_changed` | The watchlist record changed since the entry was approved against it. |
| `entry_expired` | The entry's `expires_at` has passed. |
| `entry_lifetime_exceeded` | The entry lasts longer than the workspace's `maxEntryLifetimeDays`. |

Every status other than `suppressed` and `would_suppress` alerts as usual. The other fields are:

* `mode`: `hint` or `suppress`.
* `list`: `{id, name, version_id, version_sequence}` of the allowlist version that screened the match.
* `entries[]`: a snapshot of the entries that decided the outcome, with `record_uid`, `name`, `scope`, `covers`, `reason`, `added_by`, `added_at`, and `expires_at`. Your customer IDs are never echoed.
* `matched_on`: the effective `match_rules`, how the name was accepted (`subject_match`), the field-by-field `comparison`, and `records_covered` out of `records_total`.
* `near_misses[]`: up to 3 entries that cover the record for a different customer.
* `decided_by`: `stage` for screening, `analyst` or `application` for a match resolved later.
* `evaluated_at`: when the allowlist evaluated the match.

## Recipe: allowlist a payee end to end

### 1. Create the allowlist

```bash cURL theme={null}
curl -X POST "$BASE" \
  -H "Authorization: Api-Key $MINERVA_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "name": "Cleared payees",
    "description": "Payees cleared by compliance. Reviewed quarterly.",
    "purpose": "allowlist"
  }'
```

The response is `201`:

```json theme={null}
{
  "data": {
    "id": "LIST_ID",
    "purpose": "allowlist",
    "tenant_id": "ORG_ID",
    "name": "Cleared payees",
    "description": "Payees cleared by compliance. Reviewed quarterly.",
    "status": "active",
    "schema_version": 1,
    "record_id_column": "record_uid",
    "default_feed_category": "",
    "risk_score_impact": 0,
    "created_by": "APPLICATION_ID",
    "created_at": "2026-11-18T16:06:27.719948795Z",
    "updated_at": "2026-11-18T16:06:27.719948795Z"
  }
}
```

Keep `data.id` as `LIST_ID`. `purpose` is fixed at create. An allowlist does not take `default_feed_category` or `risk_score_impact`: the response shows them empty, and sending either returns `400` with `error: allowlist_field_not_allowed`. A `purpose` other than `screening` or `allowlist` returns `400`:

```json theme={null}
{
  "error": "validation_failed",
  "message": "custom-list: validation failed: purpose must be screening or allowlist"
}
```

To find the list later, call `GET $BASE?purpose=allowlist`.

### 2. Add a name-only entry

This entry covers one OFAC record that the payee's name keeps matching:

```bash cURL theme={null}
curl -X POST "$BASE/$LIST_ID/records" \
  -H "Authorization: Api-Key $MINERVA_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "name": "NatWest Bank",
    "entity_type": "organization",
    "scope": "known_records",
    "covers": [
      {
        "category": "sanctions",
        "source": "OFAC SDN",
        "record_name": "Natwest Logistics LLC"
      }
    ],
    "reason": "Cleared by compliance. Ticket COMP-2291.",
    "expires_at": "2027-01-15"
  }'
```

The response is `201`:

```json theme={null}
{
  "data": {
    "id": "ENTRY_ID",
    "list_id": "LIST_ID",
    "record_uid": "al_ENTRY_UID",
    "status": "active",
    "name": "NatWest Bank",
    "aliases": [],
    "entity_type": "organization",
    "date_of_birth": null,
    "date_of_incorporation": null,
    "countries": [],
    "identifiers": {
      "company_number": null,
      "national_id": null
    },
    "customer_ids": [],
    "scope": "known_records",
    "covers": [
      {
        "category": "sanctions",
        "source": "OFAC SDN",
        "record_name": "Natwest Logistics LLC",
        "added_by": {
          "type": "application",
          "id": "app_APPLICATION_ID",
          "name": "Payments sync"
        },
        "added_at": "2026-11-18T16:06:28Z"
      }
    ],
    "sources": [],
    "categories": [],
    "match_rules": null,
    "reason": "Cleared by compliance. Ticket COMP-2291.",
    "expires_at": "2027-01-15T00:00:00Z",
    "review_by": null,
    "added_by": {
      "type": "application",
      "id": "app_APPLICATION_ID",
      "name": "Payments sync"
    },
    "added_at": "2026-11-18T16:06:28Z",
    "custom_fields": {},
    "created_at": "2026-11-18T16:06:28.203144201Z",
    "updated_at": "2026-11-18T16:06:28.203144201Z",
    "working_set_revision": 1,
    "warnings": []
  }
}
```

* Do not send `record_uid`: Minerva derives it from the customer's identity and returns it as `data.record_uid` (`al_…`). Keep it.
* Optional fields you leave out come back empty (`aliases`, `countries`, `identifiers`, `customer_ids`) or `null` (`match_rules`, `review_by`). `added_by` is the application whose key made the request.
* `data.working_set_revision` is the list's revision after this write; send it as `expected_revision` when you publish.
* `data.covers[].record_ref` is set only when an entry is added [from a match](#add-a-customer-from-a-match). For an entry added this way, Minerva pins the record's content at the first screen the entry covers; from then on, a later change to the record alerts again with `record_changed`.
* `data.warnings` lists anything worth a second look, such as `allowlist_subject_is_listed_party` when an entry name equals a covered record name on a feed other than Sanctions (on Sanctions that is a `400`).

### 3. Add a more specific entry

An individual with a date of birth. A screen that sends a different date of birth is not covered, except under the `tolerant` match rule, where a birth year within one year of the entry's still is and the comparison reads `within_tolerance`. A screen that sends no date of birth is still covered under the `standard` and `tolerant` match rules (set in step 5), and the comparison reads `missing_on_screen`. Only `exact` requires the screen to send it. A screen that sends no country is treated the same way. The request:

```bash cURL theme={null}
curl -X POST "$BASE/$LIST_ID/records" \
  -H "Authorization: Api-Key $MINERVA_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "name": "Maria Garcia Lopez",
    "entity_type": "individual",
    "scope": "known_records",
    "covers": [
      {
        "category": "sanctions",
        "source": "OFAC SDN",
        "record_name": "Maria Garcia Lopes"
      }
    ],
    "reason": "Customer verified by IDV; not the listed party. Ticket COMP-2302.",
    "expires_at": "2027-01-15",
    "date_of_birth": "1980-05-06"
  }'
```

The response is `201`, shaped like the entry above, with `"date_of_birth": "1980-05-06"` and `"working_set_revision": 2`.

* `date_of_birth` is `YYYY-MM-DD` or `YYYY`. Any other form returns `400`:

  ```json theme={null}
  {
    "error": "validation_failed",
    "message": "custom-list: validation failed: allowlist.date_of_birth must be YYYY-MM-DD or YYYY"
  }
  ```

* `scope` is `known_records` (only the records in `covers`), `source` (any record from the sources in `sources`), or `category` (any record on the feeds in `categories`). Broader scopes take effect only on feeds whose workspace `feedPolicy` allows them.

* Sanctions accepts `known_records` only. `"scope": "category"` with `"categories": ["sanctions"]` returns `400` with `error: allowlist_scope_not_allowed`. Internal records can never be covered; a cover with `"category": "internal"` returns:

  ```json theme={null}
  {
    "error": "allowlist_scope_not_allowed",
    "message": "internal lists can never be allowlisted"
  }
  ```

* `match_rules` sets a stricter match level for this entry only, for example `{ "level": "exact" }`.

* `expires_at` is required and can be at most 730 days after the entry is added; otherwise the response is `400` with `error: allowlist_expiry_out_of_range` and `data.max_expires_at`.

### 4. Publish and activate

Publish as for any custom list (see [Publishing](https://docs.gominerva.com/api-reference/custom-lists-api.md#publishing)), sending the latest `working_set_revision` as `expected_revision`:

```bash cURL theme={null}
curl -X POST "$BASE/$LIST_ID/publish" \
  -H "Authorization: Api-Key $MINERVA_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  --data '{"expected_revision": 2}'
```

The response is `202` with the new version; keep `data.id` as `VERSION_ID`:

```json theme={null}
{
  "data": {
    "id": "VERSION_ID",
    "purpose": "allowlist",
    "tenant_id": "ORG_ID",
    "list_id": "LIST_ID",
    "version_number": 1,
    "status": "published",
    "record_count": 2,
    "active_record_count": 2,
    "content_checksum": "CONTENT_CHECKSUM",
    "index_artifact_ref": "allowlist-versions/ORG_ID/LIST_ID/CONTENT_CHECKSUM.jsonl",
    "published_by": "APPLICATION_ID",
    "published_at": "2026-11-18T16:06:37.790828426Z",
    "name": "Cleared payees",
    "description": "Payees cleared by compliance. Reviewed quarterly.",
    "risk_score_impact": 0
  }
}
```

Then activate the version in the workspace. An allowlist activation takes `enabled` and `versionId` only:

```bash cURL theme={null}
curl -X PUT "$BASE/workspaces/$WORKSPACE_ID/lists/$LIST_ID/activation" \
  -H "Authorization: Api-Key $MINERVA_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  --data "{\"enabled\": true, \"versionId\": \"$VERSION_ID\"}"
```

```json theme={null}
{
  "data": {
    "list_id": "LIST_ID",
    "workspace_id": "WORKSPACE_ID",
    "purpose": "allowlist",
    "enabled": true,
    "status": "active",
    "version_id": "VERSION_ID",
    "deployment_status": "deploying",
    "updated_at": "2026-11-18T16:06:38.002379242Z",
    "warnings": [
      {
        "code": "allowlist_mode_off",
        "message": "Allowlist Suppression is off for this workspace, so this list has no effect until it is set to hint or suppress."
      }
    ]
  }
}
```

* `allowlist_mode_off` warns that the workspace mode is still `off`; step 5 turns it on.
* `deployment_status` is `deploying` until screening reads the version, and then `live`. `live` can come before screening applies the allowlist. Until it does, screens report `off_reason: no_active_allowlist` and alert as usual. This can take up to about a minute: in Minerva's tests, a screen about 7 seconds after `live` still reported `no_active_allowlist`, and one about 38 seconds after `live` used the allowlist. Before you rely on suppression, run a test screen and check that it no longer reports `no_active_allowlist`.
* To turn the allowlist off, send `"enabled": false`. The response has `"status": "inactive"`. Suppression doesn't stop at once: in the same tests, a screen 1 second later was still suppressed, and one about 20 seconds later alerted with `no_active_allowlist`.
* `feedCategory` returns `400` with `error: allowlist_field_not_allowed`. The Internal threshold and screening feed checks of a screening list do not apply.

### 5. Set the workspace mode and match rules

The workspace's `allowlist` object is replaced as a whole on each `PATCH`; keys you leave out take their defaults. Start in `hint`:

```bash cURL theme={null}
curl -X PATCH "https://api.gominerva.com/workspaces/v2/organizations/$ORG_ID/$WORKSPACE_ID" \
  -H "Authorization: Api-Key $MINERVA_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "allowlist": {
      "version": 1,
      "mode": "hint",
      "channels": {
        "onboarding": true,
        "monitoring": true,
        "direct_api": true,
        "risk_assessment": true
      },
      "matchRules": {
        "default": "exact",
        "tolerantThreshold": null,
        "allowTolerantForSanctions": false
      }
    }
  }'
```

The response is `200` with the whole workspace. Its allowlist fields, with the defaults filled in and the binding from step 4:

```json expandable theme={null}
{
  "data": {
    "id": "ORG_ID",
    "workspace": {
      "id": "WORKSPACE_ID",
      "allowlist": {
        "version": 1,
        "mode": "hint",
        "channels": {
          "onboarding": true,
          "monitoring": true,
          "direct_api": true,
          "risk_assessment": true
        },
        "matchRules": {
          "default": "exact",
          "tolerantThreshold": null,
          "allowTolerantForSanctions": false
        },
        "feedPolicy": {
          "sanctions": {
            "scopes": ["known_records"]
          },
          "pep": {
            "scopes": ["known_records"]
          },
          "news": {
            "scopes": ["known_records"]
          },
          "criminal": {
            "scopes": ["known_records"]
          },
          "legal": {
            "scopes": ["known_records"]
          }
        },
        "allowUnknownEntityType": false,
        "maxEntryLifetimeDays": 365
      },
      "allowlistBindings": [
        {
          "listId": "LIST_ID",
          "listName": "Cleared payees",
          "versionId": "VERSION_ID",
          "versionSequence": 1,
          "artifactKey": "allowlist-versions/ORG_ID/LIST_ID/CONTENT_CHECKSUM.jsonl",
          "artifactVersionId": "ARTIFACT_VERSION_ID",
          "checksum": "CONTENT_CHECKSUM",
          "enabled": true,
          "status": "live",
          "activatedBy": "app_APPLICATION_ID",
          "activatedAt": "2026-11-18T16:06:38.002Z"
        }
      ]
    }
  }
}
```

* `mode` is `off` (the default), `hint`, or `suppress`.
* `channels` turns the allowlist on per screening channel.
* `matchRules.default` is `exact`, `standard`, or `tolerant`. `tolerant` needs a `tolerantThreshold`. Turning on `allowTolerantForSanctions` also needs `"acknowledgements": ["allowlist_tolerant_sanctions"]` next to `allowlist` in the same request.
* `feedPolicy` lists the scopes each feed allows. Every feed allows `known_records`, Sanctions allows nothing else, and `internal` is not accepted.
* `allowlistBindings` is read-only; sending it returns `400`. Use activation instead.

These two `400` errors have plain-text bodies. Without `tolerantThreshold`:

```text theme={null}
Validation error: tolerantThreshold is required when the default match rule is tolerant. at "body.allowlist.matchRules.tolerantThreshold"
```

With `allowTolerantForSanctions` but no acknowledgement:

```text theme={null}
allowlist_ack_required: allowlist.matchRules.allowTolerantForSanctions requires acknowledgements ["allowlist_tolerant_sanctions"]
```

See [Workspace Management API](https://docs.gominerva.com/api-reference/workspace-management-api.md) for the rest of the workspace object.

### 6. Screen the payee and read the annotation

```bash cURL theme={null}
curl -X POST https://api.gominerva.com/v1/search-sync \
  -H "x-api-key: $MINERVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "NatWest Bank",
    "type": "organization",
    "feeds": [
      "Sanctions"
    ]
  }'
```

A shortened response in Hint Mode:

```json expandable theme={null}
{
  "status": 200,
  "pending": false,
  "allowlist_summary": {
    "status": "available",
    "suppressed": 0,
    "would_suppress": 1,
    "alertable": 1
  },
  "results": [
    {
      "name": {
        "value": "Natwest Logistics Llc"
      },
      "review_status": "unresolved",
      "checklist": {
        "screen": {
          "Sanctions": true
        },
        "hits": {
          "Sanctions": ["OFAC SDN"]
        },
        "hits_info": [
          {
            "feed": "Sanctions",
            "source": "OFAC SDN",
            "allowlist": {
              "status": "suppressed",
              "record_uid": "al_ENTRY_UID",
              "record_fingerprint": "sha256:RECORD_FINGERPRINT"
            }
          }
        ]
      },
      "allowlist": {
        "status": "would_suppress",
        "mode": "hint",
        "list": {
          "id": "LIST_ID",
          "name": "Cleared payees",
          "version_id": "VERSION_ID",
          "version_sequence": 1
        },
        "entries": [
          {
            "record_uid": "al_ENTRY_UID",
            "name": "NatWest Bank",
            "entity_type": "organization",
            "scope": "known_records",
            "covers": [
              {
                "category": "sanctions",
                "source": "OFAC SDN",
                "record_name": "Natwest Logistics LLC",
                "fingerprint_source": "none"
              }
            ],
            "reason": "Cleared by compliance. Ticket COMP-2291.",
            "added_by": {
              "type": "application",
              "id": "app_APPLICATION_ID",
              "name": "Payments sync"
            },
            "added_at": "2026-11-18T16:06:28Z",
            "expires_at": "2027-01-15T00:00:00Z"
          }
        ],
        "matched_on": {
          "match_rules": {
            "level": "exact",
            "source": "workspace"
          },
          "subject_match": {
            "tier": "exact",
            "key": "full_norm",
            "score": 1.0
          },
          "comparison": [
            {
              "field": "name",
              "entry": "NatWest Bank",
              "screened": "NatWest Bank",
              "result": "same"
            },
            {
              "field": "entity_type",
              "entry": "organization",
              "screened": "organization",
              "result": "same"
            }
          ],
          "records_covered": 1,
          "records_total": 1
        },
        "decided_by": "stage",
        "evaluated_at": "2026-11-18T16:07:12Z"
      }
    }
  ]
}
```

* The match stays `unresolved` and `allowlist_summary.would_suppress` counts it. `alertable` still counts it too, because Hint Mode changes nothing.
* `checklist.hits_info[].allowlist.status` is `suppressed`: that record is covered. The match-level `allowlist.status` and `mode` say whether the coverage acted.

In Suppression Mode the same screen returns `"review_status": "suppressed"`, `"suppression_reason": "allowlist"`, and `allowlist.status` `suppressed`, and the summary reads:

```json theme={null}
{
  "status": "available",
  "suppressed": 1,
  "would_suppress": 0,
  "alertable": 0
}
```

### 7. Gate on `alertable`

Route the entity to review while `allowlist_summary.alertable` is greater than 0, and let it through when it is 0. Do not branch on `status` alone: `unavailable` suppresses nothing, so `alertable` already counts every open match.

## Broken states

A match whose entry no longer applies alerts as usual and says why. Here the entry from step 3 has date of birth `1980-05-06` and the screen sent `1980-05-07`:

```json expandable theme={null}
"allowlist": {
  "status": "details_not_matched",
  "mode": "suppress",
  "list": {
    "id": "LIST_ID",
    "name": "Cleared payees",
    "version_id": "VERSION_ID",
    "version_sequence": 1
  },
  "entries": [
    {
      "record_uid": "al_ENTRY_UID",
      "name": "Maria Garcia Lopez",
      "entity_type": "individual",
      "date_of_birth": "1980-05-06",
      "scope": "known_records",
      "covers": [
        {
          "category": "sanctions",
          "source": "OFAC SDN",
          "record_name": "Maria Garcia Lopes",
          "fingerprint_source": "none"
        }
      ],
      "reason": "Customer verified by IDV; not the listed party. Ticket COMP-2302.",
      "added_by": {
        "type": "application",
        "id": "app_APPLICATION_ID",
        "name": "Payments sync"
      },
      "added_at": "2026-11-18T16:06:28Z",
      "expires_at": "2027-01-15T00:00:00Z"
    }
  ],
  "matched_on": {
    "match_rules": {
      "level": "exact",
      "source": "workspace"
    },
    "subject_match": {
      "tier": "exact",
      "key": "full_norm",
      "score": 1.0
    },
    "comparison": [
      {
        "field": "name",
        "entry": "Maria Garcia Lopez",
        "screened": "Maria Garcia Lopez",
        "result": "same"
      },
      {
        "field": "entity_type",
        "entry": "individual",
        "screened": "individual",
        "result": "same"
      },
      {
        "field": "date_of_birth",
        "entry": "1980-05-06",
        "screened": "1980-05-07",
        "result": "different"
      }
    ],
    "records_covered": 0,
    "records_total": 1
  },
  "decided_by": "stage",
  "evaluated_at": "2026-11-18T16:08:34Z"
}
```

* `details_not_matched` and `subject_not_matched`: the screened customer is not the one on the entry. Check `matched_on.comparison`. When the screened name is the listed party's own name, `subject_not_matched` also carries `"screened_name_is_record": true` and `comparison` is empty.
* `record_changed`: the watchlist record was amended. Review the new content, then add the customer from this match again to approve it.
* `record_not_covered`: a new record appeared that the entry does not cover. `record_not_covered_reason` is `new_record` or `ambiguous_first_sighting`.
* `entry_expired` and `entry_lifetime_exceeded`: renew the entry with a new `expires_at`.

### Good to know

* A name-only entry can't tell records apart when one screen returns the same record name more than once on a source, or when the cover's record name is also an alias of another record on that source. The match then alerts with `record_not_covered` and `record_not_covered_reason: ambiguous_first_sighting`. [Add the customer from the match](#add-a-customer-from-a-match) and send `records` naming those records: Minerva pins the exact records on that match, and later screens that return them unchanged are covered. Don't rely on the default `"all_uncovered"` here; when the entry already names those records, it returns `422` with `error: no_uncovered_records`.
* Send countries in screening requests as ISO 3166-1 codes, such as `CG`. A country name can be ambiguous: `Congo` can mean the Republic of the Congo (`CG`) or the Democratic Republic of the Congo (`CD`), so a screen that sends `Congo` is not covered by an entry limited to `CG`, and the match alerts with `details_not_matched`. In Minerva's tests, `Republic of the Congo` did not match `CG` either.

## Add a customer from a match

When an analyst or your system clears a match, add the customer straight from it. Minerva captures the subject and the exact record content from the match, so the entry is approved against what was actually screened:

```bash cURL theme={null}
curl -X POST "$BASE/$LIST_ID/records/from-match" \
  -H "Authorization: Api-Key $MINERVA_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "match_id": "MATCH_ID",
    "workspace_id": "'"$WORKSPACE_ID"'",
    "reason": "Payee is NatWest Bank, the UK clearing bank",
    "expires_at": "2027-11-14",
    "publish": true,
    "expected_revision": 41
  }'
```

* `countries` defaults to the ISO 3166-1 alpha-2 code of the screened country. If Minerva could not confirm that country, the response is `400` with `error: country_unresolved` and `data.field: countries`, and nothing is written. Send the customer's country codes in `countries`, or send `[]` if the entry should apply whatever country a screen sends: `[]` adds the entry for this name in any country. A screen that sent an ambiguous country name, such as `Congo`, is one way to get this error (see [Good to know](#good-to-know)).
* Customer fields default to the match's screened subject, and `records` defaults to `"all_uncovered"`. Send `records` as a list of `{category, source, record_name}` to cover only some; a record not on the match returns `422` with `error: record_not_on_match`. If every record on the match is already covered, the default `"all_uncovered"` returns `422` with `error: no_uncovered_records`.
* `resolve_match` defaults to `true` and marks this match `suppressed` with `suppression_reason: allowlist`. The entry must be live for that, so send `publish: true` with `expected_revision`, or the response is `400` with `error: resolve_requires_live_entry` and nothing is written. Send `resolve_match: false` to save the entry without resolving.
* `resolve_other_open_matches: true` also resolves the profile's other open matches that the entry covers.
* The response is `201` for a new entry, or `200` when the covers were merged into an existing entry for the same customer:

```json theme={null}
{
  "data": {
    "entry": {
      "record_uid": "al_be8ed741b581485c4d5668ee",
      "name": "NatWest Bank",
      "scope": "known_records"
    },
    "working_set_revision": 42,
    "published_version_id": "VERSION_ID",
    "resolved_match_ids": ["MATCH_ID"],
    "skipped": [],
    "warnings": []
  }
}
```

`skipped[]` lists matches that were not resolved, each with a `reason`: `subject_not_matched`, `details_not_matched`, `screened_name_is_record`, `record_not_covered`, `record_changed`, `not_open` (already reviewed), or `not_live_yet` (the version the entry is in is not yet readable by screening, or the list's live version changed while the request ran; screen again shortly). A skipped match is never an error: the entry is saved either way.

## Keep entries in sync

If your system of record holds the cleared customers, sync them like any custom list, with these differences:

* Store `data.record_uid` from the `201` and address the entry by it afterwards.
* `409` with `error: allowlist_entry_exists` means an entry for the same customer already exists; adopt `data.record_uid` from the error, and restore it first if `data.status` is `archived`.
* `409` with `error: allowlist_similar_entry_exists` (from-match only) means another entry has a similar name; pick it with `record_uid`, or send `create_separate: true`.
* To decide whether to activate, read the workspace's `allowlistBindings` entry for the list (returned with the workspace, see step 5; `enabled: true`, `status: live`) or the `status: active` your last activation returned, not `GET $BASE/$LIST_ID/status`. For an allowlist, `workspace_activation_status` reads `not_activated` even while the list is active, so a sync that checks it would activate again on every run.
* CSV and XLSX uploads check each cover's `source` against Minerva's source catalogue, for example `US OFAC SDN Sanctions`. A match can spell the same source differently, such as `OFAC SDN List`, and a row that uses that spelling fails with `allowlist_unknown_source`. To build entries from matches, use [Add a customer from a match](#add-a-customer-from-a-match) or `POST /records`, which accept the match's spelling. To upload a file, ask [support@gominerva.com](mailto:support@gominerva.com) for the catalogue spellings first.
* `PATCH` replaces the entry. Changing the customer's identity (name, entity type, date of birth or incorporation, company number, or national ID) returns `400` with `error: allowlist_identity_immutable`; archive the entry and create a new one instead.

### Update an entry

`PATCH $BASE/$LIST_ID/records/$RECORD_UID` replaces the whole entry, so send every field, not only the ones that change. Read the entry first and send it back with your change. A partial body is refused, and nothing is written. This request replaces the entry's cover with a different OFAC record, but leaves out `scope` and `reason`:

```bash cURL theme={null}
curl -X PATCH "$BASE/$LIST_ID/records/$RECORD_UID" \
  -H "Authorization: Api-Key $MINERVA_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "name": "NatWest Bank",
    "entity_type": "organization",
    "expires_at": "2027-01-15",
    "covers": [
      {
        "category": "sanctions",
        "source": "OFAC SDN",
        "record_name": "Natwest Holdings Ltd"
      }
    ]
  }'
```

```json theme={null}
{
  "error": "validation_failed",
  "data": {
    "field": "scope"
  },
  "message": "scope: Required"
}
```

`data.field` names the first missing or invalid field. The same request with the full entry:

```bash cURL theme={null}
curl -X PATCH "$BASE/$LIST_ID/records/$RECORD_UID" \
  -H "Authorization: Api-Key $MINERVA_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "name": "NatWest Bank",
    "entity_type": "organization",
    "scope": "known_records",
    "reason": "Cleared by compliance. Ticket COMP-2291.",
    "expires_at": "2027-01-15",
    "covers": [
      {
        "category": "sanctions",
        "source": "OFAC SDN",
        "record_name": "Natwest Holdings Ltd"
      }
    ]
  }'
```

The response is `200` with the updated entry, shortened. `record_uid` and the entry's `added_at` stay as they were in [step 2](#2-add-a-name-only-entry). A cover you keep keeps its `added_at`; the new cover gets its own. `working_set_revision` increases:

```json theme={null}
{
  "data": {
    "record_uid": "al_ENTRY_UID",
    "scope": "known_records",
    "covers": [
      {
        "category": "sanctions",
        "source": "OFAC SDN",
        "record_name": "Natwest Holdings Ltd",
        "added_by": {
          "type": "application",
          "id": "app_APPLICATION_ID",
          "name": "Payments sync"
        },
        "added_at": "2026-11-18T18:25:30Z"
      }
    ],
    "added_at": "2026-11-18T16:06:28Z",
    "updated_at": "2026-11-18T18:25:30.218440127Z",
    "working_set_revision": 5
  }
}
```

Publish and activate the new revision as in [step 4](#4-publish-and-activate). Screening uses the change only once that version is live.

## Audit

List matches by how the allowlist treated them:

```bash cURL theme={null}
curl "https://api.gominerva.com/v2/search/matches?suppression_reason=allowlist" \
  -H "x-api-key: $MINERVA_API_KEY"

curl "https://api.gominerva.com/v2/search/matches?allowlist_status=record_changed,record_not_covered" \
  -H "x-api-key: $MINERVA_API_KEY"
```

To read the matches of one screen, filter by its request ID. A shortened response for the payee from step 6, screened in Suppression Mode:

```bash cURL theme={null}
curl "https://api.gominerva.com/v2/search/matches?request_id=$REQUEST_ID" \
  -H "x-api-key: $MINERVA_API_KEY"
```

```json expandable theme={null}
{
  "pagination": {
    "page": 1,
    "limit": 10,
    "total_count": 1,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  },
  "matches": [
    {
      "id": "MATCH_ID",
      "request_id": "REQUEST_ID",
      "workspace_id": "WORKSPACE_ID",
      "name": {
        "value": "Natwest Logistics Llc"
      },
      "review_status": "suppressed",
      "suppression_reason": "allowlist",
      "allowlist": {
        "status": "suppressed",
        "mode": "suppress",
        "list": {
          "id": "LIST_ID",
          "name": "Cleared payees",
          "version_id": "VERSION_ID",
          "version_sequence": 1
        },
        "entries": [
          {
            "record_uid": "al_ENTRY_UID",
            "name": "NatWest Bank",
            "entity_type": "organization",
            "scope": "known_records",
            "covers": [
              {
                "category": "sanctions",
                "source": "OFAC SDN",
                "record_name": "Natwest Logistics LLC",
                "fingerprint_source": "pinned"
              }
            ],
            "reason": "Cleared by compliance. Ticket COMP-2291.",
            "added_by": {
              "type": "application",
              "id": "app_APPLICATION_ID",
              "name": "Payments sync"
            },
            "added_at": "2026-11-18T16:06:28Z",
            "expires_at": "2027-01-15T00:00:00Z"
          }
        ],
        "matched_on": {
          "match_rules": {
            "level": "exact",
            "source": "workspace"
          },
          "subject_match": {
            "tier": "exact",
            "key": "full_norm",
            "score": 1.0
          },
          "comparison": [
            {
              "field": "name",
              "entry": "NatWest Bank",
              "screened": "NatWest Bank",
              "result": "same"
            },
            {
              "field": "entity_type",
              "entry": "organization",
              "screened": "organization",
              "result": "same"
            }
          ],
          "records_covered": 1,
          "records_total": 1
        },
        "decided_by": "stage",
        "evaluated_at": "2026-11-18T16:07:13Z"
      },
      "created_at": "2026-11-18T16:07:13.366Z",
      "updated_at": "2026-11-18T16:07:13.366Z"
    }
  ]
}
```

`suppression_reason` reads the current reason; `allowlist_status` reads how the allowlist screened the match and stays after a later review. To find matches that were allowlisted and then reviewed, combine `allowlist_status=suppressed` with `review_status=true_positive,false_positive`.

## Related documentation

* [Custom Lists API](https://docs.gominerva.com/api-reference/custom-lists-api.md) for lists, publishing, activation, and errors
* [Alert Suppression Guide](https://docs.gominerva.com/alert-suppression-guide.md) for repeated alert suppression (No Material Change)
* [Automatic Disposition Guide](https://docs.gominerva.com/api-reference/automatic-disposition-guide.md) for the step that runs after allowlisting
* [Screening Integration Guide](https://docs.gominerva.com/api-reference/screening-integration-guide.md) for the base screening response


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.