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.
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.
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/…becomesapi.gominerva.com/custom-lists/v2/organizations/{orgId}/…admin-api.gominerva.com/v2/organizations/{orgId}/workspaces/…becomesapi.gominerva.com/workspaces/v2/organizations/{orgId}/…admin-api.gominerva.com/v2/webhooks/screening/…becomesapi.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:suppressedwhen the allowlist suppressed it.suppression_reason: present only whenreview_statusissuppressed.allowlistmeans your allowlist suppressed it;no_material_changemeans 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 asno_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
- Read
allowlist_summary.status.offmeans the allowlist did not run, andoff_reasonsays why (not_enabled,no_active_allowlist,mode_off, orchannel_disabled).unavailablemeans it could not be checked in time: nothing was suppressed. - Gate on
allowlist_summary.alertable. The entity needs review whilealertableis greater than 0. It counts every match whosereview_statusis neithersuppressednorfalse_positive, so it is safe to use even when the allowlist wasunavailable. A response withoutallowlist_summarycomes from before allowlists; count the matches yourself. - For each match, read
review_status, thensuppression_reason, thenallowlist.status.
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:hintorsuppress.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, withrecord_uid,name,scope,covers,reason,added_by,added_at, andexpires_at. Your customer IDs are never echoed.matched_on: the effectivematch_rules, how the name was accepted (subject_match), the field-by-fieldcomparison, andrecords_coveredout ofrecords_total.near_misses[]: up to 3 entries that cover the record for a different customer.decided_by:stagefor screening,analystorapplicationfor a match resolved later.evaluated_at: when the allowlist evaluated the match.
Recipe: allowlist a payee end to end
1. Create the allowlist
cURL
201:
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:
GET $BASE?purpose=allowlist.
2. Add a name-only entry
This entry covers one OFAC record that the payee’s name keeps matching:cURL
201:
- Do not send
record_uid: Minerva derives it from the customer’s identity and returns it asdata.record_uid(al_…). Keep it. - Optional fields you leave out come back empty (
aliases,countries,identifiers,customer_ids) ornull(match_rules,review_by).added_byis the application whose key made the request. data.working_set_revisionis the list’s revision after this write; send it asexpected_revisionwhen you publish.data.covers[].record_refis 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 withrecord_changed.data.warningslists anything worth a second look, such asallowlist_subject_is_listed_partywhen an entry name equals a covered record name on a feed other than Sanctions (on Sanctions that is a400).
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 thetolerant 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
201, shaped like the entry above, with "date_of_birth": "1980-05-06" and "working_set_revision": 2.
-
date_of_birthisYYYY-MM-DDorYYYY. Any other form returns400: -
scopeisknown_records(only the records incovers),source(any record from the sources insources), orcategory(any record on the feeds incategories). Broader scopes take effect only on feeds whose workspacefeedPolicyallows them. -
Sanctions accepts
known_recordsonly."scope": "category"with"categories": ["sanctions"]returns400witherror: allowlist_scope_not_allowed. Internal records can never be covered; a cover with"category": "internal"returns: -
match_rulessets a stricter match level for this entry only, for example{ "level": "exact" }. -
expires_atis required and can be at most 730 days after the entry is added; otherwise the response is400witherror: allowlist_expiry_out_of_rangeanddata.max_expires_at.
4. Publish and activate
Publish as for any custom list (see Publishing), sending the latestworking_set_revision as expected_revision:
cURL
202 with the new version; keep data.id as VERSION_ID:
enabled and versionId only:
cURL
allowlist_mode_offwarns that the workspace mode is stilloff; step 5 turns it on.deployment_statusisdeployinguntil screening reads the version, and thenlive.livecan come before screening applies the allowlist. Until it does, screens reportoff_reason: no_active_allowlistand alert as usual. This can take up to about a minute: in Minerva’s tests, a screen about 7 seconds afterlivestill reportedno_active_allowlist, and one about 38 seconds afterliveused the allowlist. Before you rely on suppression, run a test screen and check that it no longer reportsno_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 withno_active_allowlist. feedCategoryreturns400witherror: 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’sallowlist object is replaced as a whole on each PATCH; keys you leave out take their defaults. Start in hint:
cURL
200 with the whole workspace. Its allowlist fields, with the defaults filled in and the binding from step 4:
modeisoff(the default),hint, orsuppress.channelsturns the allowlist on per screening channel.matchRules.defaultisexact,standard, ortolerant.tolerantneeds atolerantThreshold. Turning onallowTolerantForSanctionsalso needs"acknowledgements": ["allowlist_tolerant_sanctions"]next toallowlistin the same request.feedPolicylists the scopes each feed allows. Every feed allowsknown_records, Sanctions allows nothing else, andinternalis not accepted.allowlistBindingsis read-only; sending it returns400. Use activation instead.
400 errors have plain-text bodies. Without tolerantThreshold:
allowTolerantForSanctions but no acknowledgement:
6. Screen the payee and read the annotation
cURL
- The match stays
unresolvedandallowlist_summary.would_suppresscounts it.alertablestill counts it too, because Hint Mode changes nothing. checklist.hits_info[].allowlist.statusissuppressed: that record is covered. The match-levelallowlist.statusandmodesay whether the coverage acted.
"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 birth1980-05-06 and the screen sent 1980-05-07:
details_not_matchedandsubject_not_matched: the screened customer is not the one on the entry. Checkmatched_on.comparison. When the screened name is the listed party’s own name,subject_not_matchedalso carries"screened_name_is_record": trueandcomparisonis 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_reasonisnew_recordorambiguous_first_sighting.entry_expiredandentry_lifetime_exceeded: renew the entry with a newexpires_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_coveredandrecord_not_covered_reason: ambiguous_first_sighting. Add the customer from the match and sendrecordsnaming 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 returns422witherror: no_uncovered_records. - Send countries in screening requests as ISO 3166-1 codes, such as
CG. A country name can be ambiguous:Congocan mean the Republic of the Congo (CG) or the Democratic Republic of the Congo (CD), so a screen that sendsCongois not covered by an entry limited toCG, and the match alerts withdetails_not_matched. In Minerva’s tests,Republic of the Congodid not matchCGeither.
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
countriesdefaults to the ISO 3166-1 alpha-2 code of the screened country. If Minerva could not confirm that country, the response is400witherror: country_unresolvedanddata.field: countries, and nothing is written. Send the customer’s country codes incountries, 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 asCongo, is one way to get this error (see Good to know).- Customer fields default to the match’s screened subject, and
recordsdefaults to"all_uncovered". Sendrecordsas a list of{category, source, record_name}to cover only some; a record not on the match returns422witherror: record_not_on_match. If every record on the match is already covered, the default"all_uncovered"returns422witherror: no_uncovered_records. resolve_matchdefaults totrueand marks this matchsuppressedwithsuppression_reason: allowlist. The entry must be live for that, so sendpublish: truewithexpected_revision, or the response is400witherror: resolve_requires_live_entryand nothing is written. Sendresolve_match: falseto save the entry without resolving.resolve_other_open_matches: truealso resolves the profile’s other open matches that the entry covers.- The response is
201for a new entry, or200when 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_uidfrom the201and address the entry by it afterwards. 409witherror: allowlist_entry_existsmeans an entry for the same customer already exists; adoptdata.record_uidfrom the error, and restore it first ifdata.statusisarchived.409witherror: allowlist_similar_entry_exists(from-match only) means another entry has a similar name; pick it withrecord_uid, or sendcreate_separate: true.- To decide whether to activate, read the workspace’s
allowlistBindingsentry for the list (returned with the workspace, see step 5;enabled: true,status: live) or thestatus: activeyour last activation returned, notGET $BASE/$LIST_ID/status. For an allowlist,workspace_activation_statusreadsnot_activatedeven 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
sourceagainst Minerva’s source catalogue, for exampleUS OFAC SDN Sanctions. A match can spell the same source differently, such asOFAC SDN List, and a row that uses that spelling fails withallowlist_unknown_source. To build entries from matches, use Add a customer from a match orPOST /records, which accept the match’s spelling. To upload a file, ask support@gominerva.com for the catalogue spellings first. PATCHreplaces the entry. Changing the customer’s identity (name, entity type, date of birth or incorporation, company number, or national ID) returns400witherror: 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
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:
Audit
List matches by how the allowlist treated them:cURL
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.
Related documentation
- Custom Lists API for lists, publishing, activation, and errors
- Alert Suppression Guide for repeated alert suppression (No Material Change)
- Automatic Disposition Guide for the step that runs after allowlisting
- Screening Integration Guide for the base screening response