Skip to main content

​
Exclusion lists

An exclusion suppresses results you don’t want to be alerted about — your own test accounts, a partner’s domain, a known-benign pattern. Exclusions belong to a single rule, and they’re forward-only: they’re applied as new hits are recorded, so they shape future matches and never re-scan ones you already have. Excluded hits aren’t deleted — they’re flagged is_excluded and hidden by default (and they don’t count toward notifications). See them anytime with show_excluded=true when reading a match.

​
How an exclusion works

An exclusion is a condition — an AND/OR group of field/value tests:
  • A leaf is {"field": "email", "value": "security@acme.com"}.
  • A group is {"match": "all" | "any", "rules": [ … ]} — all means every rule must match (AND), any means at least one (OR). Groups can nest, and the top level is always a group.
When a hit is recorded, each of its values is tested. The field is matched by key name anywhere in the result — field: "email" finds an email key at any depth of the hit’s data. How the value is compared (exact, case-insensitive, substring) comes from the source’s own field config, not from your request — so field must be one of that service’s excludable fields, or the condition is rejected.

​
Add exclusions

alert-system-exclusions-create takes a non-empty JSON array of condition groups — one group per exclusion. Re-posting an identical condition is a no-op (exclusions are unique per rule). Suppress a single address:
Suppress only when both fields match (a combo — useful so a reused password elsewhere still alerts you):
Suppress any of several addresses in one exclusion with "match": "any". A 201 returns the created exclusions, each { id, condition, created_at }.

​
Upload a list

To suppress many values at once, alert-system-exclusions-upload takes a CSV file:
The file is a header row of field names, then one row of values per exclusion:
Each row becomes one exclusion, combining its non-empty cells with the match query param (all or any, default any). So with match=all, jdoe@acme.com,Summer2024! suppresses hits matching that email and that password. Limits: .csv only, UTF-8, up to 5 MB and 1000 rows; the file must have a header and at least one value. The response summarizes the run: { total_added, total_processed, total_skipped_invalid, total_skipped_duplicate } — duplicates (already present on the rule) and invalid fields (not excludable for the source) are skipped, not errored.

​
List and remove

Exclusions apply to the sources that declare excludable fields — in practice the credential sources ([Raw Data](/api/guides/credentials-raw-sweep) and [Filtered credentials](/api/guides/credentials-filtered)). Read a service’s `excludable_fields` from the [service catalog](/api/guides/monitoring-rules) to see which `field` values it accepts.