Skip to main content
An allowlist is a custom list 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.
Enterprise feature: Allowlists use the custom lists entitlement. Contact your Minerva representative or 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.
  • 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:
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/…
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

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 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, so a match the allowlist suppressed carries no disposition.

Modes

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

Annotation fields

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

cURL
The response is 201:
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:
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:
cURL
The response is 201:
  • 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. 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:
cURL
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:
  • 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:
  • 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), sending the latest working_set_revision as expected_revision:
cURL
The response is 202 with the new version; keep data.id as VERSION_ID:
Then activate the version in the workspace. An allowlist activation takes enabled and versionId only:
cURL
  • 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:
cURL
The response is 200 with the whole workspace. Its allowlist fields, with the defaults filled in and the binding from step 4:
  • 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:
With allowTolerantForSanctions but no acknowledgement:
See Workspace Management API for the rest of the workspace object.

6. Screen the payee and read the annotation

cURL
A shortened response in Hint Mode:
  • 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:

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:
  • 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 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:
cURL
  • 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).
  • 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:
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 or POST /records, which accept the match’s spelling. To upload a file, ask 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:
cURL
data.field names the first missing or invalid field. The same request with the full entry:
cURL
The response is 200 with the updated entry, shortened. record_uid and the entry’s added_at stay as they were in step 2. A cover you keep keeps its added_at; the new cover gets its own. working_set_revision increases:
Publish and activate the new revision as in step 4. Screening uses the change only once that version is live.

Audit

List matches by how the allowlist treated them:
cURL
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:
cURL
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.