Global Sanctions Screening API
One API call. Every major sanctions list. Every match tells you exactly how it was found, why it scored the way it did, and what to do about it.
What Is Noble Sight?
Noble Sight is a free global sanctions screening API. One call screens a name against nine sanctions lists — OFAC, UK, EU, UN, France, Canada, Australia, Belgium, and Netherlands — using hybrid trigram, phonetic, and AI-powered matching.
Every match tells you exactly what triggered it: which list, which name form, the character similarity score, and whether phonetics agreed. Provide secondary attributes — date of birth, country, or entity type — and mismatches are flagged with structured reasons. Nothing is hidden behind an opaque number.
Screening results are stored immutably with the list version used, full request and response, and trace ID. Designed for OFAC's 10-year recordkeeping requirement and SOC 2 audit readiness.
Why Noble Sight
| Capability | Noble Sight (Free) | Open Source Alternatives | Paid APIs ($79–999/mo) |
|---|---|---|---|
| Per-match pathway breakdown | Every match shows source, trigram score, soundex flag | Single opaque score | Basic score only |
| AI name variations | 89,117 pre-computed + real-time deep screen | None | None |
| Dismissal reasons | Structured DOB, country, entity type explanations | None | None |
| Audit persistence | Full request/response + OFAC list version | Stateless — lost on restart | Yes |
| OFAC list version tracking | Every screening tagged with publish ID | None | Varies |
| Real-time alert delivery | HMAC-signed webhooks with retry + cursor polling | None | Varies |
| Internal watchlist screening | SAR subjects, exited customers, 314(a) names — same fuzzy engine, same API call | None | Separate system |
| Response time | Published target: 110 ms median, 350 ms p99, server-side; every response carries a Server-Timing header so you can check it | Not published | Not published |
Built Different
Noble Sight is a single 18 MB binary. No runtime. No interpreter. No framework. No node_modules. The entire screening engine, API server, and audit system compiles to one static executable running on a read-only filesystem as a non-root user.
Most screening vendors ship 500 MB–1 GB container images packed with runtimes, package managers, and shells — each one an entry point for attackers. Noble Sight ships on a distroless base image with no shell, no package manager, and no utilities. There is nothing to exploit because there is nothing there.
| Property | Noble Sight | Typical Screening Vendor |
|---|---|---|
| Container image | 18 MB, distroless, no shell | 500 MB–1 GB, full OS with package manager |
| Runtime | None — compiled to native machine code | JVM, Node.js, or Python interpreter |
| Attack surface | Zero shell utilities, zero writable paths | Full Linux userland |
| Cold start | <1 second | 15–30 seconds (JVM warmup) |
| Memory at idle | ~30 MB | 300–500 MB (runtime overhead) |
| Dependencies | Go standard library + PostgreSQL | Hundreds of transitive packages |
| SQL | Parameterized queries, no ORM | ORM-generated queries, abstraction layers |
Every dependency is a liability. Every abstraction layer is a place where queries slow down, errors get swallowed, and auditors lose the trail. Noble Sight has fewer moving parts because compliance software should be the most predictable thing in your stack — not the most complex.
Architecture
The screening engine implements the model cascade architecture recommended by Federal Reserve research (FEDS 2025-092). Allen & Hatfield found that LLMs reduce false positives by 92% but are 10,000x slower than fuzzy matching. Their recommendation: fast fuzzy matching for routine screens, LLM escalation for hard cases.
Noble Sight pre-computes LLM-generated spelling, transliteration, and cultural name variations at import time — amortizing the AI cost once per SDN update, not once per query. This innovation is not discussed in the Fed paper.
Lists Screened
| List | Source | Status |
|---|---|---|
| OFAC SDN | U.S. Treasury — Specially Designated Nationals | Live |
| OFAC Consolidated | U.S. Treasury — Non-SDN Consolidated List | Live |
| UK Sanctions | HM Treasury — UK Financial Sanctions (OFSI) | Live |
| EU Sanctions | European Commission — EU Consolidated Financial Sanctions | Live |
| UN Sanctions | UN Security Council — Consolidated List | Live |
| France | Direction Generale du Tresor — Registre National des Gels | Live |
| Canada | Global Affairs Canada — SEMA Consolidated List | Live |
| Australia | DFAT — Australian Consolidated Sanctions List | Live |
| Belgium | Belgian Federal Finance Ministry — National Terrorist List | Live |
| Netherlands | Rijksoverheid — National Terrorism List | Live |
Every live list uses the same screening engine — trigram, phonetic, and AI-powered matching. Every list is watched continuously and delta-imported on change. Portfolio monitoring automatically re-screens your entities when any list updates. GET /v1/lists reports the version of each list in use and whether it is current.
Screen a Name in 60 Seconds
Noble Sight is currently in invite-only beta. Contact sales@noblesight.io for an invite code. With a code, the steps below take 60 seconds.
Get an API Key
curl -X POST https://noblesight.io/v1/keys \
-H "Content-Type: application/json" \
-d '{"client_id": "your-company", "accept_terms": true, "invite_code": "noble_inv_..."}'
Screen a Name
curl -X POST https://noblesight.io/v1/screen \
-H "Content-Type: application/json" \
-H "X-API-Key: $NOBLE_API_KEY" \
-d '{"name": "Vladimir Putin"}'
Get Results
{
"screened_name": "Vladimir Putin",
"alert_id": 42,
"match_count": 1,
"matches": [{
"uid": "36095",
"first_name": "Vladimir",
"last_name": "PUTIN",
"score": 97.5,
"source": "OFAC",
"programs": ["RUSSIA-EO14024"],
"date_of_birth": "1952-10-07",
"place_of_birth": "Leningrad, Russia",
"nationalities": ["Russia"],
"match_sources": [{
"source": "ofac_sdn",
"trigram_score": 100,
"soundex_match": true
}]
}],
"meta": {
"disclaimer": "Noble Sight provides sanctions screening results for informational purposes only. This service is not a substitute for a comprehensive sanctions compliance program. Noble Sight does not provide legal, regulatory, or compliance advice. Screening results reflect data available at the time of the request and may not capture all sanctions designations, aliases, or name variations. Final screening decisions, risk assessments, and compliance obligations remain the sole responsibility of the subscribing institution. Use of this service does not satisfy or replace any obligation under OFAC regulations, the Bank Secrecy Act, or any other applicable law."
}
}
Workflow Playbook
The API reference tells you what each endpoint does. This guide shows you how to use them together. Eight workflows, step by step, with copy-paste curl examples.
1. Onboard a Customer
A new customer applies. You need to screen their name against sanctions lists before opening the account. Provide every attribute you have — name, date of birth, country, entity type, and government ID — to get the most accurate score with the fewest false positives.
Screen with full attributes
Pass everything you collected during KYC. Each attribute reduces false positives — a DOB mismatch alone can drop a 96 to a 38.
curl -X POST https://noblesight.io/v1/screen \
-H "Content-Type: application/json" \
-H "X-API-Key: $NOBLE_API_KEY" \
-H "X-Trace-ID: onboarding-acct-7891" \
-d '{
"name": "Alexander Volkov",
"date_of_birth": "1985-03-15",
"country": "RU",
"entity_type": "individual",
"id_number": "P1234567",
"id_type": "Passport"
}'
Read the response
Check match_count and alert_id. If match_count is 0, the customer is clear. If an alert_id is present, a match exceeded your alert threshold and needs review.
{
"screening_id": 5678,
"alert_id": 0,
"screened_name": "Alexander Volkov",
"match_count": 0,
"average_score": 0,
"lists_screened": ["ofac", "uk", "eu", "france", "belgium", "netherlands", "un", "canada", "australia"],
"matches": [],
"meta": { "disclaimer": "..." }
}
No matches, no alert. Proceed with account opening. The screening is stored immutably with your trace ID for audit.
If there is a match
When the response includes an alert_id, a match needs investigation. Check the dismissal_reasons array — it tells you exactly which attributes mismatched and by how much. Then move to the alert triage workflow below.
{
"screening_id": 5679,
"alert_id": 44,
"screened_name": "Alexander Volkov",
"match_count": 1,
"matches": [{
"uid": "12345",
"first_name": "Aleksandr",
"last_name": "VOLKOV",
"score": 42.3,
"source": "OFAC",
"programs": ["RUSSIA-EO14024"],
"match_sources": [{"source": "ofac_sdn", "trigram_score": 84.5, "soundex_match": true}],
"dismissal_reasons": [
"DOB mismatch: provided 1985-03-15, SDN has 1960-07-22 (far mismatch, 0.4x)",
"Country matches: RU"
],
"date_of_birth": "1960-07-22",
"nationalities": ["Russia"]
}]
}
The raw trigram score was 84.5, but the 25-year DOB mismatch applied a 0.4x penalty, dropping the final score to 42.3. The dismissal_reasons array explains exactly why.
2. Triage and Resolve Alerts
A screening returned a match. Someone needs to review it, decide if it is real, and document the decision. This is the full alert lifecycle — from new alert through investigation to resolution. Every action is recorded immutably.
List new alerts
Pull all unreviewed alerts. Filter by score to prioritize the highest-confidence matches first.
curl "https://noblesight.io/v1/alerts?status=new&min_score=80&limit=25" \ -H "X-API-Key: $NOBLE_API_KEY"
Assign to an analyst
SLA deadlines are set automatically: 24 hours for scores 90+, 72 hours for all others.
curl -X POST "https://noblesight.io/v1/alerts/44/assign" \
-H "Content-Type: application/json" \
-H "X-API-Key: $NOBLE_API_KEY" \
-d '{"assign_to": "analyst@yourcompany.com"}'
Investigate and add notes
Pull the full alert detail, compare secondary identifiers, and document your findings. Notes are immutable — they become part of the audit trail.
# Get full alert detail
curl "https://noblesight.io/v1/alerts/44" \
-H "X-API-Key: $NOBLE_API_KEY"
# Add an investigation note
curl -X POST "https://noblesight.io/v1/alerts/44/notes" \
-H "Content-Type: application/json" \
-H "X-API-Key: $NOBLE_API_KEY" \
-d '{"note": "Checked passport against OFAC records. DOB differs by 25 years. Different person."}'
Resolve as false positive
Close the alert with a structured reason code. Examiners can aggregate these across your entire history to verify your process is systematic.
curl -X POST "https://noblesight.io/v1/alerts/44/resolve" \
-H "Content-Type: application/json" \
-H "X-API-Key: $NOBLE_API_KEY" \
-d '{
"status": "closed_false_positive",
"reason": "false_positive_dob_mismatch",
"note": "SDN DOB is 1960, customer DOB is 1985. 25-year gap. Not the same individual."
}'
Reason codes: false_positive_name_only, false_positive_dob_mismatch, false_positive_country_mismatch, false_positive_entity_type_mismatch, false_positive_other, true_match.
3. Handle a True Match
Your analyst confirmed a sanctions match. What happens next depends on what your institution did — block the transaction, reject a wire, or permit it under a General License. Each disposition carries a different OFAC reporting obligation and deadline.
Resolve as true match with disposition
Choose the disposition that matches your institution's action. blocked and rejected require filing with OFAC within 10 business days.
curl -X POST "https://noblesight.io/v1/alerts/42/resolve" \
-H "Content-Type: application/json" \
-H "X-API-Key: $NOBLE_API_KEY" \
-d '{
"status": "closed_true_match",
"reason": "true_match",
"disposition": "blocked",
"note": "Wire transfer blocked. Customer name and nationality confirmed against SDN entry 36095."
}'
Pull the OFAC report
For blocked and rejected dispositions, this endpoint assembles the evidence your compliance team needs to file with OFAC. Fill in the institution_fields (transaction description and value) before submitting.
curl "https://noblesight.io/v1/alerts/42/ofac-report" \ -H "X-API-Key: $NOBLE_API_KEY"
{
"alert_id": 42,
"report_type": "blocking",
"generated_at": "2026-03-10T14:30:00Z",
"screened_name": "Vladimir Putin",
"sdn_match": {
"uid": "36095",
"first_name": "Vladimir",
"last_name": "PUTIN",
"programs": ["RUSSIA-EO14024"],
"score": 97.5
},
"screening": {
"screened_at": "2026-03-09T10:15:00Z",
"ofac_publish_id": "1234",
"ofac_publish_date": "2026-03-08",
"trace_id": "onboarding-customer-42"
},
"resolution": {
"status": "closed_true_match",
"disposition": "blocked",
"reason": "true_match",
"resolved_by": "analyst@yourcompany.com",
"resolved_at": "2026-03-10T14:00:00Z"
},
"institution_fields": {
"transaction_description": null,
"transaction_value": null,
"instructions": "Complete transaction_description and transaction_value before filing with OFAC."
}
}
Know your deadlines
| Disposition | OFAC Obligation | Deadline |
|---|---|---|
blocked | File a blocking report | 10 business days |
rejected | File a reject report | 10 business days |
permitted_gl | Document the General License citation | Immediately |
no_action_required | Maintain internal documentation | Immediately |
4. Screen a Batch
Onboard a portfolio of customers, run a periodic re-screen, or process a file from your core banking system. Submit up to 10,000 names, poll for completion, review results. Standard tier and above.
Submit the batch
Each name can include its own secondary attributes. The response returns a batch ID for polling.
curl -X POST https://noblesight.io/v1/batch \
-H "Content-Type: application/json" \
-H "X-API-Key: $NOBLE_API_KEY" \
-d '{
"names": [
{"full_name": "Vladimir Putin", "date_of_birth": "1952-10-07", "country": "RU"},
{"full_name": "Ali Khamenei", "country": "IR"},
{"full_name": "Jane Smith", "country": "US"}
]
}'
{
"id": 1234,
"status": "pending",
"total_names": 3,
"processed_names": 0,
"match_count": 0
}
Poll for completion
Check status until it reaches completed. Per-name results include match counts, highest scores, and alert IDs.
curl "https://noblesight.io/v1/batch/status?id=1234" \ -H "X-API-Key: $NOBLE_API_KEY"
{
"id": 1234,
"status": "completed",
"total_names": 3,
"processed_names": 3,
"match_count": 2,
"items": [
{"full_name": "Vladimir Putin", "status": "screened", "match_count": 1, "highest_score": 97.5, "alert_id": 42, "alert_reason": "score_threshold",
"ownership": {"schema": 2, "overall": {"status": "designated", "regimes": ["us"]}, "determinations": {"us": {"rule": "ofac_sdn_50_percent", "status": "designated"}}}},
{"full_name": "Ali Khamenei", "status": "screened", "match_count": 1, "highest_score": 94.2, "alert_id": 43, "alert_reason": "score_threshold",
"ownership": {"schema": 2, "overall": {"status": "designated", "regimes": ["us"]}, "determinations": {"us": {"rule": "ofac_sdn_50_percent", "status": "designated"}}}},
{"full_name": "Jane Smith", "status": "screened", "match_count": 0, "highest_score": 0}
]
}
Triage the alerts
Names that generated alerts need review. Use the alert triage workflow for each one, or resolve low-confidence matches in bulk:
curl -X POST "https://noblesight.io/v1/alerts/bulk/resolve" \
-H "Content-Type: application/json" \
-H "X-API-Key: $NOBLE_API_KEY" \
-d '{
"alert_ids": [43],
"status": "closed_false_positive",
"reason": "false_positive_name_only"
}'
5. Set Up Portfolio Monitoring
Onboarding screens a customer once. Portfolio monitoring screens them continuously — whenever sanctions lists change, Noble Sight automatically re-screens your enrolled entities using reverse screening. Add-on for any paid tier.
Add a customer to your portfolio
The entity is screened automatically whenever a sanctions list it could match changes, and whenever Noble's ownership recompute newly blocks an entity its name resolves to under the 50 Percent Rule (see Ownership alerts). Adding it does not screen it against the lists as they stand, so screen a new customer with POST /v1/screen first. With the add-on, every name you screen with POST /v1/screen is enrolled too, and the response's enrollment.status says what happened: enrolled, already_enrolled, not_entitled, or failed with an enrollment_failed warning, in which case the name is not monitored until you screen it again or add it here.
curl -X POST https://noblesight.io/v1/portfolio \
-H "Content-Type: application/json" \
-H "X-API-Key: $NOBLE_API_KEY" \
-d '{
"full_name": "Dmitry Medvedev",
"date_of_birth": "1965-09-14",
"country": "RU"
}'
What happens when lists update
Noble Sight detects the delta — new, modified, or removed sanctions entries. Changed entries are screened against your entire portfolio. Matches generate alerts with source: "monitoring". You receive them the same way you receive any other alert: via webhooks or polling.
Review your portfolio
Check which entities are enrolled, their latest scores, and when they were last screened.
curl "https://noblesight.io/v1/portfolio?limit=25" \ -H "X-API-Key: $NOBLE_API_KEY"
Remove an entity when the relationship ends
Historical screening records are retained for audit. Only future re-screening stops.
curl -X DELETE "https://noblesight.io/v1/portfolio?id=4821" \ -H "X-API-Key: $NOBLE_API_KEY"
6. Manage Internal Watchlists
Government lists tell you who regulators have designated. Internal watchlists tell you who your institution has flagged — SAR subjects, exited customers, 314(a) names. Noble Sight screens against both in the same API call. Standard tier and above.
Add a SAR subject
The name is available for screening immediately. Phonetic codes are computed at insert time.
curl -X POST https://noblesight.io/v1/watchlist \
-H "Content-Type: application/json" \
-H "X-API-Key: $NOBLE_API_KEY" \
-d '{
"full_name": "John Doe",
"list_name": "SAR Subjects",
"reason": "SAR filed 2026-03-01, case #2026-0042",
"entity_type": "individual",
"country": "US"
}'
Screen as normal — watchlist matches appear automatically
Every POST /v1/screen call checks your watchlist alongside all government lists. No opt-in flag, no separate call. Matches appear with source: "Internal Watchlist".
curl -X POST https://noblesight.io/v1/screen \
-H "Content-Type: application/json" \
-H "X-API-Key: $NOBLE_API_KEY" \
-d '{"name": "Jon Doe"}'
# Response includes:
# "source": "Internal Watchlist"
# "match_sources": [{"source": "internal_watchlist", "trigram_score": 88.5, "soundex_match": true}]
# "remarks": "[SAR Subjects] SAR filed 2026-03-01, case #2026-0042"
Add a time-limited entry
Use expires_at for entries that should stop matching after a specific date — FinCEN 314(a) requests, time-limited law enforcement inquiries.
curl -X POST https://noblesight.io/v1/watchlist \
-H "Content-Type: application/json" \
-H "X-API-Key: $NOBLE_API_KEY" \
-d '{
"full_name": "Jane Roe",
"list_name": "314a Names",
"reason": "FinCEN 314(a) request dated 2026-03-15",
"expires_at": "2026-09-15T00:00:00Z"
}'
7. Set Up Webhooks
Without webhooks, your system polls for new alerts. With webhooks, Noble Sight pushes them to you the moment they are created — signed with HMAC-SHA256 so you can verify they came from us. Standard tier and above.
Register your endpoint
Provide a shared secret (minimum 32 characters) for signature verification. The secret is encrypted at rest — Noble Sight never stores it in plaintext.
curl -X POST https://noblesight.io/v1/webhooks \
-H "Content-Type: application/json" \
-H "X-API-Key: $NOBLE_API_KEY" \
-d '{
"url": "https://your-app.com/webhooks/noble",
"secret": "your-shared-secret-minimum-32-characters-long"
}'
Verify the signature in your handler
Every delivery includes X-Noble-Signature and X-Noble-Timestamp headers. The signature is HMAC-SHA256 over timestamp + "." + body. Verify the signature, then reject deliveries where the timestamp is more than 5 minutes old to prevent replay attacks.
# Go:
timestamp := r.Header.Get("X-Noble-Timestamp")
mac := hmac.New(sha256.New, []byte(secret))
mac.Write([]byte(timestamp))
mac.Write([]byte("."))
mac.Write(body)
expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
if !hmac.Equal([]byte(expected), []byte(signature)) { reject }
// Reject if timestamp is more than 5 minutes old
ts, _ := strconv.ParseInt(timestamp, 10, 64)
if time.Since(time.Unix(ts, 0)) > 5*time.Minute { reject }
# Node.js:
const timestamp = req.headers["x-noble-timestamp"];
const expected = "sha256=" + crypto.createHmac("sha256", secret)
.update(timestamp + "." + body).digest("hex");
if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) { reject }
if (Date.now()/1000 - parseInt(timestamp) > 300) { reject }
Process the event
The payload contains the alert ID, screened name, score, source, status and trace ID, and on a monitoring alert the trigger that opened it. Use the alert ID to fetch full details or route to your case management system.
{
"id": "evt_a1b2c3d4e5f6g7h8",
"type": "alert.created",
"created_at": "2026-03-23T10:05:00Z",
"data": {
"id": 42,
"screened_name": "Vladimir Putin",
"score": 97.5,
"source": "api",
"status": "new",
"trace_id": "8c0e7f0a-5d2b-4f8e-9a51-3b6c2d1e0f42"
}
}
Respond with any 2xx within 10 seconds. Failed deliveries are retried on a durable backoff schedule spanning roughly 10 hours (up to 8 passes), and retry state survives server restarts. Every attempt carries the same X-Noble-Event-ID, so you can deduplicate. A webhook failure never suppresses an alert — it still appears in GET /v1/alerts.
8. Prepare for an Examination
An OFAC examiner asks for your screening records and alert decisions for the last quarter. Every screening and every alert action is stored immutably. Here is how to pull the evidence.
Export screening records
Bulk export returns the full request, full response, list version, and trace ID for every screening in the date range.
curl "https://noblesight.io/v1/export/bulk?from=2026-01-01&to=2026-03-31" \ -H "X-API-Key: $NOBLE_API_KEY"
Export alert activity
The case activity log shows every status change, assignment, note, and resolution with full attribution and timestamps. This is the audit trail examiners expect to see.
curl "https://noblesight.io/v1/alerts/activity?from=2026-01-01&to=2026-03-31&limit=500" \ -H "X-API-Key: $NOBLE_API_KEY"
Pull a specific screening by trace ID
If the examiner asks about a specific transaction, use the trace ID you attached during screening to pull the exact record.
curl "https://noblesight.io/v1/export?trace_id=onboarding-acct-7891" \ -H "X-API-Key: $NOBLE_API_KEY"
What examiners look for
| Examiner Question | Where the Answer Lives |
|---|---|
| "What list were you screening against on March 1?" | ofac_list_version in the screening record |
| "Who reviewed this alert and what did they decide?" | Alert activity log — actor, action, reason, timestamp |
| "How quickly are alerts resolved?" | SLA deadlines + due_at vs. resolution timestamp |
| "What percentage of alerts are false positives?" | Aggregate reason codes across alert resolutions |
| "Can you produce the screening that triggered this blocking report?" | GET /v1/export?trace_id=... |
API Reference
The API contract is the code. This is api/v1/api.go — the sole source of truth for request types, response types, error codes, validation constants, and the alert state machine. Embedded at compile time.
// Package v1 defines the public REST API contract for Noble.
// This file is the source of truth for the v1 API.
// Update this file first, then implement handlers in server.go.
//
// # API versioning
//
// The wire API has two version axes. The major axis is the URL path (/v1) —
// reserved for a wholesale redesign and changed almost never. The minor axis is
// the dated Noble-Version request header (see version.go), which is how routine
// breaking changes to response shapes are managed:
//
// - Clients pin a version: `Noble-Version: 2026-06-01` (a release date, not a
// SemVer — SemVer is for the installable noble CLI/SDK artifacts, not the
// wire). Version dates are the breaking-change dates from the changelog
// (GET /v1/changelog); additive changelog entries do not mint a version.
// The resolved version is echoed in the response header and recorded in the
// audit trail.
// - No header pins to the latest version, so existing callers keep working.
// An unrecognized version is rejected: 400 invalid_version.
// - Backward-compatibility policy: additive changes (new response fields, new
// endpoints, new optional request fields) do NOT bump the version. Only a
// change that alters or removes existing response shape mints a new dated
// version; clients pinned to an older date continue to receive the old
// shape via a response transform applied at that point.
//
// Today exactly one version exists (VersionLatest), so no transform layer is
// built yet — the header, validation, and contract are in place so the first
// breaking change has a home.
package v1
import (
"encoding/json"
"errors"
"fmt"
"slices"
"strings"
"time"
)
// =============================================================================
// POST /v1/screen - Screen a name against sanctions lists
// =============================================================================
// Screening deadlines. Every POST /v1/screen either answers or fails within
// its deadline — it never holds the connection open. When the deadline passes,
// the request ends with 504 and the structured Error body (type "api_error",
// code CodeScreeningTimeout) carrying both request_id and trace_id. Set your
// client timeout a few seconds above the deadline that applies to your
// request.
//
// Name screening is refused with 503, the structured Error body (type
// "api_error", code CodeCoverageUnavailable) and a Retry-After header
// (seconds) when the server cannot serve it from a sanctions-list index it
// can vouch for: none loaded yet, the one it holds not confirmed current
// against the database within the staleness bound, or — for as_of and
// POST /v1/export/replay — the index at the requested list versions still
// being prepared, or every slot for preparing one in use. This applies to
// POST /v1/screen with a name, POST /v1/batch (refused before any job is
// created) and POST /v1/export/replay. No partial result is returned and no
// other method is used to screen; retry after Retry-After. Every other
// endpoint — alerts, exports, lists, portfolio, webhooks, keys — keeps
// serving from the same server, and GET /status reports
// components.screening as "degraded" or "outage" (see StatusComponents).
//
// A screening that fails after its input was accepted — a timeout or any
// other server-side error — is still written to the audit trail as a failed
// screening (ExportRecord.Outcome == ScreeningOutcomeFailed), retrievable
// with GET /v1/export?request_id= or ?trace_id= using the IDs from the error
// body. A failed screening is not a result: it carries no matches and you
// should screen the name again.
const (
// ScreenDeadline applies to a screening without deep_screen or
// deep_summary.
ScreenDeadline = 10 * time.Second
// ScreenDeadlineDeep applies when deep_screen or deep_summary is
// requested. Both call a language model; if that call fails or runs too
// long, the screening still answers, with the fallback signal
// (deep_screen_fallback_reason or summary.fallback_reason) set to
// "llm_failure".
ScreenDeadlineDeep = 25 * time.Second
)
// Name input. One rule applies to every name Noble accepts — ScreenRequest.Name,
// BatchNameInput.FullName, WatchlistAddRequest.FullName, portfolio names and
// the screen MCP tool — and to the variations deep_screen generates:
//
// - A name is at most MaxNameLength characters, counted as Unicode code
// points, not bytes, so a name in Cyrillic or Arabic gets the same room
// as one in Latin. Surrounding whitespace is trimmed first. A longer
// name is refused with 400 name_too_long on every endpoint that takes
// a name.
// - The request body must be UTF-8. A field holding bytes that are not
// UTF-8 is refused with 400 invalid_parameter, param naming the field
// ("name" on /v1/screen), message "<field> is not valid UTF-8" — Noble
// never screens something other than what you sent. On POST /v1/batch
// such an item is reported as its own error and the rest are screened
// (BatchItemResponse.ErrorCode).
// - U+FFFD REPLACEMENT CHARACTER is valid UTF-8 and is screened: it is
// what a core system writes where it has already lost a letter. The
// rest of the name is compared as usual, and the response carries a
// WarningReplacementCharacter warning, because the lost letter could not
// be compared.
//
// A name screening can also be refused with 503 coverage_unavailable and a
// Retry-After header when the server cannot screen it from a sanctions-list
// index it can vouch for — see "Screening deadlines" above. Retry after the
// interval; no partial result is ever returned.
const (
// MaxNameLength is the maximum length of a name, in characters (Unicode
// code points), not bytes.
MaxNameLength = 500
// MaxDeepScreenVariations is the most name variations one deep_screen
// request screens. Variations beyond it, repeats, and variations that
// break the name rule above are dropped before screening, so
// DeepScreenCoverage.VariationsGenerated never exceeds it.
MaxDeepScreenVariations = 24
)
// ScreenRequest is the input for screening a name against sanctions lists.
type ScreenRequest struct {
// Name to screen against sanctions lists. Required unless at least one
// identifier (IDNumber or IDs) is supplied — an identifier-only request
// (e.g. a digital-currency wallet address) is screened by exact ID match
// with no name. A name that is itself an identifier (a pasted wallet
// address) is additionally exact-matched, so it is caught even when not
// labelled as an id. Whitespace is trimmed; a whitespace-only name is
// rejected. The name is screened exactly as written; a name that carries
// a parenthetical — "NOOR ENERGY (MALAYSIA) LTD.", or an annotation of
// your own — is additionally screened with the parenthetical removed,
// and each match reports whichever comparison scored higher. When
// neither a name nor an identifier is present the request is rejected
// with code query_required.
//
// At most MaxNameLength (500) characters, counted as Unicode code
// points. Bytes that are not UTF-8 are refused with 400
// invalid_parameter, param "name"; a U+FFFD replacement character is
// screened and warned about (WarningReplacementCharacter). See "Name
// input" above. When the server's sanctions-list index is unavailable
// the screening is refused with 503 coverage_unavailable and a
// Retry-After header; retry after it.
Name string `json:"name"`
// Maximum number of matches to return (default: 10, max: 100)
Limit *int `json:"limit,omitempty"`
// DeepScreen enables real-time AI expansion of the search input.
// When true, the server calls Gemini to generate spelling/cultural
// variations of the input name and screens each one. Adds ~1-3s latency.
DeepScreen bool `json:"deep_screen,omitempty"`
// EntityType of the subject being screened: "individual", "entity", "vessel", "aircraft".
// When provided, matches against a different entity type are flagged with a dismissal reason.
EntityType string `json:"entity_type,omitempty"`
// DateOfBirth of the person being screened, in YYYY-MM-DD format.
// When provided, matches are penalized if the OFAC entity's DOB
// differs significantly.
DateOfBirth string `json:"date_of_birth,omitempty"`
// Country of residence (ISO 3166-1 alpha-2, e.g., "US", "RU", "CN").
// Serves two independent purposes: matches are penalized if the entity's
// nationality does not match, and a country under a comprehensive OFAC
// embargo raises JurisdictionRisk on the response.
//
// To declare a sub-national nexus (an embargoed region rather than a
// country), use Location — a region code supplied here is treated as a
// country for scoring purposes and will penalize matches.
Country string `json:"country,omitempty"`
// Address of the subject being screened (street, city, postal code).
// Recorded in the screening's audit record for manual comparison against
// the sanctions entity's address data.
//
// It is scanned for one thing only: a word that names an embargoed
// region of Ukraine — Crimea, Sevastopol, or a town on the Crimean
// peninsula, in Latin or Cyrillic — raises JurisdictionRisk for that
// region whatever Country says, and JurisdictionNexus reports the field
// ("address") and the word. Whole words only: "Krymskaya ulitsa" in
// Moscow does not fire. Nothing else is inferred from the address: no
// country, no other region, no nexus. To declare geography in a form
// the engine acts on in full, use Location.
Address string `json:"address,omitempty"`
// Location declares where the subject is, in structured form. Its purpose
// is nexus detection: it is the only way to express a sub-national
// embargoed region (Crimea, Sevastopol, and the so-called DNR and LNR
// covered regions), which have no ISO 3166-1 country code of their own.
//
// Unlike Country, Location never affects match scores — declaring a nexus
// cannot depress a score. It is evaluated for JurisdictionRisk only.
//
// Nexus detection reads Location.Region first, then Location.Country,
// then the legacy Country field, and stops at the first that RESOLVES —
// not the first that is present. A region Noble has no determination
// about defers to the country, so {country: "IR", region: "IR-07"} still
// raises the Iran embargo; a region it does have one about wins, so
// {country: "UA", region: "UA-40"} raises the Sevastopol embargo rather
// than being flattened to unembargoed Ukraine. Supplying more precise
// geography never removes a signal.
//
// When no declared field carries an embargo, Location.Region,
// Location.City and Address are scanned for a word naming Crimea,
// Sevastopol or a Crimean town (see Address). A hit outranks an
// unembargoed country — {country: "RU", city: "Yalta"} raises the Crimea
// embargo — and the nexus names the field and the word it came from.
//
// An undeclared nexus is not detected: a name alone is never parsed for
// region tokens.
Location *Location `json:"location,omitempty"`
// IDNumber is any identifier published on a sanctions list: a government ID
// (passport, tax ID, cedula, national ID), a financial routing code
// (SWIFT/BIC), a corporate registration number, a digital currency (crypto
// wallet) address, or a vessel IMO number. When provided, actively matched
// against the ID tables of every list in scope (OFAC, UK, EU, France,
// Belgium, UN, Canada, Australia) using exact match after normalization —
// both the input and the stored value are uppercased with spaces, dashes,
// dots, and slashes stripped, so formatting differences never cause a miss.
// A vessel IMO number matches whether written "IMO 9102198" (OFAC's
// published form) or as the bare number "9102198".
IDNumber string `json:"id_number,omitempty"`
// IDType filters ID matching to a single sanctions-list ID category.
// Optional; when omitted, the IDNumber is searched against every type.
//
// Matching is case-insensitive prefix against the category strings the
// publishers record — "Tax ID" matches OFAC's "Tax ID No.", "National ID"
// matches "National ID No.". Industry tokens whose publisher label
// differs are also accepted: "IMO" reaches OFAC's "Vessel Registration
// Identification" rows. A type that matches no stored category on any
// screened list is rejected with a structured 400 (code
// "invalid_parameter") — a typed request never silently screens nothing.
//
// Common values (use the string as published by the source list):
//
// Government IDs:
// "Passport", "National ID", "Tax ID", "Cedula No.", "Driver's License",
// "Birth Certificate Number"
//
// Financial routing:
// "SWIFT/BIC" — bank/financial institution identifier
//
// Corporate:
// "Business Registration Number", "Certificate of Incorporation Number"
//
// Digital currency (OFAC SDN):
// "Digital Currency Address - XBT" (Bitcoin)
// "Digital Currency Address - ETH" (Ethereum)
// "Digital Currency Address - USDT" (Tether)
// "Digital Currency Address - USDC" (USD Coin)
// "Digital Currency Address - XMR" (Monero)
// "Digital Currency Address - SOL" (Solana)
// "Digital Currency Address - TRX" (Tron)
// "Digital Currency Address - XRP" (Ripple)
// "Digital Currency Address - LTC" (Litecoin)
// "Digital Currency Address - BCH" (Bitcoin Cash)
// plus ARB, BSC, BSV, BTG, DASH, ETC, XVG, ZEC.
//
// The full list of in-use idType strings is the union of every <idType>
// element across the publishers' source files (e.g., OFAC's sdn.xml and
// consolidated.xml).
IDType string `json:"id_type,omitempty"`
// IDs is an additional set of identifiers to screen alongside IDNumber.
// A single person or entity often carries several — passport plus tax ID
// plus a crypto wallet plus a SWIFT/BIC. Submitting them in one request
// avoids one round-trip per identifier and produces a single merged
// response with one audit row.
//
// Each entry is screened independently. The result set is the union of
// every ID's hits, deduplicated by sanctions-list UID; on hit, the
// corresponding ScreenMatch.MatchedVia field names which submitted
// IDs triggered the match.
//
// IDNumber/IDType (singular) and IDs (plural) compose — if both are
// present, the singular is screened in addition to every entry in IDs.
// Capped at MaxIDsPerRequest entries; entries with an empty Number, or a
// Number or Type longer than MaxIDValueLength, are rejected with code
// "invalid_parameter".
IDs []IDInput `json:"ids,omitempty"`
// Lists restricts screening to the specified sanctions lists.
// Valid values: "ofac", "uk", "eu", "france", "belgium", "netherlands", "un", "canada", "australia".
// When omitted or empty, all lists are screened (default behavior).
// Lists also selects the ownership regimes the response determines
// (OwnershipRegimesForLists): lists:["ofac"] returns the OFAC 50
// Percent Rule determination alone and raises an ownership alert only
// for it. Without lists, the response determines the regimes the
// tenant declared (GET /v1/account features.ownership_regimes, #728;
// every regime by default), and ownership.regimes_from says which.
Lists []string `json:"lists,omitempty"`
// AllowDegradedCoverage opts into receiving a screening whose coverage
// is degraded — a requested list whose ingestion freshness verdict is
// "stale", or a response that could only screen a subset of the lists
// it should have (#230). The default is fail-closed: such a screening
// is refused with 503 coverage_degraded, because an all-clear computed
// over missing or stale coverage is indistinguishable from a real one.
// With this flag true the screening proceeds, the response's Coverage
// object states exactly what was degraded and why, and the flag is
// stored on the audit record with the rest of the request — the
// institution's knowing election, on the record. Live screenings only:
// an as_of screening reads history, is not gated on today's ingestion
// freshness, and may screen the subset of lists holding history at the
// instant without this flag — the as_of_before_history warning and the
// Coverage object both report that reduced set.
AllowDegradedCoverage bool `json:"allow_degraded_coverage,omitempty"`
// Include opts into response fields that are excluded by default.
// Reserved for future per-field opt-ins. Unknown values are ignored —
// additive evolution without breaking clients. The value "summary" is
// accepted for backwards compatibility but is now a no-op: ScreenSummary
// is populated by default on every response.
Include []string `json:"include,omitempty"`
// DeepSummary, when true, generates the summary text with an LLM (Gemini)
// instead of the deterministic template. The verdict bucket itself
// remains deterministic — the LLM only writes prose. Requires Standard
// tier or higher. Adds ~1s latency.
DeepSummary bool `json:"deep_summary,omitempty"`
// AsOf runs the screening against the sanctions lists as they stood at a
// historical instant — point-in-time screening for audit and examination
// support ("what would this name have returned on date X?"). Accepts an
// RFC 3339 timestamp ("2026-07-01T15:04:05Z") for an exact instant, or a
// bare date ("2026-07-01"), which means end of that day UTC — "the list
// as it stood on July 1" includes July 1's updates. Today's date is
// accepted and resolves to the current instant. Anything later is a 400
// invalid_parameter: as_of must not be in the future.
//
// An as-of screening is an inquiry into historical list state, not a
// present-day compliance decision: it is persisted to the audit trail
// (with as_of recorded in the stored request) but never creates an alert,
// never enrolls the name in portfolio monitoring, and never dispatches a
// webhook. The response's ListVersions reports the snapshots that were
// active at the requested instant, and ScreenedAsOf echoes the resolved
// instant.
//
// History floor: Noble's history for a list begins the instant Noble
// first imported it; GET /v1/lists reports it per list as history_from.
// An as_of earlier than the floor of EVERY requested list is refused
// with 400 invalid_parameter (param as_of) whose message names the
// earliest instant that can be screened; a screening against no list is
// never answered as a clean one. When some requested lists have history
// at the instant and others do not, the others are omitted from
// ListsScreened/ListVersions and named in an as_of_before_history
// warning (Warning.Lists), so a partial lookback is visibly partial.
// For the embargo in force on a date before the floor, use
// GET /v1/jurisdictions/{code}?as_of=; for decisions Noble itself
// recorded, POST /v1/export/replay.
//
// JurisdictionRisk under as_of reports the embargo that was legally in
// force at the requested instant, not the one Noble's table happened to
// name then: an as-of screen of an Iranian counterparty in 2020 returns
// the 31 CFR Part 560 advisory, because Iran has been comprehensively
// embargoed since 1995 whether or not this API had a field for it. The
// complementary question — what a stored screening was actually told —
// is answered by POST /v1/export/replay, which reproduces the advisory as
// issued.
//
// Known fidelity boundary: OFAC's secondary tables (aliases, addresses,
// identifiers, DOB/POB) are maintained at current state only. Under
// as_of an OFAC alias first published after the instant is not screened
// and a native-script name removed since still is, but an alias's text,
// identifier matching and match detail reflect today's child records.
// The response says so with an ofac_child_detail_current_state warning
// whenever OFAC was screened. OFAC primary names and all other lists'
// records (including their aliases and identifiers) are fully historical.
// The authoritative historical record of OFAC child data is the changelog
// (GET /v1/changelog) and the archived list snapshots.
AsOf string `json:"as_of,omitempty"`
}
// IDInput is a single identifier in ScreenRequest.IDs. Type is optional and
// follows the same string-set documented on ScreenRequest.IDType (Passport,
// SWIFT/BIC, "Digital Currency Address - XBT", etc.). When Type is empty,
// the Number is matched against every ID type the publisher recorded.
type IDInput struct {
// Number is the identifier to screen for (e.g., passport number, SWIFT/BIC,
// crypto wallet address). Required. Same normalization as IDNumber:
// uppercased with spaces, dashes, dots, and slashes stripped before
// comparison.
Number string `json:"number"`
// Type restricts matching to a single sanctions-list ID category.
// Optional; when omitted, Number is searched against every type.
// Same semantics as ScreenRequest.IDType: case-insensitive prefix match
// against publisher category strings, industry tokens like "IMO"
// accepted, and an unmatchable type is a structured 400 — never a
// silent zero-match response.
Type string `json:"type,omitempty"`
}
// ScreenResponse is the response from a screening request (200).
//
// Instead of a ScreenResponse, POST /v1/screen can answer 400 for input the
// "Name input" rule refuses, 504 screening_timeout past its deadline, and
// 503 coverage_unavailable with a Retry-After header (seconds) when the
// server has no sanctions-list index it can vouch for — none loaded yet, or
// the one it holds not confirmed current — or is preparing the index an
// as_of screening needs. A 503 returns no partial result and is safe to
// retry after the Retry-After interval.
type ScreenResponse struct {
// TraceID is the audit key this screening is persisted under. It echoes the
// caller's X-Trace-ID, or a server-generated value when none was supplied —
// the screening is always retrievable. Feed it straight into
// GET /v1/export?trace_id= to pull the full audit record. Also returned in
// the X-Trace-ID response header.
TraceID string `json:"trace_id"`
// RequestID is the per-call HTTP request ID for this screening — the same
// value carried in the X-Request-Id response header and in the request_id
// field of error bodies. Distinct from TraceID: a trace can span many
// calls, each with its own RequestID. Persisted alongside TraceID so an
// operator can pivot between the two; see GET /v1/export?request_id=.
RequestID string `json:"request_id,omitempty"`
// Unique screening record ID for audit cross-referencing
ScreeningID int64 `json:"screening_id,omitempty"`
// AlertID is the alert created for this screening. Zero/omitted means no
// alert was generated. When a recent duplicate alert already exists, its
// ID is returned instead of creating a new one (idempotent behavior): a
// duplicate is the same subject screened again by the same account within
// five minutes, where the subject is the name, or, for an identifier-only
// screening, the identifiers as sent ("IMO 9333591"). Two different
// identifiers are two subjects and two alerts (#504).
// Later changes to alert_threshold never affect alerts that already exist:
// GET /v1/alerts returns every alert as created (#170).
//
// AlertReason names which rule raised it — read that rather than inferring
// the rule from the score.
AlertID int64 `json:"alert_id,omitempty"`
// AlertReason names the rule that raised AlertID (or OwnershipAlertID when
// only that fired). Present whenever an alert was created, absent
// otherwise. The complete rule set, and it is a set rather than a single
// comparison:
//
// "score_threshold" the highest match score reached the tenant's
// alert_threshold (GET /v1/account,
// features.alert_threshold). The ordinary case.
// "name_near_miss" the top match sits a character or two from a
// listed name while scoring UNDER the threshold. A
// one-character difference from a published sanctions
// name is a different object from an unrelated name
// that happens to score similarly, and under strict
// liability the expensive direction is the miss. The
// match carries a name_near_miss dismissal signal
// naming the two tokens and the distance between
// them.
// "ownership_control" a derivative-ownership determination came back
// blocked under a selected regime. Categorical
// rather than a match score, so it is not gated on
// the threshold at all.
// "ownership_review" a derivative-ownership determination came back
// review under a selected regime (#706): an
// ownership or control relationship to a designated
// party with no disclosed stake, or a stake that
// fell after a block. Not a block; a relationship
// for a human to assess. The alert scores 60, below
// the four-eyes line, on the 72-hour SLA, and is
// counted apart from blocking alerts by this reason
// and by change_type ownership_review.
//
// Read this to tune alert volume per trigger — a tenant that wants
// near-miss alerts routed to a different queue, or counted separately, can
// do that without weakening either rule. GET /v1/alerts does not filter
// on it.
AlertReason string `json:"alert_reason,omitempty"`
// OwnershipAlertID is the alert created because this screening's
// ownership determination came back "blocked" or "review" (see
// Ownership; AlertReason says which). Distinct from AlertID: a
// name-match alert and an ownership alert are separate compliance
// events, and either can fire without the other. Ownership alerts are
// not gated on the tenant's score threshold — a derivative-ownership
// determination is categorical, not a fuzzy-match score. Dedup is
// idempotent like AlertID: one open alert per determined entity, change
// type (ownership_blocked, ownership_review) and regime set (#832). An
// open alert whose evidence was computed under other regimes, such as
// the pre-regime shape retired on 2026-11-05, is not reused: a new
// alert is raised with the current determination, and both alerts'
// timelines (Alert.Activity) note the supersession; the older stays
// open for the analyst to close.
OwnershipAlertID int64 `json:"ownership_alert_id,omitempty"`
// Enrollment reports what this screening did to the caller's portfolio:
// a key with the portfolio add-on enrolls every name it screens for
// continuous monitoring, with the date_of_birth and country the request
// carried, so the monitored customer is the one screened. Present on
// every present-day screening; absent on an as-of screening, which never
// enrolls (see ScreenRequest.AsOf). A screening with no name enrolls
// nothing and reports "no_name": monitoring screens names, so an
// identifier is not monitored. A failed enrollment is status "failed"
// with an enrollment_failed warning, and the name is not monitored until
// it is enrolled: screen it again or POST /v1/portfolio. Recorded with
// the screening, so an export shows what the caller saw.
Enrollment *Enrollment `json:"enrollment,omitempty"`
// DeepScreenFallbackReason is populated only when the caller requested
// deep_screen and the AI variation expansion could not run in full — the
// response then falls short of the enhanced recall that was requested. A
// paid feature never degrades silently (same honesty contract as
// ScreenSummary.FallbackReason); value is one of the FallbackReason*
// constants: llm_failure means the expansion did not run at all and the
// results are standard recall; variation_screening_failure means the
// expansion ran but covered only some generated variations — see
// DeepScreenCoverage for the exact counts. A deployment with deep_screen
// entirely unconfigured rejects the request with 503
// deep_screen_unavailable instead — see CodeDeepScreenUnavailable.
DeepScreenFallbackReason string `json:"deep_screen_fallback_reason,omitempty"`
// DeepScreenCoverage reports how much of the requested AI variation
// expansion actually ran. Present whenever deep_screen was requested and
// the variation generation succeeded (including when zero variations were
// generated); nil when deep_screen was not requested or the generation
// call itself failed (DeepScreenFallbackReason: llm_failure).
//
// Invariant: on a deep_screen=true response, either DeepScreenCoverage
// shows VariationsScreened == VariationsGenerated or
// DeepScreenFallbackReason is non-empty. Callers can rely on this to
// detect partial enhanced-recall delivery without parsing logs.
DeepScreenCoverage *DeepScreenCoverage `json:"deep_screen_coverage,omitempty"`
// Warnings states anything about this screening's coverage that the
// matches alone cannot show: an input Noble accepted but could not screen
// in full. Absent when there is nothing to disclose. Read it before
// treating an empty or low-scoring match set as clear. Each entry's Code
// is one of the Warning* constants. The set may grow; treat an unknown
// code as a coverage caveat, never as clear.
Warnings []Warning `json:"warnings,omitempty"`
// The name that was screened
ScreenedName string `json:"screened_name"`
// When this screening was performed (RFC 3339)
ScreenedAt string `json:"screened_at"`
// ScreenedAsOf is the historical instant this screening was evaluated
// against (RFC 3339), present only when the request carried as_of. The
// matches and list_versions then reflect the sanctions lists as they
// stood at this instant, not at ScreenedAt.
ScreenedAsOf string `json:"screened_as_of,omitempty"`
// EngineVersion names the matching rules that produced this screening
// (#364). It changes only with a rules change — what the engine finds or
// how it scores — and every such change ships with a changelog entry and
// a shadow delta report. Two screenings of the same name against the
// same list_versions and the same EngineVersion produce the same result;
// replay compares a record's EngineVersion to the current one and
// reports a mismatch as the engine_version_changed caveat rather than as
// data drift.
EngineVersion string `json:"engine_version"`
// MatchEngine names the engine that scored the candidates. "index": the
// in-memory engine every screening runs on — names compared in memory
// against a snapshot of the lists at the version vector in
// list_versions; portfolio monitoring records say "index" from engine
// 2.5.0, when monitoring began deciding each pair with that engine.
// "scorer": portfolio monitoring records from engine 1.3.0 until 2.5.0 —
// candidates retrieved from the database, every decision and score made
// by a second scorer on folded names. Screenings scored before
// engine 2.0.0 say "database" (candidates scored in SQL) and keep that
// value; replaying one carries the engine_version_changed caveat.
MatchEngine string `json:"match_engine"`
// Number of matches returned
MatchCount int `json:"match_count"`
// Mean score across all matches in this screening (0-100).
// Useful for portfolio risk assessment. Zero when no matches.
AverageScore float64 `json:"average_score"`
// ListsScreened reports which sanctions lists were included in this screening.
// Always populated, even when the caller did not specify a lists filter.
//
// It is exact, never a best effort: a list is listed here only if its
// publisher snapshot was confirmed (see ListVersions). If any list's
// snapshot cannot be confirmed, the request fails with 503
// coverage_unavailable rather than returning a shortened list — an
// under-reported screen must never look like a completed one.
ListsScreened []string `json:"lists_screened"`
// Coverage is the explicit, machine-readable coverage assertion for
// this screening (#230): always present, on healthy and degraded
// responses alike, so a consumer never infers coverage from absence.
// Degraded is true when a screened list's freshness verdict is "stale"
// or Screened is a proper subset of Expected — and a degraded 200 can
// only exist because the request carried allow_degraded_coverage; the
// default is a 503 coverage_degraded refusal.
Coverage *ScreenCoverage `json:"coverage"`
// Matched sanctions entries, ranked by score
Matches []ScreenMatch `json:"matches"`
// ListVersions reports the publisher snapshot active at screening time
// for every list named in ListsScreened — one entry per list with
// imported data. Examiners use this to pin a screening decision to the
// exact list snapshots that produced it. For a name screening it is read
// inside the scan's own database transaction, under the same snapshot
// the candidates were read from, so it can never cite a list version the
// scan did not see; replay (POST /v1/export/replay) is keyed on these
// publish ids.
ListVersions []ListVersion `json:"list_versions,omitempty"`
// OFACListVersion is the OFAC entry from ListVersions, retained as a
// convenience field.
//
// Deprecated: use ListVersions for full multi-list coverage. New
// integrations should read ListVersions and filter for List == "ofac".
// Removal scheduled after the 90-day deprecation window.
OFACListVersion *OFACListInfo `json:"ofac_list_version,omitempty"`
// Summary is an executive synthesis of the screening result: verdict
// bucket, top match, distinct lists, strong-match count, and a one-line
// prose synthesis. Populated by default on every response — the
// deterministic path is pure-function with no I/O cost. Callers that
// want LLM-rewritten prose pass DeepSummary=true (paid tier).
Summary *ScreenSummary `json:"summary,omitempty"`
// JurisdictionRisk is present when the geography declared on the request
// places the subject in a jurisdiction under a comprehensive OFAC embargo
// — Cuba, Iran, North Korea, or an embargoed region of Ukraine (Crimea,
// Sevastopol, and the so-called DNR/LNR covered regions). The declaration
// is read from Location.Region, then Location.Country, then the legacy
// Country field, stopping at the first that resolves to a jurisdiction on
// record; a sub-national region can only be declared through Location.
//
// This is nexus detection, not list matching: it fires even when matches
// is empty, because the request itself disclosed the embargo nexus.
// Absent when the declared geography carries no comprehensive embargo and
// when no geography was supplied. The jurisdiction set tracks current
// OFAC programs: Syria was removed when its comprehensive program was
// revoked effective July 1, 2025 (E.O. 14312). Under AsOf it reports the
// embargo in force at that instant; see ScreenRequest.AsOf.
JurisdictionRisk *JurisdictionRisk `json:"jurisdiction_risk,omitempty"`
// JurisdictionNexus reports which geographic declaration was evaluated
// for embargo nexus and what the embargo record said about it. Present
// whenever the request declared any geography, including when
// JurisdictionRisk is absent — that is the case it exists for.
JurisdictionNexus *JurisdictionNexus `json:"jurisdiction_nexus,omitempty"`
// Ownership is the OFAC 50 Percent Rule determination for the screened
// name: whether the ownership graph shows it to be 50%-or-more owned by
// sanctioned parties, with the full evidence chains (see OwnershipMatch).
// This is how a company that appears on no sanctions list — but is owned
// by listed parties — surfaces in a screening. Present whenever a name
// was screened live on a deployment with ownership screening enabled;
// absent on identifier-only requests and as_of screenings. Advisory
// plus alerting: a "blocked" determination raises an alert (see
// OwnershipAlertID) but never alters match scores or the summary verdict.
Ownership *OwnershipMatch `json:"ownership,omitempty"`
// Response metadata including legal disclaimer
Meta ResponseMeta `json:"meta"`
}
// Warning is a coverage caveat on a screening: something about the input
// that Noble accepted but did not screen in full. A warning never changes a
// match or a score; it says what the matches could not have found.
type Warning struct {
// Code is the machine-readable kind of caveat; one of the Warning*
// constants.
Code string `json:"code"`
// Message is a human-readable statement of what was not screened and
// what to do about it.
Message string `json:"message"`
// Script is the Unicode script name ("Cyrillic", "Arabic", "Han",
// "Hangul", ...) the warning is about. Present on script warnings.
Script string `json:"script,omitempty"`
// Lists names the sanctions lists the warning is about, by the short
// identifiers used in ScreenRequest.Lists. Present on
// as_of_before_history.
Lists []string `json:"lists,omitempty"`
}
// Warning codes.
const (
// WarningScriptNotScreened means part of the name is written in Script.
// Noble compared that part only against the names the lists publish in
// Script (OFAC, the UN and the UK publish native-script names for some
// parties) and does not yet romanize it, so a party listed only in Latin
// script was not compared against it. An empty or low-scoring result is
// therefore not a clear result for such a party. Screen the romanized
// form of the name as well.
WarningScriptNotScreened = "script_not_screened"
// WarningOFACChildDetailCurrent appears on an as_of screening that
// screened OFAC. OFAC's primary names are read exactly as they stood at
// as_of, an alias first published after it is not screened, and a name
// in a party's own script removed since is still screened. An alias's
// text, and the addresses, identifiers and dates of birth in match
// detail, are read as they stand today: OFAC publishes no history for
// them. The same boundary is the ofac_child_detail_current_state replay
// caveat.
WarningOFACChildDetailCurrent = "ofac_child_detail_current_state"
// WarningAsOfBeforeHistory appears on an as_of screening when the
// history of one or more requested lists begins after the instant, or a
// requested list has no imported data: those lists were not screened,
// are absent from lists_screened, and are named in Warning.Lists with
// each list's history_from in the message. An as_of that predates every
// requested list is refused outright with 400 invalid_parameter (see
// ScreenRequest.AsOf), never answered as a clean screening.
WarningAsOfBeforeHistory = "as_of_before_history"
// WarningReplacementCharacter means the name contains U+FFFD, the
// replacement character a system writes where it could not represent a
// letter. Noble screened the rest of the name; the lost letter could not
// be compared, so a match may score lower than the intact name would.
// Screen the name as originally spelled when you have it.
WarningReplacementCharacter = "name_replacement_character"
// WarningEnrollmentFailed means the screening completed but the name
// could not be enrolled in the caller's portfolio, so list changes will
// not be screened against it (see ScreenResponse.Enrollment). Screen the
// name again or add it with POST /v1/portfolio.
WarningEnrollmentFailed = "enrollment_failed"
// WarningOwnershipUnavailable means the ownership control did not run:
// the derivative-ownership determination could not be read, so
// ownership.overall.status is "unavailable" and every selected regime's
// determination says the same, and coverage carries an
// ownership_unavailable issue. The name matches are complete; the 50
// Percent Rule question is unanswered. Screen the name again (#708).
WarningOwnershipUnavailable = "ownership_unavailable"
// WarningListSourceUnavailable means a list in this screening was
// screened against its last imported snapshot because its publisher is
// down (#749): Noble's watcher is polling and the publisher answers
// with its own server error. The coverage object carries a
// list_source_unavailable issue per affected list, with the publisher's
// error, when it went down and the publish_id screened. Nobody can hold
// a newer copy of the list than the publisher serves, so the result is
// complete against the latest published version Noble could obtain;
// once the outage passes the list's escalation threshold (see
// SanctionsListVersion.EscalateAfterS) the message says the snapshot may
// be missing designations.
WarningListSourceUnavailable = "list_source_unavailable"
)
// Enrollment is what a screening did to the caller's portfolio (#484).
type Enrollment struct {
// Status is one of the Enrollment* constants.
Status string `json:"status"`
// PortfolioEntityID is the portfolio entity monitoring the name: the id
// GET /v1/portfolio returns, and the column monitoring alerts record
// (#602 adds it to alerts under the same name). Named for the resource
// it points to: "entity" alone means a non-individual party in this API
// (EntityType). Present when Status is enrolled or already_enrolled.
PortfolioEntityID int64 `json:"portfolio_entity_id,omitempty"`
}
// Enrollment statuses.
const (
// EnrollmentEnrolled means this screening added the name to the
// portfolio; it is now monitored.
EnrollmentEnrolled = "enrolled"
// EnrollmentAlreadyEnrolled means the name was already in the portfolio
// and stays monitored; its scores and last-screened time were updated.
EnrollmentAlreadyEnrolled = "already_enrolled"
// EnrollmentNotEntitled means the key does not hold the portfolio add-on,
// so screenings do not enroll names.
EnrollmentNotEntitled = "not_entitled"
// EnrollmentNoName means the screening had no name, so nothing was
// enrolled. Monitoring screens names: an identifier screened alone is
// not monitored, and no portfolio entity is created for it.
EnrollmentNoName = "no_name"
// EnrollmentFailed means enrollment was attempted and failed; the name
// is not monitored. The response also carries an enrollment_failed
// warning.
EnrollmentFailed = "failed"
)
// ScreenCoverage is the coverage assertion on every screening response
// (#230). A sanctions screening must state the coverage it was computed
// over: which lists were asked for, which the deployment should have
// screened, which it actually screened, and every issue that separates
// them. Three conditions make Degraded true. Two concern the lists and
// refuse the screening with 503 coverage_degraded unless
// allow_degraded_coverage is set: a screened list whose ingestion
// freshness verdict is "stale" (the same verdict GET /v1/lists and /status
// report), and Screened being a proper subset of Expected. The third
// concerns the ownership control (#708): when its determination could not
// be read, the response is returned with an ownership_unavailable issue
// (List "ownership") and Degraded true, with no election, because the name
// matches are complete and only the ownership question is unanswered.
type ScreenCoverage struct {
// Degraded is the one-bit verdict: false means every expected list was
// screened at a fresh ingestion verdict and Issues is empty.
Degraded bool `json:"degraded"`
// Requested is the lists the request named, after validation and
// de-duplication; empty when the request omitted lists and took the
// default of every list.
Requested []string `json:"requested,omitempty"`
// Expected is the full set this screening should have covered: the
// requested lists, or every list this deployment serves when the
// request named none.
Expected []string `json:"expected"`
// Screened mirrors ListsScreened: the lists whose publisher snapshot
// was confirmed inside this screening.
Screened []string `json:"screened"`
// Issues names each problem, one entry per affected list. Empty on a
// healthy response.
Issues []ScreenCoverageIssue `json:"issues"`
}
// ScreenCoverageIssue is one list's coverage problem.
type ScreenCoverageIssue struct {
// List is the affected list identifier.
List string `json:"list"`
// Code is "list_stale" (ingestion freshness verdict is stale — the
// watcher has not successfully polled the publisher within the list's
// staleness bound), "list_source_unavailable" (the list's publisher is
// down and the list was screened at its last imported snapshot, see
// WarningListSourceUnavailable), "list_missing" (the list was expected
// but absent from this screening — the lists_screened-subset case) or
// "ownership_unavailable" (List is "ownership": the derivative-ownership
// control did not run for this screening, see
// WarningOwnershipUnavailable).
Code string `json:"code"`
// LastChecked is when the list's watcher last successfully polled the
// publisher (RFC 3339, UTC); present on list_stale and
// list_source_unavailable.
LastChecked string `json:"last_checked,omitempty"`
// SourceError is the publisher's answer to Noble's last poll, e.g.
// "http_500"; present on list_source_unavailable.
SourceError string `json:"source_error,omitempty"`
// SourceUnavailableSince is when Noble first saw the publisher fail
// after its last successful poll (RFC 3339, UTC); present on
// list_source_unavailable.
SourceUnavailableSince string `json:"source_unavailable_since,omitempty"`
// PublishID is the snapshot the list was screened at — the publish_id
// of its list_versions entry; present on list_source_unavailable.
PublishID int `json:"publish_id,omitempty"`
// Escalated is true when the publisher outage has lasted longer than
// the list's escalation threshold (SanctionsListVersion.EscalateAfterS),
// or the publisher's own feed has announced a newer version that could
// not be downloaded: the snapshot may be, or is, missing designations
// the publisher has made since. Detail says which.
Escalated bool `json:"escalated,omitempty"`
// Detail is one sentence for a human.
Detail string `json:"detail"`
}
// Coverage issue codes (ScreenCoverageIssue.Code).
const (
CoverageIssueListStale = "list_stale"
CoverageIssueListMissing = "list_missing"
// CoverageIssueListSourceUnavailable marks a list screened at its last
// imported snapshot while its publisher is down (#749).
CoverageIssueListSourceUnavailable = "list_source_unavailable"
// CoverageIssueOwnershipUnavailable marks the ownership control as not
// evaluated; its issue's List is CoverageListOwnership.
CoverageIssueOwnershipUnavailable = "ownership_unavailable"
// CoverageListOwnership is the List of an ownership coverage issue: the
// control, not a sanctions list.
CoverageListOwnership = "ownership"
)
// DeepScreenCoverage quantifies a deep_screen expansion: how many AI name
// variations were generated and how many of them were actually screened
// against the sanctions lists. VariationsScreened < VariationsGenerated means
// the enhanced recall is incomplete — the response also carries
// deep_screen_fallback_reason: variation_screening_failure so the shortfall
// is never silent. Equal counts confirm the full expansion was delivered.
//
// At most MaxDeepScreenVariations (24) variations are screened per request;
// repeats, the screened name itself, and variations that break the "Name
// input" rule are dropped first, and VariationsGenerated counts what
// remains.
type DeepScreenCoverage struct {
// VariationsGenerated is the number of name variations the LLM produced
// for this request.
VariationsGenerated int `json:"variations_generated"`
// VariationsScreened is the number of generated variations that were
// screened against the sanctions lists.
VariationsScreened int `json:"variations_screened"`
}
// JurisdictionRecord is one jurisdiction's comprehensive-embargo status as a
// historical record, answering "was this place embargoed then?" — the same
// question a screening's JurisdictionRisk answers, and a different one from
// what POST /v1/export/replay answers, which is "what did we tell you when
// you asked?".
//
// The record and a replay can legitimately disagree for the same date. A
// screening record may carry an advisory for a program that had already been
// revoked when the screening ran, because the embargo table reflected the
// revocation later. The screening's advisory is preserved as issued and
// replays as issued; this record reports the law. Neither is corrected to
// match the other.
//
// GET /v1/jurisdictions/{code} accepts every token screening accepts — the
// canonical code in any case, plus the region names ("CRIMEA", "SEVASTOPOL",
// "DPRK"). A token screening would act on always has a record to answer for
// it. A code the set has never evaluated is a 404, not an "embargoed: false"
// record, which would imply a determination nobody made.
type JurisdictionRecord struct {
// Jurisdiction is the canonical code: ISO 3166-1 alpha-2 for countries,
// ISO 3166-2 for embargoed regions.
Jurisdiction string `json:"jurisdiction"`
// Name is the human-readable jurisdiction name.
Name string `json:"name"`
// Status is "embargoed" for a jurisdiction under a comprehensive embargo
// for some period, or "excluded" for one evaluated and determined not to
// be. An excluded entry is published deliberately: "we considered this
// and it is not embargoed, for this cited reason" is a materially
// different answer from silence.
Status string `json:"status"`
// Embargoed reports whether the comprehensive embargo was in force at the
// queried instant (or now, when no as_of was supplied).
Embargoed bool `json:"embargoed"`
// Program is the OFAC sanctions program establishing the embargo.
Program string `json:"program,omitempty"`
// Authority is the regulatory citation for the program.
Authority string `json:"authority,omitempty"`
// Determination cites the instruments behind this record's dates: the one
// that established the embargo, and, for a lapsed program, the one that
// revoked it. For an excluded jurisdiction it cites the authority relied
// on for the negative determination. No date on this record is published
// without the instrument that sets it.
Determination string `json:"determination,omitempty"`
// EffectiveFrom is the effective date of the instrument that ESTABLISHED
// the comprehensive embargo (YYYY-MM-DD) — the executive order or
// proclamation, never the CFR part that later implemented it. The two can
// be years apart: Cuba's embargo commenced with Proclamation 3447 on
// 1962-02-07, while the Cuban Assets Control Regulations (31 CFR Part
// 515, the Authority) followed on 1963-07-08. Determination names the
// instrument this date comes from.
EffectiveFrom string `json:"effective_from,omitempty"`
// EffectiveTo is the date the embargo was revoked (YYYY-MM-DD).
// Absent means still in force.
EffectiveTo string `json:"effective_to,omitempty"`
// ReviewedAt is when this entry was last reconciled against OFAC's
// published programs (YYYY-MM-DD).
ReviewedAt string `json:"reviewed_at,omitempty"`
}
// JurisdictionsResponse is the full comprehensive-embargo record.
type JurisdictionsResponse struct {
// AsOf echoes the instant the record was evaluated at, when one was
// supplied.
AsOf string `json:"as_of,omitempty"`
// Jurisdictions is every jurisdiction on record, embargoed and
// explicitly excluded alike, ordered by code.
Jurisdictions []JurisdictionRecord `json:"jurisdictions"`
Meta ResponseMeta `json:"meta"`
}
// JurisdictionResponse is a single jurisdiction's record. The record's fields
// are inline, so embargoed and the citations sit at the top level.
type JurisdictionResponse struct {
JurisdictionRecord
// AsOf echoes the instant the record was evaluated at, when one was
// supplied.
AsOf string `json:"as_of,omitempty"`
Meta ResponseMeta `json:"meta"`
}
// Location is a structured declaration of where the screened subject is.
//
// It exists because the comprehensive embargoes under E.O. 13685 and
// E.O. 14065 apply to REGIONS — Crimea, Sevastopol, and the so-called DNR and
// LNR covered regions — which have no ISO 3166-1 country code. Ukraine itself
// is not embargoed, so "UA" is the correct and insufficient answer for a party
// in Sevastopol; there was previously no field in which a caller could say
// where in Ukraine they meant.
//
// Location is evaluated for jurisdiction nexus only. It never contributes to
// match scoring, so declaring a nexus can never reduce a match score — a
// disclosure should not be penalized.
//
// Every field is optional. Country must be an ISO 3166-1 alpha-2 code;
// anything else is rejected with code "invalid_parameter" rather than
// ignored, since an alpha-3 or spelled-out country is a caller mistake with
// one unambiguous correction. (The legacy ScreenRequest.Country field remains
// liberal and is unchanged.)
//
// Region is NOT checked against the embargo table. Comprehensive embargoes
// cover a handful of regions and every other subdivision on earth is
// legitimately absent, so an unrecognized region is recorded in the audit
// trail and simply raises no advisory — refusing it would fail the screening
// over a supplementary signal, and on /v1/batch one such item would fail an
// otherwise valid job. The one region rejection is a contradiction: a
// subdivision code that is not inside the declared Country, where one of the
// two values is wrong and neither can be privileged.
//
// GET /v1/jurisdictions publishes the set that does raise an advisory, so a
// caller who needs certainty can check it rather than inferring coverage from
// the absence of a 400.
type Location struct {
// Country is the ISO 3166-1 alpha-2 country code (e.g. "UA").
Country string `json:"country,omitempty"`
// Region is the ISO 3166-2 subdivision code (e.g. "UA-40" Sevastopol,
// "UA-43" Crimea, "UA-14" DNR, "UA-09" LNR). Common English region names
// ("Crimea", "Sevastopol", "Donetsk", "Luhansk") are also accepted.
Region string `json:"region,omitempty"`
// City is recorded in the audit record for analyst context. It is
// consulted for one thing: a city on the Crimean peninsula (Simferopol,
// Yalta, Kerch, Feodosia, Yevpatoria and the rest, Latin or Cyrillic)
// raises the Crimea or Sevastopol embargo whatever Country says, and the
// nexus names "location.city" and the word. Any other city name is
// never parsed and raises nothing.
City string `json:"city,omitempty"`
}
// JurisdictionRisk is an advisory signal that the screened subject's
// geographic input touches a comprehensive OFAC embargo. It is deliberately
// advisory — enhanced due diligence, never an auto-block: the licensing and
// exemption determination belongs to the institution's compliance program.
// It does not alter match scores or the summary verdict.
//
// Detection accepts ISO 3166-1 alpha-2 codes (the documented country
// format), ISO 3166-2 Ukrainian region codes ("UA-43" Crimea, "UA-40"
// Sevastopol, "UA-14" Donetsk, "UA-09" Luhansk), and common English
// jurisdiction names. Ukraine ("UA") and Russia ("RU") themselves never
// fire — only the embargoed regions do.
//
// Identical detection runs on /v1/screen and per-item on /v1/batch, and the
// signal is persisted in the screening's audit record.
type JurisdictionRisk struct {
// Jurisdiction is the canonical identifier: ISO 3166-1 alpha-2 for
// countries ("CU", "IR", "KP"), ISO 3166-2 for the Ukrainian
// regions ("UA-43", "UA-40", "UA-14", "UA-09").
Jurisdiction string `json:"jurisdiction"`
// Name is the human-readable jurisdiction name.
Name string `json:"name"`
// Program is the OFAC sanctions program establishing the embargo.
Program string `json:"program"`
// Authority is the regulatory citation (e.g. "31 CFR Part 560").
Authority string `json:"authority"`
// Level says how sure the engine is that the subject has a nexus with
// Jurisdiction: JurisdictionLevelComprehensiveEmbargo when the declared
// geography, or an uncontradicted word in the address or city, places
// the subject there; JurisdictionLevelPossibleEmbargoNexus when a word
// in the address or city names the jurisdiction but the declared
// country places the subject elsewhere. An enum rather than a bool so
// further levels can be added without a contract break. Integrations
// that gate a hard EDD workflow on this signal should key on Level, not
// on the block's presence.
Level string `json:"level"`
// Guidance is fixed EDD advisory text for the Level: what the signal
// means, what resolves it, and that it does not block the subject.
Guidance string `json:"guidance"`
}
// Values for JurisdictionRisk.Level.
const (
// JurisdictionLevelComprehensiveEmbargo: the jurisdiction is under a
// comprehensive OFAC embargo (country program or embargoed region) and
// the declared geography places the subject there. Always paired with
// JurisdictionNexus.Status "embargoed".
JurisdictionLevelComprehensiveEmbargo = "comprehensive_embargo"
// JurisdictionLevelPossibleEmbargoNexus: the jurisdiction is under a
// comprehensive OFAC embargo and a word in address or location.city
// names it, but the declared country (country or location.country) is
// neither Russia nor Ukraine, so the word may be a street, a surname or
// a namesake town — "Kerch Street 5, Sydney" under country "AU". The
// advisory is issued so the analyst sees it; the level says it is
// evidence of a nexus, not proof. Always paired with
// JurisdictionNexus.Status "possible", whose Conflicts name the
// contradicting fields.
JurisdictionLevelPossibleEmbargoNexus = "possible_embargo_nexus"
)
// JurisdictionNexus reports the geography the engine evaluated for embargo
// nexus, and what the embargo record had to say about it. Present on every
// response whose request declared any geography; absent when none was.
//
// It exists because silence is ambiguous on a disclosure-based control.
// Without it, "we evaluated Kherson, no Treasury covered-region determination
// exists, no advisory" and "we have no determination for the string you sent,
// no advisory" are byte-identical answers — and a caller who mistypes a
// region believes they disclosed a nexus when they did not. JurisdictionRisk
// answers what was found; this answers what was looked at.
//
// Read it together with JurisdictionRisk: Status "embargoed" always
// accompanies a JurisdictionRisk block at Level "comprehensive_embargo",
// Status "possible" one at Level "possible_embargo_nexus", and the other two
// statuses never carry a JurisdictionRisk block.
type JurisdictionNexus struct {
// Evaluated is the declaration the engine acted on, echoed as the caller
// wrote it. Because precedence is first-RESOLVING, this is not
// necessarily the most specific field supplied: a request declaring
// {country: "IR", region: "IR-07"} reports "IR", because the embargo
// record has no determination about that province and the country's
// embargo therefore stands.
Evaluated string `json:"evaluated"`
// Source is the request field Evaluated was read from:
// "location.region", "location.country", "country", or — when the
// embargoed-region keyword scan resolved it — "location.city" or
// "address", in which case Evaluated is the single word that matched
// ("Simferopol"), not the whole field.
Source string `json:"source"`
// Status is what the embargo record says about Evaluated — one of
// NexusStatusEmbargoed, NexusStatusPossible,
// NexusStatusEvaluatedNotEmbargoed, or NexusStatusNoDetermination.
Status string `json:"status"`
// Conflicts names the declared country fields that contradict a keyword
// nexus, most specific first. Present only when Status is
// NexusStatusPossible: {"evaluated": "Kerch", "source": "address",
// "status": "possible", "conflicts": [{"source": "country",
// "evaluated": "AU"}]} says the address named a Crimean town and the
// caller said the subject is in Australia, in one field, so an analyst
// sees why the advisory fired and how strong it is.
Conflicts []NexusConflict `json:"conflicts,omitempty"`
}
// NexusConflict is one declared field that contradicts a keyword nexus.
type NexusConflict struct {
// Source is the request field: "location.country" or "country".
Source string `json:"source"`
// Evaluated is the declaration as the caller wrote it.
Evaluated string `json:"evaluated"`
}
// Values for JurisdictionNexus.Status.
const (
// NexusStatusEmbargoed means the declared geography is under a
// comprehensive OFAC embargo. Always accompanied by JurisdictionRisk at
// Level "comprehensive_embargo".
NexusStatusEmbargoed = "embargoed"
// NexusStatusPossible means a word in address or location.city names a
// comprehensively embargoed region, but the declared country places the
// subject elsewhere (Conflicts says where), so the nexus is evidence,
// not established: a Crimean toponym is also a street name in Sydney
// and a surname in London. Accompanied by JurisdictionRisk at Level
// "possible_embargo_nexus". The hedge is narrow: it applies only to a
// single town name contradicted by a declared country written as a
// two-letter code. The same word under RU or UA, or with no declared
// country, is "embargoed" — the CoinList shape; so is the peninsula
// named outright ("Crimea", "Krym", "Крым") or two different Crimean
// tokens agreeing across the fields ("Simferopol, Republic of Crimea"),
// whatever the country field says; a country that is not a two-letter
// code ("Россия", "AUS") hedges nothing; and a word in location.region
// is a declaration and is never hedged.
NexusStatusPossible = "possible"
// NexusStatusEvaluatedNotEmbargoed means the embargo record carries a
// determination for this jurisdiction and it is not comprehensively
// embargoed — Kherson, say, where no Secretary of the Treasury
// covered-region determination exists under E.O. 14065. A cited answer,
// not an absence. GET /v1/jurisdictions returns the full record.
NexusStatusEvaluatedNotEmbargoed = "evaluated_not_embargoed"
// NexusStatusNoDetermination means the embargo record says nothing about
// the declared geography — an ordinary region like "California", or a
// value that did not match anything Noble evaluates. The screening ran
// normally; only the embargo advisory had nothing to report.
//
// This is the status to check if you rely on declaring a nexus: it is
// how a typo ("Crimea Republic" for "Crimea") surfaces instead of
// silently looking like a clean result.
NexusStatusNoDetermination = "no_determination"
)
// OwnershipMatch reports what Noble's ownership graph knows about the
// screened name under each sanctioning authority's derivative-ownership
// rule: OFAC's 50 Percent Rule (an entity owned 50% or more in the
// aggregate, directly or indirectly, by one or more blocked persons is
// itself blocked, FAQs 398/401/402), OFSI's "owned or controlled" test
// (more than 50%, holdings of different designated persons not aggregated),
// the EU's (50% or more, aggregated), Canada's deemed ownership (50% or
// more, aggregated), and the UN and Australian "owned or controlled"
// tests, which have no numeric threshold. A regime is a legal authority,
// not a feed: a determination under "us" rests only on owners OFAC
// designates, under "eu" only on owners the EU or one of its member-state
// registers (France, Belgium, the Netherlands) designate, and so on. The
// same entity can be blocked under one regime and clean under another: a
// 50/50 joint venture of two OFAC-designated owners is blocked under us and
// not owned under uk, and the response says both.
//
// The determinations are precomputed from the ownership graph (sanctions-
// list ownership assertions corroborated by GLEIF corporate-relationship
// data) and looked up by name at screening time: one computation, one rule
// per regime. The lookup adds no meaningful latency and never alters match
// scores or the summary verdict.
//
// Present on every live /v1/screen response that screened a name, on
// deployments with ownership screening enabled. Absent on identifier-only
// requests and on as_of (point-in-time) screenings: the ownership graph
// reflects current data only, and attaching today's ownership to a
// historical inquiry would misstate the record.
//
// Schema 2 (2026-11). A screening record persisted before it carries the
// earlier shape (schema 1: one status, one aggregate across every list);
// GET /v1/alerts/{id} renders such evidence under the "legacy" regime with
// rule "pre_regime_union".
type OwnershipMatch struct {
// Schema is the version of this object's shape: 2. Readers of persisted
// records and alert evidence written before 2026-11 see 1.
Schema int `json:"schema"`
// EntityName is the name the screened input resolved to in the
// ownership graph: the entity's primary name when a determination
// exists, otherwise the indexed name that matched (in normalized,
// lowercase form). Compare it against the screened input: name
// resolution is fuzzy, and this field shows exactly which entity the
// determinations are about. Empty when nothing resolved.
EntityName string `json:"entity_name,omitempty"`
// EntityKey is the ownership-graph key of the entity EntityName names
// (e.g. "xname:advanced mining works", "lei:5493001KJTIIGC8Y1R12"), the
// same key space as OwnershipHop.EntityKey. It identifies the entity
// independently of how its name was spelled, and an ownership alert is
// deduplicated on it. Empty when nothing resolved.
EntityKey string `json:"entity_key,omitempty"`
// NameSimilarity is the trigram similarity (0-100) between the
// normalized screened name and the graph name it resolved to. 100 is an
// exact normalized match. Omitted when nothing resolved.
NameSimilarity float64 `json:"name_similarity,omitempty"`
// Entity is the graph entity the screened name resolved to, with its
// designation set: present whenever a determination exists for it,
// and also when the name is, under the engine's fold, exactly a name
// of a designated party (whose regimes then report "designated").
// Absent when the name resolved to nothing, or only fuzzily to a party
// with no determination, which is "unknown" under every regime.
Entity *OwnershipEntity `json:"entity,omitempty"`
// Overall is derived from Determinations over the selected regimes
// (RegimesFrom says what selected them): it never carries a rule of its
// own. Its status is "blocked" when any selected regime reached its
// blocking consequence, else "designated" when the entity is itself
// designated under a selected regime (its own listing is the strongest
// ownership finding there is, and the name alert carries it; #818),
// else "review" when any regime is under review, else "clean" when
// every selected regime evaluated the entity and found nothing, else
// "unknown"; "unavailable" when the control did not run (#708). Regimes
// names the regimes behind that status; a review under a regime that
// does not designate the party stays on its own determination. An
// ownership alert is raised exactly when Overall.Status is "blocked"
// (alert_reason ownership_control) or "review" (ownership_review,
// #706), so none is raised for a party itself designated under a
// selected regime; a determination whose alert cannot be written fails
// the screening with 503 alert_unavailable rather than returning a
// finding nobody is notified of.
Overall OwnershipOverall `json:"overall"`
// Determinations is one determination per regime, keyed by regime
// ("us", "uk", "eu", "un", "ca", "au"): the regimes ScreenRequest.Lists
// selects, or without Lists the regimes the account declared
// (features.ownership_regimes, every regime by default; #728). A regime
// absent here was not determined: absence is never a clean result. Each
// is reached under that regime's own rule (OwnershipRules) and names
// it.
Determinations map[string]*OwnershipDetermination `json:"determinations"`
// AsOf is the date (YYYY-MM-DD) of the ownership computation these
// determinations came from.
AsOf string `json:"as_of,omitempty"`
// RegimesFrom says what selected the regimes determined here (#728):
// "lists" when the request's lists did, "account" when the tenant's
// declared regimes did (GET /v1/account features.ownership_regimes),
// for a request without lists and for portfolio monitoring. Part of
// the audit record of the screening it shaped.
RegimesFrom string `json:"regimes_from,omitempty"`
// SourcePublishIDs pins the snapshot of every data source that
// contributed to the ownership computation (source name -> snapshot
// identifier), so the determinations are reproducible for audit.
SourcePublishIDs map[string]string `json:"source_publish_ids,omitempty"`
}
// OwnershipOverall is the derived summary of OwnershipMatch.Determinations
// (see OwnershipMatch.Overall).
type OwnershipOverall struct {
// Status is "blocked", "review", "designated", "clean", "unknown" or
// "unavailable".
Status string `json:"status"`
// Regimes names the regimes whose determination gave Status: the
// blocking regimes when Status is "blocked", the designating ones when
// "designated", the reviewing ones when "review"; empty for "clean"
// and "unknown".
Regimes []string `json:"regimes,omitempty"`
}
// OwnershipDetermination is one regime's answer about the screened entity.
type OwnershipDetermination struct {
// Rule is the key of the rule this determination was reached under
// (OwnershipRules[regime].Key), e.g. "ofac_sdn_50_percent".
Rule string `json:"rule"`
// Status is the determination under this regime's rule:
//
// the regime's blocking consequence word (OwnershipRule.Blocked):
// "blocked" under us, "owned_or_controlled" under uk, eu
// and un, "deemed_owned" under ca, "controlled_asset"
// under au. The entity is a blocked (frozen, deemed-owned)
// person under that regime although it appears on none
// of its lists; treat it as a designation under that
// regime.
// "designated" — the screened name is a designated party's under this
// regime (see Designations). The designation is the
// finding; no derivative determination is made.
// "review" — an ownership or control relationship to a party this
// regime designates exists, but no source discloses a
// percentage (a GLEIF consolidation parent, an OFAC
// "Linked To" pointer, an extracted control statement),
// or a stake that once blocked the entity has fallen
// below the threshold (Reason says which). The
// relationship is real; a compliance officer must
// investigate. Not a blocked state.
// "clean" — the computation evaluated this entity under this regime
// and found no ownership by parties the regime designates
// within the graph's source coverage, with nothing
// conflicting under a near-identical name. The graph sees
// only the ownership its sources disclose, so "clean" is
// advisory input to the institution's own programme, not
// an exhaustive all-clear, and is never returned merely
// because no determination was found.
// "unknown" — no conclusion is supported: the name is not in the
// ownership graph, or a near-identically named entity
// carries a determination that this one does not.
// "not_applicable" — the regime has no derivative rule for the
// programme the owner is designated under.
//
// Under the regimes with no numeric threshold (un, au) the computation
// reports "review", "designated", "clean" or "unknown" only: ownership
// or control, direct or indirect, by a party the regime designates is
// a relationship for a human to assess, never a categorical result.
// Their consequence words are reserved in OwnershipRules and are not
// produced.
Status string `json:"status"`
// AggregatePercent is the stake held by parties this regime designates,
// as the regime's rule counts it: the sum across every chain's first
// hop where the rule aggregates (us, eu, ca), the largest single
// designated holding where it does not (uk). Present with chains that
// carry explicit percentages; absent on review-only chains.
AggregatePercent float64 `json:"aggregate_percent,omitempty"`
// Control reports that the chains include a relationship with no
// disclosed stake (a control or undisclosed-percentage link). Such a
// link never yields a categorical result on its own: it holds the
// determination at "review" until a human approves the assertion.
Control bool `json:"control,omitempty"`
// BlockedSince is the date (YYYY-MM-DD) the entity was first determined
// blocked under this regime by a computation whose records are
// unbroken since. Under us a block is sticky (FAQ 402): property blocked
// while ownership was 50% or more stays blocked when the stake later
// falls below it, until the relationship is gone or a human clears it.
BlockedSince string `json:"blocked_since,omitempty"`
// Reason qualifies Status when it was not reached by the rule's
// threshold alone: "ownership_reduced_after_block" marks a stake that
// fell below the threshold after the entity was blocked (still
// "blocked" under us, "review" under the other regimes);
// "blocked_government_candidate" (us) marks an entity a list's text
// names as a state body of a programme that blocks by definition
// (#715), awaiting an analyst's confirmation; and
// "controlled_by_blocked_government" (us) marks a stake-less link to a
// confirmed one, which the regulation reaches and the 50 Percent Rule
// does not; and "owned_by_non_sdn_designee" (us) marks an entity owned
// by a party OFAC designates on its non-SDN lists alone (#707), which
// does not block it; "ssi_owned" (us) marks an entity owned 50 percent
// or more, alone or in the aggregate, by Sectoral Sanctions
// Identifications parties, directly or through entities they own, or
// linked to such an entity at an undisclosed stake (control set),
// which the SSI directives restrict (#738): not a block, never clean,
// the programme on the hop. Its aggregate_percent is the SSI parties'
// combined stake under the directives' 50 percent rule, not a stake
// under the regime's blocking rule; "short_extracted_name" marks an
// entity the rule would block that is known only by a one-word name
// under six letters a list's text gives it ("GSK"), read as review so
// a human tells the party meant from every company of that name;
// "possible_same_party" marks an entity whose owner has a record on
// another list, sharing its name and not linked to it, that the regime
// designates (#786): review, or blocked when a sticky regime had already
// blocked the entity (#812, see PossibleSameParty); the record and the
// evidence for and against on the hop's possible_same_party.
Reason string `json:"reason,omitempty"`
// Designations are, on a "designated" determination, the designations
// under this regime's lists that make it one: those of the entity the
// name resolved to, and those of any other designated party that
// publishes exactly the screened name (equal under the engine's fold;
// a list's weak aliases excluded). A party two lists designate stays
// two ownership entities until identity resolution corroborates them
// (see OwnershipDesignation.Grade), so the name can resolve to one
// list's record while another list's record of it is a direct
// score-100 match on the same response; the regime reads designated
// either way, and this field names the designation (#748). Absent on
// every other status.
Designations []OwnershipDesignation `json:"designations,omitempty"`
// BlockedBasis names the programme definition a us determination
// rests on when it rests on no designation and no stake (#715): one of
// the OwnershipBasis* values, e.g. "government_of_iran" (31 CFR
// 560.211, 560.304). Present on a confirmed blocked-government person's
// own determination, on a candidate's review, and on a determination
// whose chains reach such a person; the hop names it too.
BlockedBasis string `json:"blocked_basis,omitempty"`
// Chains are the discrete ownership paths from the screened entity up
// to the owners this regime designates: the examiner-grade evidence
// behind Status. Ordered by first-hop stake, descending. A chain
// propagates only through intermediaries that are themselves blocked
// under this regime.
Chains []OwnershipPath `json:"chains,omitempty"`
}
// Ownership regimes: the sanctioning authorities a determination is made
// under. ScreenRequest.Lists selects them through OwnershipRegimeForList.
const (
OwnershipRegimeUS = "us" // OFAC
OwnershipRegimeUK = "uk" // OFSI
OwnershipRegimeEU = "eu" // the EU and its member-state registers
OwnershipRegimeUN = "un" // UN Security Council
OwnershipRegimeCA = "ca" // Global Affairs Canada
OwnershipRegimeAU = "au" // DFAT
// OwnershipRegimeLegacy keys evidence persisted before schema 2: one
// determination under the union of every list. Never produced by a live
// screening.
OwnershipRegimeLegacy = "legacy"
)
// OwnershipAllRegimes lists every regime a live screening determines, in
// response order.
var OwnershipAllRegimes = []string{OwnershipRegimeUS, OwnershipRegimeUK, OwnershipRegimeEU, OwnershipRegimeUN, OwnershipRegimeCA, OwnershipRegimeAU}
// OwnershipRegimeForList maps a list key (ScreenRequest.Lists) to the
// regime whose designations it carries. The national registers of France,
// Belgium and the Netherlands mirror EU designations and add domestic ones;
// both seed the EU regime, and the national list stays visible as the
// designation's list. Unknown list keys map to "".
func OwnershipRegimeForList(list string) string {
switch list {
case ListOFAC:
return OwnershipRegimeUS
case ListUK:
return OwnershipRegimeUK
case ListEU, ListFrance, ListBelgium, ListNetherlands:
return OwnershipRegimeEU
case ListUN:
return OwnershipRegimeUN
case ListCanada:
return OwnershipRegimeCA
case ListAustralia:
return OwnershipRegimeAU
}
return ""
}
// What selected the regimes of an ownership determination
// (OwnershipMatch.RegimesFrom, #728).
const (
OwnershipRegimesFromLists = "lists"
OwnershipRegimesFromAccount = "account"
)
// ForRegimes is m narrowed to regimes (#728): only their determinations,
// and overall re-derived over them, so a regime the reader is not bound by
// never reaches its overall status or its alert. m is not modified. An
// "unavailable" overall stays unavailable.
func (m *OwnershipMatch) ForRegimes(regimes []string) *OwnershipMatch {
if m == nil {
return nil
}
out := *m
out.Determinations = make(map[string]*OwnershipDetermination, len(regimes))
var kept []string
for _, r := range OwnershipAllRegimes {
if !slices.Contains(regimes, r) {
continue
}
kept = append(kept, r)
if d, ok := m.Determinations[r]; ok {
out.Determinations[r] = d
}
}
if m.Overall.Status != OwnershipStatusUnavailable {
out.Overall = DeriveOwnershipOverall(out.Determinations, kept)
}
return &out
}
// ParseOwnershipRegimes validates a declared set of regimes (#728): at
// least one, every one a key of OwnershipRules. It returns them in
// OwnershipAllRegimes order without duplicates.
func ParseOwnershipRegimes(regimes []string) ([]string, error) {
if len(regimes) == 0 {
return nil, fmt.Errorf("at least one regime is required; valid regimes: %s", strings.Join(OwnershipAllRegimes, ", "))
}
for _, r := range regimes {
if _, ok := OwnershipRules[r]; !ok {
return nil, fmt.Errorf("unknown regime %q; valid regimes: %s", r, strings.Join(OwnershipAllRegimes, ", "))
}
}
var out []string
for _, r := range OwnershipAllRegimes {
if slices.Contains(regimes, r) {
out = append(out, r)
}
}
return out, nil
}
// OwnershipRegimesForLists is the regimes a request's Lists select, in
// OwnershipAllRegimes order and without duplicates; every regime when lists
// is empty.
func OwnershipRegimesForLists(lists []string) []string {
if len(lists) == 0 {
return append([]string(nil), OwnershipAllRegimes...)
}
want := map[string]bool{}
for _, l := range lists {
if r := OwnershipRegimeForList(l); r != "" {
want[r] = true
}
}
var out []string
for _, r := range OwnershipAllRegimes {
if want[r] {
out = append(out, r)
}
}
return out
}
// OwnershipRule is one regime's derivative-ownership rule, as the
// computation applies it. The table (OwnershipRules) is the contract: a
// determination's AggregatePercent and Status follow from it.
type OwnershipRule struct {
// Key names the rule on the determination (OwnershipDetermination.Rule).
Key string
// Threshold is the ownership percentage at which the rule's consequence
// attaches; 0 for a rule with no numeric test (un, au), under which any
// ownership or control relationship to a designated party is "review".
Threshold float64
// Inclusive reports whether a stake equal to Threshold attaches the
// consequence ("50 percent or more", us/eu/ca) or only a greater one
// ("more than 50 percent", uk).
Inclusive bool
// Aggregates reports whether the holdings of different designated
// owners are summed (us, FAQ 401; eu; ca) or each owner's holding is
// tested alone (uk).
Aggregates bool
// Sticky reports that a block survives a later fall of the stake below
// Threshold while the relationship persists (us, FAQ 402). A non-sticky
// regime reports such an entity as "review" with Reason set.
Sticky bool
// Blocked is the regime's consequence word: the Status a determination
// carries when the rule attaches.
Blocked string
}
// Rule keys and consequence words.
const (
OwnershipRuleUS = "ofac_sdn_50_percent"
OwnershipRuleUK = "uk_ownership_or_control"
OwnershipRuleEU = "eu_ownership_or_control"
OwnershipRuleUN = "un_owned_or_controlled"
OwnershipRuleCA = "ca_deemed_ownership"
OwnershipRuleAU = "au_owned_or_controlled"
// OwnershipRuleLegacy marks schema-1 evidence: one aggregate over every
// list, "blocked" at 50% or more.
OwnershipRuleLegacy = "pre_regime_union"
OwnershipConsequenceBlocked = "blocked"
OwnershipConsequenceOwnedOrControlled = "owned_or_controlled"
OwnershipConsequenceDeemedOwned = "deemed_owned"
OwnershipConsequenceControlledAsset = "controlled_asset"
)
// OwnershipRules is the rule each regime's determination is reached under.
// Under us an owner counts when OFAC's SDN list designates it: a party
// on OFAC's non-SDN Consolidated list alone (Sectoral Sanctions
// Identifications, NS-MBS, CMIC, HKAA, NS-PLC) is identified but its
// property is not blocked, so the 50 Percent Rule does not make what it
// owns a blocked person (#707).
// Sources: OFAC FAQs 398, 401 and 402 and the sham-transactions guidance of
// 2026-03-31 (us); OFSI general guidance updated 2026-05-12 and the
// OFAC–OFSI comparison guide of 2026-06-23 (uk); the Council's Best
// Practices of 2024-07-03 (eu); Global Affairs Canada's deemed-ownership
// guidance, in force 2023-06-22 (ca); UN Security Council resolutions (un);
// the DFAT Sanctions Compliance Toolkit (au).
var OwnershipRules = map[string]OwnershipRule{
OwnershipRegimeUS: {Key: OwnershipRuleUS, Threshold: 50, Inclusive: true, Aggregates: true, Sticky: true, Blocked: OwnershipConsequenceBlocked},
OwnershipRegimeUK: {Key: OwnershipRuleUK, Threshold: 50, Inclusive: false, Aggregates: false, Blocked: OwnershipConsequenceOwnedOrControlled},
OwnershipRegimeEU: {Key: OwnershipRuleEU, Threshold: 50, Inclusive: true, Aggregates: true, Blocked: OwnershipConsequenceOwnedOrControlled},
OwnershipRegimeUN: {Key: OwnershipRuleUN, Blocked: OwnershipConsequenceOwnedOrControlled},
OwnershipRegimeCA: {Key: OwnershipRuleCA, Threshold: 50, Inclusive: true, Aggregates: true, Blocked: OwnershipConsequenceDeemedOwned},
OwnershipRegimeAU: {Key: OwnershipRuleAU, Blocked: OwnershipConsequenceControlledAsset},
}
// OwnershipEntity is a node of the ownership graph as the screening
// reports it: its key, its primary name, and the designations it carries.
// A designated party is one node however many lists designate it (one
// entity identity across lists): its designations are merged only on
// graded evidence (see OwnershipDesignation.Grade), never on a fuzzy name,
// so a parent and a subsidiary that share an alias stay two entities.
type OwnershipEntity struct {
// Key is the entity's key in the graph: "ent:<id>" for a designated
// party, "xname:<name>" for a party known only from a list's narrative,
// "lei:<LEI>" for a GLEIF-registered company. When two entities are
// merged, one "ent:" key retires: the next ownership import moves
// everything under it to the surviving entity's key, and no
// determination is reported under the retired key after that.
Key string `json:"key"`
// Name is the entity's primary name: for a designated party, the name
// its first designating list publishes (OFAC first).
Name string `json:"name"`
// Designations is every list's designation of this party, ordered by
// list then uid. Empty for an entity no list designates.
Designations []OwnershipDesignation `json:"designations,omitempty"`
// IdentityGrade is the grade of the entity as a whole: "singleton" for
// one designation, otherwise the weakest grade among the designations
// that joined it (a merge is as strong as its weakest link). Empty for
// an undesignated entity.
IdentityGrade string `json:"identity_grade,omitempty"`
}
// OwnershipDesignation is one list's designation of an entity.
type OwnershipDesignation struct {
// List is the designating list's key ("ofac", "uk", "eu", "france", ...).
List string `json:"list"`
// UID is the list's own identifier for the designation (the uid a
// match of that list reports).
UID string `json:"uid"`
// Grade is the evidence by which this designation joined the entity:
//
// "singleton" — the entity has this one designation.
// "reference" — the designation cites the same published reference
// number (a UN reference) as another designation of
// the entity.
// "strong" — a name equal under the engine's fold on both sides,
// corroborated by an equal date of birth, a shared
// identification number, or, for an entity, two or
// more distinct name forms in common.
// "verdict" — an analyst's recorded merge verdict.
// "corroborated" — the same primary name on two lists, legal form
// aside, specific enough to name one party (two or
// more words, not all generic; three or more for a
// person), the same kind, listed
// under an overlapping programme family (Russia, Iran,
// DPRK, counter-terrorism, ...), with no conflicting
// date or year of birth (#763). The weakest automatic
// grade; an analyst's separate verdict undoes it.
//
// Equal names alone, an alias against a primary, an acronym, or a
// fuzzy name never merge: such a pair waits in the identity review
// queue as a candidate and is not part of any entity.
Grade string `json:"grade,omitempty"`
// NonBlocking marks a designation whose programme does not block
// property (#707): an OFAC designation on the non-SDN Consolidated list
// alone (SSI, NS-MBS, CMIC, HKAA, NS-PLC). Such an owner does not make
// what it owns blocked under us; what it owns reads review with reason
// owned_by_non_sdn_designee. Present on a hop's designations.
NonBlocking bool `json:"non_blocking,omitempty"`
// Programs is the programme tags OFAC lists the designation under, the
// codes ScreenMatch.Programs shows for the same uid (#765), e.g.
// ["VENEZUELA-EO13884"]. Absent on another list's designation.
Programs []string `json:"programs,omitempty"`
// Restricted marks an OFAC designation on the non-SDN Consolidated
// list, alone or beside the SDN list (#738): Programs then names the
// restriction that reaches what the party owns, e.g. "UKRAINE-EO13662"
// for a Sectoral Sanctions Identifications party. An SDN-only
// designation is never restricted, though its programme may be EO
// 13662: being designated under it is not being on the SSI list.
Restricted bool `json:"restricted,omitempty"`
}
// OwnershipPath is one ownership chain from the screened entity up to a
// sanctioned owner. Hops[0] is the direct owner of the screened entity;
// the last hop is the party the regime designates.
type OwnershipPath struct {
// Percent is the stake the chain's first hop holds in the screened
// entity: this chain's contribution to the regime's aggregate. Per OFAC
// FAQ 401, indirect ownership propagates only through links that
// themselves clear the threshold, so a chain's contribution is its
// first-hop stake, never a product of percentages along the path. Zero
// on review-status chains (percentage undisclosed).
Percent float64 `json:"percent"`
// Hops are the ownership steps, ordered from the screened entity's
// direct owner upward.
Hops []OwnershipHop `json:"hops"`
}
// OwnershipHop is one ownership step: an owner, and its stake in the
// entity one step below it in the chain.
type OwnershipHop struct {
// EntityKey is the owner's canonical key in the ownership graph
// (e.g. "ent:12345" for a designated party, "lei:5493001KJTIIGC8Y1R12").
// A designation the identity resolver has not placed keeps its per-list
// key ("sdn:36419", "uk:RUS0001"). Keys are opaque: compare them, never
// parse them.
EntityKey string `json:"entity_key"`
// EntityName is the owner's primary name.
EntityName string `json:"entity_name"`
// PercentOwned is this owner's stake in the entity one step below it.
// Omitted when the source discloses no percentage.
PercentOwned float64 `json:"percent_owned,omitempty"`
// IsSanctioned reports whether this owner is itself designated on a
// sanctions list (any list, not only the regime's).
IsSanctioned bool `json:"is_sanctioned"`
// SanctionedList names the designating list(s) when IsSanctioned,
// comma-separated (e.g. "ofac", "ofac,uk"): the lists of Designations.
SanctionedList string `json:"sanctioned_list,omitempty"`
// Designations is the owner's designation set when IsSanctioned: one
// entry per list that designates it, with the grade by which each
// joined the entity (see OwnershipDesignation). A party several lists
// designate appears once, with all of them.
Designations []OwnershipDesignation `json:"designations,omitempty"`
// IdentityGrade is the grade of the owner's entity as a whole (see
// OwnershipEntity.IdentityGrade): "singleton", "reference", "strong",
// "corroborated" or "verdict". Present, with Designations, when the owner's designation
// set is known; an owner under a per-list key carries neither.
IdentityGrade string `json:"identity_grade,omitempty"`
// Source identifies the data source that asserted this ownership step:
// "gleif" (GLEIF corporate-relationship data), "ofac_linked_to" (an
// OFAC "(Linked To:)" designation pointer), or "list_text:<list>" (an
// ownership statement extracted from that list's published narrative
// text, retained verbatim in Noble's audit store).
Source string `json:"source"`
// Confidence grades the source assertion: "high" (explicit percentage
// from an authoritative source, a list's own published text included),
// "medium" (GLEIF consolidation relationship), or "low" (a relationship
// with no stated percentage: a designation linkage, or an extracted
// statement without a number).
Confidence string `json:"confidence"`
// AssertionID identifies the extracted ownership statement a
// "list_text:<list>" hop rests on: the row Noble's audit store keeps
// with the list's verbatim text, its publish id and its review status,
// readable by the operator at GET /v1/admin/ownership/assertions/{id}.
// Absent on hops from other sources (#168).
AssertionID int64 `json:"assertion_id,omitempty"`
// AssertionIDs is every live statement of the list that states this
// stake (#725): two records of one list can state the same
// relationship, the owner's and the owned's. AssertionID, the statement
// the stake is taken from (the highest stated percentage), is first.
AssertionIDs []int64 `json:"assertion_ids,omitempty"`
// SourceSentence is the verbatim sentence of the list's published text
// the assertion was extracted from: the evidence an examiner reads
// against the stake. Present with AssertionID.
SourceSentence string `json:"source_sentence,omitempty"`
// BlockedBasis marks an owner blocked by programme definition rather
// than by a designation (#715): one of the OwnershipBasis* values. Such
// an owner has IsSanctioned false and no Designations; it blocks under
// us because the regulation names it. Program is the OFAC programme
// when known; on an ssi_owned determination's chains it is
// "UKRAINE-EO13662" on the hop to each SSI owner (#738).
BlockedBasis string `json:"blocked_basis,omitempty"`
Program string `json:"program,omitempty"`
// PossibleSameParty names, on the hop of a possible_same_party
// determination, the records on other lists that may be this owner
// but are not linked to it (#786): they share a name and lack the hard
// evidence (an identification number, a full date of birth, a
// reference, an analyst's verdict) that links two records. Each is
// listed under the regime the determination is for, and the owner is
// not. Noble does not decide that they are one party; the analyst does,
// from the evidence given. Absent on every other hop.
PossibleSameParty []OwnershipPossibleSameParty `json:"possible_same_party,omitempty"`
}
// OwnershipPossibleSameParty is a record that may be the hop's owner: a
// designation on another list sharing a name with it and not linked to it.
type OwnershipPossibleSameParty struct {
// List and UID identify the designation ("ofac", "25654").
List string `json:"list"`
UID string `json:"uid"`
// EntityKey is the entity the designation belongs to.
EntityKey string `json:"entity_key"`
// Name is the designation's primary name as its list publishes it.
Name string `json:"name"`
// Evidence is what the two records share and where they disagree.
Evidence []OwnershipTwinEvidence `json:"evidence"`
}
// OwnershipTwinEvidence is one fact for or against two records being one
// party. Type is one of OwnershipTwin*: shared_reference, shared_name,
// shared_programme and birth_year support it; identifier_conflict,
// birth_date_conflict, birth_year_conflict and programme_mismatch do not.
// Value is the fact ("QDi.123", "tamas company", "iran", "1963",
// "9866380 / 9898254", "1963-02-23 / 1964-01-01"). A pair that cites one
// published reference number but is held apart by a birth-year gap of two
// years or more (#813) is listed with both, so the owner's stake reads
// review, never clean, until an analyst rules.
type OwnershipTwinEvidence struct {
Type string `json:"type"`
Value string `json:"value"`
Supports bool `json:"supports"`
}
// OwnershipTwinEvidence.Type values.
const (
OwnershipTwinSharedReference = "shared_reference" // one published reference number (a UN reference) on both
OwnershipTwinSharedName = "shared_name"
OwnershipTwinSharedProgramme = "shared_programme"
OwnershipTwinBirthYear = "birth_year"
OwnershipTwinIdentifierConflict = "identifier_conflict" // registry numbers of one kind that differ, "a / b"
OwnershipTwinBirthDateConflict = "birth_date_conflict"
OwnershipTwinBirthYearConflict = "birth_year_conflict"
OwnershipTwinProgrammeMismatch = "programme_mismatch"
)
// Blocked-government bases (#715): the programme definitions OFAC blocks
// persons under without a designation (FAQ 398).
const (
OwnershipBasisGovernmentOfIran = "government_of_iran" // 31 CFR 560.211, 560.304
OwnershipBasisGovernmentOfNorthKorea = "government_of_north_korea" // 31 CFR 510.201, 510.311
OwnershipBasisGovernmentOfSyria = "government_of_syria" // 31 CFR 542.201, 542.305
OwnershipBasisGovernmentOfVenezuela = "government_of_venezuela" // E.O. 13884
OwnershipBasisGovernmentOfCuba = "government_of_cuba" // 31 CFR 515.201, 515.302
OwnershipBasisCrimeaRegion = "crimea_region" // E.O. 13685
)
// Determination reasons beside OwnershipReasonReducedAfterBlock.
const (
OwnershipReasonBlockedGovernmentCandidate = "blocked_government_candidate"
OwnershipReasonControlledByBlockedGovernment = "controlled_by_blocked_government"
OwnershipReasonOwnedByNonSDNDesignee = "owned_by_non_sdn_designee"
OwnershipReasonSSIOwned = "ssi_owned"
// OwnershipReasonPossibleSameParty: an owner's unlinked same-name
// record on another list is designated under the regime and the owner
// is not (#786). Review, never a new block: the stake is not
// attributed to a party Noble has not shown to be designated. The hop
// carries PossibleSameParty. One carve-out (#812, 2026-11-14): an
// entity the previous computation had blocked under a sticky regime
// (us, FAQ 402) keeps "blocked" with this reason when the owner's
// identity falls open, since an unreviewed identity re-run never
// unblocks what a bank blocked yesterday; an analyst's verdict on the
// pair settles it either way.
OwnershipReasonPossibleSameParty = "possible_same_party"
)
// OwnershipMatch.Overall.Status and OwnershipDetermination.Status values
// every regime shares; a regime's blocking consequence word is
// OwnershipRules[regime].Blocked.
const (
OwnershipStatusBlocked = "blocked"
OwnershipStatusReview = "review"
OwnershipStatusClean = "clean"
OwnershipStatusUnknown = "unknown"
OwnershipStatusDesignated = "designated"
OwnershipStatusNotApplicable = "not_applicable"
// OwnershipStatusUnavailable means the control did not run for this
// screening (#708): the determination could not be read. It is never
// an answer about the entity. The response also carries a
// WarningOwnershipUnavailable warning and an ownership_unavailable
// coverage issue, so the record never reads as a clean check when
// none ran.
OwnershipStatusUnavailable = "unavailable"
)
// OwnershipSchema is the current OwnershipMatch.Schema.
const OwnershipSchema = 2
// OwnershipReasonReducedAfterBlock is OwnershipDetermination.Reason for a
// stake that fell below the regime's threshold after the entity was
// blocked.
const OwnershipReasonReducedAfterBlock = "ownership_reduced_after_block"
// OwnershipReasonShortExtractedName is OwnershipDetermination.Reason for an
// entity the regime's rule would block that is known only by a name a
// list's text gives it of one word under six letters ("GSK"), which names
// many companies (#712 risk 9): it reads "review", never the consequence
// word, so a human tells the party the text meant from every other
// company of that name. What it owns is still evaluated as blocked.
const OwnershipReasonShortExtractedName = "short_extracted_name"
// OwnershipMatchWithStatus is the ownership object for a screening that
// has no determination to report: status under every selected regime, each
// naming its rule, and the same status overall. The resolver uses it for a
// name that resolved to nothing ("unknown"); the screening handler for a
// control that did not run ("unavailable", #708).
func OwnershipMatchWithStatus(regimes []string, status string, entity *OwnershipEntity) *OwnershipMatch {
m := &OwnershipMatch{Schema: OwnershipSchema, Entity: entity, Determinations: map[string]*OwnershipDetermination{}}
for _, regime := range regimes {
m.Determinations[regime] = &OwnershipDetermination{Rule: OwnershipRules[regime].Key, Status: status}
}
m.Overall = DeriveOwnershipOverall(m.Determinations, regimes)
if status == OwnershipStatusUnavailable {
m.Overall = OwnershipOverall{Status: OwnershipStatusUnavailable}
}
return m
}
// IsBlocked reports whether d reached its regime's blocking consequence.
func (d *OwnershipDetermination) IsBlocked(regime string) bool {
return d != nil && d.Status == OwnershipRules[regime].Blocked
}
// DeriveOwnershipOverall computes OwnershipMatch.Overall from
// determinations over regimes (in OwnershipAllRegimes order). It is the one
// definition of "overall": the server and any reader of persisted records
// derive it the same way. Precedence is blocked, designated, review, clean,
// unknown (#818): a party's own designation outranks a review it is under
// elsewhere, since the review asks whether the party is reached by a
// designated owner and its own listing has already answered.
func DeriveOwnershipOverall(determinations map[string]*OwnershipDetermination, regimes []string) OwnershipOverall {
var blocked, review, designated []string
clean := len(regimes) > 0
for _, r := range regimes {
d := determinations[r]
switch {
case d == nil:
clean = false
case d.IsBlocked(r):
blocked = append(blocked, r)
case d.Status == OwnershipStatusReview:
review = append(review, r)
case d.Status == OwnershipStatusDesignated:
designated = append(designated, r)
case d.Status == OwnershipStatusClean:
default:
clean = false
}
}
switch {
case len(blocked) > 0:
return OwnershipOverall{Status: OwnershipStatusBlocked, Regimes: blocked}
case len(designated) > 0:
return OwnershipOverall{Status: OwnershipStatusDesignated, Regimes: designated}
case len(review) > 0:
return OwnershipOverall{Status: OwnershipStatusReview, Regimes: review}
case clean:
return OwnershipOverall{Status: OwnershipStatusClean}
}
return OwnershipOverall{Status: OwnershipStatusUnknown}
}
// OwnershipAlertStatus is the one definition of which ownership alert a
// determination raises (#829), for /v1/screen, batch items and portfolio
// monitoring alike: OwnershipStatusBlocked when any selected regime
// reached its consequence word, else OwnershipStatusReview when any
// selected regime reads review, else "". It is decided regime by regime,
// never from Overall. A designation under a regime answers a review under
// that same regime (the determination then reads designated, not review)
// and answers nothing under another regime, whose analyst is bound by its
// own rule: a party listed only by Canada that a designated owner reaches
// under us raises an ownership_review alert beside overall "designated".
// Ruling of 2026-11-14 on nepdave/noble#829; the summary precedence of
// DeriveOwnershipOverall (#818) is unchanged.
func OwnershipAlertStatus(determinations map[string]*OwnershipDetermination) string {
review := false
for regime, d := range determinations {
switch {
case d.IsBlocked(regime):
return OwnershipStatusBlocked
case d != nil && d.Status == OwnershipStatusReview:
review = true
}
}
if review {
return OwnershipStatusReview
}
return ""
}
// AlertStatus is OwnershipAlertStatus over m's determinations: "" for a nil
// m and for a control that did not run.
func (m *OwnershipMatch) AlertStatus() string {
if m == nil || m.Overall.Status == OwnershipStatusUnavailable {
return ""
}
return OwnershipAlertStatus(m.Determinations)
}
// SummaryVerdict is a deterministic classification of screening results,
// computed from match scores. The verdict is reproducible from the structured
// response alone — it is never decided by an LLM.
type SummaryVerdict string
// Verdict buckets driven by the top match score.
const (
VerdictConfirmedMatch SummaryVerdict = "confirmed_match" // top_score >= 95
VerdictStrongMatch SummaryVerdict = "strong_match" // top_score >= 80
VerdictPossibleMatch SummaryVerdict = "possible_match" // top_score >= 65
VerdictWeakMatch SummaryVerdict = "weak_match" // top_score >= 50
VerdictNoSignificantMatch SummaryVerdict = "no_significant_match" // < 50 or no matches
)
// Prohibition type constants classify the regulatory action an OFAC hit
// carries, per OFAC's BLOCK vs. REJECT vs. restricted-dealings framework
// (Introduction to OFAC, June 2026, pp. 7-8). Surfaced on ScreenMatch.ProhibitionType.
const (
ProhibitionBlocking = "blocking" // SDN and 50%-Rule entities: freeze property, file a blocking report
ProhibitionCMICInvestment = "cmic_investment" // NS-CMIC (E.O. 13959): securities investment ban; NOT blocked, 50% Rule does not apply
ProhibitionSSISectoral = "ssi_sectoral" // SSI (E.O. 13662 Directives): restricted new debt/equity/services; NOT blocked
ProhibitionFSEReject = "fse_reject" // FSE (E.O. 13608): reject the transaction
ProhibitionPLCReject = "plc_reject" // NS-PLC: reject the transaction
ProhibitionCAPTA = "capta" // CAPTA: correspondent/payable-through-account restriction
)
// ScreenSummary is an executive synthesis of a screening result. Populated
// on every screening response — the deterministic path is pure-function and
// emits a verdict bucket, top match, distinct lists, strong-match count, and
// a one-line prose synthesis at no I/O cost. Callers that want LLM-rewritten
// prose pass DeepSummary=true (paid tier).
//
// Verdict is always deterministic — even in LLM mode, the bucket is computed
// from scores and the LLM only rewrites the prose. This keeps the audit trail
// reproducible from structured data alone.
type ScreenSummary struct {
// Verdict is a coarse classification of the screening result, computed
// from the top match score (see Verdict* constants).
Verdict SummaryVerdict `json:"verdict"`
// Text is a one-line human-readable synthesis. Up to ~280 characters,
// plus one sentence naming the ownership determination when it is
// blocked, review, designated or unavailable (#218): Verdict is computed
// from match scores alone, so a blocked entity with no name match reads
// "no_significant_match" there, and Text says what the ownership
// control found.
Text string `json:"text"`
// TopMatch identifies the single highest-scoring match. Absent (omitted from
// JSON) when no matches were returned. Lets callers act on the winning hit
// without reparsing the full Matches array.
TopMatch *SummaryTopMatch `json:"top_match,omitempty"`
// StrongMatches counts matches with score >= 80.
StrongMatches int `json:"strong_matches"`
// DistinctLists names the unique source labels present in matches
// (e.g., ["OFAC SDN", "UK", "France"]).
DistinctLists []string `json:"distinct_lists"`
// GeneratedBy identifies how Text was produced:
// "deterministic" or "llm:<model-id>" (e.g., "llm:gemini-flash-latest";
// the id is the exact serving model when the API reports one).
GeneratedBy string `json:"generated_by"`
// ModelVersion is the exact model identifier when GeneratedBy starts with
// "llm:" (empty for deterministic).
ModelVersion string `json:"model_version,omitempty"`
// FallbackReason is populated only when the caller requested
// deep_summary=true but the LLM path did not execute and the response
// fell back to deterministic prose. Empty when deep_summary was not
// requested or when the LLM successfully produced the text. See the
// FallbackReason* constants for the documented values. Surfacing this
// prevents silent paid-feature non-delivery.
//
// Invariant: on a deep_summary=true response, either GeneratedBy starts
// with "llm:" or FallbackReason is non-empty. Callers can rely on this
// to detect silent paid-feature degradation without parsing prose.
FallbackReason string `json:"fallback_reason,omitempty"`
}
// Fallback reason codes for ScreenSummary.FallbackReason and
// ScreenResponse.DeepScreenFallbackReason.
const (
// FallbackReasonLLMUnavailable indicates the server is not configured to
// call an LLM (e.g., GEMINI_API_KEY is unset). Operator action required.
FallbackReasonLLMUnavailable = "llm_unavailable"
// FallbackReasonLLMFailure indicates the LLM call returned an error
// (network failure, timeout, rate limit, invalid response). The
// deterministic summary is returned instead.
FallbackReasonLLMFailure = "llm_failure"
// FallbackReasonVariationScreeningFailure (deep_screen only) indicates
// the LLM produced name variations but one or more of them could not be
// screened against the sanctions lists. The response carries every match
// that was found, but the enhanced recall is incomplete —
// ScreenResponse.DeepScreenCoverage reports exactly how many variations
// were screened out of how many were generated. Retry the request to
// re-attempt full coverage.
FallbackReasonVariationScreeningFailure = "variation_screening_failure"
)
// SummaryTopMatch identifies the single highest-scoring match within a
// screening result and carries OFAC FAQ 1591's 5-step validation set for that
// entity: name, date of birth, place of birth, nationality, ID, and address.
// Exposing these on the summary lets AI agents and compliance officers
// confirm or dismiss the top hit without a second round-trip into Matches.
//
// All fields refer to the same entity — drawn from whichever ScreenMatch in
// the response carries the maximum Score. SummaryTopMatch is a pointer field
// on ScreenSummary so it is omitted from JSON entirely when no matches were
// returned.
type SummaryTopMatch struct {
// Score is the highest combined match score across all matches (0-100).
Score float64 `json:"score"`
// UID is the source-list record identifier of the top match
// (e.g., the OFAC UID). This is the list pointer, not a government ID
// — see IDs for passports, tax IDs, and cedulas.
UID string `json:"uid,omitempty"`
// Name is the rendered display name of the top match
// ("Last, First" for individuals, otherwise the last/full-name field).
Name string `json:"name,omitempty"`
// Source is the sanctions list that produced the top match
// (e.g., "OFAC SDN", "UK", "France").
Source string `json:"source,omitempty"`
// DateOfBirth from the sanctions list, in the publisher's original format
// (commonly YYYY-MM-DD or a free-form string). Empty when not provided
// by the source list.
DateOfBirth string `json:"date_of_birth,omitempty"`
// PlaceOfBirth from the sanctions list (free-form city/region/country).
PlaceOfBirth string `json:"place_of_birth,omitempty"`
// Nationalities lists every nationality the source has on file for the
// entity. OFAC and other publishers sometimes record multiple — all are
// retained verbatim.
Nationalities []string `json:"nationalities,omitempty"`
// IDs are government identifiers (passport, tax ID, national ID, cedula)
// for the entity. Used in OFAC 5-step validation step 3 (ID match).
IDs []MatchID `json:"ids,omitempty"`
// Addresses associated with the entity on the sanctions list. Used in
// OFAC 5-step validation step 5 (address match).
Addresses []MatchAddress `json:"addresses,omitempty"`
}
// ScreenMatch represents a single matched sanctions entry.
// Includes all secondary identifiers from the source list so compliance officers
// can perform OFAC's 5-step validation (FAQ 1591) without a separate lookup.
type ScreenMatch struct {
// UID is the unique identifier from the source list (e.g., OFAC UID).
UID string `json:"uid"`
// First name of the sanctioned entity (if individual)
FirstName *string `json:"first_name,omitempty"`
// Last name or full name of the sanctioned entity
LastName *string `json:"last_name,omitempty"`
// Type of entry: Individual, Entity, Vessel, Aircraft
SdnType *string `json:"sdn_type,omitempty"`
// Combined match score (0-100), higher is stronger match.
// When secondary attributes (DOB, country) are provided in the request,
// this score is adjusted downward for mismatches.
Score float64 `json:"score"`
// Additional remarks from the source list
Remarks *string `json:"remarks,omitempty"`
// Source of the match (e.g., "OFAC SDN", "OFAC CONS", "UK", "EU")
Source string `json:"source,omitempty"`
// Sanctions programs this entity is listed under (e.g., "SDGT", "IRAN", "UKRAINE-EO13662").
// Essential for determining which regulations apply and which general licenses may be relevant.
Programs []string `json:"programs,omitempty"`
// ProhibitionType is the regulatory action this OFAC hit carries — which is
// NOT the same for every designation, and drives whether a transaction is
// blocked, rejected, or merely restricted. A full SDN listing (and a
// 50%-Rule entity) is "blocking" — freeze the property and file a blocking
// report. A CMIC listing (E.O. 13959) is a securities "cmic_investment" ban
// with no blocking. An SSI listing (E.O. 13662) is "ssi_sectoral" restricted
// dealings, not blocked. FSE and NS-PLC are reject actions; CAPTA restricts
// correspondent/payable-through accounts. Derived from Programs. Populated
// for OFAC matches only — the taxonomy is OFAC-specific; empty for other
// lists, which follow their own action frameworks. One of the Prohibition*
// constants.
ProhibitionType string `json:"prohibition_type,omitempty"`
// WeakAliasOnly is true when every pathway that produced this match fired
// via a weak OFAC AKA — no primary name, strong alias, variation, ID, or
// other list corroborates it. OFAC does not expect a weak-AKA-only hit to
// be treated like a strong-name match (FAQ 122-124), so this is the
// primary false-positive control: callers may deprioritize or auto-dismiss
// these. Per-pathway detail is on MatchSource.AliasQuality. Absent (false)
// when any corroborating pathway is present.
WeakAliasOnly bool `json:"weak_alias_only,omitempty"`
// Per-source scoring breakdown showing how and why this entity matched,
// one entry per pathway, strongest first (highest trigram_score, then
// soundex agreement). The order is deterministic: the same lists and the
// same request always produce the same array.
MatchSources []MatchSource `json:"match_sources"`
// DismissalReasons explains why the score was adjusted downward.
// Only present when secondary attributes (DOB, country, entity_type) were provided
// and a mismatch was detected.
//
// Deprecated: free-text reasons cannot be filtered, aggregated, or
// audit-mapped. Use DismissalSignals for the structured form. Both
// fields are populated in parallel during a 90-day deprecation window
// and are guaranteed to have equal length and ordered correspondence.
DismissalReasons []string `json:"dismissal_reasons,omitempty"`
// DismissalSignals is the structured form of DismissalReasons: stable
// reason codes, severity tiers, the conflicting request/target values,
// and the exact point reduction each signal applied to the score.
//
// Always emitted — empty array means "no penalties applied," never
// "we forgot." See the Dismissal* constants for the stable code set.
// Each signal's position in this array corresponds 1:1 with the
// position of its free-text form in DismissalReasons.
DismissalSignals []DismissalSignal `json:"dismissal_signals"`
// MatchedVia names which submitted identifier(s) triggered this match,
// when the hit came from ID-based screening (ScreenRequest.IDNumber or
// any entry in ScreenRequest.IDs). Empty when the match came only from
// name-based screening. A single match may carry multiple entries when
// several submitted IDs all resolve to the same sanctioned entity.
MatchedVia []IDInput `json:"matched_via,omitempty"`
// Secondary identifiers from the sanctions list for OFAC 5-step validation.
// These enable compliance officers to compare against transaction data.
Addresses []MatchAddress `json:"addresses,omitempty"`
IDs []MatchID `json:"ids,omitempty"`
DateOfBirth string `json:"date_of_birth,omitempty"`
PlaceOfBirth string `json:"place_of_birth,omitempty"`
Nationalities []string `json:"nationalities,omitempty"`
Citizenships []string `json:"citizenships,omitempty"`
}
// MatchAddress is an address associated with a sanctioned entity.
type MatchAddress struct {
Address1 string `json:"address1,omitempty"`
Address2 string `json:"address2,omitempty"`
City string `json:"city,omitempty"`
StateOrProvince string `json:"state_or_province,omitempty"`
PostalCode string `json:"postal_code,omitempty"`
Country string `json:"country,omitempty"`
}
// MatchID is a government identifier (passport, tax ID, cedula) for a sanctioned entity.
type MatchID struct {
IDType string `json:"id_type"`
Number string `json:"number"`
Country string `json:"country,omitempty"`
}
// MatchSource provides scoring details for a single match pathway.
// An entity may match via multiple sources (e.g., both direct SDN and AI variation).
type MatchSource struct {
// How the match was found: "ofac_sdn", "ofac_aka", "ofac_ai_variation",
// "ofac_cons", "ofac_cons_aka" (OFAC's Consolidated non-SDN lists),
// "ofac_id", "uk_designation", "uk_alias", "uk_non_latin", "uk_id",
// "<list>_designation", "<list>_alias", "<list>_id" for the other lists,
// "ofac_native_script" and "un_original_script" (a name the publisher
// gives in the party's own script), "deep_screen", or
// "internal_watchlist". Treat an unrecognized value as another way the
// same record was found.
Source string `json:"source"`
// Raw trigram similarity score (0-100) for this source
TrigramScore float64 `json:"trigram_score"`
// Whether the last name matched phonetically via Soundex
SoundexMatch bool `json:"soundex_match"`
// SoundexBoost is how many points (0-100) this pathway's phonetic name
// agreement actually added on top of TrigramScore. The two sum to the
// pathway's contribution, so a low TrigramScore with a large SoundexBoost
// is a phonetic collision rather than a close literal match.
//
// It is the contribution, not a fixed amount: phonetic agreement is
// weighted by the literal similarity it corroborates, so the same
// agreement adds more to a strong literal match than to a weak one.
SoundexBoost float64 `json:"soundex_boost,omitempty"`
// The form that matched, when it is not the record's own name: the
// AI-generated variation (source "ofac_ai_variation" or "deep_screen"),
// or the published native-script name (source "uk_non_latin" or
// "un_original_script").
Variation string `json:"variation,omitempty"`
// Why that form is a name of this party: the reason Gemini gave for a
// variation, the script for "uk_non_latin", or that the publisher lists
// it as the party's original-script name for "un_original_script".
Reason string `json:"reason,omitempty"`
// MatchedText is the source-list string that produced this pathway's
// trigram score — the actual primary name, alias, or variation text
// the comparison fired against. Lets consumers distinguish "matched
// primary name 'Vladimir Putin'" from "matched 4-character alias
// 'JOHN'" and is the foundation for length- and quality-aware
// reweighting (and the calibration corpus those depend on).
MatchedText string `json:"matched_text,omitempty"`
// MatchedLength is the rune count of MatchedText. Pre-computed so
// aggregations like "fraction of dismissed alerts with matched_length
// <= 5" can run server-side without scanning every match.
MatchedLength int `json:"matched_length,omitempty"`
// AliasQuality is OFAC's alias-strength classification — "weak" or
// "strong" — when this pathway fired via an OFAC AKA (source "ofac_aka" or
// "ofac_cons_aka"); empty for primary-name, variation, ID, and non-OFAC
// pathways. OFAC flags weak AKAs because they are a dominant false-positive
// source and does not expect a weak-AKA-only hit to be treated like a
// strong-name match (FAQ 122-124). Use it to deprioritize or suppress hits
// driven solely by a weak alias — see ScreenMatch.WeakAliasOnly.
AliasQuality string `json:"alias_quality,omitempty"`
}
// =============================================================================
// Dismissal Signals
// =============================================================================
//
// Structured replacement for the legacy ScreenMatch.DismissalReasons []string
// field. Every penalty applied during attribute comparison emits a
// DismissalSignal carrying the canonical reason code, severity, conflicting
// request/target values, and the score impact.
//
// Reason codes are stable identifiers — consumers filter, aggregate, and
// audit-map on them. They are grounded in OFAC FAQ 5 ("How do I determine
// if I have a valid OFAC match?") where applicable: Step 2 (entity-type
// sanity), Step 3 (single-token name match), and Step 4 (full-entry
// comparison covering DOB, country, and the broader identity set).
// DismissalSignal is a structured reason a match's score was reduced.
type DismissalSignal struct {
// Field that drove the signal: "date_of_birth", "country",
// "entity_type", or "name".
Field string `json:"field"`
// ReasonCode is one of the Dismissal* constants below. Stable across
// releases — clients depend on these strings.
ReasonCode string `json:"reason_code"`
// Severity is the strength tier of this signal. High signals are
// safe-to-auto-dismiss; low signals are advisory.
Severity DismissalSeverity `json:"severity"`
// RequestValue is the value the request supplied, rendered as text.
RequestValue string `json:"request_value,omitempty"`
// TargetValue is the value the source list carries, rendered as text.
TargetValue string `json:"target_value,omitempty"`
// ImpactOnScore is the point reduction this signal applied to the
// match score (negative, on the same 0-100 scale as Score).
ImpactOnScore float64 `json:"impact_on_score"`
// EditDistance is the character distance between RequestValue and
// TargetValue. Set only by name_near_miss; absent otherwise. A near miss
// is only actionable if you can see how near — "one character from a
// listed name" is a different object from "scored 78 by coincidence", and
// without the number the response cannot tell you which you have.
EditDistance int `json:"edit_distance,omitempty"`
}
// DismissalSeverity is the strength tier of a DismissalSignal. Derived
// from penalty depth — locked in code, not data, so the mapping is
// reproducible from the response alone.
type DismissalSeverity string
const (
// SeverityInfo marks a signal that records an evaluation outcome rather
// than dismissal evidence: the caller supplied an attribute and the
// matched record carries nothing to compare it against. Its
// ImpactOnScore is always 0. Do not read it as weak exculpatory
// evidence — it is the absence of evidence in either direction.
SeverityInfo DismissalSeverity = "info"
SeverityLow DismissalSeverity = "low"
SeverityMedium DismissalSeverity = "medium"
SeverityHigh DismissalSeverity = "high"
)
// Dismissal reason codes. Stable identifiers — clients filter on these.
//
// - DismissalEntityTypeMismatch and DismissalPartialNameMatchSingleToken
// are OFAC FAQ 5 Steps 2 and 3 respectively (not-a-valid-match
// conditions).
// - The DOB and country codes are OFAC FAQ 5 Step 4 (full-entry
// comparison). The "_far" suffix splits today's overloaded
// dob_year_mismatch and dob_mismatch into distinct codes per
// penalty depth.
// - DismissalPhoneticNameBoost is the one entry carrying a POSITIVE
// ImpactOnScore. It reports how much of a match's score came from a
// phonetic name agreement rather than from literal similarity, and is
// emitted only for a match nothing reduced — otherwise the array would be
// empty for exactly the matches that reach the alert threshold, since a
// penalty large enough to record usually drops a match below it. It never
// changes a score; it accounts for one.
// - The "_not_comparable" codes report that the caller supplied an
// attribute the matched record carries no value for, so Step 4 could
// not be performed on that field. They carry SeverityInfo and an
// ImpactOnScore of 0. Step 4 requires evaluating the attribute, and
// "the record has no data" is an evaluation outcome — without it, a
// match that was never compared is indistinguishable from one that was
// compared and agreed. Attribute coverage varies by source, so an
// unpenalized match from a list carrying no countries can otherwise
// outrank a penalized match for the same person with no marker of the
// asymmetry.
const (
DismissalEntityTypeMismatch = "entity_type_mismatch"
DismissalPartialNameMatchSingleToken = "partial_name_match_single_token"
DismissalDOBYearNearMiss = "dob_year_near_miss"
DismissalDOBYearMismatch = "dob_year_mismatch"
DismissalDOBYearMismatchFar = "dob_year_mismatch_far"
DismissalDOBNearMiss = "dob_near_miss"
DismissalDOBMismatch = "dob_mismatch"
DismissalDOBMismatchFar = "dob_mismatch_far"
DismissalCountryMismatch = "country_mismatch"
DismissalDOBNotComparable = "dob_not_comparable"
DismissalCountryNotComparable = "country_not_comparable"
DismissalEntityTypeNotComparable = "entity_type_not_comparable"
DismissalPhoneticNameBoost = "phonetic_name_boost"
DismissalNameNearMiss = "name_near_miss"
DismissalInsufficientData = "insufficient_data_to_discriminate"
)
// =============================================================================
// Sanctions List Selection
// =============================================================================
// List constants for selective screening.
const (
ListOFAC = "ofac"
ListUK = "uk"
ListEU = "eu"
ListFrance = "france"
ListBelgium = "belgium"
ListNetherlands = "netherlands"
ListUN = "un"
ListCanada = "canada"
ListAustralia = "australia"
)
// AllLists is the complete set of supported sanctions lists.
var AllLists = []string{ListOFAC, ListUK, ListEU, ListFrance, ListBelgium, ListNetherlands, ListUN, ListCanada, ListAustralia}
// validLists is the lookup set for O(1) validation.
var validLists = map[string]bool{
ListOFAC: true, ListUK: true, ListEU: true,
ListFrance: true, ListBelgium: true, ListNetherlands: true,
ListUN: true, ListCanada: true, ListAustralia: true,
}
// ValidateListNames returns an error message for the first invalid list name, or "".
func ValidateListNames(lists []string) string {
for _, l := range lists {
if !validLists[l] {
return fmt.Sprintf("unknown list %q; valid values: %s", l, strings.Join(AllLists, ", "))
}
}
return ""
}
// DeduplicateLists removes duplicate list names, preserving order.
func DeduplicateLists(lists []string) []string {
seen := make(map[string]bool, len(lists))
out := make([]string, 0, len(lists))
for _, l := range lists {
if !seen[l] {
seen[l] = true
out = append(out, l)
}
}
return out
}
// =============================================================================
// Common Types
// =============================================================================
// Error type categories for machine-readable error handling.
//
// Fault attribution is a contract, not a convention: a 4xx always describes
// something about the request or the account — the API key really is unknown,
// the tenant really is not provisioned, the record really is absent — and it
// will still be true on retry. An infrastructure failure is always 5xx with
// type api_error, never dressed up as 401, 403, or 404.
//
// Clients can therefore treat 4xx as terminal and 5xx as retryable. That
// distinction is load-bearing: an outage reported as 401 leads customers to
// rotate working credentials, and one reported as 404 leads them to re-enroll
// records that already exist or abandon jobs that are still running.
const (
ErrTypeInvalidRequest = "invalid_request_error"
ErrTypeAuthentication = "authentication_error"
ErrTypeForbidden = "forbidden_error"
ErrTypeRateLimit = "rate_limit_error"
ErrTypeAPI = "api_error"
ErrTypeNotFound = "not_found_error"
ErrTypeConflict = "conflict_error"
ErrTypeComplianceRule = "compliance_rule_error"
ErrTypePaymentRequired = "payment_required"
)
// Error code constants for machine-readable error handling.
const (
CodeInvalidBody = "invalid_request_body"
CodeNameRequired = "name_required"
CodeQueryRequired = "query_required"
CodeNameTooLong = "name_too_long"
CodeMissingParameter = "missing_parameter"
CodeInvalidParameter = "invalid_parameter"
CodeKeyRequired = "api_key_required"
CodeKeyInvalid = "api_key_invalid"
CodeAPIKeyRevoked = "api_key_revoked"
CodeKeyPrefixAmbiguous = "key_prefix_ambiguous"
CodeKeyRevokeForbidden = "api_key_revoke_forbidden"
CodeTenantNotProvisioned = "tenant_not_provisioned"
CodeTierInsufficient = "tier_insufficient"
CodeRateLimitExceeded = "rate_limit_exceeded"
CodeBatchTooLarge = "batch_too_large"
CodeTooManyIDs = "too_many_ids"
CodeNotFound = "not_found"
CodeInvalidTransition = "invalid_status_transition"
CodeInvalidReason = "invalid_reason_code"
CodeInvalidDisposition = "invalid_disposition"
CodeDispositionRequired = "disposition_required"
CodeGLCitationRequired = "gl_citation_required"
CodeFourEyesViolation = "four_eyes_violation"
CodeConcurrentModification = "concurrent_modification"
CodeInvalidAssignee = "invalid_assignee"
CodeInvalidActor = "invalid_actor"
CodeTeamMemberNotFound = "team_member_not_found"
CodeTeamMemberLimit = "team_member_limit_exceeded"
CodeNoteEmpty = "note_empty"
CodeNoteTooLong = "note_too_long"
CodeInternalError = "internal_error"
CodeKeyRevoked = "encryption_key_revoked"
CodeConfirmationRequired = "confirmation_required"
CodeMethodNotAllowed = "method_not_allowed"
CodeWebhookURLInvalid = "webhook_url_invalid"
CodeWebhookSecretTooShort = "webhook_secret_too_short"
CodeWebhookNotFound = "webhook_not_found"
CodeWebhookLimitExceeded = "webhook_limit_exceeded"
CodeWebhookSignatureInvalid = "webhook_signature_invalid"
CodeTrialExpired = "trial_expired"
CodeSignupClosed = "signup_closed"
CodeInviteRequired = "invite_code_required"
CodeInviteInvalid = "invite_code_invalid"
CodeInviteExpired = "invite_code_expired"
CodeInviteExhausted = "invite_code_exhausted"
CodeInviteRevoked = "invite_code_revoked"
CodeIdempotencyMismatch = "idempotency_key_mismatch"
CodeIdempotencyInProgress = "idempotency_in_progress"
CodeIdempotencyKeyTooLong = "idempotency_key_too_long"
CodeScopeRequired = "scope_required"
CodeScopeNoChange = "scope_no_change"
CodeFeatureNoChange = "feature_no_change"
CodeQuotaNoChange = "quota_no_change"
CodeQuotaTierIneligible = "quota_tier_ineligible"
CodeReplayUnsupportedChannel = "replay_unsupported_channel"
CodeInvalidVersion = "invalid_version"
// CodeCoverageUnavailable: the screening could not confirm which
// sanctions list snapshots it ran against, so the response would have
// reported coverage it did not verify. 503 — the request is NOT answered
// with a shortened lists_screened, because a partial screen is
// indistinguishable on the wire from a legitimately narrow one. Retry;
// if it persists, contact support@noblesight.io.
//
// It is also the refusal when the server has no sanctions-list index it
// can screen against (see "Screening deadlines" above): the 503 then
// carries a Retry-After header, in seconds — a few seconds while an
// index for an as_of or replay is prepared, longer while the server
// waits to confirm its lists are current. Name screening only; the rest
// of the API is unaffected.
CodeCoverageUnavailable = "coverage_unavailable"
// CodeCoverageDegraded refuses a live screening whose coverage would be
// degraded (a stale requested list, or a subset screen) when the
// request did not carry allow_degraded_coverage (#230). HTTP 503. The
// message names the offending lists and the opt-in parameter. A list
// whose publisher is down ("source_unavailable" on GET /v1/lists) does
// not refuse: it is screened at its last snapshot and named in coverage
// (#749).
CodeCoverageDegraded = "coverage_degraded"
// CodeScreeningTimeout: the screening did not finish within its deadline
// (ScreenDeadline, or ScreenDeadlineDeep with deep_screen/deep_summary).
// 504. No partial result is returned. The attempt is recorded as a failed
// screening, retrievable by the request_id and trace_id in the error
// body. Retry the screening.
CodeScreeningTimeout = "screening_timeout"
// CodeRequestCanceled appears only in the stored response of a failed
// screening (GET /v1/export), never on the wire: the caller closed the
// connection before the screening finished, so no answer was delivered.
CodeRequestCanceled = "request_canceled"
// CodeAlertUnavailable (503): the screening produced a result that must
// carry an alert (a name match at or above the tenant's threshold or a
// near miss, or a blocked ownership determination) and the alert could
// not be written (#708). No result is returned and nothing of the
// attempt is committed: the record, the alert, its webhook and its
// audit row commit together or not at all, so a hit nobody is told
// about never exists. The attempt is recorded as failed under the
// returned request_id and trace_id; retry the screening.
CodeAlertUnavailable = "alert_unavailable"
// CodeReplayUnsupportedOutcome: POST /v1/replay was asked to re-run a
// failed screening. A failed screening has no result to compare against;
// screen the name again instead.
CodeReplayUnsupportedOutcome = "replay_unsupported_outcome"
)
// Error is the standard error response following Stripe's error model.
type Error struct {
// Error category: invalid_request_error, authentication_error, rate_limit_error, api_error
Type string `json:"type"`
// Machine-readable error code for programmatic handling
Code string `json:"code"`
// Human-readable error message
Message string `json:"message"`
// Which request parameter caused the error (if applicable)
Param string `json:"param,omitempty"`
// Server-generated request ID for debugging and audit correlation
RequestID string `json:"request_id"`
// TraceID is set on POST /v1/screen errors raised after the request was
// accepted for screening (e.g. screening_timeout). That attempt is in the
// audit trail as a failed screening under this trace ID.
TraceID string `json:"trace_id,omitempty"`
}
// ResponseMeta contains metadata included in every API response.
type ResponseMeta struct {
// Legal disclaimer bounding Noble Sight's liability
Disclaimer string `json:"disclaimer"`
}
// Disclaimer is the standard legal disclaimer included in all screening API responses.
// This text is a material part of Noble Sight's liability boundary and must not be
// modified without legal review.
const Disclaimer = "Noble Sight provides sanctions screening results for informational purposes only. " +
"This service is not a substitute for a comprehensive sanctions compliance program. " +
"Noble Sight does not provide legal, regulatory, or compliance advice. " +
"Screening results reflect data available at the time of the request and may not capture all " +
"sanctions designations, aliases, or name variations. " +
"Final screening decisions, risk assessments, and compliance obligations remain the sole " +
"responsibility of the subscribing institution. " +
"Use of this service does not satisfy or replace any obligation under OFAC regulations, " +
"the Bank Secrecy Act, or any other applicable law."
// =============================================================================
// Pagination — the uniform contract for every collection endpoint
// =============================================================================
//
// Every list endpoint (alerts, portfolio, watchlist, audit export, case
// activity) returns the same envelope and paginates the same way. This section
// is the contract; handlers must not deviate.
//
// # Envelope
//
// A list response is always:
//
// { "data": [ ... ], "has_more": true, "meta": { "disclaimer": "..." } }
//
// `data` is the page of items (the array key is ALWAYS "data" — never "alerts",
// "entities", "records", etc.). `has_more` is true when at least one more item
// exists past this page. There is no other top-level shape.
//
// # Cursor pagination only — never offset
//
// Pagination is keyset (cursor) based:
//
// GET /v1/portfolio?after=<id>&limit=<n>
//
// - `after` — exclusive cursor: return items with id > after. Omit (or 0) for
// the first page. The cursor is the `id` of the last item in the previous
// page's `data`. Results are ordered by `id` ascending (chronological and
// stable, since id is a monotonic BIGSERIAL). A descending/`before` cursor
// may be ADDED later without breaking this contract.
// - `limit` — page size; defaults to DefaultPageLimit, hard-capped at
// MaxPageLimit. Values above the cap are clamped, not rejected.
//
// Offset/page pagination (`?offset=`, `?page=`) is PROHIBITED. It is O(n) at
// depth — the database scans and discards `offset` rows on every request — and
// it returns duplicate or skipped rows when items are inserted concurrently,
// which is unacceptable for an append-only audit system. The scale that forces
// this: a portfolio-monitoring customer (e.g. a top-tier bank) may enroll tens
// of millions of entities; offset page 500,000 would scan ~50M rows per call,
// while a keyset cursor stays O(log n + limit) at any depth.
//
// # No `total` in list responses — counts live in a /stats companion
//
// List responses do NOT carry a row count. COUNT(*) over a large, filtered, or
// date-ranged set adds latency and lock contention to every page fetch and is
// racy under concurrent writes. Counts are instead a first-class, cheap read on
// a dedicated companion endpoint, uniformly: a collection at `/v1/<name>`
// exposes its counts at `/v1/<name>/stats`. Every stats response carries at
// least a `total`; most add a small, cheap breakdown (by_status, by_score_band,
// by_action, …). A stats endpoint honors the SAME filters as its list sibling,
// so the count matches the page the caller is browsing.
//
// /v1/alerts → /v1/alerts/stats (AlertStatsResponse)
// /v1/portfolio → /v1/portfolio/stats (PortfolioStatsResponse)
// /v1/webhooks → /v1/webhooks/stats (WebhookStatsResponse)
// /v1/alerts/activity → /v1/alerts/activity/stats (ActivityStatsResponse)
//
// # Full extraction is not pagination
//
// Paging through millions of rows via GET is for browsing/triage, not bulk
// extraction. A customer who needs their entire portfolio or audit history
// pulls it via the async export/batch job, which is built for volume.
//
// # Per-endpoint application
//
// /v1/alerts cursor + filters (already the reference implementation)
// /v1/portfolio cursor (requires a (tenant_id, id) index — see migrations)
// /v1/watchlist cursor
// /v1/export/bulk cursor + hard limit; large pulls use the export job
// /v1/alerts/activity cursor + hard limit
// /v1/webhooks NO pagination — capped at a handful per tenant; returns
// the {data} envelope with every webhook, no cursor params.
// List is the uniform envelope returned by every collection endpoint. The
// generic parameter is the item type (e.g. List[AlertResponse]). The "data"
// key and "has_more" flag are invariant across all list endpoints; meta is
// injected by the response writer.
type List[T any] struct {
// Data is the page of items, ordered by id ascending.
Data []T `json:"data"`
// HasMore reports whether at least one item exists past this page. When
// true, request the next page with ?after=<id of the last item in Data>.
HasMore bool `json:"has_more"`
}
// Pagination bounds for list endpoints.
const (
DefaultPageLimit = 50 // page size when ?limit is omitted
MaxPageLimit = 100 // hard cap; larger ?limit values are clamped to this
)
// PageParams is the parsed cursor-pagination query shared by list handlers.
// Produced by parsePageParams; never construct it from offset/page inputs.
type PageParams struct {
// After is the exclusive id cursor: return items with id > After.
// Zero means start from the beginning.
After int64
// Limit is the clamped page size, in [1, MaxPageLimit].
Limit int
}
// =============================================================================
// Changelog
// =============================================================================
//
// GET /v1/changelog returns the API's release notes as structured JSON so that
// customers — banks, AI compliance agents, MCP clients — can surface "what's
// new" inside their own dashboards without scraping HTML. The endpoint is
// public (no API key required) so prospects and discovery tools can read it.
//
// The source of truth is a checked-in Go slice (api/v1/changelog.go); new
// entries ship with the binary version and are reviewed in PRs.
// Changelog categories. Follows the Keep-a-Changelog convention
// (https://keepachangelog.com).
const (
ChangeAdded = "added"
ChangeChanged = "changed"
ChangeDeprecated = "deprecated"
ChangeRemoved = "removed"
ChangeFixed = "fixed"
ChangeSecurity = "security"
)
// ChangelogEntry is one published API change.
type ChangelogEntry struct {
// Release date in YYYY-MM-DD (UTC).
Date string `json:"date"`
// One of ChangeAdded, ChangeChanged, ChangeDeprecated, ChangeRemoved,
// ChangeFixed, ChangeSecurity.
Category string `json:"category"`
// Single-line headline. Required.
Summary string `json:"summary"`
// Optional longer body. Plain text; no HTML.
Details string `json:"details,omitempty"`
// Optional endpoint the change scopes to (e.g. "/v1/screen").
Endpoint string `json:"endpoint,omitempty"`
// Breaking marks this entry as an API version boundary: a change that
// altered or removed existing response shape, minting a new dated
// Noble-Version equal to Date. The set of supported API versions is derived
// from exactly the Breaking entries (see version.go), so the changelog is
// the single source of truth and the two cannot drift. Additive entries
// leave this false and never mint a version.
Breaking bool `json:"breaking,omitempty"`
// Verification is a customer-runnable proof the change behaves as
// described — Steps a caller executes against the live API with their own
// key, an Expect assertion, and how to replay it for audit. Required on
// every fix/feature/breaking entry dated on or after the verification
// cutover (see changelog.go): a compliance vendor's changes must be
// independently provable by the customer, not asserted. Optional (nil) on
// historical entries that predate the policy.
Verification *ChangelogVerification `json:"verification,omitempty"`
}
// ChangelogVerification is a self-contained, customer-runnable check that a
// changelog entry's change works as described. It carries no privileged steps:
// every command runs against the public API with the caller's own key.
type ChangelogVerification struct {
// Steps are exact, copy-pasteable requests that exercise the change.
Steps []string `json:"steps"`
// Expect is the precise pass assertion (e.g. a field == value condition).
Expect string `json:"expect"`
// Audit is how to independently replay or prove the result after the fact
// (trace id, export, list_versions). Optional.
Audit string `json:"audit,omitempty"`
// Regression links the test(s) that lock the change. Optional.
Regression string `json:"regression,omitempty"`
}
// ChangelogResponse is returned by GET /v1/changelog.
type ChangelogResponse struct {
// Entries are ordered newest first.
Entries []ChangelogEntry `json:"entries"`
// EntryCount is len(Entries). Present so a consumer can detect that
// entries were added without hashing or diffing the list.
EntryCount int `json:"entry_count"`
// Fingerprint identifies this exact changelog content. It changes if and
// only if the entries change, and is stable across identical requests.
//
// It exists because a regulated customer has to be able to show an
// examiner when their screening vendor's behaviour changed. Before this,
// the only correct way to detect a Noble behaviour change was to store
// every entry and diff them on each poll: entries carry no identifier,
// several can share a date, and Noble-Version deliberately does not move
// for additive or fixed entries. A customer's vendor-change guard missed
// four behaviour changes shipped on one day for exactly that reason
// (#302).
//
// The same value is served as the response ETag, so a guard can poll with
// If-None-Match and get 304; this field is for consumers that log the body
// rather than the headers, and want the fingerprint on the record.
Fingerprint string `json:"fingerprint"`
Meta ResponseMeta `json:"meta"`
}
// =============================================================================
// Sanctions list versions
// =============================================================================
//
// GET /v1/lists returns the active publisher snapshot for every sanctions list
// Noble screens against. Public — no API key required — so customers and AI
// compliance agents can answer "are you screening against the latest OFAC?"
// without spending screening quota. The same per-list version info is also
// embedded in every /v1/screen response's list_versions field; this endpoint
// is the standalone fetch path used by status dashboards and the
// noble://sanctions-lists MCP resource.
//
// One entry per list. Lists that have never been imported into this Noble
// deployment are omitted (rather than emitting a sentinel row) so consumers
// don't need to special-case missing data.
// SanctionsListVersion describes the active publisher snapshot for a single
// sanctions list.
type SanctionsListVersion struct {
// List is the canonical short identifier matching the values accepted in
// ScreenRequest.Lists: "ofac", "uk", "eu", "france", "belgium",
// "netherlands", "un", "canada", "australia".
List string `json:"list"`
// DisplayName is the human-readable name surfaced in dashboards
// (e.g., "OFAC SDN", "UK OFSI Consolidated", "EU Financial Sanctions").
DisplayName string `json:"display_name"`
// PublishID is the publish_info row identifier — the audit pointer back
// to the imported source file.
PublishID int `json:"publish_id"`
// PublishDate is the date the publisher released this version (YYYY-MM-DD),
// taken verbatim from the source list.
PublishDate string `json:"publish_date"`
// RecordCount is the number of entries in this version.
RecordCount int `json:"record_count"`
// ImportedAt is when Noble ingested this version (RFC 3339, UTC).
// Compare against PublishDate to see how stale the imported snapshot is.
ImportedAt string `json:"imported_at"`
// HistoryFrom is the instant this list's point-in-time history begins
// (RFC 3339, UTC): Noble's first import of it. A POST /v1/screen as_of
// at or after it screens this list as it stood then; an as_of before it
// cannot, and is refused or warned about (see ScreenRequest.AsOf).
HistoryFrom string `json:"history_from"`
// LastChecked is when Noble last polled the upstream publisher for this
// list (RFC 3339, UTC) — the ingestion heartbeat. Unlike ImportedAt, it
// advances on every poll even when the source is unchanged, so a recent
// LastChecked is the proof that ingestion is live and you are on the
// current published version. A LastChecked far in the past means the
// watcher is not running, regardless of how healthy ImportedAt looks.
// For OFAC (which polls the SDN and Consolidated files separately) this
// is the oldest of the two checks, so a single dead watcher surfaces here.
LastChecked string `json:"last_checked"`
// LastImport is when the upstream content last actually changed and was
// loaded (RFC 3339, UTC). Empty if the content has not changed since this
// deployment began watching. For OFAC it is the most recent change across
// both source files.
LastImport string `json:"last_import"`
// Status is the ingestion-freshness verdict for this list, measured in
// the list's poll intervals:
// "ok" — LastChecked is within FreshWithinS; the watcher is
// polling and this snapshot is current.
// "degraded" — LastChecked is older than FreshWithinS but within
// StaleAfterS: several polls in a row have failed. Noble
// is alarmed and retrying; screening continues against
// the snapshot described here, which may be missing a
// publisher update of the last hour or so.
// "stale" — LastChecked is older than StaleAfterS or unknown; treat
// ingestion as broken and investigate before relying on
// screening results for this list. POST /v1/screen
// refuses a live screening that includes it (503
// coverage_degraded) unless the request carries
// allow_degraded_coverage.
// "source_unavailable" — LastChecked is older than StaleAfterS
// because the publisher is down, not Noble's ingestion
// (#749): the watcher is still polling, the publisher
// answers each poll with its own HTTP 5xx, and other
// lists poll normally. Screening continues against the
// snapshot described here, and every screening that
// includes the list carries a list_source_unavailable
// coverage issue and warning. SourceError and
// SourceUnavailableSince describe the outage.
// The verdict is intentionally fail-closed: when in doubt it reports
// "stale" rather than implying freshness it cannot prove. Only a
// publisher's own server error earns "source_unavailable"; a timeout,
// connection, DNS or TLS failure, a 4xx, or a response that is not the
// list stays "stale", because each may be Noble's to fix.
Status string `json:"status"`
// FreshWithinS is the longest, in seconds, LastChecked may lag the time
// of the response with Status still "ok": ListDegradedAfterPolls of this
// list's poll interval (1800 for a list polled every five minutes).
FreshWithinS int `json:"fresh_within_s"`
// StaleAfterS is the age of LastChecked, in seconds, beyond which Status
// is "stale": ListStaleAfterPolls of this list's poll interval (7200 for
// a list polled every five minutes).
StaleAfterS int `json:"stale_after_s"`
// SourceError is the publisher's answer to Noble's last poll, e.g.
// "http_500"; present when Status is "source_unavailable".
SourceError string `json:"source_error,omitempty"`
// SourceUnavailableSince is when Noble first saw the publisher fail
// after its last successful poll (RFC 3339, UTC); present when Status is
// "source_unavailable".
SourceUnavailableSince string `json:"source_unavailable_since,omitempty"`
// EscalateAfterS is how long, in seconds, a publisher outage of this
// list may last before it is escalated: the list's median gap between
// publications, floored at one day and capped at seven. Inside it a
// missed publication is less likely than not. Screening never refuses
// on it; past it, Escalated is true, Noble's operator is escalated and
// every screening's warning says the snapshot may be missing
// designations.
EscalateAfterS int `json:"escalate_after_s"`
// Escalated is true when Status is "source_unavailable" and the outage
// has lasted longer than EscalateAfterS, or the publisher's own feed has
// announced a newer version that could not be downloaded.
Escalated bool `json:"escalated"`
// Monitoring reports whether portfolio monitoring has caught up with
// this list's changes:
// "ok" — every change Noble has imported from this list has been
// queued for screening against monitored portfolios.
// "delayed" — a change imported more than ListMonitoringDelayAfter ago
// is not yet queued. Noble keeps retrying on its own; the
// change is recorded durably, so its monitoring alerts
// arrive late, not never. Screening (POST /v1/screen) is
// unaffected: it already reads the imported version.
Monitoring string `json:"monitoring"`
// LastChange traces the most recent content change of this list through
// every hop of the monitoring chain, with the duration of each hop, so a
// customer can see — not infer — how long a list change takes to reach
// them (#555). Nil only when this list has never recorded a change delta
// (a deployment watching it from before monitoring existed).
LastChange *ListLastChange `json:"last_change"`
}
// ListLastChange is the hop-by-hop timeline of a list's most recent content
// change: publisher → detected → imported → queued → re-screened →
// (tenant's) first alert → first webhook delivery. Hops 1–4 are global
// facts; the alert and delivery hops are the calling tenant's own and are
// null, with NullReason stating why, when the tenant had no portfolio match
// or no webhook delivery for this change. Durations are whole seconds and
// are each computed from the two stored instants they name; a null input
// yields a null duration, never a guess.
type ListLastChange struct {
// PublishID is the publish_info row of the change — the same audit
// pointer PublishID carries above, but for the latest change rather
// than the latest import.
PublishID int `json:"publish_id"`
// SourceLastModified is the publisher's own instant for the changed
// document (its HTTP Last-Modified), RFC 3339 UTC; empty when the
// publisher exposes none.
SourceLastModified string `json:"source_last_modified,omitempty"`
// SourceTime says whether SourceLastModified is the publisher's own
// instant ("publisher") or unavailable ("unknown"). DetectedAfterS is
// only computable — and only present — when it is "publisher".
SourceTime string `json:"source_time"`
// DetectedAt is when Noble's watcher committed the change (the delta
// outbox row's instant, written in the import transaction), RFC 3339 UTC.
DetectedAt string `json:"detected_at"`
// ImportedAt is when the change's import transaction committed. It
// equals DetectedAt to within the transaction, and is carried separately
// so the response states both stored instants rather than aliasing them.
ImportedAt string `json:"imported_at"`
// JobEnqueuedAt is when the change's first reverse-screen job row was
// created; empty while the outbox has not yet been drained. A change's
// jobs are the ones queued for that change itself: engine re-screens,
// variation backfills and operator reprobes that later run against the
// same list version are not the change's work and never move its hops.
JobEnqueuedAt string `json:"job_enqueued_at,omitempty"`
// JobFinishedAt is when the change's last reverse-screen job completed
// — the instant every monitored portfolio had been screened against the
// change; empty until then. A job of the change's own that stalled and
// was retried or requeued counts at its real, late finish.
JobFinishedAt string `json:"job_finished_at,omitempty"`
// FirstAlertAt is when the calling tenant's first monitoring alert
// raised by this change's own jobs was created; empty when the change matched nothing in the
// tenant's portfolio (see NullReason).
FirstAlertAt string `json:"first_alert_at,omitempty"`
// FirstDeliveredAt is when the first webhook delivery for such an alert
// completed; empty when the tenant has no webhook or no alert (see
// NullReason).
FirstDeliveredAt string `json:"first_delivered_at,omitempty"`
// DetectedAfterS is DetectedAt minus SourceLastModified, in seconds:
// how long the change sat at the publisher before Noble saw it. Null
// when SourceTime is "unknown".
DetectedAfterS *int64 `json:"detected_after_s"`
// QueuedAfterS is JobEnqueuedAt minus DetectedAt, in seconds. Null
// until the job is enqueued.
QueuedAfterS *int64 `json:"queued_after_s"`
// RescreenedAfterS is JobFinishedAt minus DetectedAt, in seconds: the
// re-screen hop the notify-within-minutes budget measures. Null until
// every job for the change completes.
RescreenedAfterS *int64 `json:"rescreened_after_s"`
// DeliveredAfterS is FirstDeliveredAt minus DetectedAt, in seconds, for
// the calling tenant. Null with NullReason when there is no delivery.
DeliveredAfterS *int64 `json:"delivered_after_s"`
// NullReason states why the tenant-scoped hops are null when they are:
// "no_portfolio_match" (the change raised no alert for this tenant) or
// "no_webhook_delivery" (an alert exists but no webhook delivery does).
// Empty when DeliveredAfterS is set.
NullReason string `json:"null_reason,omitempty"`
}
// Sanctions list ingestion-freshness verdicts (SanctionsListVersion.Status).
const (
// ListStatusOK means the list was polled within FreshWithinS.
ListStatusOK = "ok"
// ListStatusDegraded means several consecutive polls have failed: the
// last successful poll is older than FreshWithinS but within StaleAfterS.
ListStatusDegraded = "degraded"
// ListStatusStale means the list has not been polled within StaleAfterS
// (or the last-poll time is unknown). Fail-closed default.
ListStatusStale = "stale"
// ListStatusSourceUnavailable means the list has not been polled within
// StaleAfterS because its publisher is serving server errors while
// Noble's watcher is healthy (#749). Screening continues against the
// last imported snapshot and says so.
//
// Where the publisher has a feed of its own files (the EU's FSF feed),
// Noble reads it on every poll: it supplies the current download link,
// and when downloads fail but the feed shows nothing published since
// Noble's last confirmed poll, the snapshot is confirmed current and
// the list stays "ok".
ListStatusSourceUnavailable = "source_unavailable"
)
// Freshness bounds, in poll intervals of the list (SanctionsListVersion
// FreshWithinS and StaleAfterS are these multiplied out, in seconds). Every
// list is polled every five minutes.
const (
ListDegradedAfterPolls = 6
ListStaleAfterPolls = 24
)
// Portfolio-monitoring verdicts for SanctionsListVersion.Monitoring.
const (
ListMonitoringOK = "ok"
ListMonitoringDelayed = "delayed"
)
// ListMonitoringDelayAfter is how long an imported list change may wait to
// be queued for portfolio monitoring before Monitoring reports "delayed".
const ListMonitoringDelayAfter = 15 * time.Minute
// ListFreshThreshold is the longest StaleAfterS across every list: no list
// goes this long without a successful poll and still reports anything but
// "stale".
//
// Deprecated: freshness is per list since 2026-10-25. Read
// SanctionsListVersion.FreshWithinS and StaleAfterS; a list is "degraded"
// long before this bound.
const ListFreshThreshold = 2 * time.Hour
// ListsResponse is returned by GET /v1/lists.
type ListsResponse struct {
// Lists ordered by canonical short identifier (alphabetical).
Lists []SanctionsListVersion `json:"lists"`
Meta ResponseMeta `json:"meta"`
}
// =============================================================================
// Idempotency
// =============================================================================
//
// All state-mutating POST endpoints accept an optional Idempotency-Key request
// header. Noble caches the response for 24 hours under (scope, method, path,
// key); a retry with the same body returns the cached response and produces
// zero new side effects (no second screening_result row, no duplicate webhook
// delivery, no second alert activity row).
//
// Idempotency-Key: <string> (1-255 chars; UUID v4 recommended)
//
// Scope:
// - Authenticated endpoints: the key is namespaced by tenant_id.
// - POST /v1/keys (unauthenticated signup): the key is namespaced by the
// client's source IP, so a customer whose first signup attempt's response
// was lost mid-flight can retry and receive the original plaintext key.
//
// Behavior on a second request with the same (scope, method, path, key):
//
// Same request body hash, first request completed
// → Replay cached status + body + headers (X-Request-Id, X-RateLimit-*,
// Content-Type). Replays do not consume rate-limit quota.
//
// Same request body hash, first request still in flight (< 60s)
// → 409 with code=idempotency_in_progress and Retry-After: 1.
//
// Same request body hash, first request abandoned (>= 60s, no completion)
// → Treat as new — claim the slot and re-process.
//
// Different request body hash
// → 400 with code=idempotency_key_mismatch. To retry with a different
// body, generate a fresh Idempotency-Key.
//
// Key longer than 255 characters
// → 400 with code=idempotency_key_too_long.
//
// Caching policy:
// - 2xx and 4xx responses ARE cached (4xx is deterministic from the request).
// - 5xx responses are NOT cached (transient errors should be retryable).
// - Replays do not re-trigger webhooks, do not insert new audit rows, and
// do not consume rate-limit quota.
//
// Endpoints that honor Idempotency-Key:
// POST /v1/screen, /v1/batch, /v1/portfolio, /v1/watchlist, /v1/webhooks,
// /v1/alerts/{id}/resolve, /v1/alerts/{id}/assign, /v1/alerts/{id}/review,
// /v1/alerts/{id}/escalate, /v1/alerts/{id}/notes,
// /v1/alerts/bulk/resolve, /v1/alerts/bulk/assign,
// /v1/account/checkout, /v1/keys.
//
// Endpoints that ignore Idempotency-Key (header is silently dropped):
// GET and DELETE methods (idempotent by HTTP semantics), and /v1/admin/*
// (operator-driven, Phase 1 only — revisit when IAP gating lands).
// MaxIdempotencyKeyLength caps the Idempotency-Key header at the Stripe-
// compatible 255-character limit. Longer keys return 400 idempotency_key_too_long.
const MaxIdempotencyKeyLength = 255
// IdempotencyRetentionHours is how long cached responses live before the
// hourly cleanup goroutine deletes them.
const IdempotencyRetentionHours = 24
// IdempotencyInProgressTimeoutSeconds is how long an in-progress row is
// considered live. After this window, the row is treated as abandoned and a
// retry may claim its slot. Matched to the server's WriteTimeout (60s) — any
// handler still in_progress past that point has already been killed by the
// timeout, so its row is safely reclaimable.
const IdempotencyInProgressTimeoutSeconds = 60
// =============================================================================
// POST /v1/batch - Submit a batch screening job
// =============================================================================
// BatchRequest is the input for batch screening.
type BatchRequest struct {
// Names to screen (required, max 10,000 per batch)
Names []BatchNameInput `json:"names"`
// Lists restricts screening to the specified sanctions lists (batch-level).
// Same values as ScreenRequest.Lists. Applied to all names in the batch.
Lists []string `json:"lists,omitempty"`
}
// BatchNameInput is a single name entry in a batch request.
type BatchNameInput struct {
// Full name to screen (required). The "Name input" rule applies: at most
// MaxNameLength characters, and an empty name or one over the limit
// refuses the whole request with 400 naming its index. An item holding
// bytes that are not UTF-8 does not: the job is accepted, that item is
// reported with status "error" and error_code "invalid_parameter", and
// every other item is screened.
FullName string `json:"full_name"`
// Date of birth in YYYY-MM-DD format (optional)
DateOfBirth string `json:"date_of_birth,omitempty"`
// Country code ISO 3166-1 alpha-2 (optional). Applied identically to
// ScreenRequest.Country: it penalizes a nationality mismatch and raises
// JurisdictionRisk on an embargoed country.
Country string `json:"country,omitempty"`
// Location declares the subject's position in structured form, for
// sub-national nexus detection. Identical semantics to
// ScreenRequest.Location — nexus only, never scoring — so a batch item
// and a single screen of the same subject cannot disagree.
Location *Location `json:"location,omitempty"`
// EntityType of the subject: "individual", "entity", "vessel", "aircraft"
// (optional). Applied identically to ScreenRequest.EntityType — a genuine
// type mismatch against the matched record reduces the score (OFAC FAQ 5
// Step 2). Omitted means no entity-type penalty, matching /v1/screen.
EntityType string `json:"entity_type,omitempty"`
// IDNumber is a passport, tax ID, or other government identifier (optional).
// When provided, actively matched against OFAC and UK sanctions ID tables.
IDNumber string `json:"id_number,omitempty"`
// IDType filters ID matching by type (e.g., "Passport") (optional).
IDType string `json:"id_type,omitempty"`
}
// BatchResponse is the response after creating a batch job, and to every
// poll of it. POST /v1/batch answers 202 Accepted: the job is queued, not
// done. GET /v1/batch/status?id= answers 200 at every stage, including
// pending, processing and failed — read Status, not the HTTP code, for the
// job's state.
type BatchResponse struct {
// Batch job ID for status polling
ID int64 `json:"id"`
// Current status: pending, processing, completed, failed.
// A job that encounters an unrecoverable error is marked "failed" with an error_message.
Status string `json:"status"`
// Total names submitted
TotalNames int `json:"total_names"`
// Names processed so far
ProcessedNames int `json:"processed_names"`
// Names that had at least one match
MatchCount int `json:"match_count"`
// Detailed results per name (populated as items are screened; complete when status=completed)
Items []BatchItemResponse `json:"items,omitempty"`
}
// BatchItemResponse is a single name result within a batch. It carries the
// ownership control exactly as POST /v1/screen does (#729): Ownership is the
// item's determination under the job's lists, OwnershipAlertID the ownership
// alert it raised, AlertReason the rule that raised its alert.
type BatchItemResponse struct {
// Name that was screened
FullName string `json:"full_name"`
// Status: pending, screened, error
Status string `json:"status"`
// Number of sanctions matches found
MatchCount int `json:"match_count"`
// Highest match score (0-100)
HighestScore float64 `json:"highest_score"`
// Alert ID created for this name, if the highest score exceeded the tenant's
// alert threshold. Zero/omitted means no alert was generated.
AlertID int64 `json:"alert_id,omitempty"`
// AlertReason names the rule that raised AlertID, or OwnershipAlertID
// when only that fired, as on ScreenResponse.AlertReason.
AlertReason string `json:"alert_reason,omitempty"`
// OwnershipAlertID is the ownership alert this item raised (a blocked
// or review determination), distinct from AlertID, as on ScreenResponse.
OwnershipAlertID int64 `json:"ownership_alert_id,omitempty"`
// Ownership is the item's derivative-ownership determination under the
// job's lists (see OwnershipMatch), present on every screened item on a
// deployment with the control; "unavailable" when the control could not
// run or its record cannot be read. A batch item has no coverage
// object: the ownership_unavailable warning in Warnings, beside
// Ownership.Overall.Status, is the item's signal that the 50 Percent
// Rule question is unanswered, and the item should be screened again.
Ownership *OwnershipMatch `json:"ownership,omitempty"`
// JurisdictionRisk is present when the geography declared on this item —
// its Location, else its Country — places the subject under a
// comprehensive OFAC embargo. Identical detection to
// ScreenResponse.JurisdictionRisk, so batch and single-screen can never
// disagree about the same input, and resolved at the instant the item was
// screened rather than now.
JurisdictionRisk *JurisdictionRisk `json:"jurisdiction_risk,omitempty"`
// JurisdictionNexus reports which of this item's geographic declarations
// was evaluated and what the embargo record said about it — identical
// semantics to ScreenResponse.JurisdictionNexus, so a name screened in a
// batch and the same name screened singly cannot disagree.
JurisdictionNexus *JurisdictionNexus `json:"jurisdiction_nexus,omitempty"`
// Warnings states what this item's screening could not cover — identical
// semantics to ScreenResponse.Warnings, so a name screened in a batch and
// the same name screened singly carry the same caveats.
Warnings []Warning `json:"warnings,omitempty"`
// Enrollment is what screening this item did to the caller's portfolio,
// exactly as ScreenResponse.Enrollment reports it for POST /v1/screen:
// enrolled or already_enrolled with the portfolio_entity_id, not_entitled
// when the submitting key has no portfolio add-on, no_name for an item
// with no name, or failed with an enrollment_failed warning on the item.
// The name is enrolled with the item's date_of_birth and country. Present
// on every item screened after 2026-10-29; absent on an item that was
// not screened and on items screened before then.
Enrollment *Enrollment `json:"enrollment,omitempty"`
// EngineVersion and MatchEngine name the rules and engine that scored
// this item (see ScreenResponse). Absent on items screened before they
// were recorded.
EngineVersion string `json:"engine_version,omitempty"`
MatchEngine string `json:"match_engine,omitempty"`
// ErrorCode and ErrorMessage say why an item with Status "error" was
// not screened, when the cause was its own input: ErrorCode is an
// Error code (CodeInvalidParameter for an item holding bytes that are
// not UTF-8 — see "Name input"). Such an item never fails the rest of
// the batch; the other items are screened. Absent on every other item.
// Screen the corrected name again, on its own or in a new batch.
ErrorCode string `json:"error_code,omitempty"`
ErrorMessage string `json:"error_message,omitempty"`
}
// =============================================================================
// GET /v1/portfolio - List monitored entities
// =============================================================================
//
// Returns List[PortfolioEntityResponse], cursor-paginated by entity id
// (?after=&limit=), ordered id ascending — see the "Pagination" contract.
// Optional filters: q (name substring), min_score and max_score (numbers
// from 0 to 100; a bound you send applies, 0 included). A malformed value is
// a 400 invalid_parameter naming it. q matches a Confidential Portfolio
// (encrypted) entity's name the same as a plaintext one — encrypted names
// are matched in memory after decryption, never in the database — and
// GET /v1/portfolio/stats counts with the same filters, so its total always
// agrees with the filtered list. Full extraction of a large portfolio
// belongs to the async export/batch job, not GET paging.
// PortfolioEntityResponse is a single entity in the portfolio.
type PortfolioEntityResponse struct {
// Entity ID
ID int64 `json:"id"`
// Full name being monitored
FullName string `json:"full_name"`
// NameFold is the form of full_name that monitoring compares against
// the lists: lower case, accents removed ("Ališer" → "aliser"),
// ligatures and fullwidth letters expanded, apostrophes dropped,
// punctuation as spaces, and lookalike letters from another script
// inside a Latin word mapped to Latin. Every list name goes through the
// same fold, so the two are always compared on equal terms. Omitted for
// an entity enrolled before this field existed until the portfolio is
// re-folded.
NameFold string `json:"name_fold,omitempty"`
// Date of birth (YYYY-MM-DD) if known
DateOfBirth string `json:"date_of_birth,omitempty"`
// Country code (ISO 3166-1 alpha-2) if known
Country string `json:"country,omitempty"`
// Entity type: individual or entity
EntityType string `json:"entity_type"`
// Highest match score from last screening
HighestScore float64 `json:"highest_score"`
// Mean match score from last screening
AverageScore float64 `json:"average_score"`
// When this entity was last screened
LastScreenedAt string `json:"last_screened_at"`
// When this entity was first enrolled
CreatedAt string `json:"created_at"`
// Screening is the screening POST or PUT /v1/portfolio ran on the
// entity as written, before answering (#618). Absent from GET.
Screening *PortfolioScreening `json:"screening,omitempty"`
}
// PortfolioScreening is the screening that enrolling or changing a portfolio
// entity runs. It is a POST /v1/screen of the entity's full_name,
// date_of_birth and country against every list: the same decision, recorded
// the same way (GET /v1/export?trace_id= returns it, and it replays), and
// raising an alert through the same threshold and dedup. A name already on
// a list is alerted at enrollment, not when its listed record next changes.
//
// The entity is written only after the screening succeeds. When the
// screening cannot run (503 coverage_unavailable, 504 screening_timeout),
// nothing is enrolled or changed and the request can be retried as sent.
type PortfolioScreening struct {
// TraceID is the audit key the screening is recorded under.
TraceID string `json:"trace_id"`
// ScreeningID is the screening's id in the audit trail.
ScreeningID int64 `json:"screening_id,omitempty"`
// ScreenedAt is when the screening ran (RFC 3339, UTC).
ScreenedAt string `json:"screened_at"`
// MatchCount is the number of matches, as on ScreenResponse.
MatchCount int `json:"match_count"`
// TopMatch is the highest-scoring match, exactly as /v1/screen returns
// it; null when nothing matched.
TopMatch *ScreenMatch `json:"top_match"`
// AlertID is the alert the screening raised; null when it raised none.
// AlertReason names the rule, as on ScreenResponse.
AlertID *int64 `json:"alert_id"`
AlertReason string `json:"alert_reason,omitempty"`
// OwnershipAlertID is the alert raised by a blocked 50 Percent Rule
// determination, as on ScreenResponse.
OwnershipAlertID int64 `json:"ownership_alert_id,omitempty"`
// Warnings are the screening's warnings, as on ScreenResponse.
Warnings []Warning `json:"warnings,omitempty"`
}
// PortfolioAddRequest is the input for adding or updating a portfolio entity.
// The entity is screened as sent before it is written (see
// PortfolioScreening).
type PortfolioAddRequest struct {
// Full name to monitor (required)
FullName string `json:"full_name"`
// Date of birth in YYYY-MM-DD format (optional). Any other form is a
// 400 invalid_parameter.
DateOfBirth string `json:"date_of_birth,omitempty"`
// Country code ISO 3166-1 alpha-2 (optional), in either case. Anything
// else is a 400 invalid_parameter.
Country string `json:"country,omitempty"`
}
// PortfolioStatsResponse is the count companion to GET /v1/portfolio. Answers
// "how many entities am I monitoring, and how many are high-risk?" without
// paging the whole portfolio. Honors the same q/min_score/max_score filters as
// the list endpoint, so the count matches the filtered view.
type PortfolioStatsResponse struct {
// Total active entities matching the (optional) filters.
Total int `json:"total"`
// ByScoreBand counts entities by highest match score (0–100):
// "95-100", "90-94", "80-89", "below-80".
ByScoreBand map[string]int `json:"by_score_band"`
}
// =============================================================================
// GET /v1/export - Compliance export of screening decisions
// =============================================================================
// ExportRecord.Outcome values.
const (
ScreeningOutcomeCompleted = "completed"
ScreeningOutcomeFailed = "failed"
)
// ExportRecord is a single screening decision for compliance export.
// It contains the complete request, response, and metadata for regulatory
// audit trails, across ALL screening channels (see Channel).
type ExportRecord struct {
// Row ID
ID int64 `json:"id"`
// Trace ID from the original screening request
TraceID string `json:"trace_id"`
// RequestID is the per-call HTTP request ID of the original screening,
// stored alongside TraceID. Lets an operator pivot from a request_id to
// this record. Empty outside the api channel and for screenings persisted
// before this field existed.
RequestID string `json:"request_id,omitempty"`
// Client that owns this record
ClientID string `json:"client_id"`
// Channel is the screening pathway that produced this record: "api"
// (POST /v1/screen), "batch" (POST /v1/batch items), or "monitoring"
// (a sanctions-list change reverse-screened against the portfolio).
// Records persisted before channels existed report "api".
Channel string `json:"channel"`
// ScreenedName is the name that was screened, surfaced first-class so
// exports can be filtered by entity. For monitoring records the
// direction is inverted: this is the changed sanctions-list name that
// was screened against your portfolio.
ScreenedName string `json:"screened_name,omitempty"`
// Request is the verbatim audit payload of the screening inputs. Its
// shape is channel-dependent: for "api" it is a ScreenRequest; for
// "batch" it carries the item's fields under the same JSON keys (name,
// date_of_birth, country, entity_type, id_number, id_type, lists); for
// "monitoring" it describes the list change (source, uid, name,
// change_type, publish_id, job_id).
Request json.RawMessage `json:"request"`
// Response is the verbatim audit payload of the screening outcome. For
// "api" it is a ScreenResponse (incl. list_versions); for "batch" it
// carries matches, match_count, highest_score, average_score, and
// list_versions; for "monitoring" it carries the matched portfolio
// entities (PII blanked for Confidential Portfolio rows), match_count,
// highest_score, publish_id, and source. For a failed screening
// (Outcome == ScreeningOutcomeFailed) it is the Error body the caller
// received — type, code, message, request_id, trace_id — not a result.
Response json.RawMessage `json:"response"`
// Outcome is ScreeningOutcomeCompleted when the screening produced a
// result, or ScreeningOutcomeFailed when its input was accepted but the
// screening did not finish (timeout, server error, caller disconnect). A
// failed screening carries no matches: it records that the attempt was
// made, not what the lists said.
Outcome string `json:"outcome"`
// OFAC list version active at screening time
OFACListVersion *OFACListInfo `json:"ofac_list_version,omitempty"`
// When the screening occurred (RFC 3339)
ScreenedAt string `json:"screened_at"`
// ScanPin is what this record's name scan read, by id (#363): the
// publish id of every list it scanned, the highest AI-variation id it
// could see, and the instant of the scan's database transaction. It is
// the key replay uses. Absent on records stored before the pin existed,
// on identifier-only screenings (no name scan) and on the batch and
// monitoring channels.
ScanPin *ScanPin `json:"scan_pin,omitempty"`
// Alerts lists every alert this screening raised or folded into, oldest
// first, so the record shows on its own whether the screening led to an
// alert: the alert_id and ownership_alert_id the screening's response
// carried appear here, and a monitoring record lists one alert per
// matched portfolio entity. An empty array means the screening raised
// none. Always [] for the batch channel, whose alerts are not yet linked
// to their screening records. A screening that matched an already-open
// alert before this field existed omits that alert: the link was not
// recorded then.
Alerts []ExportAlert `json:"alerts"`
}
// ExportAlert is one alert a screening led to (ExportRecord.Alerts).
type ExportAlert struct {
// ID is the alert's id, for GET /v1/alerts/{id}.
ID int64 `json:"id"`
// Source is the alert's source: "api", "monitoring" or "ownership".
Source string `json:"source"`
// Relation is how the screening led to the alert:
// ExportAlertCreated when the screening raised it, or
// ExportAlertDeduplicated when it matched an alert that was already
// open, whose id the screening's response returned instead of a new one.
Relation string `json:"relation"`
}
// ExportAlert.Relation values.
const (
ExportAlertCreated = "created"
ExportAlertDeduplicated = "deduplicated"
)
// ScanPin identifies exactly which list state a screening's scan read.
type ScanPin struct {
// ScannedAt is the instant of the scan's read-only database transaction
// (RFC 3339, nanoseconds). Informational: replay keys on the ids below.
ScannedAt string `json:"scanned_at"`
// Lists maps each list the scan read to the publish id it read it at.
// Equal to the response's list_versions by construction.
Lists map[string]int `json:"lists"`
// AIVariationsMaxID is the highest ofac.ai_name_variations id visible to
// the scan; variations generated later cannot have contributed. Omitted
// when OFAC was not scanned.
AIVariationsMaxID int64 `json:"ai_variations_max_id,omitempty"`
// NativeNamesMaxID is the highest id of the names OFAC publishes in a
// party's own script (SDN Advanced feed) visible to the scan. That feed
// is imported on its own schedule, so replay cuts native-script names on
// this id, not on the OFAC publish's instant. A name the feed later
// drops stays on record, so the replay still screens it when the scan
// saw it. Omitted when OFAC was not scanned and on records stored before
// it existed.
NativeNamesMaxID int64 `json:"native_names_max_id,omitempty"`
}
// OFACListInfo identifies the OFAC sanctions list version.
//
// Deprecated: prefer ListVersion, which carries the same data plus the
// canonical list identifier. Retained while ScreenResponse.OFACListVersion
// is being phased out.
type OFACListInfo struct {
ID int `json:"id"`
PublishDate string `json:"publish_date"`
RecordCount int `json:"record_count"`
}
// ListVersion identifies the publisher snapshot active at screening time for
// a single sanctions list. ScreenResponse.ListVersions surfaces one entry
// per list named in ListsScreened so examiners can pin a screening decision
// to the exact list snapshots that produced it.
type ListVersion struct {
// List is the canonical identifier matching the values accepted in
// ScreenRequest.Lists (e.g., "ofac", "uk", "eu", "france", "belgium",
// "netherlands", "un", "canada", "australia").
List string `json:"list"`
// PublishID is the source-list publish_info row identifier — the audit
// pointer back to the imported file in <list>.publish_info.
PublishID int `json:"publish_id"`
// PublishDate is the date the publisher released this version
// (YYYY-MM-DD), taken verbatim from the source list.
PublishDate string `json:"publish_date"`
// RecordCount is the number of entries in this version.
RecordCount int `json:"record_count"`
}
// GET /v1/export/bulk returns List[ExportRecord], cursor-paginated by screening
// row id (?after=&limit=) within a required from/to (YYYY-MM-DD) date range,
// ordered id ascending — see the "Pagination" contract. Optional filters:
// ?name= restricts to records whose screened_name matches case-insensitively
// (entity-centric audit: one customer's screening history across every
// channel), and ?channel= restricts to one of api|batch|monitoring. limit is hard-capped at
// MaxPageLimit; a full audit pull belongs to the async export job. There is no
// total. Requires Standard tier or higher; client isolation enforced.
//
// Output format: the audit/export endpoints — GET /v1/export, GET
// /v1/export/bulk, and GET /v1/alerts/activity — accept ?format=json (default)
// or ?format=csv. CSV is a flat, examiner-friendly table, one row per record,
// with a header row; an unrecognized format value is a 400 invalid_parameter.
// Because a CSV body cannot carry the JSON meta.disclaimer, CSV responses
// surface the liability disclaimer in the X-Noble-Disclaimer response header
// and set Content-Disposition so the download is saved as a named .csv file.
// The full nested match detail is JSON-only; the CSV columns summarize each
// decision (top match, list version, request attributes).
// =============================================================================
// POST /v1/export/replay - Recompute a stored screening against its historical
// list snapshot and compare
// =============================================================================
//
// Replay is the examiner-grade proof that the system reproduces a recorded
// decision: it loads a stored screening by trace_id (or request_id), re-runs
// the screening engine pinned to the sanctions-list state at the original
// screening instant (as_of = the record's screened_at), and reports a
// field-by-field comparison. Requires Standard tier or higher; client
// isolation enforced (you can only replay your own records).
//
// Scope: channel "api" records only — batch and monitoring records store
// channel-specific payload shapes and are rejected with
// replay_unsupported_channel. The comparison deliberately excludes what
// cannot be deterministically reproduced, and names each exclusion in
// caveats rather than hiding it:
//
// - internal watchlist matches (WL- UIDs): the tenant watchlist is mutable
// tenant data with no version history; stored watchlist matches are
// excluded from comparison and the replay does not re-screen it.
// - deep_screen influence: LLM variation expansion is non-deterministic;
// when the stored request used deep_screen, the replay runs the
// deterministic engine only. Per-match scores are not compared, and
// match identity is compared asymmetrically: stored matches absent from
// the replay are attributed to variation expansion (caveat, not drift),
// while replay-only matches are still reported as differences.
// - volatile identifiers: trace_id, request_id, screened_at, screening_id,
// alert_id, and LLM summary prose are never compared.
// - OFAC child detail: see ScreenRequest.AsOf's fidelity boundary.
// ReplayRequest selects the stored screening to replay. Exactly one of
// TraceID or RequestID is required; TraceID wins when both are present.
type ReplayRequest struct {
// TraceID of the stored screening (ScreenResponse.TraceID).
TraceID string `json:"trace_id,omitempty"`
// RequestID of the stored screening (ScreenResponse.RequestID).
RequestID string `json:"request_id,omitempty"`
}
// ReplayVerdict is the outcome of a replay comparison.
type ReplayVerdict string
const (
// ReplayVerdictMatch: every compared field reproduced exactly.
ReplayVerdictMatch ReplayVerdict = "match"
// ReplayVerdictMismatch: at least one compared field differed — see
// Differences. A mismatch is a finding to investigate (list data
// mutated outside the import path, or an engine behavior change), not
// necessarily an error in the stored record.
//
// Two rules keep the two causes apart. A record scored by other rules or
// another engine than the replay's — its engine_version absent (stored
// before engine versions were recorded) or different, or its
// match_engine (absent means "database") different — carries
// CaveatEngineVersionChanged, and its per-match scores, match_count and
// average_score are not compared, so moved scores are never reported as
// list drift. The decision is compared under an engine change too: a
// summary.verdict that differs from the record's is a difference and the
// verdict is "mismatch". Only a record whose stored side the replay
// cannot reproduce — a deep_screen run, or one with watchlist matches —
// skips the decision, and its own caveat says so. Otherwise "match"
// means the replay would have decided as the record did.
ReplayVerdictMismatch ReplayVerdict = "mismatch"
)
// ReplayDifference is one compared field that did not reproduce.
type ReplayDifference struct {
// Field is a dotted path identifying what differed, e.g.
// "list_versions.ofac.publish_id", "matches.uids",
// "matches.12345.score", "summary.verdict", "match_count".
Field string `json:"field"`
// Stored is the value in the audit record.
Stored string `json:"stored"`
// Replayed is the value the re-run produced.
Replayed string `json:"replayed"`
}
// ReplayResponse reports a point-in-time replay of a stored screening.
type ReplayResponse struct {
// TraceID of the replayed record.
TraceID string `json:"trace_id"`
// ScreeningID is the stored audit row id.
ScreeningID int64 `json:"screening_id"`
// ScreenedAt is when the original screening ran (RFC 3339). The replay
// pins the engine to the list versions the record stores (its
// list_versions publish ids and the AI-variation state its scan saw);
// for a record stored before that pin existed it falls back to this
// instant and adds the pinned_to_record_time caveat.
ScreenedAt string `json:"screened_at"`
// Verdict is the comparison outcome across every compared field.
Verdict ReplayVerdict `json:"verdict"`
// Differences lists each compared field that failed to reproduce.
// Empty when Verdict is "match".
Differences []ReplayDifference `json:"differences,omitempty"`
// Caveats names each comparison exclusion that applied to this record
// (Caveat* constants), so the verdict's scope is explicit.
Caveats []string `json:"caveats,omitempty"`
// Stored is the verbatim audit response payload of the original
// screening (a ScreenResponse).
Stored json.RawMessage `json:"stored"`
// Replayed is the full re-computed screening response. Its own volatile
// fields (trace_id, screened_at, ...) describe the replay run, not the
// original.
Replayed *ScreenResponse `json:"replayed"`
Meta ResponseMeta `json:"meta"`
}
// Replay comparison caveats (ReplayResponse.Caveats).
const (
// CaveatWatchlistExcluded: the stored screening contained internal
// watchlist matches; they were excluded from comparison.
CaveatWatchlistExcluded = "watchlist_matches_excluded"
// CaveatDeepScreenScoresNotCompared: the stored request used deep_screen;
// match identity was compared but per-match scores, average_score, and
// summary.verdict were not.
CaveatDeepScreenScoresNotCompared = "deep_screen_scores_not_compared"
// CaveatDeepScreenMatchesNotReproduced: the stored deep_screen run
// contains matches absent from the deterministic replay. They are
// attributed to LLM variation expansion — which can discover matches the
// deterministic engine cannot find from the original name — and excluded
// from the identity comparison rather than reported as drift. Matches
// found only by the replay are still reported as a difference.
CaveatDeepScreenMatchesNotReproduced = "deep_screen_matches_not_reproduced"
// CaveatOFACChildDetailCurrent: the record or its replay contains OFAC
// matches, whose alias text and address/identifier child data replay at
// current state (see ScreenRequest.AsOf). Aliases first published after
// the record's cut are not replayed, and native-script names removed
// since are; an OFAC match found only by the replay carries this caveat
// too.
CaveatOFACChildDetailCurrent = "ofac_child_detail_current_state"
// CaveatEngineVersionChanged: the record was scored by other rules or
// another engine than the replay: its engine_version is absent (stored
// before engine versions were recorded, when every screening was scored
// by the "database" engine) or differs from the replay's, or its
// match_engine (absent means "database") differs. Match identity, the
// list snapshot and the decision (summary.verdict) are still compared;
// per-match scores, match_count and average_score are not, because a
// rules change is expected to move them and reporting it as drift would
// hide real drift. A changed decision is still a mismatch.
CaveatEngineVersionChanged = "engine_version_changed"
// CaveatPinnedToRecordTime: the record predates the scan pin, so the
// replay cut every list at the record's own clock (screened_at, or
// screened_as_of for an as-of screening) rather than at the exact
// publish ids the scan read. A list import that was committing while
// the original scan ran can make such a replay differ from the record
// without either being wrong. Records stored since the pin exists carry
// it and replay without this caveat.
CaveatPinnedToRecordTime = "pinned_to_record_time"
)
// Values of ScreenResponse.MatchEngine.
const (
MatchEngineDatabase = "database"
MatchEngineScorer = "scorer"
MatchEngineIndex = "index"
)
// =============================================================================
// POST /v1/keys - Provision a new API key
// =============================================================================
//
// Behavior depends on the server's signup_mode:
//
// open - anyone may create a free-tier key; invite_code is optional
// and, when supplied, overrides the tier per the invite row.
// invite_only - invite_code is required; tier comes from the invite row.
// closed - all signups return 403 with code=signup_closed.
//
// signup_mode is a server configuration value (SIGNUP_MODE env var). It is
// not part of the request — clients discover the current mode through the
// 403 (signup_closed) or 400 (invite_code_required) error responses.
//
// Rate limit: 10 requests per minute per client IP, answered with 429
// rate_limit_exceeded and Retry-After. The count is kept by each server
// instance, so while more than one instance serves traffic the effective
// ceiling can exceed 10 per minute. Clients must not depend on the exact
// figure; the limit exists to blunt signup abuse, not to meter usage. API-key
// quotas (daily/monthly) are counted centrally and are exact.
// TermsVersion is the current version of Noble Sight's Terms of Service.
// Bump this when terms change to require re-acceptance on new key creation.
const TermsVersion = "1.0"
// CodeTermsNotAccepted is the error code when accept_terms is not true.
const CodeTermsNotAccepted = "terms_not_accepted"
// Signup mode constants. These govern whether POST /v1/keys is reachable and
// whether it requires an invite code. The value is set via SIGNUP_MODE env var.
const (
SignupModeOpen = "open"
SignupModeInviteOnly = "invite_only"
SignupModeClosed = "closed"
)
// ValidSignupModes is the immutable set of accepted signup_mode values.
// Used at startup to validate the SIGNUP_MODE config and fail loud on typos.
var ValidSignupModes = map[string]bool{
SignupModeOpen: true,
SignupModeInviteOnly: true,
SignupModeClosed: true,
}
// CreateKeyRequest is the input for provisioning a new API key.
type CreateKeyRequest struct {
// Label for the client organization (required, 1-100 chars). Noble
// stores the key under a client_id it assigns: this label, cut to 91
// bytes if longer, followed by "-" and 8 random hex characters
// ("acme-bank" → "acme-bank-3f9c02ab"). Every signup creates a new
// customer identity, whether or not another customer used the same label,
// and the response is the same either way. The assigned value is returned
// as CreateKeyResponse.ClientID and by GET /v1/account. To add a key to an
// existing customer, contact Noble.
ClientID string `json:"client_id"`
// Human-readable label for the key (optional, max 255 chars)
Name string `json:"name,omitempty"`
// Must be true to create a key. Indicates acceptance of Noble Sight's
// Terms of Service (https://noblesight.io/terms) and acknowledgment that
// screening results are informational only and do not constitute legal
// or compliance advice.
AcceptTerms bool `json:"accept_terms"`
// InviteCode redeems an invite issued by Noble Sight. Required when the
// server is in signup_mode=invite_only. Optional in signup_mode=open
// (when supplied, the tier and scopes on the invite override the free-tier
// defaults — used for promo codes, design-partner trials, and sales-led
// trials). Format: noble_inv_ + 20 hex characters.
InviteCode string `json:"invite_code,omitempty"`
}
// CreateKeyResponse is returned after successfully creating an API key.
type CreateKeyResponse struct {
// Plaintext API key (shown once — store securely)
Key string `json:"key"`
// First 16 characters of the key for identification
KeyPrefix string `json:"key_prefix"`
// ClientID is the customer identity Noble assigned to this key: the
// requested client_id label followed by "-" and 8 random hex characters.
// GET /v1/account reports the same value.
ClientID string `json:"client_id"`
// Tier assigned to this key
Tier string `json:"tier"`
// Daily rate limit (free tier)
RateLimitPerDay int `json:"rate_limit_per_day"`
// Version of the Terms of Service accepted
TermsVersion string `json:"terms_version"`
}
// =============================================================================
// POST /v1/admin/keys — Mint a comped or trial API key (internal admin only)
// =============================================================================
//
// Reserved for internal admin tooling (provisioning design-partner trials,
// pilot comps, event comps). Reachable in Phase 1 only via the localhost
// interface of the noble-server pod — `kubectl port-forward` from an
// operator who already has GKE IAM access. Phase 2 will gate `/v1/admin/*`
// via Google IAP and override `granted_by` from the IAP-verified JWT email
// so callers cannot misrepresent themselves; the request/response shapes
// below remain unchanged.
// AdminCreateKeyRequest mints a comped/trial API key for a customer.
type AdminCreateKeyRequest struct {
// Customer identifier (required, 1-100 chars)
ClientID string `json:"client_id"`
// Human-readable label for the key (optional, max 255 chars)
Name string `json:"name,omitempty"`
// Tier: free, standard, premium, enterprise. Trials are typically enterprise.
Tier string `json:"tier"`
// Trial duration in whole days. Zero/omitted means no expiry.
// 30 = 30-day trial, 180 = 6-month trial, 365 = year-long comp.
TrialDays int `json:"trial_days,omitempty"`
// Comp category for cohort analysis: design_partner, pilot, evaluation, event.
// Required when trial_days > 0.
CompCategory string `json:"comp_category,omitempty"`
// Free-text justification for the comp (required). Surfaced in audit logs
// and the eventual admin-key list endpoint.
CompReason string `json:"comp_reason"`
// Operator identity for the audit trail (e.g., gcloud account email).
// Required in Phase 1; overridden by IAP-verified email in Phase 2.
GrantedBy string `json:"granted_by"`
// Contact email — recorded in slog audit only, not the api_key row.
Email string `json:"email,omitempty"`
}
// AdminCreateKeyResponse echoes the audit metadata and returns the plaintext
// key ONCE. Operators copy the key from this response; it is not retrievable
// later (only the SHA-256 hash is stored).
type AdminCreateKeyResponse struct {
// Plaintext API key — shown once, store securely.
Key string `json:"key"`
// First 16 characters of the key for identification.
KeyPrefix string `json:"key_prefix"`
// Customer identifier this key was minted for.
ClientID string `json:"client_id"`
// Tier assigned to this key.
Tier string `json:"tier"`
// When the trial expires (RFC 3339). Empty when no trial.
TrialEndsAt string `json:"trial_ends_at,omitempty"`
// Comp category recorded for this key.
CompCategory string `json:"comp_category,omitempty"`
// Free-text justification recorded for this key.
CompReason string `json:"comp_reason"`
// Operator identity recorded for this key.
CompGrantedBy string `json:"comp_granted_by"`
}
// Error codes for admin endpoints.
const (
CodeReasonRequired = "comp_reason_required"
CodeCategoryRequired = "comp_category_required"
CodeGrantedByRequired = "granted_by_required"
CodeInvalidTrialDays = "invalid_trial_days"
CodeInvalidCategory = "invalid_comp_category"
CodeInvalidAdminTier = "invalid_tier"
CodeInviteNotesTooLong = "invite_notes_too_long"
CodeInvalidMaxRedemptions = "invalid_max_redemptions"
CodeInvalidExpiresAt = "invalid_expires_at"
// CodeEncryptionKeyActive: confidential_portfolio cannot be withdrawn
// while the client holds an active encryption key (409). The customer
// shreds it via DELETE /v1/portfolio/key, which clears the entitlement.
CodeEncryptionKeyActive = "encryption_key_active"
)
// =============================================================================
// /v1/admin/invites — Mint and manage invite codes (internal admin only)
// =============================================================================
//
// Internal admin tooling for provisioning controlled signup access. Same
// auth posture as /v1/admin/keys: localhost-only in Phase 1 (reachable via
// kubectl port-forward), Google IAP in Phase 2. The created_by field is
// captured from the request in Phase 1 and overridden by the IAP-verified
// JWT email in Phase 2.
//
// Issuing one of these codes is the *only* way new customers (post-Royal
// Bank) enter the system while signup_mode=invite_only. Every code is a
// row with a created_by + timestamp — the auditable artifact a regulator
// reviews when asking "who granted this customer access?"
// AdminCreateInviteRequest mints a new invite code.
type AdminCreateInviteRequest struct {
// Tier granted to keys redeemed from this invite (required).
// Values: free, standard, premium, enterprise.
Tier string `json:"tier"`
// MaxRedemptions caps how many keys can be minted from this code.
// Defaults to 1. Use higher values for promo codes ("BLACKFRIDAY: 100 redemptions").
MaxRedemptions int `json:"max_redemptions,omitempty"`
// ExpiresAt is when the code stops being redeemable (RFC 3339).
// Empty/omitted = never expires. Use for time-limited promos.
ExpiresAt string `json:"expires_at,omitempty"`
// CreatedBy is the operator identity recorded for audit (e.g., gcloud
// account email). Required in Phase 1; overridden by IAP email in Phase 2.
CreatedBy string `json:"created_by"`
// Notes is free-text context for the audit trail (e.g., "Royal Bank beta",
// "Q1 conference comp"). Max 500 chars. Surfaced in the admin invite list.
Notes string `json:"notes,omitempty"`
// Scopes are capability scopes inherited by every key minted from this
// invite. Omit or pass empty for the default ["api"]. Pass ["api","mcp"]
// for design-partner invites that need MCP from day one. Must always
// include "api" — every key needs REST access.
Scopes []string `json:"scopes,omitempty"`
}
// AdminCreateInviteResponse echoes the audit metadata and returns the plaintext
// code ONCE. Codes are reversible (stored in plaintext so customers can be
// re-sent their code if lost), but operators should still capture this response.
type AdminCreateInviteResponse struct {
// Plaintext invite code (noble_inv_ + 20 hex chars).
Code string `json:"code"`
// Unique invite ID (UUID).
ID string `json:"id"`
// Tier granted by this invite.
Tier string `json:"tier"`
// Maximum redemptions allowed.
MaxRedemptions int `json:"max_redemptions"`
// Expiry timestamp (RFC 3339), empty when never expires.
ExpiresAt string `json:"expires_at,omitempty"`
// Operator who minted the invite.
CreatedBy string `json:"created_by"`
// Free-text notes recorded for this invite.
Notes string `json:"notes,omitempty"`
// When the invite was created (RFC 3339).
CreatedAt string `json:"created_at"`
// Scopes inherited by every key minted from this invite.
Scopes []string `json:"scopes"`
}
// InviteResponse is a single invite in admin listings. The plaintext code is
// included — invites are not secret credentials (the redeemed API key is).
type InviteResponse struct {
ID string `json:"id"`
Code string `json:"code"`
Tier string `json:"tier"`
MaxRedemptions int `json:"max_redemptions"`
RedemptionsUsed int `json:"redemptions_used"`
ExpiresAt string `json:"expires_at,omitempty"`
Status string `json:"status"`
CreatedBy string `json:"created_by"`
Notes string `json:"notes,omitempty"`
CreatedAt string `json:"created_at"`
RevokedAt string `json:"revoked_at,omitempty"`
Scopes []string `json:"scopes"`
}
// InviteListResponse wraps a list of invites for admin tooling.
type InviteListResponse struct {
Total int `json:"total"`
Invites []InviteResponse `json:"invites"`
}
// MaxInviteNotesLength caps the notes field on an invite to prevent abuse.
const MaxInviteNotesLength = 500
// =============================================================================
// POST /v1/admin/keys/scopes - Grant or revoke capability scopes on an
// existing API key. Localhost-only. Writes an append-only audit row to
// customers.api_key_scope_change capturing before/after, operator, and
// reason — examiners reconstruct capability history from that table.
// =============================================================================
// AdminChangeKeyScopesRequest mutates the scopes on an existing API key.
// The change is transactional: the UPDATE on customers.api_key and the
// INSERT on customers.api_key_scope_change either both commit or neither.
// =============================================================================
// POST /v1/admin/reverse-screen-jobs - Re-probe listed designations
// =============================================================================
// MaxReverseScreenRequestUIDs caps how many designations one operator request
// may re-probe. This enqueues real work against every active portfolio in the
// system, so the cap is deliberately small: it is a verification and recovery
// tool, not a bulk re-screen.
const MaxReverseScreenRequestUIDs = 25
// AdminReverseScreenRequest is the body of POST /v1/admin/reverse-screen-jobs.
type AdminReverseScreenRequest struct {
// Source is the list slug whose designations are being re-probed, in the
// reverse_screen_job vocabulary: "ofac_sdn", "ofac_cons", or any live
// list ("uk", "eu", "un", "france", "belgium", "netherlands", "canada",
// "australia"). Any other source returns 400 invalid_parameter (param
// "source"), naming the valid sources, rather than an empty job. It is
// authoritative for the whole job: AI name-variation expansion is
// enabled for ofac_sdn only, and the worker rebuilds names from this
// value.
//
// The job probes every name the forward screen can match the designation
// on: the primary name, every alias, and the names the list publishes in
// the party's own script — OFAC's native-script names (ofac_sdn), the
// UK's non-Latin names (uk), and the original-script aliases other lists
// publish among their aliases.
Source string `json:"source"`
// UIDs are the designations to re-probe, in the same prefixed form the
// screening API returns (bare integers for OFAC, "UK-...", "EU-...",
// "UN-...", "FR-...", "BE-...", "NL-...", "CA-...", "AU-..." for the
// others); a list's own bare id is accepted too.
UIDs []string `json:"uids"`
}
// AdminReverseScreenResponse reports the enqueued job.
type AdminReverseScreenResponse struct {
JobID int64 `json:"job_id"`
Source string `json:"source"`
NameCount int `json:"name_count"`
// Skipped is true when the request exceeded the re-import guard and the
// job was parked rather than queued.
Skipped bool `json:"skipped"`
}
// =============================================================================
// GET /v1/admin/reverse-screen-jobs - List reverse-screen jobs
// POST /v1/admin/reverse-screen-jobs/{id}/requeue - Put a failed or skipped
// job back in the queue (internal admin only, #556, #483)
// =============================================================================
//
// A reverse-screen job that fails is retried on its own three times (after
// 1, 5 and 15 minutes); one whose last retry fails stays "failed", and a job
// holding a single designation too large to split is parked "skipped". Each
// is a list change not yet screened against every monitored portfolio.
//
// GET lists jobs oldest first as a List[AdminReverseScreenJob], with the
// uniform ?after=&limit= pagination and an optional ?status= filter (one of
// pending, processing, completed, failed, skipped; anything else is 400
// invalid_parameter, param "status").
//
// POST .../{id}/requeue puts a failed or skipped job of any source back to
// "pending" with its retries reset and answers 200 with the job and
// previous_status. The worker resumes it from the names already screened; a
// skipped job screens its whole name list. No request body. Errors: 400
// invalid_parameter (param "id") for an id that is not a positive integer;
// 404 not_found for no such job; 409 conflict_error /
// invalid_status_transition for a job that is pending, processing or
// completed, so a finished change is never screened twice by accident.
//
// Localhost-only, behind LocalhostOnly, like every admin endpoint.
// AdminReverseScreenJob is one reverse-screen job: the screening of one list
// change, or one part of a change too large for one job, against every
// monitored portfolio.
type AdminReverseScreenJob struct {
ID int64 `json:"id"`
// Source is the list slug ("ofac_sdn", "uk", "eu", ...), or "ownership"
// for an ownership recompute's job, whose PublishID is the recompute run.
Source string `json:"source"`
PublishID int `json:"publish_id"`
// Status is pending, processing, completed, failed or skipped.
Status string `json:"status"`
// NameCount is how many names the job screens, AI name variations
// included; NamesDone how many it has screened so far.
NameCount int `json:"name_count"`
NamesDone int `json:"names_done"`
AlertsGenerated int `json:"alerts_generated"`
// Retries counts retries scheduled after a failure (at most 3); RetryAt
// is when a pending job waiting out one may run, omitted otherwise.
Retries int `json:"retries"`
RetryAt *time.Time `json:"retry_at,omitempty"`
// ErrorMessage is the last failure or the reason a job was skipped. It
// is kept after a retry or requeue succeeds.
ErrorMessage string `json:"error_message,omitempty"`
// EngineVersion is set on an engine re-screen job only.
EngineVersion string `json:"engine_version,omitempty"`
// TraceID is the list import's trace id; every job of one change shares it.
TraceID string `json:"trace_id"`
CreatedAt time.Time `json:"created_at"`
StartedAt *time.Time `json:"started_at,omitempty"`
FinishedAt *time.Time `json:"finished_at,omitempty"`
// EncryptedSkipped lists the Confidential Portfolio clients the job did
// not screen in full, omitted when it skipped none. GET /status counts
// those of the job that finished last.
EncryptedSkipped []AdminEncryptedSkip `json:"encrypted_skipped,omitempty"`
}
// AdminEncryptedSkip is one Confidential Portfolio client a reverse-screen
// job did not screen in full.
type AdminEncryptedSkip struct {
ClientID string `json:"client_id"`
// Reason is key_unusable (KMS refused the client's key: disabled,
// destroyed or gone), key_unavailable (KMS calls for the key still
// failed on the job's last retry) or ciphertext_invalid (some entities
// did not decrypt under a working key; the rest were screened). With
// either key reason none of the client's encrypted entities was screened.
Reason string `json:"reason"`
// Entities is how many encrypted entities were skipped.
Entities int `json:"entities"`
// EntityIDs are the portfolio entity ids that did not decrypt
// (ciphertext_invalid), at most 100; Entities keeps the full count.
EntityIDs []int64 `json:"entity_ids,omitempty"`
// Since is when the client's current unbroken run of skips began.
Since time.Time `json:"since"`
}
// AdminRequeueReverseJobResponse is the requeued job, now pending, with the
// status it had.
type AdminRequeueReverseJobResponse struct {
AdminReverseScreenJob
// PreviousStatus is "failed" or "skipped".
PreviousStatus string `json:"previous_status"`
}
// =============================================================================
// POST /v1/admin/rescreen - Re-screen every portfolio against every listed
// name after an engine change (internal admin only, #364)
// =============================================================================
//
// Portfolio monitoring is keyed on list deltas: it screens what a publisher
// changed. A change to Noble's own matching rules — a new engine_version
// that finds more — changes nothing on any list, so without this every
// enrolled portfolio entity would keep the clear it earned under the old
// rules. This enqueues every currently listed name on every list (or the
// sources named) as ordinary reverse-screen jobs, chunked under the
// re-import guard, each tagged with the engine_version that warranted it.
// Alerts the jobs raise carry change_type "engine_change". Every
// recall-improving engine_version bump runs it after deploy and records the
// job and alert counts.
//
// Source "ownership" (#687) re-screens every portfolio against every blocked
// 50 Percent Rule determination, as of the latest successful ownership
// recompute (its run id is the job's publish_id), deciding each pair as an
// ownership recompute does. Ownership monitoring otherwise reacts only to a
// recompute's newly blocked entities, so this is how entities blocked before
// that, or reached through a newly indexed name, are checked. A pair that
// already has an ownership alert for the same determined entity, open or
// closed (for a screen-time alert, under the same name), is not raised
// again; the alert gets a list_event saying the re-screen reached it. An
// earlier alert for a different entity never suppresses one. Alerts carry
// trigger kind "engine_change" with list "ownership".
//
// Localhost-only, behind LocalhostOnly, like every admin endpoint.
// AdminRescreenRequest is the body of POST /v1/admin/rescreen.
type AdminRescreenRequest struct {
// EngineVersion must equal the engine_version the serving process
// reports (ScreenResponse.EngineVersion); a mismatch is refused, so a
// re-screen can never be attributed to an engine that is not the one
// doing the screening.
EngineVersion string `json:"engine_version"`
// Sources restricts the re-screen to these reverse-screen sources
// ("ofac_sdn", "ofac_cons", "uk", "eu", "france", "belgium",
// "netherlands", "un", "canada", "australia", "ownership"). Empty means
// all, ownership included.
Sources []string `json:"sources,omitempty"`
// DryRun enumerates and chunks without enqueuing, reporting what would
// be queued.
DryRun bool `json:"dry_run,omitempty"`
}
// CodeRescreenIncompleteCoverage refuses a live (non-dry-run) re-screen that
// would leave listed records out of every job because no screenable name can
// be built for them. HTTP 409. The dry run reports the same count as
// records_without_probe, with per-source counts in the server log, so the
// gap can be seen and fixed before anything is enqueued. A re-screen exists
// to prove coverage; one that silently covered less than the lists would be
// worse than none (#636).
const CodeRescreenIncompleteCoverage = "rescreen_incomplete_coverage"
// AdminRescreenResponse reports the jobs enqueued (or, under dry_run, the
// jobs that would be).
type AdminRescreenResponse struct {
EngineVersion string `json:"engine_version"`
DryRun bool `json:"dry_run"`
TotalNames int `json:"total_names"`
// RecordsWithoutProbe is the number of live listed records, over every
// source enumerated, that yield no screenable name and so would be in
// no job. Non-zero only under dry_run: a live run is refused over it
// (CodeRescreenIncompleteCoverage), so an enqueued re-screen always
// covers every record of every list it names.
RecordsWithoutProbe int `json:"records_without_probe"`
Jobs []AdminRescreenJob `json:"jobs"`
}
// AdminRescreenJob is one enqueued chunk.
type AdminRescreenJob struct {
Source string `json:"source"`
// PublishID is the list publish the job is decided against, or for
// source "ownership" the recompute run.
PublishID int `json:"publish_id"`
JobID int64 `json:"job_id,omitempty"` // 0 under dry_run
// RecordCount is the number of listed records (designations) in the
// chunk. NameCount is the number of names screened for them: under
// dry_run, each record's name plus its aliases; a live run's enqueued
// jobs also carry the stored AI name variations of OFAC names, so a
// live NameCount can exceed the dry run's for the two OFAC sources.
RecordCount int `json:"record_count"`
NameCount int `json:"name_count"`
Skipped bool `json:"skipped"`
}
type AdminChangeKeyScopesRequest struct {
// KeyID is customers.api_key.id of the target key (required).
KeyID int64 `json:"key_id"`
// Add lists scopes to grant. Already-present scopes are silently ignored.
// Recognized values today: "mcp". ("api" cannot be added — every key has
// it by construction.)
Add []string `json:"add,omitempty"`
// Remove lists scopes to revoke. Already-absent scopes are silently
// ignored. "api" cannot be removed — every key must retain REST access.
Remove []string `json:"remove,omitempty"`
// Reason is the human-readable justification recorded on the audit row
// (required). Examples: "Royal Bank MCP design-partner enrollment",
// "revoked per support ticket #1234". Max 500 chars.
Reason string `json:"reason"`
// ChangedBy is the operator identity recorded for audit (required).
// Phase 1: gcloud account email passed in the request body. Phase 2:
// overridden by the IAP-verified email and the request body field is
// ignored.
ChangedBy string `json:"changed_by"`
}
// AdminChangeKeyScopesResponse returns the before/after state and the
// audit row ID so operators can cite it in change tickets.
type AdminChangeKeyScopesResponse struct {
KeyID int64 `json:"key_id"`
ClientID string `json:"client_id"`
KeyPrefix string `json:"key_prefix"`
ScopesBefore []string `json:"scopes_before"`
ScopesAfter []string `json:"scopes_after"`
AuditID int64 `json:"audit_id"`
ChangedAt string `json:"changed_at"` // RFC 3339
}
// =============================================================================
// POST /v1/admin/tenants/features - Grant or revoke a paid add-on for a
// customer (internal admin only, #492). Localhost-only, behind LocalhostOnly
// like every /v1/admin/* endpoint.
// =============================================================================
//
// Portfolio monitoring and the Confidential Portfolio (BYOK) add-on are
// entitlements stored per key on customers.api_key (portfolio_enabled,
// confidential_portfolio_enabled). Stripe checkout is the customer's
// self-serve path for a paid add-on; this endpoint is the operator's path
// for a design-partner trial, a comp, or a revocation, and the only one —
// there is no hand-run UPDATE. The change applies to every non-revoked key
// the client_id holds at the time of the call (a key minted afterwards
// starts without the add-on; re-run the grant), and is visible on the
// customer's very next request: the gate reads the flag from the key row on
// every call, nothing is cached.
//
// Every flip of either flag — here, by Stripe checkout, or by the customer's
// crypto-shred — goes through one writer and lands as an append-only row in
// customers.api_key_feature_change (per key, per feature), in the same
// transaction as the UPDATE, carrying before/after, actor, reason and
// trace_id. That table is the complete entitlement history; the server logs
// the operator path as admin_feature_changed.
//
// confidential_portfolio ordering matters. Granting it is the prerequisite
// for the customer to provision their key (POST /v1/portfolio/key is gated
// on the entitlement); until a key exists, portfolio writes for that client
// fail closed rather than fall back to plaintext, exactly as after a Stripe
// purchase. Withdrawing it while the client still holds an active key is
// refused with 409 encryption_key_active: the customer shreds the key via
// DELETE /v1/portfolio/key, which clears the entitlement itself and records
// the change.
// Feature* are the add-on names accepted by AdminTenantFeaturesRequest and
// recorded in customers.api_key_feature_change.feature. They are the same
// field names GET /v1/account reports under features.
const (
FeaturePortfolioMonitoring = "portfolio_monitoring"
FeatureConfidentialPortfolio = "confidential_portfolio"
)
// AdminTenantFeaturesRequest grants or revokes add-ons for one customer.
// Omitted feature fields are left unchanged; at least one must be present.
type AdminTenantFeaturesRequest struct {
// ClientID identifies the customer (required). Every non-revoked key
// under this client_id is updated. 404 not_found when the client has
// no such key; 409 encryption_key_active when confidential_portfolio is
// false and the client still holds an active encryption key.
ClientID string `json:"client_id"`
// PortfolioMonitoring sets the portfolio-monitoring add-on
// (features.portfolio_monitoring on GET /v1/account; gates
// /v1/portfolio and auto-enrollment on /v1/screen). nil leaves it as is.
PortfolioMonitoring *bool `json:"portfolio_monitoring,omitempty"`
// ConfidentialPortfolio sets the Confidential Portfolio (BYOK) add-on
// (features.confidential_portfolio; gates /v1/portfolio/key). nil
// leaves it as is.
ConfidentialPortfolio *bool `json:"confidential_portfolio,omitempty"`
// Reason is the human-readable justification recorded on every audit
// row (required, max 500 chars). Examples: "design-partner trial, 90
// days", "revoked per support ticket #1234". It is visible to the
// customer, verbatim, on GET /v1/account/features/history, and so to
// their examiner: write it for that reader.
Reason string `json:"reason"`
// ChangedBy is the operator identity recorded for audit (required).
// Phase 1: gcloud account email passed in the request body. Phase 2:
// overridden by the IAP-verified email and the request body field is
// ignored. The customer sees it as "operator:noblesight"; the stored
// value is returned only on the admin GET.
ChangedBy string `json:"changed_by"`
}
// AdminTenantCanaryRequest (POST /v1/admin/tenants/canary, localhost-only)
// flags or unflags a tenant as the canary tenant (#558): the ONLY tenant
// reverse screening may raise canary-list alerts for. The flag widens
// nothing — a canary tenant still monitors real lists like any other — and
// it is not an entitlement, so it lives on customers.tenant; the change
// still writes the standard append-only audit rows (feature
// 'tenant_canary') with reason, operator and trace id.
type AdminTenantCanaryRequest struct {
// ClientID identifies the customer whose tenant is flagged (required).
ClientID string `json:"client_id"`
// Canary is the new flag value (required).
Canary *bool `json:"canary"`
// Reason is the human-readable justification (required, max 500 chars).
Reason string `json:"reason"`
// ChangedBy is the operator identity recorded for audit (required).
ChangedBy string `json:"changed_by"`
}
// AdminTenantCanaryResponse reports the tenant's canary flag after the
// change. A request that changes nothing is refused with 400
// feature_no_change rather than answered as though it acted.
type AdminTenantCanaryResponse struct {
ClientID string `json:"client_id"`
Canary bool `json:"canary"`
// AuditID is the append-only audit row written for this change (the
// last one when the client holds several keys).
AuditID int64 `json:"audit_id"`
ChangedAt string `json:"changed_at"` // RFC 3339
}
// AdminTenantFeaturesResponse reports the customer's entitlements after the
// change, exactly as GET /v1/account would show them, plus every audit row
// the call wrote. A request that changes nothing — every named flag already
// holds the requested value — is refused with 400 feature_no_change rather
// than answered with an empty audit trail.
type AdminTenantFeaturesResponse struct {
ClientID string `json:"client_id"`
// Features is the same object GET /v1/account returns under "features",
// computed from the client's first active key after the change.
Features AccountFeatures `json:"features"`
// Changes lists every audit row written: one per key per feature whose
// value actually changed.
Changes []AdminFeatureChange `json:"changes"`
// AuditID is the id of the audit row written for this call. When the
// call changed more than one flag (or the client holds several keys) it
// is the last row's id and Changes carries all of them.
AuditID int64 `json:"audit_id"`
ChangedAt string `json:"changed_at"` // RFC 3339
}
// AdminFeatureChange is one row of customers.api_key_feature_change.
type AdminFeatureChange struct {
KeyID int64 `json:"key_id"`
KeyPrefix string `json:"key_prefix"`
Feature string `json:"feature"` // FeaturePortfolioMonitoring or FeatureConfidentialPortfolio
EnabledBefore bool `json:"enabled_before"`
EnabledAfter bool `json:"enabled_after"`
AuditID int64 `json:"audit_id"`
}
// =============================================================================
// POST /v1/admin/keys/quota - Set a customer's quota: a contract-specific
// monthly limit, or none at all (internal admin only, #565). Localhost-only,
// behind LocalhostOnly like every /v1/admin/* endpoint.
// =============================================================================
//
// Every paid key is minted with its tier's monthly limit (Standard 5,000,
// Premium 25,000, Enterprise 100,000). Enterprise is sold as "custom": the
// contract sets the number. This endpoint is how the operator applies it,
// and the only way — there is no hand-run UPDATE. It sets either
// monthly_limit (a positive integer, which also clears unlimited) or
// unlimited: true on every non-revoked paid key the client_id holds, and
// the change applies on the customer's very next request.
//
// The call is the customer's contract quota, not just a setting on today's
// keys: a key an operator mints for the client later (POST /v1/admin/keys,
// e.g. a rotation) inherits it, so a rotation never drops the customer to
// the tier default mid-month. Keys created through public signup never
// inherit: signup always opens a new customer (#569).
//
// An unlimited key is never refused on quota. Its usage is still counted,
// so GET /v1/usage reports it, but there is no limit to report: the
// X-RateLimit-* headers are omitted, and GET /v1/usage and GET /v1/account
// return "unlimited": true without limit or remaining. A client that
// decodes limit and remaining into plain integers will read 0 for both;
// such a client should check unlimited first.
//
// Free-tier keys keep the free plan's daily quota and are listed in
// skipped_free_keys; a client with no paid key at all is refused with 409
// quota_tier_ineligible. A request that changes nothing is refused with
// 400 quota_no_change. A later Stripe checkout on a key replaces its quota
// with the purchased tier's default, and is recorded the same way.
//
// Each change — here, by Stripe checkout, or by inheritance at mint — lands
// as an append-only row in customers.api_key_quota_change, in the same
// transaction as the UPDATE, with its source, before/after, actor, reason
// and trace_id; the server logs operator changes as admin_quota_changed.
// AdminKeyQuotaRequest sets one customer's quota. Exactly one of
// MonthlyLimit or Unlimited (true) is required.
type AdminKeyQuotaRequest struct {
// ClientID identifies the customer (required). Every non-revoked key
// under this client_id is updated. 404 not_found when it has none.
ClientID string `json:"client_id"`
// MonthlyLimit is the contract's requests per calendar month (UTC). It
// must be positive, and it replaces an earlier unlimited grant.
MonthlyLimit *int `json:"monthly_limit,omitempty"`
// Unlimited, when true, lifts the quota entirely. false is refused: to
// return an unlimited customer to a limit, send MonthlyLimit.
Unlimited *bool `json:"unlimited,omitempty"`
// Reason is the justification recorded on every audit row (required,
// max 500 chars), e.g. "MSA 2026-11: 500,000 screenings/month".
Reason string `json:"reason"`
// ChangedBy is the operator identity recorded for audit (required).
ChangedBy string `json:"changed_by"`
}
// AdminKeyQuotaResponse lists every audit row the call wrote: one per key
// whose quota actually changed.
type AdminKeyQuotaResponse struct {
ClientID string `json:"client_id"`
Changes []AdminQuotaChange `json:"changes"`
// SkippedFreeKeys lists the prefixes of the client's free-tier keys,
// which keep the free plan's daily quota. Empty, never null.
SkippedFreeKeys []string `json:"skipped_free_keys"`
AuditID int64 `json:"audit_id"` // id of the last audit row written
ChangedAt string `json:"changed_at"` // RFC 3339
}
// AdminQuotaChange is one row of customers.api_key_quota_change. An
// unlimited key carries a null monthly limit.
type AdminQuotaChange struct {
KeyID int64 `json:"key_id"`
KeyPrefix string `json:"key_prefix"`
MonthlyLimitBefore *int `json:"monthly_limit_before"`
MonthlyLimitAfter *int `json:"monthly_limit_after"`
UnlimitedBefore bool `json:"unlimited_before"`
UnlimitedAfter bool `json:"unlimited_after"`
AuditID int64 `json:"audit_id"`
}
// =============================================================================
// POST /v1/admin/keys/revoke - Revoke a customer's API key (#570)
// =============================================================================
//
// The operator's revocation, for incident response (a leaked key) and for
// retiring the old key after a rotation. Localhost-only, like every
// /v1/admin/* endpoint. It applies the same rules as the customer's DELETE
// /v1/account/keys/{key_prefix}, through the same writer and audit table,
// with source "admin" and the operator as revoked_by. The operator is not
// bound by the issued-before rule.
//
// client_id is required with key_prefix: a 16-character prefix is not unique
// across customers, so it alone never identifies a key. 404 not_found when
// the client holds no key with that prefix; 409 key_prefix_ambiguous when it
// holds more than one, which no request can then resolve. reason and
// changed_by are required.
// AdminRevokeKeyRequest names one key of one customer.
type AdminRevokeKeyRequest struct {
ClientID string `json:"client_id"`
KeyPrefix string `json:"key_prefix"`
Reason string `json:"reason"` // required, max 500 chars
ChangedBy string `json:"changed_by"` // operator identity, required
}
// AdminRevokeKeyResponse is RevokeKeyResponse plus the audit row.
type AdminRevokeKeyResponse struct {
ClientID string `json:"client_id"`
RevokeKeyResponse
// AuditID is the customers.api_key_revocation row: the one this call
// wrote, or the original one when the key was already revoked (0 for a
// key revoked before revocation was recorded).
AuditID int64 `json:"audit_id"`
}
// GET /v1/admin/tenants/features?client_id=<id>[&after=&limit=&feature=&from=&to=]
// is the operator's read of the same record the customer sees on GET
// /v1/account/features/history, with one difference: changed_by is returned
// as stored (the operator's email), not masked to the vendor. 404 not_found
// only when the client has never held a key; a client whose keys are all
// revoked still has a history, and that is exactly the case an examiner
// asks about. Localhost-only.
// AdminTenantFeaturesHistoryResponse is the operator's view of a client's
// entitlement state and history.
type AdminTenantFeaturesHistoryResponse struct {
ClientID string `json:"client_id"`
// Features is the current entitlement state, as GET /v1/account would
// report it, from the client's first active key. Omitted when the client
// has no active key.
Features *AccountFeatures `json:"features,omitempty"`
// Data is the page of changes, oldest first; HasMore and ?after= page
// forward as on every list endpoint.
Data []FeatureChangeResponse `json:"data"`
HasMore bool `json:"has_more"`
}
// =============================================================================
// GET /v1/admin/ownership/pending - 50 Percent Rule extraction review queue.
// GET /v1/admin/ownership/assertions/{id} - one extracted assertion by id.
// POST /v1/admin/ownership/assertions/{id}/verdict - approve or reject it.
// Localhost-only. The queue lists LLM-extracted ownership assertions (#63
// Phase C) awaiting human review: every relation the list-text extractor
// persisted to ownership.extracted_relation with its verbatim source quote.
// Reviewing these is how an operator validates the extraction layer feeding
// the ownership graph. The by-id read resolves the assertion_id a chain hop
// cites (#168) to that row, with its review status. A verdict (#164) is the
// human-review control: a rejected assertion is dropped from every
// determination at the next recompute, its edge is retired from the graph
// at the next import, and a re-extraction of the same record never
// resurrects it; an approved one is marked so. A stated percentage in a
// list's own published text blocks without prior approval: the text is the
// authority's, the extraction cites it verbatim, and the verdict is the
// correction.
// =============================================================================
// OwnershipPendingResponse lists extracted ownership relations awaiting
// review, oldest first.
type OwnershipPendingResponse struct {
// Total is the number of relations awaiting review (may exceed
// len(Relations) when the queue is longer than the page cap).
Total int `json:"total"`
Relations []OwnershipPendingRelation `json:"relations"`
}
// OwnershipPendingRelation is one LLM-extracted ownership assertion, exactly
// as persisted to the audit store before it became a graph edge.
type OwnershipPendingRelation struct {
// ID is the assertion's stable identifier in ownership.extracted_relation.
ID int64 `json:"id"`
// List is the sanctions list whose published text the assertion came
// from ("france", "uk", "un", "eu").
List string `json:"list"`
// UID is the source-native designation ID of the list record.
UID string `json:"uid"`
// Subject is the list record's subject name (the designated party whose
// entry carried the text).
Subject string `json:"subject"`
// OwnerText and OwnedText are the owner and owned entity names exactly
// as written in the source text.
OwnerText string `json:"owner_text"`
OwnedText string `json:"owned_text"`
// RelType is "ownership" or "control".
RelType string `json:"rel_type"`
// Percent is the ownership percentage, present only when the source
// text states a number.
Percent *float64 `json:"percent,omitempty"`
// Quote is the verbatim minimal substring of the list text the
// assertion was extracted from — the audit evidence.
Quote string `json:"quote"`
// OwnerKey and OwnedKey are the graph entity keys the names resolved
// to; empty when unresolved.
OwnerKey string `json:"owner_key,omitempty"`
OwnedKey string `json:"owned_key,omitempty"`
// Model is the LLM that performed the extraction.
Model string `json:"model"`
// ListPublishID is the list snapshot the text came from.
ListPublishID int `json:"list_publish_id"`
// ExtractedAt is when the assertion was extracted (RFC 3339).
ExtractedAt string `json:"extracted_at"`
}
// MaxOwnershipPendingPage caps one review-queue page.
const MaxOwnershipPendingPage = 500
// OwnershipAssertionResponse is one extracted ownership assertion by id
// (GET /v1/admin/ownership/assertions/{id}, localhost-only, #168): the row
// a chain hop's assertion_id cites, with its review status.
type OwnershipAssertionResponse struct {
OwnershipPendingRelation
// Status is one of the OwnershipAssertion* values: "auto" (extracted,
// not yet reviewed), "approved" or "rejected" (an analyst's verdict).
Status string `json:"status"`
// RunID is the extraction run that recorded the assertion.
RunID int64 `json:"run_id"`
// SupersededAt is when a completed re-extraction (or carry) of the
// record stopped restating this statement (#724). Set, the assertion is
// kept, still resolves here and keeps its status, but is no evidence
// for any determination.
SupersededAt string `json:"superseded_at,omitempty"`
}
// Assertion review statuses (ownership.extracted_relation.status).
const (
OwnershipAssertionAuto = "auto"
OwnershipAssertionApproved = "approved"
OwnershipAssertionRejected = "rejected"
)
// MaxOwnershipVerdictReasonLength caps a verdict's reason, for identity
// and assertion verdicts alike.
const MaxOwnershipVerdictReasonLength = 500
// =============================================================================
// GET /v1/admin/ownership/program-blocked - persons blocked by programme definition
// POST /v1/admin/ownership/program-blocked - confirm, reject or name one
// Localhost-only (#715). Persons OFAC blocks by programme definition (FAQ
// 398: the blocked government of Iran, North Korea, Syria, Venezuela, Cuba,
// the Crimea region) appear on no list. A list's text that names an owner
// as such a state body makes it a candidate: its us determination is
// review with reason blocked_government_candidate and nothing it owns is
// clean. An analyst confirms or rejects the candidate here; a confirmed
// person seeds the us regime at the next recompute, blocks what it owns at
// 50 percent or more with its basis on every hop, and reviews what it
// holds without a stake (controlled_by_blocked_government). Append-only:
// the newest record per entity governs.
// =============================================================================
// OwnershipProgramBlocked is the governing record for one entity.
type OwnershipProgramBlocked struct {
// EntityKey is the entity's ownership-graph key.
EntityKey string `json:"entity_key"`
// Name is the entity's name as recorded.
Name string `json:"name"`
// Basis is one of the OwnershipBasis* values; Citation the regulation.
Basis string `json:"basis"`
Citation string `json:"citation"`
// Program is the OFAC programme when known (e.g. "IRAN").
Program string `json:"program,omitempty"`
// Status is "candidate", "confirmed" or "rejected".
Status string `json:"status"`
// EvidenceAssertionID cites the extracted assertion whose text named
// the entity a state body, when the candidate came from list text.
EvidenceAssertionID int64 `json:"evidence_assertion_id,omitempty"`
// Reason, DecidedBy and DecidedAt are the record's audit fields.
Reason string `json:"reason"`
DecidedBy string `json:"decided_by"`
DecidedAt string `json:"decided_at"`
}
// OwnershipProgramBlockedResponse lists the governing records, candidates
// first, then confirmed, then rejected, by entity key within each.
type OwnershipProgramBlockedResponse struct {
Total int `json:"total"`
Records []OwnershipProgramBlocked `json:"records"`
}
// OwnershipProgramBlockedRequest records a decision on an entity (#715).
type OwnershipProgramBlockedRequest struct {
// EntityKey is the entity's ownership-graph key (required); it must be
// indexed in the graph, so a confirmed person can seed it.
EntityKey string `json:"entity_key"`
// Basis is one of the OwnershipBasis* values (required).
Basis string `json:"basis"`
// Program is the OFAC programme (optional, max 64 chars).
Program string `json:"program,omitempty"`
// Status is "confirmed", "rejected" or "candidate" (required).
Status string `json:"status"`
// Reason is the analyst's justification (required, max
// MaxOwnershipVerdictReasonLength chars).
Reason string `json:"reason"`
// DecidedBy is the analyst identity recorded for audit (required, max
// MaxOwnershipIdentityActorLength chars).
DecidedBy string `json:"decided_by"`
}
// MaxOwnershipProgramLength caps a programme name.
const MaxOwnershipProgramLength = 64
// OwnershipAssertionVerdictRequest is the body of POST
// /v1/admin/ownership/assertions/{id}/verdict (localhost-only, #164): an
// analyst's verdict on one extracted assertion. It is recorded append-only
// with the actor and the time, applied to the assertion and to every copy
// of the same relationship (the same record's same owner and owned, as
// the text states them, under other publishes), and governs any later
// extraction of that relationship.
type OwnershipAssertionVerdictRequest struct {
// Verdict is "approved" or "rejected" (required). A rejected assertion
// contributes to no determination from the next recompute on, unless
// another live assertion states the same relationship, and its edge is
// retired from the graph at the next import. The newest verdict on a
// relationship governs, so a later verdict reverses an earlier one.
Verdict string `json:"verdict"`
// Reason is the analyst's justification (required, max
// MaxOwnershipVerdictReasonLength chars).
Reason string `json:"reason"`
// DecidedBy is the analyst identity recorded for audit (required, max
// MaxOwnershipIdentityActorLength chars).
DecidedBy string `json:"decided_by"`
}
// OwnershipAssertionVerdictResponse is the recorded verdict and the
// assertion as it now stands.
type OwnershipAssertionVerdictResponse struct {
// VerdictID is the verdict's own identifier.
VerdictID int64 `json:"verdict_id"`
// Verdict, Reason, DecidedBy and DecidedAt are the recorded verdict.
Verdict string `json:"verdict"`
Reason string `json:"reason"`
DecidedBy string `json:"decided_by"`
DecidedAt string `json:"decided_at"`
// Applied counts the assertion rows the verdict was applied to: the
// one named and its unreviewed copies.
Applied int `json:"applied"`
// Assertion is the assertion after the verdict.
Assertion OwnershipAssertionResponse `json:"assertion"`
}
// =============================================================================
// GET /v1/admin/ownership/identity/{key} - One ownership entity across lists
// GET /v1/admin/ownership/identity/candidates - The identity review queue
// POST /v1/admin/ownership/identity/verdicts - Record an analyst's verdict
//
// Localhost-only. Cross-list identity (#714): a party designated by several
// lists is ONE ownership entity (key "ent:<id>") carrying a set of
// designations, merged only on graded evidence. These endpoints show what
// an entity rests on, list the pairs no evidence settled, and take the
// analyst's verdict that settles one.
// =============================================================================
// OwnershipIdentityResponse is one ownership entity: every designation
// that names it, each with the grade and evidence of its link, and the
// entity's membership history.
//
// {key} is either the entity key ("ent:42") or any of its designations
// ("ofac:29046", "uk:SYR0258"); both return the same entity.
type OwnershipIdentityResponse struct {
// Key is the stable, list-independent entity key ("ent:42").
Key string `json:"key"`
// RetiredKey is the key asked for when an identity merge retired it
// (#764): the response is then its survivor's, the one entity that now
// holds every former designation of the retired key still active, and
// the entity a determination resting on the retired key is read as.
RetiredKey string `json:"retired_key,omitempty"`
// Designations are the active designations the entity carries, ordered
// by list then uid. One designation means no other list names the
// party (grade "singleton").
Designations []OwnershipIdentityDesignation `json:"designations"`
// Log is the entity's membership history, newest first: every
// designation that joined or left it, with the grade and evidence at
// the time. Append-only; capped at MaxOwnershipIdentityLog entries.
Log []OwnershipIdentityLogEntry `json:"log"`
}
// OwnershipIdentityDesignation is one list's designation of the entity.
type OwnershipIdentityDesignation struct {
// List is the list slug ("ofac", "uk", "france", ...) and UID the
// list's native id, together the designation key "<list>:<uid>".
List string `json:"list"`
UID string `json:"uid"`
// Name is the designation's primary name as the list publishes it.
Name string `json:"name"`
// Kind is the party's type as the list publishes it, normalized:
// "individual", "entity", "vessel", "aircraft", or "" when the list
// publishes none. Designations of different known kinds never merge.
Kind string `json:"kind,omitempty"`
// Grade is the strongest evidence linking this designation into the
// entity:
//
// "reference" it and another designation cite the same UN reference
// number
// "strong" a name equal under the engine fold on both sides,
// corroborated by an equal date of birth, a shared
// identification number, or (entities) two or more
// distinct substantive name forms in common
// "verdict" an analyst's recorded merge
// "corroborated" the same specific primary name (legal form aside;
// three or more words for a person), the same kind
// and an overlapping programme family,
// nothing contradicting (#763); Evidence.Programs
// names the families
// "singleton" no other list names the party
//
// Equal names alone never merge; such pairs are in the candidates queue.
Grade string `json:"grade"`
// Evidence lists the pairs this designation's link rests on: for each,
// the other designation and what they share. Empty for a singleton.
Evidence []OwnershipIdentityEvidence `json:"evidence"`
// LinkedAt is when the designation joined this entity (RFC 3339).
LinkedAt string `json:"linked_at"`
// RunID is the identity resolution run that last wrote this membership.
RunID int64 `json:"run_id"`
}
// OwnershipIdentityEvidence is what two designations share.
type OwnershipIdentityEvidence struct {
// With is the other designation's key ("france:2112").
With string `json:"with"`
// Grade is the grade this pair alone supports.
Grade string `json:"grade"`
// Names are the name forms equal under the engine fold on both sides
// (folded, lower case).
Names []string `json:"names,omitempty"`
// DateOfBirth is the full date of birth (YYYY-MM-DD) both publish, when
// that is what corroborated the name.
DateOfBirth string `json:"date_of_birth,omitempty"`
// Identifier is the identification number both publish (letters and
// digits only), when that is what corroborated the name.
Identifier string `json:"identifier,omitempty"`
// Reference is the UN reference number both cite ("QDI.372").
Reference string `json:"reference,omitempty"`
// Programs are the programme families both are listed under, for
// grade "corroborated" ("russia", "iran", "dprk", "terrorism", ...).
Programs []string `json:"programs,omitempty"`
// VerdictID is the analyst verdict the link rests on, for grade
// "verdict".
VerdictID int64 `json:"verdict_id,omitempty"`
}
// OwnershipIdentityLogEntry is one membership change.
type OwnershipIdentityLogEntry struct {
// ID orders the log; RunID is the run that made the change.
ID int64 `json:"id"`
RunID int64 `json:"run_id"`
// List and UID name the designation; Action is "joined" or "left".
List string `json:"list"`
UID string `json:"uid"`
Action string `json:"action"`
// Grade and Evidence are the link as it stood when the change was
// recorded (for "left", the link that was removed).
Grade string `json:"grade,omitempty"`
Evidence []OwnershipIdentityEvidence `json:"evidence"`
// At is when the change was recorded (RFC 3339).
At string `json:"at"`
}
// MaxOwnershipIdentityLog caps the history returned with an entity.
const MaxOwnershipIdentityLog = 200
// OwnershipIdentityCandidatesResponse is the identity review queue: pairs
// of designations on different lists that share a name with nothing
// corroborating it, or that evidence would have merged had an analyst's
// separate verdict not kept them apart. Nothing here is merged until a
// verdict says so.
type OwnershipIdentityCandidatesResponse struct {
// Total is the queue depth; Candidates is the first page, oldest
// first (by the run that first saw the pair).
Total int `json:"total"`
Candidates []OwnershipIdentityCandidate `json:"candidates"`
}
// OwnershipIdentityCandidate is one unresolved pair.
type OwnershipIdentityCandidate struct {
// A and B are the two designation keys, in canonical order (A < B),
// with their primary names as published.
A string `json:"a"`
AName string `json:"a_name"`
B string `json:"b"`
BName string `json:"b_name"`
// SharedName is the folded name form both publish.
SharedName string `json:"shared_name"`
// Reason says why the pair is here and not merged:
//
// "name_only" a shared name and nothing else
// "year_only" a shared name and an equal birth year, no full date
// "vetoed" evidence would merge; an analyst's separate verdict,
// a same-list constraint or a different published
// reference number kept the pair (or its entities) apart
Reason string `json:"reason"`
// FirstSeenRun and LastSeenRun are the identity runs that first and
// most recently produced the pair.
FirstSeenRun int64 `json:"first_seen_run"`
LastSeenRun int64 `json:"last_seen_run"`
}
// MaxOwnershipIdentityCandidatesPage caps one queue page.
const MaxOwnershipIdentityCandidatesPage = 500
// OwnershipIdentityVerdictRequest records an analyst's verdict on a pair
// of designations. It takes effect at the next identity resolution run
// (nightly with the ownership import, or `nobled ownership-identity`):
// "merge" joins the pair into one entity with grade "verdict";
// "separate" keeps them apart on every later run, and keeps apart any
// evidence that would join their entities transitively. The newest verdict
// on a pair governs; verdicts are append-only.
type OwnershipIdentityVerdictRequest struct {
// A and B are the two designation keys ("ofac:29046", "france:2112"),
// in either order (required, distinct, each at most
// MaxOwnershipIdentityKeyLength chars, on different lists unless the
// verdict is "merge"). Both must be designations the resolver has
// seen: an unknown key is refused with 404 rather than stored.
A string `json:"a"`
B string `json:"b"`
// Verdict is "merge" or "separate" (required).
Verdict string `json:"verdict"`
// Reason is the analyst's justification (required, max
// MaxOwnershipVerdictReasonLength chars).
Reason string `json:"reason"`
// DecidedBy is the analyst identity recorded for audit (required, max
// MaxOwnershipIdentityActorLength chars).
DecidedBy string `json:"decided_by"`
}
// MaxOwnershipIdentityKeyLength caps one designation key ("<list>:<uid>").
const MaxOwnershipIdentityKeyLength = 128
// MaxOwnershipIdentityActorLength caps a verdict's decided_by.
const MaxOwnershipIdentityActorLength = 200
// OwnershipIdentityVerdictResponse is the recorded verdict.
type OwnershipIdentityVerdictResponse struct {
ID int64 `json:"id"`
A string `json:"a"`
B string `json:"b"`
Verdict string `json:"verdict"`
Reason string `json:"reason"`
DecidedBy string `json:"decided_by"`
DecidedAt string `json:"decided_at"`
}
// =============================================================================
// GET /v1/usage - Check API usage for the current key
// =============================================================================
// UsageResponse returns the current usage stats for the authenticated API key.
type UsageResponse struct {
// Tier of the authenticated key
Tier string `json:"tier"`
// Requests used in the current window
Used int `json:"used"`
// Total request limit for the current window. Absent when Unlimited.
Limit *int `json:"limit,omitempty"`
// Requests remaining in the current window. Absent when Unlimited.
Remaining *int `json:"remaining,omitempty"`
// Unlimited is true when the key has no quota (#565): it is never
// refused on quota, and Used still counts its requests.
Unlimited bool `json:"unlimited"`
// Rate limit window: "day" (free) or "month" (paid)
Window string `json:"window"`
// Trial details — present only when this key is a comped/trial key.
// Customers and customer dashboards use this to show "your trial ends in N days".
Trial *TrialInfo `json:"trial,omitempty"`
}
// TrialInfo describes the trial window for a comped API key.
// Trial keys receive full enterprise-tier access until ends_at, after which
// a daily job flips the key's status to "expired" and subsequent requests
// return 402 Payment Required with code=trial_expired.
type TrialInfo struct {
// When the trial expires (RFC 3339, UTC)
EndsAt string `json:"ends_at"`
// Days remaining until expiry (0 on the day of expiry; never negative)
DaysRemaining int `json:"days_remaining"`
// Comp category for the trial: design_partner, pilot, evaluation, event
Category string `json:"category,omitempty"`
}
// =============================================================================
// Team member registry - /v1/team
// =============================================================================
//
// The team registry names the analysts who work alerts. Alert assignment
// (POST /v1/alerts/{id}/assign) validates its assign_to against it, and the
// X-Actor header (below) validates against it, which is what makes four-eyes
// closure of high-score alerts workable for a team sharing one API key: the
// key authenticates the institution, X-Actor attests which registered analyst
// acted, and the attestation is recorded in the immutable case activity.
//
// POST /v1/team - register a team member {email, role}
// GET /v1/team - list the tenant's team members
// DELETE /v1/team/{email} - deactivate a member
//
// Registration is idempotent: re-registering an existing member reactivates
// it and applies the requested role. Deactivation never deletes — the
// identity stays resolvable in historical case activity, it just stops
// validating for assignment and X-Actor. The collection is capped at
// MaxTeamMembersPerTenant and returned whole by GET (no cursor).
//
// # The X-Actor header
//
// Any alert-mutating call (resolve, assign, review, escalate, notes, bulk)
// may carry X-Actor: the email of a registered, ACTIVE team member of the
// calling tenant. The action's audit actor is then "analyst:<email>" instead
// of the default "apikey:<prefix>". An X-Actor that is not a registered
// active member is rejected with 400 invalid_actor — fail closed, so the
// audit trail never records an unverifiable human identity. Four-eyes
// compares actors, so two analysts working through the same API key satisfy
// it by each passing their own X-Actor.
// CreateTeamMemberRequest is the body for POST /v1/team.
type CreateTeamMemberRequest struct {
// Email is the analyst's address — the identity used by assign_to and
// X-Actor. Lowercased on storage; must be a plausible address of at most
// MaxTeamEmailLength characters.
Email string `json:"email"`
// Role is "analyst" (default) or "admin". Roles are recorded for audit
// context; API permissions are governed by the key's scopes, not roles.
Role string `json:"role,omitempty"`
}
// TeamMemberResponse is a single registry entry.
type TeamMemberResponse struct {
Email string `json:"email"`
Role string `json:"role"`
Status string `json:"status"` // active | disabled
// CreatedAt is when the member was first registered (RFC 3339, UTC).
CreatedAt string `json:"created_at"`
}
// MaxTeamMembersPerTenant caps the registry per tenant (active plus
// deactivated — deactivation preserves the row for audit resolution).
const MaxTeamMembersPerTenant = 200
// MaxTeamEmailLength bounds a team-member email (RFC 5321 path limit).
const MaxTeamEmailLength = 254
// =============================================================================
// GET /v1/alerts - List alerts for the authenticated tenant
// =============================================================================
//
// Returns List[AlertResponse], cursor-paginated by alert id (?after=&limit=),
// ordered id ascending — see the "Pagination" contract. Filters (all optional):
// status (an AlertResponse.Status value), source (an AlertResponse.Source
// value), min_score and max_score (numbers from 0 to 100), assigned_to,
// portfolio_entity_id (a positive integer — only alerts raised on the
// monitored portfolio record whose id it names, the value AlertResponse
// returns in portfolio_entity_id and GET /v1/portfolio returns as id; the
// query for "what has monitoring found for this customer"), from
// and to (YYYY-MM-DD, to inclusive). A filter you send always applies: a
// malformed or unknown value is a 400 invalid_parameter naming it, never
// silently ignored. There is no total; use GET /v1/alerts/stats for queue
// counts.
//
// The listing is complete: every alert the tenant ever generated is
// returned, regardless of the tenant's CURRENT alert_threshold. The
// threshold gates alert creation only — changing it later never hides an
// existing alert from this endpoint (#170). Use min_score for an explicit
// read-time floor.
//
// =============================================================================
// GET /v1/alerts/{id} - Single alert with full detail
// =============================================================================
//
// Returns a single AlertResponse including the match payload and the full case
// activity timeline (Activity, oldest first). 404 if the id is unknown or not
// owned by the caller's tenant.
// AlertResponse is a single alert in list or detail views.
type AlertResponse struct {
// Unique alert identifier
ID int64 `json:"id"`
// The name that was screened or, for an identifier-only screening, the
// identifiers that were screened as the caller sent them ("IMO 9333591";
// several joined with ", "). Never empty for an api alert (#504).
ScreenedName string `json:"screened_name"`
// Combined match score (0-100)
Score float64 `json:"score"`
// Number of sanctions matches
MatchCount int `json:"match_count"`
// How the alert originated: "api" (POST /v1/screen match), "batch"
// (POST /v1/batch item), "monitoring" (portfolio monitoring delta),
// "ownership" (a derivative-ownership determination, raised by a
// screening or, for a monitored portfolio entity, by the ownership
// recompute that newly blocked it or newly placed it under review;
// score is 100 for a blocked determination and 60 for a review one,
// match_count 0, alert_reason ownership_control or ownership_review,
// and the evidence is Ownership), or "console" (legacy).
Source string `json:"source"`
// Alert lifecycle status
Status string `json:"status"`
// Analyst assigned to this alert (email or "apikey:<prefix>")
AssignedTo string `json:"assigned_to,omitempty"`
// Structured resolution reason (only when closed)
Reason string `json:"reason,omitempty"`
// Disposition records what action was taken for true matches.
// Values: "blocked", "rejected", "permitted_gl", "no_action_required".
Disposition string `json:"disposition,omitempty"`
// GLCitation documents which general license permits the transaction.
GLCitation string `json:"gl_citation,omitempty"`
// Whether the four-eyes rule applies to this alert (score >= 90)
FourEyesRequired bool `json:"four_eyes_required"`
// SLA deadline (RFC 3339). Set at creation — score >= 90: 24h, others:
// 72h — and reset to the same window on assignment; escalation pulls it
// to at most 24h away.
DueAt string `json:"due_at,omitempty"`
// Whether the SLA deadline has passed for an open alert
Overdue bool `json:"overdue"`
// SDN match details (present when matched against a specific SDN entry)
SdnUID int `json:"sdn_uid,omitempty"`
SdnFirstName string `json:"sdn_first_name,omitempty"`
SdnLastName string `json:"sdn_last_name,omitempty"`
// AlertReason names the rule that raised this alert — "score_threshold",
// "name_near_miss", or "ownership_control". Same vocabulary as
// ScreenResponse.AlertReason, which documents each value.
//
// Absent on alerts created before 2026-09-14, when the rule that fired was
// not recorded. That is reported as absence rather than inferred from the
// score: for alerts predating the near-miss rule the inference would even
// be correct, which is exactly what would make it misleading.
AlertReason string `json:"alert_reason,omitempty"`
// PriorDisposition is present on a monitoring alert raised by a re-screen
// after a change to Noble's matching rules (change_type "engine_change")
// for a pair an analyst had already closed as a false positive. It names
// that earlier alert, how and at what score it was closed, and why this
// one was raised anyway. A re-screen raises a closed false positive again
// only when the new score is higher than the one it was dismissed at, or
// the match came through a pathway the dismissed alert did not have. A
// pair dismissed from a monitoring alert raised before engine 2.5.0,
// whose match came through the legacy "reverse" pathway, is raised again
// only on a higher score: the named pathways it now reports are forms
// that pathway already covered. It never raises a pair closed as a true
// match again. When it does not
// re-alert, the closed alert's activity timeline gets a list_event entry
// saying the re-screen reached the pair. Absent otherwise.
PriorDisposition *AlertPriorDisposition `json:"prior_disposition,omitempty"`
// Trigger says why a monitoring alert opened: the event that made Noble
// evaluate this customer against this listed party, the list publish
// that carried it, and when. Present on monitoring alerts raised from
// 2026-10-29 and on ownership alerts raised by an ownership recompute
// (kind "ownership_change"); absent on api and batch alerts, on
// ownership alerts raised by a screening, and on earlier monitoring
// alerts. A later event that matches the alert while it is open does
// not change it: it is recorded as a list_event activity entry carrying
// its own trigger.
Trigger *AlertTrigger `json:"trigger,omitempty"`
// Ownership is the 50 Percent Rule determination an ownership alert was
// raised on, exactly as it stood when the alert was created: status
// "blocked", the cumulative percentage, the designating lists, every
// ownership chain with its hops, and as_of and source_publish_ids, which
// pin the ownership data it was computed from. It is the alert's
// evidence, and it does not change when the graph later does. Present
// on ownership alerts in the detail view (GET /v1/alerts/{id} and the
// mutation responses); absent on other sources and in the list view.
Ownership *OwnershipMatch `json:"ownership,omitempty"`
// ScreeningID is the screening record the alert was raised from: the
// screening_id POST /v1/screen returned, or the record of the
// monitoring decision (channel "monitoring") for a monitoring alert or
// an ownership alert raised by an ownership recompute. GET
// /v1/export?trace_id= with TraceID returns it. Absent on alerts whose
// source recorded none (batch alerts, #208).
ScreeningID int64 `json:"screening_id,omitempty"`
// TraceID is the audit key of the event that raised the alert: the
// screening's trace_id (GET /v1/export?trace_id= returns the record), or
// for monitoring the list import or ownership recompute behind it.
TraceID string `json:"trace_id,omitempty"`
// PortfolioEntityID is the monitored portfolio entity a monitoring alert
// was raised for, the id GET /v1/portfolio returns. Absent on api and
// batch alerts.
PortfolioEntityID *int64 `json:"portfolio_entity_id,omitempty"`
// Full match payload: a JSON array of the matches, each a ScreenMatch as
// POST /v1/screen returns it. A screening or batch alert carries every
// match of its screening; a monitoring alert carries the one hit that
// raised it, which is the match POST /v1/screen returns for the same
// customer and listed party (engine 2.5.0). Monitoring and batch alerts
// raised before engine 2.5.0 store the engine's Go field names
// (UID, Score, Sources, DismissalSignals) instead.
MatchPayload json.RawMessage `json:"match_payload,omitempty"`
// Portfolio entity (present when alert is linked to a monitored entity)
Entity *AlertEntityResponse `json:"entity,omitempty"`
// Case activity timeline (present in detail view, omitted in list)
Activity []AlertActivityResponse `json:"activity,omitempty"`
// When the alert was created (RFC 3339)
CreatedAt string `json:"created_at"`
}
// AlertPriorDisposition is the earlier, closed alert on the same pair (the
// same portfolio entity, designation and list) that an engine re-screen
// alert follows. See AlertResponse.PriorDisposition.
type AlertPriorDisposition struct {
// AlertID is the earlier alert; GET /v1/alerts/{id} returns its timeline.
AlertID int64 `json:"alert_id"`
// Status is how it was closed: "closed_false_positive".
Status string `json:"status"`
// Score is the earlier alert's score (0-100).
Score float64 `json:"score"`
// RealertedBecause is "higher_score" (this alert scores above Score) or
// "new_pathway" (this match came through a pathway the earlier alert's
// evidence did not include).
RealertedBecause string `json:"realerted_because"`
}
// AlertEntityResponse is the portfolio entity linked to an alert.
type AlertEntityResponse struct {
FullName string `json:"full_name"`
DateOfBirth string `json:"date_of_birth,omitempty"`
Country string `json:"country,omitempty"`
EntityType string `json:"entity_type"`
}
// Alert trigger kinds: why a monitoring pair was evaluated when it was.
const (
// TriggerKindListChange: the list published a change to the listed
// party (an added or modified designation), or added a name to it.
TriggerKindListChange = "list_change"
// TriggerKindEngineChange: Noble re-screened every listed party after a
// change to its matching or monitoring rules (EngineVersion names the
// serving version, and the changelog announces it). With List
// "ownership", the re-screen checked every blocked 50 Percent Rule
// determination, and PublishID is the ownership recompute run.
TriggerKindEngineChange = "engine_change"
// TriggerKindOperatorReprobe: Noble's operations re-screened the listed
// party on request. No list changed.
TriggerKindOperatorReprobe = "operator_reprobe"
// TriggerKindVariationAdded: Noble added spelling or transliteration
// variations of the listed party's names and screened them. No list
// changed.
TriggerKindVariationAdded = "variation_added"
// TriggerKindOwnershipChange: Noble's ownership recompute newly
// determined an entity blocked under the 50 Percent Rule, and a
// monitored portfolio entity's name resolves to it. List is "ownership",
// PublishID the recompute run, and ImportedAt when the run recorded the
// change.
TriggerKindOwnershipChange = "ownership_change"
// TriggerKindRegimesAdded: the tenant added ownership regimes it is
// bound by (PATCH /v1/account), and Noble checked its portfolio against
// every determination under them (#744). List is "ownership", PublishID
// the recompute run decided against, ImportedAt when that run finished.
TriggerKindRegimesAdded = "regimes_added"
)
// AlertTrigger is why a monitoring alert opened. The same object is stored
// on the screening record behind the alert, so GET /v1/export returns it
// byte for byte.
type AlertTrigger struct {
// Kind is one of the TriggerKind constants.
Kind string `json:"kind"`
// List is the sanctions list evaluated: "ofac_sdn", "ofac_cons", "uk",
// "eu", "france", "belgium", "netherlands", "un", "canada" or
// "australia"; "ownership" on an ownership_change, or on an
// engine_change re-screen of the ownership determinations.
List string `json:"list"`
// PublishID is the list publish the pair was evaluated against: the
// publish that carried the change for list_change, the list as it stood
// otherwise. It is the publish_id GET /v1/lists reports for that
// version.
PublishID int `json:"publish_id"`
// PublishDate is the publisher's own date for that publish
// (YYYY-MM-DD), as GET /v1/lists reports it.
PublishDate string `json:"publish_date,omitempty"`
// ImportedAt is when Noble ingested that publish (RFC 3339, UTC), as GET
// /v1/lists reports it. ScreenedAt minus ImportedAt is how long the
// change took to reach this customer.
ImportedAt string `json:"imported_at,omitempty"`
// ScreenedAt is when this customer was evaluated against the listed
// party (RFC 3339, UTC).
ScreenedAt string `json:"screened_at"`
// ChangeType is "added" or "modified" on a list_change: what the
// publish did to the listed party. Absent on other kinds.
ChangeType string `json:"change_type,omitempty"`
// Changes is what a modified list_change changed in the listed party's
// designation, read from the list's own record of its state before and
// after the publish: each alias, name, program or other field added,
// removed or changed. CausedHit marks the change this customer's match
// came through (see AlertTriggerChange.CausedHit). An alert whose new
// alias matched is a different event from one where only a program
// changed and a name already listed was the match.
// Present on modified list_change alerts; absent on added ones (the
// whole designation is new), on other kinds, and where the list keeps no
// before and after for the publish, never an empty list.
Changes []AlertTriggerChange `json:"changes,omitempty"`
// EngineVersion is the matching-rules version whose re-screen raised
// the alert, on engine_change only.
EngineVersion string `json:"engine_version,omitempty"`
}
// AlertTriggerChange is one change a publish made to a designation. See
// AlertTrigger.Changes.
type AlertTriggerChange struct {
// Field is the part of the designation that changed, named the same
// way for every list: "name", "aka", "native_name" (a name in its own
// script), "programs", "type", "title", "remarks", "date_of_birth", or
// the list's own field name for a field only that list publishes.
Field string `json:"field"`
// Op is "added", "removed" or "changed".
Op string `json:"op"`
// Value is the value added or removed, or the new value of a change. A
// name is written as the list publishes it. An alias whose attributes
// beside its name changed (OFAC's strong/weak category, UK's name type)
// is a "changed" alias, and its value and previous show the attributes
// in brackets: "AMESCUA, Chuey [category: weak]".
Value string `json:"value"`
// Previous is the old value, on a change ("changed") only.
Previous string `json:"previous,omitempty"`
// CausedHit is true on the change this alert's match came through:
// the match's matched_text is a name the change added, either whole or
// one part a match can rest on alone (an alias's surname), compared word
// for word, case and accents aside. A name the designation already
// listed before the publish never caused a hit, so an alias promoted to
// primary, or a new alias sharing a surname the record already had, is
// false on that text.
CausedHit bool `json:"caused_hit"`
}
// AlertActivityResponse is a single entry in the alert's audit trail.
type AlertActivityResponse struct {
// Who performed the action: "analyst:<email>" when the call carried a
// validated X-Actor header (see the /v1/team contract), "apikey:<prefix>"
// for the key principal, or "system:monitoring" for list_event entries.
Actor string `json:"actor"`
// Action type: "status_change", "assigned", "note", "escalated",
// "reopened", or "list_event". A list_event entry records a sanctions
// list update that matched this alert's entity while the alert was open
// — the same person re-designated or modified on the same list — so the
// timeline shows every designation event during the alert's life; the
// note carries the change type, list, publish id, and score. (A
// designation on a different list raises its own alert instead.)
Action string `json:"action"`
// Previous status (for status_change actions)
FromStatus string `json:"from_status,omitempty"`
// New status (for status_change actions)
ToStatus string `json:"to_status,omitempty"`
// Structured reason code (for resolution actions)
Reason string `json:"reason,omitempty"`
// Disposition (for true match closures)
Disposition string `json:"disposition,omitempty"`
// General license citation (for permitted_gl dispositions)
GLCitation string `json:"gl_citation,omitempty"`
// Free-text investigation note
Note string `json:"note,omitempty"`
// Trigger is the event a list_event entry records, in the alert's own
// trigger shape. Present on list_event entries from 2026-10-29.
Trigger *AlertTrigger `json:"trigger,omitempty"`
// When this action occurred (RFC 3339)
Time string `json:"time"`
// ID is the case-activity row id. Present in the activity export
// (GET /v1/alerts/activity) where it is the cursor for ?after=; omitted in
// the alert-detail timeline.
ID int64 `json:"id,omitempty"`
// Alert ID (present in activity export, omitted in alert detail)
AlertID int64 `json:"alert_id,omitempty"`
}
// =============================================================================
// POST /v1/alerts/{id}/resolve - Resolve an alert with a structured reason
// =============================================================================
// AlertResolveRequest is the input for resolving an alert.
type AlertResolveRequest struct {
// Target status: "closed_false_positive" or "closed_true_match"
Status string `json:"status"`
// Structured reason code (required)
Reason string `json:"reason"`
// Disposition records what action was taken for true matches (required when status=closed_true_match).
// Values: "blocked", "rejected", "permitted_gl", "no_action_required".
// OFAC requires filing blocking/reject reports within 10 business days.
Disposition string `json:"disposition,omitempty"`
// GLCitation documents which general license permits the transaction (required when disposition=permitted_gl).
// Example: "GL 8A — Iran humanitarian trade" or "Russia GL 25G".
GLCitation string `json:"gl_citation,omitempty"`
// Optional investigation note
Note string `json:"note,omitempty"`
}
// =============================================================================
// POST /v1/alerts/{id}/assign - Assign an alert to an analyst
// =============================================================================
// AlertAssignRequest is the input for assigning an alert.
type AlertAssignRequest struct {
// Email of the analyst to assign to (required)
AssignTo string `json:"assign_to"`
}
// =============================================================================
// POST /v1/alerts/{id}/review - Start investigation (assigned → under_review)
// =============================================================================
// AlertReviewRequest is the input for starting investigation on an alert.
// Unlike resolve, no reason code is required — the analyst is beginning work.
type AlertReviewRequest struct {
// Optional note capturing initial observations
Note string `json:"note,omitempty"`
}
// =============================================================================
// POST /v1/alerts/{id}/notes - Add an investigation note
// =============================================================================
// AlertNoteRequest is the input for adding a note to an alert.
type AlertNoteRequest struct {
// Investigation note text (required, max 2000 chars)
Note string `json:"note"`
}
// =============================================================================
// POST /v1/alerts/{id}/escalate - Escalate an alert
// =============================================================================
// AlertEscalateRequest is the input for escalating an alert.
type AlertEscalateRequest struct {
// Optional note explaining the escalation
Note string `json:"note,omitempty"`
}
// =============================================================================
// Alert Constants
// =============================================================================
// Alert statuses define the lifecycle of an alert.
// Both the console UI and REST API enforce the same transitions.
const (
AlertStatusNew = "new"
AlertStatusAssigned = "assigned"
AlertStatusUnderReview = "under_review"
AlertStatusEscalated = "escalated"
AlertStatusClosedFP = "closed_false_positive"
AlertStatusClosedTrueMatch = "closed_true_match"
)
// Alert resolution reason codes. Structured reasons are required for closing
// an alert and serve as the auditable justification an OFAC examiner will review.
const (
ReasonFPNameOnly = "false_positive_name_only"
ReasonFPDOBMismatch = "false_positive_dob_mismatch"
ReasonFPCountryMismatch = "false_positive_country_mismatch"
ReasonFPEntityTypeMismatch = "false_positive_entity_type_mismatch"
ReasonFPOther = "false_positive_other"
ReasonTrueMatch = "true_match"
)
// Disposition constants record what action was taken on a confirmed true match.
// OFAC requires blocking/reject reports within 10 business days (31 C.F.R. Part 501).
const (
DispositionBlocked = "blocked"
DispositionRejected = "rejected"
DispositionPermittedGL = "permitted_gl"
DispositionNoActionRequired = "no_action_required"
)
// validReasons is the immutable set of accepted resolution reason codes.
// Unexported to prevent runtime mutation — compliance state machine integrity.
var validReasons = map[string]bool{
ReasonFPNameOnly: true,
ReasonFPDOBMismatch: true,
ReasonFPCountryMismatch: true,
ReasonFPEntityTypeMismatch: true,
ReasonFPOther: true,
ReasonTrueMatch: true,
}
// IsValidReason reports whether r is an accepted resolution reason code.
func IsValidReason(r string) bool { return validReasons[r] }
// validDispositions is the immutable set of accepted disposition values for true matches.
var validDispositions = map[string]bool{
DispositionBlocked: true,
DispositionRejected: true,
DispositionPermittedGL: true,
DispositionNoActionRequired: true,
}
// IsValidDisposition reports whether d is an accepted disposition value.
func IsValidDisposition(d string) bool { return validDispositions[d] }
// validTransitions defines the allowed status transitions for alerts.
// An alert closes only from under_review or escalated, so every closure
// follows a recorded human step; new and assigned alerts can be escalated
// directly, so an escalated alert can close without under_review. Closed alerts
// can be reopened to under_review when an examiner finds a premature closure.
// Escalated alerts can be sent back to under_review for further investigation.
// Unexported to prevent runtime mutation — compliance state machine integrity.
var validTransitions = map[string]map[string]bool{
AlertStatusNew: {AlertStatusAssigned: true, AlertStatusEscalated: true},
AlertStatusAssigned: {AlertStatusUnderReview: true, AlertStatusEscalated: true},
AlertStatusUnderReview: {AlertStatusEscalated: true, AlertStatusClosedFP: true, AlertStatusClosedTrueMatch: true},
AlertStatusEscalated: {AlertStatusUnderReview: true, AlertStatusClosedFP: true, AlertStatusClosedTrueMatch: true},
AlertStatusClosedFP: {AlertStatusUnderReview: true},
AlertStatusClosedTrueMatch: {AlertStatusUnderReview: true},
}
// IsValidTransition reports whether transitioning from one status to another is allowed.
func IsValidTransition(from, to string) bool {
allowed, ok := validTransitions[from]
return ok && allowed[to]
}
// FourEyesScoreThreshold is the minimum score (0-100) that triggers the
// four-eyes rule: a different analyst must close the alert than the one
// who last moved it through the workflow.
const FourEyesScoreThreshold = 90
// SLA deadlines based on alert score.
const (
SLAHighScoreHours = 24 // score >= FourEyesScoreThreshold
SLADefaultScoreHours = 72 // score < FourEyesScoreThreshold
)
// MaxNoteLength is the maximum character length for investigation notes.
const MaxNoteLength = 2000
// AlertService sentinel errors. Defined here (alongside the interface in server.go)
// so that both internal/alert and HTTP handlers share the same error values.
var (
ErrAlertNotFound = errors.New("alert not found")
ErrAlertInvalidReason = errors.New("invalid reason code")
ErrAlertInvalidTransition = errors.New("invalid status transition")
ErrAlertInvalidDisposition = errors.New("invalid disposition")
ErrAlertDispositionRequired = errors.New("disposition required for true match closure")
ErrAlertGLCitationRequired = errors.New("gl_citation required when disposition is permitted_gl")
ErrAlertFourEyes = errors.New("four-eyes required: a different analyst must close high-score alerts")
ErrAlertConcurrentModified = errors.New("alert status changed concurrently")
ErrAlertInvalidAssignee = errors.New("assignee is not an active team member")
ErrAlertEmptyNote = errors.New("note cannot be empty")
ErrAlertNoteTooLong = errors.New("note exceeds 2000 character limit")
)
// API limits for batch operations
const (
// MaxBatchSize is the maximum number of names in a single batch.
MaxBatchSize = 10_000
// MaxIDsPerRequest caps how many entries ScreenRequest.IDs may contain.
// Real entities rarely carry more than a handful of identifiers; the cap
// is generous enough for compounded passport + tax ID + crypto wallet
// portfolios while bounding worst-case work per screening call.
MaxIDsPerRequest = 20
// MaxIDValueLength bounds each identifier number and type string. The
// longest real identifiers (digital-currency addresses, registration
// numbers) sit well under 100 characters; anything past this bound is
// noise, not an identifier, and is rejected up front (input length
// bounds on all public endpoints).
MaxIDValueLength = 200
)
// =============================================================================
// GET /v1/alerts/activity - Export case activity audit trail
// =============================================================================
//
// Returns List[AlertActivityResponse]: the case-activity audit trail, cursor-
// paginated by activity row id (?after=&limit=). Filters: from, to (YYYY-MM-DD),
// alert_id, actor, action. Large pulls belong to the async export job.
// =============================================================================
// POST /v1/alerts/bulk/resolve - Bulk resolve alerts
// =============================================================================
// BulkResolveRequest resolves multiple alerts with the same status and reason.
type BulkResolveRequest struct {
// Alert IDs to resolve
AlertIDs []int64 `json:"alert_ids"`
// Target status: "closed_false_positive" or "closed_true_match"
Status string `json:"status"`
// Structured reason code (required)
Reason string `json:"reason"`
// Disposition for true matches (required when status=closed_true_match)
Disposition string `json:"disposition,omitempty"`
// GL citation (required when disposition=permitted_gl)
GLCitation string `json:"gl_citation,omitempty"`
// Optional note applied to all alerts
Note string `json:"note,omitempty"`
}
// BulkResolveResponse reports per-alert success or failure.
type BulkResolveResponse struct {
Resolved int `json:"resolved"`
Failed int `json:"failed"`
Results []BulkResolveResult `json:"results"`
}
// BulkResolveResult is the outcome for a single alert in a bulk resolve.
type BulkResolveResult struct {
AlertID int64 `json:"alert_id"`
Success bool `json:"success"`
Error string `json:"error,omitempty"`
}
// MaxBulkResolveSize limits how many alerts can be resolved in a single bulk request.
const MaxBulkResolveSize = 200
// =============================================================================
// POST /v1/alerts/bulk/assign - Bulk assign alerts
// =============================================================================
// BulkAssignRequest assigns multiple alerts to the same analyst.
type BulkAssignRequest struct {
// Alert IDs to assign
AlertIDs []int64 `json:"alert_ids"`
// Email of the analyst to assign to (required)
AssignTo string `json:"assign_to"`
}
// BulkAssignResponse reports per-alert success or failure.
type BulkAssignResponse struct {
Assigned int `json:"assigned"`
Failed int `json:"failed"`
Results []BulkAssignResult `json:"results"`
}
// BulkAssignResult is the outcome for a single alert in a bulk assign.
type BulkAssignResult struct {
AlertID int64 `json:"alert_id"`
Success bool `json:"success"`
Error string `json:"error,omitempty"`
}
// MaxBulkAssignSize limits how many alerts can be assigned in a single bulk request.
const MaxBulkAssignSize = 200
// =============================================================================
// GET /v1/alerts/stats - Alert queue statistics
// =============================================================================
// AlertStatsResponse provides a breakdown of the alert queue for management
// dashboards and compliance reporting. Answers "how many alerts by status
// and score tier?" without paginating through the full list.
type AlertStatsResponse struct {
// Total alerts across all statuses
Total int `json:"total"`
// Counts by status
ByStatus map[string]int `json:"by_status"`
// Counts by score band for open (non-closed) alerts
ByScoreBand map[string]int `json:"by_score_band"`
// SLA compliance for open alerts
Overdue int `json:"overdue"`
WithinSLA int `json:"within_sla"`
NoDeadline int `json:"no_deadline"`
}
// ActivityStatsResponse is the count companion to GET /v1/alerts/activity.
// Answers "how many case-activity records match this filter/period?" without
// paging the trail. Honors the same alert_id/actor/action/from/to filters as
// the list endpoint.
type ActivityStatsResponse struct {
// Total activity records matching the (optional) filters.
Total int `json:"total"`
// ByAction counts records by action (e.g. assign, escalate, dismiss).
ByAction map[string]int `json:"by_action"`
}
// =============================================================================
// GET /v1/alerts/resolutions/stats - Observed false-positive rate from analyst
// resolutions
// =============================================================================
//
// The production false-positive feedback loop (#92): every alert resolution
// carries a structured reason code, and this endpoint aggregates those
// dispositions into an observed FP rate by score band — the measured
// counterpart to the fixture-derived FP benchmark. Use it to answer "of the
// alerts we raise at each score band, what share do analysts dismiss as
// false positives?" — the driving input of the threshold tuning procedure
// (docs/testing/tuning.md).
//
// Counting model: resolution events from the immutable case-activity trail
// (action=status_change into a closed_* status), joined to the alert for its
// score. A reopened-and-reclosed alert contributes each closure — the rate
// measures analyst decisions, not current alert states. Only scores >= the
// tenant's alert threshold ever create alerts, so bands below the threshold
// in effect at alert time are structurally empty.
//
// Optional query parameters: from and to (YYYY-MM-DD, inclusive) bound the
// resolution date; omitting both aggregates all history.
// ResolutionBandStats is one score band's resolution outcomes.
type ResolutionBandStats struct {
// Resolved is total resolution events in this band.
Resolved int `json:"resolved"`
// FalsePositives is resolutions into closed_false_positive.
FalsePositives int `json:"false_positives"`
// TrueMatches is resolutions into closed_true_match.
TrueMatches int `json:"true_matches"`
// FPRate is FalsePositives / Resolved (0 when the band is empty).
FPRate float64 `json:"fp_rate"`
}
// ResolutionStatsResponse reports resolution-derived screening quality
// metrics. "Resolution" here is the analyst decision recorded by POST
// /v1/alerts/{id}/resolve — distinct from ScreenMatch.DismissalSignals,
// which are engine-computed score-reduction signals on a single match.
type ResolutionStatsResponse struct {
// Total resolution events in the window.
Total int `json:"total"`
// FalsePositives and TrueMatches are the window-wide outcome split.
FalsePositives int `json:"false_positives"`
TrueMatches int `json:"true_matches"`
// ObservedFPRate is FalsePositives / Total (0 when Total is 0) — the
// production-measured false-positive rate.
ObservedFPRate float64 `json:"observed_fp_rate"`
// ByScoreBand splits outcomes by the alert's match score band
// ("95-100", "90-94", "80-89", "below-80" — same bands as
// GET /v1/alerts/stats).
ByScoreBand map[string]ResolutionBandStats `json:"by_score_band"`
// ByReason counts resolutions by their structured reason code
// (Reason* constants).
ByReason map[string]int `json:"by_reason"`
// From/To echo the applied window bounds (YYYY-MM-DD), empty when
// unbounded.
From string `json:"from,omitempty"`
To string `json:"to,omitempty"`
}
// =============================================================================
// GET /v1/alerts/{id}/ofac-report - Generate OFAC-ready blocking/reject report
// =============================================================================
// OFACReportResponse assembles everything OFAC needs for a blocking or reject
// report into a single response. Only available on alerts resolved as
// closed_true_match with a disposition of "blocked" or "rejected".
type OFACReportResponse struct {
// Alert that triggered this report
AlertID int64 `json:"alert_id"`
// Report type derived from disposition: "blocking" or "reject"
ReportType string `json:"report_type"`
// When this report was generated (RFC 3339)
GeneratedAt string `json:"generated_at"`
// The name that was screened
ScreenedName string `json:"screened_name"`
// SDN entry that matched
SDNMatch OFACReportSDNMatch `json:"sdn_match"`
// Screening audit data
Screening OFACReportScreening `json:"screening"`
// How the alert was resolved
Resolution OFACReportResolution `json:"resolution"`
// Fields your institution must complete before filing
InstitutionFields OFACReportInstitutionFields `json:"institution_fields"`
}
// OFACReportSDNMatch contains the matched SDN entry details for the report.
type OFACReportSDNMatch struct {
UID string `json:"uid"`
FirstName string `json:"first_name,omitempty"`
LastName string `json:"last_name,omitempty"`
Programs []string `json:"programs,omitempty"`
Score float64 `json:"score"`
MatchSources []MatchSource `json:"match_sources,omitempty"`
}
// OFACReportScreening contains audit trail data from the screening.
type OFACReportScreening struct {
ScreenedAt string `json:"screened_at"`
OFACPublishID string `json:"ofac_publish_id,omitempty"`
OFACPublishDate string `json:"ofac_publish_date,omitempty"`
TraceID string `json:"trace_id"`
}
// OFACReportResolution contains the alert resolution details.
type OFACReportResolution struct {
Status string `json:"status"`
Disposition string `json:"disposition"`
Reason string `json:"reason"`
ResolvedBy string `json:"resolved_by"`
ResolvedAt string `json:"resolved_at"`
GLCitation string `json:"gl_citation,omitempty"`
Note string `json:"note,omitempty"`
}
// OFACReportInstitutionFields are fields Noble Sight cannot provide.
// Your institution must complete these before filing with OFAC.
type OFACReportInstitutionFields struct {
TransactionDescription *string `json:"transaction_description"`
TransactionValue *string `json:"transaction_value"`
Instructions string `json:"instructions"`
}
// ErrAlertNotTrueMatch is returned when requesting an OFAC report for an alert
// that is not resolved as a true match with a reportable disposition.
var ErrAlertNotTrueMatch = errors.New("OFAC report requires a true match alert with blocked or rejected disposition")
// Error code for OFAC report precondition failures.
const CodeAlertNotReportable = "alert_not_reportable"
// =============================================================================
// GET /v1/account - Account overview for the authenticated API key
// =============================================================================
// AccountResponse returns the account overview for the authenticated API key.
// Combines tier, usage, billing status, and rate limits in a single call.
type AccountResponse struct {
// Client identifier
ClientID string `json:"client_id"`
// Current API key prefix (for identification)
KeyPrefix string `json:"key_prefix"`
// Current tier: free, standard, premium, enterprise
Tier string `json:"tier"`
// Billing status: "active", "none" (free tier), "past_due", "canceled"
BillingStatus string `json:"billing_status"`
// Usage in the current rate limit window
Usage AccountUsage `json:"usage"`
// Features available on this tier
Features AccountFeatures `json:"features"`
// Capability scopes granted to this key. Every key has "api" (REST access).
// Additional scopes like "mcp" gate access to specific surfaces — the MCP
// server sends X-Noble-Client: mcp on every request, which the API rejects
// with 403 (code: scope_required) when "mcp" is not present here. Agents
// can read this to discover whether MCP setup will work before attempting.
Scopes []string `json:"scopes"`
// OwnershipRecheck is present on a PATCH /v1/account response whose
// change added ownership regimes: the portfolio re-check it queued
// (#744). Absent on GET and on a PATCH that added none.
OwnershipRecheck *AccountOwnershipRecheck `json:"ownership_recheck,omitempty"`
}
// AccountOwnershipRecheck is the portfolio re-check a PATCH /v1/account
// queued for the ownership regimes it added.
type AccountOwnershipRecheck struct {
// Regimes is the regimes added, in OwnershipAllRegimes order.
Regimes []string `json:"regimes"`
// Entities is how many entities blocked or under review under those
// regimes the re-check decides against the tenant's portfolio; 0 when
// the current determinations hold none, and nothing was queued. Alerts
// it raises appear on GET /v1/alerts?source=ownership, typically within
// minutes.
Entities int `json:"entities"`
}
// AccountUsage contains current usage stats.
type AccountUsage struct {
// Requests used in the current window
Used int `json:"used"`
// Total request limit for the current window. Absent when Unlimited.
Limit *int `json:"limit,omitempty"`
// Requests remaining. Absent when Unlimited.
Remaining *int `json:"remaining,omitempty"`
// Unlimited is true when the key has no quota (#565).
Unlimited bool `json:"unlimited"`
// Rate limit window: "day" (free) or "month" (paid)
Window string `json:"window"`
}
// AccountFeatures describes what the current tier unlocks.
type AccountFeatures struct {
Screening bool `json:"screening"`
DeepScreen bool `json:"deep_screen"`
BatchScreening bool `json:"batch_screening"`
PortfolioMonitor bool `json:"portfolio_monitoring"`
ComplianceExports bool `json:"compliance_exports"`
AlertManagement bool `json:"alert_management"`
MaxBatchSize int `json:"max_batch_size"`
// MCP reports whether this key can use the Model Context Protocol server —
// the 'mcp' scope. Granted on every tier.
MCP bool `json:"mcp"`
// ConfidentialPortfolio reports whether this key holds the Confidential
// Portfolio (BYOK) add-on: portfolio PII stored encrypted at rest under a
// customer-controlled KMS key. Enterprise add-on; manage the key via
// /v1/portfolio/key.
ConfidentialPortfolio bool `json:"confidential_portfolio"`
// AlertThreshold is the minimum match score that triggers alert creation.
// Screenings with a highest match score below this value do not generate alerts.
// Default: 80. Configured per tenant; valid range 50-95 (bounds are
// database-enforced so no configuration can silently suppress
// strong-match alerts).
AlertThreshold int `json:"alert_threshold"`
// OwnershipRegimes is the ownership regimes the tenant declared it is
// bound by (#728), in OwnershipAllRegimes order. A screening without
// lists reads these regimes (ownership.regimes_from "account"), and
// portfolio monitoring raises ownership alerts under these only; lists
// on a request still select per call. Default: every regime. Set with
// PATCH /v1/account. Null when the setting could not be read.
OwnershipRegimes []string `json:"ownership_regimes"`
// OwnershipRegimesDeclared is true when the tenant has declared its
// regimes, and false when it never has (or reset with null): then it is
// bound by every regime, including any added later. An explicit list of
// all of today's regimes reads true.
OwnershipRegimesDeclared bool `json:"ownership_regimes_declared"`
}
// =============================================================================
// PATCH /v1/account - Update tenant settings (#728)
// =============================================================================
//
// Updates the settings of the caller's tenant and returns the account as
// GET /v1/account does. Only features.ownership_regimes is settable:
//
// curl -X PATCH https://api.noblesight.io/v1/account -H "X-API-Key: $KEY" \
// -H 'Content-Type: application/json' -d '{"features":{"ownership_regimes":["us"]}}'
//
// ownership_regimes must name at least one regime, each a key of
// OwnershipRules ("us", "uk", "eu", "un", "ca", "au"), or be null; anything
// else is 400 invalid_parameter with param features.ownership_regimes.
// null resets the tenant to never having declared: bound by every regime,
// including any added later, which an explicit list of today's regimes is
// not:
//
// curl -X PATCH https://api.noblesight.io/v1/account -H "X-API-Key: $KEY" \
// -H 'Content-Type: application/json' -d '{"features":{"ownership_regimes":null}}'
//
// A body that sets nothing is 400 invalid_parameter. The setting applies to every
// key of the tenant from its next request. A key with no tenant is 403
// tenant_not_provisioned.
//
// Every change is one append-only row in customers.tenant_setting_change:
// the value before and after (null when never declared, or reset), the key
// that changed it and the trace id (X-Trace-ID, or one Noble mints and returns
// in that header). A tenant that never declared is bound by every regime,
// including any added later.
// Setting the value the tenant already holds changes nothing and writes no
// row.
//
// A change that adds a regime the tenant was not bound by (["us"] to
// ["us","eu"], or ["us"] to null) re-checks its portfolio under the added
// regimes (#744). Portfolio monitoring raises an ownership alert when a
// determination changes and decides it under the regimes the tenant
// declares at that moment, so an entity blocked under a regime while the
// tenant had it off was never alerted on. The change queues, in the same
// transaction, a check of every current blocked or review determination
// under the added regimes against the tenant's portfolio, Confidential
// Portfolio entities included, and the response carries ownership_recheck.
// Alerts it raises carry trigger kind "regimes_added"; a pair the tenant
// already holds an open ownership alert for is noted on that alert, not
// raised twice. Removing a regime closes nothing: open alerts stand.
// AccountUpdateRequest is the body of PATCH /v1/account.
type AccountUpdateRequest struct {
Features *AccountFeaturesUpdate `json:"features"`
}
// AccountFeaturesUpdate is the settable part of AccountFeatures.
type AccountFeaturesUpdate struct {
// OwnershipRegimes replaces the tenant's declared regimes when present:
// a JSON array of regimes, or null to reset to the default (every
// regime, never declared). Absent leaves the setting unchanged.
OwnershipRegimes json.RawMessage `json:"ownership_regimes,omitempty"`
}
// =============================================================================
// DELETE /v1/account/keys/{key_prefix}?confirm={key_prefix} - Revoke a key (#570)
// =============================================================================
//
// Revokes one of the caller's own API keys: the key making the request, or
// a key of the same client_id issued before it. A key cannot revoke a key
// issued after it (403 api_key_revoke_forbidden), so after a rotation the
// new key retires the old one, and a leaked old key cannot revoke the key
// that replaced it. key_prefix is the key's first 16 characters (noble_live_
// and five more), as GET /v1/account and every log line show it; confirm
// must repeat it, so a stray DELETE revokes nothing (400
// confirmation_required). An optional reason query parameter (at most 500
// bytes, no control characters) is recorded.
//
// Only keys of the caller's own client_id can be revoked: any other prefix is
// 404 not_found, whether or not it exists elsewhere. Should two of the
// caller's keys share a prefix, revoking another key by it is refused with
// 409 key_prefix_ambiguous rather than guess (contact support@noblesight.io);
// a key revoking itself is never ambiguous.
//
// Revocation stops the credential; it does not undo what the key did. After
// revoking a leaked key, review GET /v1/webhooks for endpoints you did not
// register and remove them, since webhooks belong to the account, not to
// the key that registered them.
//
// Revocation applies on the key's very next request, on every replica: keys
// are read from the database on each request and never cached. A revoked
// key is answered 401 api_key_revoked, distinct from 401 api_key_invalid
// for a key Noble does not recognize. The key's records (screenings, alerts,
// usage) stay with the account; only the credential stops working. There is
// no un-revoke: ask Noble for a new key.
//
// Revoking a key that is already revoked changes nothing and returns the
// original revocation. Revoking the last active key of the client_id is
// allowed, and the response says so: active_keys_remaining is 0 and warning
// is set. This call is never refused for quota, so a leaked key that
// exhausted the quota can still be revoked. If the calling key is itself
// revoked while the request runs (two keys revoking each other), the
// request fails 401 api_key_revoked and revokes nothing.
//
// Each revocation is one append-only row in customers.api_key_revocation,
// written in the same transaction as the status change, carrying the
// revoking key, the reason and the trace id.
// RevokeKeyResponse reports a revoked key.
type RevokeKeyResponse struct {
KeyPrefix string `json:"key_prefix"`
Status string `json:"status"` // always "revoked"
// RevokedAt is when the key stopped working (RFC 3339). Empty only for
// a key revoked by Noble before revocation was recorded.
RevokedAt string `json:"revoked_at,omitempty"`
// AlreadyRevoked is true when the key was revoked before this request,
// which changed nothing.
AlreadyRevoked bool `json:"already_revoked"`
// ActiveKeysRemaining counts the client_id's keys still active after
// this revocation.
ActiveKeysRemaining int `json:"active_keys_remaining"`
// Warning is set when no active key remains: the account can no longer
// call the API until Noble issues a new key.
Warning string `json:"warning,omitempty"`
}
// =============================================================================
// =============================================================================
// GET /v1/account/coverage - Control coverage report (#524)
// =============================================================================
//
// Most of Noble's controls fire only when the integration sends the field
// they need: an exact name-and-DOB match needs date_of_birth, an identifier
// hit needs ids, the Crimea advisory needs address or location, four-eyes
// closure needs a registered analyst in X-Actor. Noble holds every tenant's
// screening requests and alert activity in the audit record, so it can tell
// a tenant, from its own data, which of those controls its integration
// actually exercises — and which OFAC enforcement release its configuration
// currently resembles (https://noblesight.io/enforcement/).
//
// GET /v1/account/coverage?from=YYYY-MM-DD&to=YYYY-MM-DD
//
// from/to are inclusive UTC days; absent, the window is the last 90 days.
// A window longer than CoverageMaxWindowDays is refused with 400
// invalid_parameter. Screenings are the tenant's api and batch channel
// screenings with outcome completed; monitoring re-screens are the
// server's, not the integration's, and are not counted. Read-only.
// CoverageMaxWindowDays caps the report window.
const CoverageMaxWindowDays = 366
// CoverageDefaultWindowDays is the window when from/to are absent.
const CoverageDefaultWindowDays = 90
// Control statuses. A control is active when the share of screenings (or
// closures) that exercise it is at least CoverageActiveShare, partial when
// some do, inactive when none do, and not applicable when there was nothing
// in the window to measure.
const (
CoverageStatusActive = "active"
CoverageStatusPartial = "partial"
CoverageStatusInactive = "inactive"
CoverageStatusNotApplicable = "not_applicable"
)
// CoverageActiveShare is the share at or above which a control is active.
const CoverageActiveShare = 0.9
// Control identifiers, one per enforcement-mapped control.
const (
CoverageControlListVersions = "list_versions"
CoverageControlExactNameDOB = "exact_name_dob"
CoverageControlNoSuppression = "no_suppression"
CoverageControlLookback = "lookback"
CoverageControlIdentifiers = "identifiers"
CoverageControlGeography = "geography"
CoverageControlNamedActors = "named_actors"
// CoverageControlMonitoringLatency measures the monitoring promise
// itself: how long list changes took to be re-screened against the
// tenant's portfolio (and delivered, where a webhook received them)
// over the window, against the notify-within-minutes budget (#555).
CoverageControlMonitoringLatency = "monitoring_latency"
)
// CoverageCanary is the latest canary verdict inside the monitoring_latency
// control (#558). The canary list itself is internal — it cannot be screened
// or listed — but its measurement is public evidence.
type CoverageCanary struct {
// LastFlip is the scheduled hour of the most recent canary flip — the
// instant both this control and the receiver's delivered_after_s
// measure from, so the published evidence and the operator alarm can
// never disagree about the same delivery.
LastFlip string `json:"last_flip"`
// DeliveredAfterS is how long that flip took to reach the canary
// tenant's webhook, in seconds; null while delivery is still pending.
DeliveredAfterS *int64 `json:"delivered_after_s"`
// WithinBudget is the newest COMPLETED delivery's verdict: delivered
// within the budget and no older than two hours. An in-flight latest
// flip defers to the delivery before it; a canary gone quiet is false.
WithinBudget bool `json:"within_budget"`
}
// MonitoringLatencyBudgetS is the end-to-end budget, in seconds, for a
// sanctions-list change to be re-screened against monitored portfolios: the
// notify-within-minutes promise (15 minutes).
const MonitoringLatencyBudgetS = 900
// CoverageReport is the response.
type CoverageReport struct {
Window CoverageWindow `json:"window"`
// Screenings is the number of api and batch screenings in the window.
Screenings int `json:"screenings"`
// Inputs is, per request input, how many screenings carried it and the
// share of Screenings that did.
Inputs CoverageInputs `json:"inputs"`
// Alerts is the alert-workflow activity in the window.
Alerts CoverageAlerts `json:"alerts"`
// Controls is one entry per enforcement-mapped control, each naming the
// release and page it answers, what it requires, what was measured, and
// what to send.
Controls []CoverageControl `json:"controls"`
}
// CoverageWindow is the inclusive UTC day range the report covers.
type CoverageWindow struct {
From string `json:"from"`
To string `json:"to"`
}
// CoverageInput is how many screenings carried an input and the share of
// all screenings in the window that did (0 when there were none).
type CoverageInput struct {
Count int `json:"count"`
Share float64 `json:"share"`
}
// CoverageInputs covers every request input a control can depend on.
type CoverageInputs struct {
Name CoverageInput `json:"name"`
DateOfBirth CoverageInput `json:"date_of_birth"`
Country CoverageInput `json:"country"`
Location CoverageInput `json:"location"`
Address CoverageInput `json:"address"`
EntityType CoverageInput `json:"entity_type"`
// Identifiers counts screenings carrying ids or id_number.
Identifiers CoverageInput `json:"identifiers"`
// Lists counts screenings that restricted the lists screened.
Lists CoverageInput `json:"lists"`
// AsOf counts historical (lookback) screenings.
AsOf CoverageInput `json:"as_of"`
}
// CoverageAlerts is the tenant's alert-workflow activity in the window.
type CoverageAlerts struct {
// Opened is the number of alerts created in the window.
Opened int `json:"opened"`
// Closed is the number of closures (closed_false_positive or
// closed_true_match) recorded in the window.
Closed int `json:"closed"`
// ClosedByNamedAnalyst is the number of those closures whose actor was a
// registered analyst named in X-Actor.
ClosedByNamedAnalyst int `json:"closed_by_named_analyst"`
// ClosedByAPIKey is the number closed by the bare API key, with no
// analyst named.
ClosedByAPIKey int `json:"closed_by_api_key"`
// FourEyesClosures is the number of closures on alerts at or above
// FourEyesScoreThreshold, each of which required a second analyst.
FourEyesClosures int `json:"four_eyes_closures"`
// OpenOverdue is the number of alerts still open whose due_at has
// passed, as of the request.
OpenOverdue int `json:"open_overdue"`
// ActiveTeamMembers is the number of registered, active analysts.
ActiveTeamMembers int `json:"active_team_members"`
}
// CoverageControl is one enforcement-mapped control and whether the
// tenant's integration exercises it.
type CoverageControl struct {
// ID is one of the CoverageControl* constants.
ID string `json:"id"`
// Title is the control in one line.
Title string `json:"title"`
// Release names the OFAC enforcement release that penalized its absence.
Release string `json:"release"`
// Page is the enforcement-series page that proves the control.
Page string `json:"page"`
// Requires lists the request inputs (or workflow practice) the control
// depends on; empty for a control every screening exercises.
Requires []string `json:"requires"`
// Share is the measured share of screenings (or closures) that
// exercised the control, 0 to 1.
Share float64 `json:"share"`
// Status is one of the CoverageStatus* constants.
Status string `json:"status"`
// Guidance is one sentence on what to send, or that nothing is needed.
Guidance string `json:"guidance"`
// Latency carries the measured distribution for the monitoring_latency
// control and is omitted on every other control.
Latency *CoverageLatency `json:"latency,omitempty"`
}
// CoverageLatency is the measured monitoring-latency distribution over the
// report window: every list change in the window, how long each took from
// detection to fully re-screened (basis "rescreened"), or to the tenant's
// first webhook delivery where the tenant had one (basis "delivered"),
// against the MonitoringLatencyBudgetS budget. Each change is measured on
// its own jobs and alerts only, as ListLastChange's hops are. A change not
// yet fully re-screened is never left out: once it is older than the budget
// it is measured at its age so far, fails the budget, and keeps the control
// from reading active until its re-screen completes.
type CoverageLatency struct {
// WindowDays is the measurement window in days.
WindowDays int `json:"window_days"`
// Changes is the number of list changes measured in the window,
// including every unfinished change older than the budget.
Changes int `json:"changes"`
// Unfinished is the number of list changes in the window not yet fully
// re-screened: not yet queued, or with a re-screen job still pending,
// processing, failed or parked for operator review. 0 in a healthy
// state. One younger than the budget is in flight; one older is also in
// Changes at its age so far.
Unfinished int `json:"unfinished"`
// BudgetS is the budget each change is held to, in seconds.
BudgetS int `json:"budget_s"`
// P50S, P95S and MaxS are the distribution of the measured hop, in
// seconds, over Changes.
P50S int64 `json:"p50_s"`
P95S int64 `json:"p95_s"`
MaxS int64 `json:"max_s"`
// WithinBudget is whether P95S is at or under BudgetS.
WithinBudget bool `json:"within_budget"`
// Basis is "delivered" when the tenant had webhook deliveries to
// measure, else "rescreened" (hops through the completed re-screen).
Basis string `json:"basis"`
// Canary is Noble's own hourly synthetic proof that the chain is alive
// (#558): a feed Noble publishes and flips every hour, enrolled in a
// Noble-held tenant whose webhook measures how long the flip took to
// arrive. Omitted until the canary has published at least once. While
// present, the control passes only when the canary is in budget AND
// every real list is fresh — a green latency distribution cannot mask a
// dead chain on a quiet day or a red publisher behind a green canary.
Canary *CoverageCanary `json:"canary,omitempty"`
// ListsFresh is whether every customer-visible list with imported data
// currently passes its freshness thresholds (GET /v1/lists shows the
// per-list verdicts). Present only while the canary publishes — it is
// the second half of the canary conjunct.
ListsFresh *bool `json:"lists_fresh,omitempty"`
}
// GET /v1/account/features/history - The customer's entitlement record
// =============================================================================
//
// Answers the examiner's question about portfolio monitoring coverage: was
// the add-on on at time T, who turned it on or off, on whose authority, and
// which request did it. One row per change to portfolio_monitoring or
// confidential_portfolio on any of the account's keys, however the change
// was made (Noble operator, Stripe checkout, or the customer's own
// crypto-shred). Rows come from an append-only, trigger-protected table with
// a single writer, under the same 10-year retention monitoring as the
// screening record (31 C.F.R. § 501.601), and are returned as stored, never
// summarised. The current state is features on GET /v1/account.
//
// Cursor-paginated per the Pagination contract (oldest first; walk forward
// with ?after=<id>). Optional filters: ?feature=portfolio_monitoring |
// confidential_portfolio, and ?from=YYYY-MM-DD / ?to=YYYY-MM-DD on
// changed_at (UTC; to is inclusive of the whole day). Available on every
// tier: the record belongs to the account, not to a plan.
// Customer-facing actor values in FeatureChangeResponse.ChangedBy. A Noble
// operator is reported as the vendor, not as a named individual; the named
// identity is retained on the row and available to Noble support.
const (
ActorOperatorNoble = "operator:noblesight"
ActorStripePrefix = "stripe:"
ActorCustomerPrefix = "customer:"
)
// FeatureChangeResponse is one entitlement change. ID is both the cursor and
// the audit id an operator can cite.
type FeatureChangeResponse struct {
ID int64 `json:"id"`
// Feature is FeaturePortfolioMonitoring or FeatureConfidentialPortfolio,
// matching the field names under GET /v1/account features.
Feature string `json:"feature"`
EnabledBefore bool `json:"enabled_before"`
EnabledAfter bool `json:"enabled_after"`
// ChangedBy is who made the change: "operator:noblesight" (a Noble
// operator acting on a documented reason), "stripe:checkout" (the
// customer's own purchase), or "customer:<client_id>" (the customer's
// own action, today the Confidential Portfolio crypto-shred).
ChangedBy string `json:"changed_by"`
// Reason is the justification recorded with the change, verbatim.
Reason string `json:"reason"`
// TraceID is the X-Trace-ID of the request that made the change, when
// one was supplied; it joins to Noble's server log of the same event.
TraceID string `json:"trace_id,omitempty"`
// KeyPrefix identifies which of the account's keys the row applies to.
KeyPrefix string `json:"key_prefix"`
ChangedAt string `json:"changed_at"` // RFC 3339, UTC
}
// =============================================================================
// /v1/portfolio/key - Confidential Portfolio (BYOK) key management
//
// GET /v1/portfolio/key → key status/metadata (never key material)
// POST /v1/portfolio/key → provision a per-customer KMS-wrapped key
// DELETE /v1/portfolio/key?confirm=<client_id> → revoke + crypto-shred
//
// Requires the Confidential Portfolio add-on (RequireConfidentialPortfolio).
// DELETE is irreversible: it destroys the KMS key, permanently rendering all of
// the customer's encrypted portfolio PII unreadable. It demands the client_id as
// a confirmation query parameter to prevent accidental destruction.
//
// Capacity: encrypted portfolios are supported up to ~1,000,000 entities.
// Ciphertext cannot be probed through the trigram index, so portfolio
// monitoring decrypts the encrypted subset in memory on each list delta —
// a cost that grows linearly with encrypted rows. Larger encrypted portfolios
// require an engineering conversation (searchable-encryption roadmap) before
// onboarding; plaintext portfolios have no such ceiling.
// =============================================================================
// PortfolioKeyStatusResponse reports the state of a client's Confidential
// Portfolio encryption key. It never includes key material (DEK or wrapped DEK).
type PortfolioKeyStatusResponse struct {
// Status is "active" (key in use), "revoked" (crypto-shredded), or "none"
// (never provisioned).
Status string `json:"status"`
CreatedAt string `json:"created_at,omitempty"`
RevokedAt string `json:"revoked_at,omitempty"`
}
// =============================================================================
// POST /v1/account/checkout - Create a Stripe Checkout session for tier upgrade
// =============================================================================
// CheckoutRequest is the input for creating a billing checkout session.
type CheckoutRequest struct {
// Target tier to upgrade to: "standard", "premium"
// Enterprise requires contacting sales.
Tier string `json:"tier"`
// AddOn, when set, purchases an add-on instead of a tier upgrade. The only
// supported value is "confidential_portfolio" (the BYOK Enterprise add-on),
// which requires the account already be on the Enterprise tier.
AddOn string `json:"add_on,omitempty"`
}
// AddOnConfidentialPortfolio is the CheckoutRequest.AddOn value that purchases
// the Confidential Portfolio (BYOK) Enterprise add-on.
const AddOnConfidentialPortfolio = "confidential_portfolio"
// CheckoutResponse returns the Stripe Checkout URL for payment.
type CheckoutResponse struct {
// URL to redirect the user to for payment
CheckoutURL string `json:"checkout_url"`
}
// Error codes for billing operations.
const (
// CodeDeepScreenUnavailable: deep_screen was requested (and the tier
// allows it) but this deployment has no AI backend configured. 503 —
// the request is NOT silently downgraded to standard screening; retry
// without deep_screen or contact support. (Runtime AI failures degrade
// with an explicit deep_screen_fallback_reason instead.)
CodeDeepScreenUnavailable = "deep_screen_unavailable"
CodeBillingNotEnabled = "billing_not_enabled"
CodeAlreadyOnTier = "already_on_tier"
CodeInvalidTier = "invalid_upgrade_tier"
)
// =============================================================================
// POST /v1/watchlist - Add an internal watchlist entry
// =============================================================================
// WatchlistAddRequest is the input for adding a watchlist entry.
type WatchlistAddRequest struct {
// Full name to add to the watchlist (required). At most
// MaxWatchlistNameLength characters, counted as Unicode code points;
// the rest of the "Name input" rule applies as on /v1/screen.
FullName string `json:"full_name"`
// List name for categorization (e.g., "SAR Subjects", "Exited Customers").
// Defaults to "default".
ListName string `json:"list_name,omitempty"`
// Why this entity is on the watchlist (recommended for audit trail)
Reason string `json:"reason,omitempty"`
// Government identifier (optional)
IDNumber string `json:"id_number,omitempty"`
// ID type (e.g., "Passport", "SSN") (optional)
IDType string `json:"id_type,omitempty"`
// Country code ISO 3166-1 alpha-2 (optional)
Country string `json:"country,omitempty"`
// Entity type: "individual" or "entity" (default: "individual")
EntityType string `json:"entity_type,omitempty"`
// Expiration date in RFC 3339 format (optional). Entry stops matching after this date.
ExpiresAt string `json:"expires_at,omitempty"`
}
// WatchlistResponse is a single watchlist entry.
type WatchlistResponse struct {
// Entry ID
ID int64 `json:"id"`
// Full name on the watchlist
FullName string `json:"full_name"`
// List category
ListName string `json:"list_name"`
// Why this entity was added
Reason string `json:"reason,omitempty"`
// Government identifier
IDNumber string `json:"id_number,omitempty"`
// ID type
IDType string `json:"id_type,omitempty"`
// Country code
Country string `json:"country,omitempty"`
// Entity type
EntityType string `json:"entity_type"`
// Who added this entry
AddedBy string `json:"added_by"`
// When this entry was created (RFC 3339)
CreatedAt string `json:"created_at"`
// When this entry expires (RFC 3339), if set
ExpiresAt string `json:"expires_at,omitempty"`
// Entry status: "active" or "removed"
Status string `json:"status"`
}
// GET /v1/watchlist returns List[WatchlistResponse], cursor-paginated by entry
// id (?after=&limit=), ordered id ascending — see the "Pagination" contract.
// Optional filters: list_name, status (defaults to "active").
// MaxWatchlistNameLength is the maximum length for a watchlist entry name,
// in characters (Unicode code points), not bytes — the same limit as
// MaxNameLength, so any name the watchlist holds can be screened.
const MaxWatchlistNameLength = MaxNameLength
// MaxWatchlistImportSize is the maximum entries in a single bulk import.
const MaxWatchlistImportSize = 10_000
// =============================================================================
// Webhooks — POST /v1/webhooks, GET /v1/webhooks, DELETE /v1/webhooks?id=N
// =============================================================================
// Webhook limits.
const (
// MaxWebhooksPerTenant is the maximum number of active webhook registrations per tenant.
MaxWebhooksPerTenant = 5
// MinWebhookSecretLength is the minimum length for the shared HMAC secret.
MinWebhookSecretLength = 32
// MaxWebhookURLLength is the maximum allowed URL length.
MaxWebhookURLLength = 2048
// MaxWebhookDeliveryPasses is the number of delivery passes before an
// alert event is marked failed. Passes are scheduled on a persisted
// backoff spanning roughly 10 hours and survive server restarts; each
// pass makes one POST per registered endpoint that has not yet accepted
// the event. Events carry a stable evt_* id (payload "id" and
// X-Noble-Event-ID header) so consumers can deduplicate at-least-once
// delivery. A delivery failure never suppresses the alert itself —
// GET /v1/alerts remains the system of record.
MaxWebhookDeliveryPasses = 8
)
// WebhookCreateRequest registers a URL to receive alert notifications.
type WebhookCreateRequest struct {
// HTTPS URL to receive POST notifications (required)
URL string `json:"url"`
// Shared secret for HMAC-SHA256 signature verification (required, min 32 chars).
// Noble signs every outbound payload with this secret. The customer verifies
// the X-Noble-Signature header to confirm authenticity.
Secret string `json:"secret"`
}
// WebhookResponse is a registered webhook. The URL is masked after creation.
type WebhookResponse struct {
ID int64 `json:"id"`
URL string `json:"url"`
Status string `json:"status"`
CreatedAt string `json:"created_at"`
}
// GET /v1/webhooks returns List[WebhookResponse]. Unlike the other collection
// endpoints it is NOT paginated — a tenant holds at most MaxWebhooksPerTenant
// registrations, so the endpoint returns them all in data and ignores any
// ?after=/?limit= cursor params.
// WebhookStatsResponse is the count companion to GET /v1/webhooks. Because
// registrations are capped per tenant, the headline value is how much of that
// budget remains — "how many more webhooks can I register?"
type WebhookStatsResponse struct {
// Total registered webhooks for the tenant.
Total int `json:"total"`
// ByStatus counts registrations by status (e.g. active, disabled).
ByStatus map[string]int `json:"by_status"`
// Limit is the per-tenant cap (MaxWebhooksPerTenant).
Limit int `json:"limit"`
// Remaining registrations available before hitting Limit (never negative).
Remaining int `json:"remaining"`
}
// WebhookEvent is the payload POSTed to customer webhook URLs.
// Customers verify authenticity via the X-Noble-Signature header, signed over
// the X-Noble-Timestamp value and the raw body joined by a dot:
//
// signature = HMAC-SHA256(secret, timestamp + "." + request_body)
// header: X-Noble-Signature: sha256=<hex>
//
// Reject a delivery whose timestamp is more than 5 minutes from now (replay
// protection). The timestamp is fresh on every attempt; ID is stable across
// attempts, so deduplicate on it (also sent as X-Noble-Event-ID).
type WebhookEvent struct {
// Unique event ID (evt_ prefix)
ID string `json:"id"`
// Event type: "alert.created"
Type string `json:"type"`
// When this event was generated (RFC 3339)
CreatedAt string `json:"created_at"`
// Event payload: an alert summary with id, screened_name, score, source,
// status, trace_id, alert_reason and change_type, and on a monitoring
// alert its trigger (the AlertTrigger GET /v1/alerts/{id} returns) —
// not the full AlertResponse. Fetch the alert with GET /v1/alerts/{id}
// for match detail. screened_name is the customer's name, so treat the
// body as PII.
Data json.RawMessage `json:"data"`
}
// =============================================================================
// GET /status - Public system status (no auth required)
// =============================================================================
// StatusResponse reports system health for customer monitoring dashboards.
// No authentication required — compliance teams need to check this independently.
type StatusResponse struct {
// Overall status: "operational", "degraded", "outage"
Status string `json:"status"`
// Human-readable description
Message string `json:"message"`
// Component health
Components StatusComponents `json:"components"`
// When this status was generated (RFC 3339)
Timestamp string `json:"timestamp"`
// Monitoring is the depth and age of each queue a sanctions-list change
// passes through on its way to a portfolio-monitoring alert and its
// webhook. Null when it could not be read. Informational: it does not
// change Status. Refreshed at most every StatusMonitoringMaxAge.
Monitoring *MonitoringPipeline `json:"monitoring"`
}
// StatusMonitoringMaxAge is the longest GET /status serves a cached
// Monitoring block before reading the queues again.
const StatusMonitoringMaxAge = 15 * time.Second
// MonitoringPipeline counts the work in each portfolio-monitoring queue.
// A list change is first recorded as a delta, then screened against every
// monitored portfolio by a reverse-screen job, and each alert it raises is
// delivered to registered webhooks. Every *_oldest_s field is the age in
// seconds of the oldest row in that queue state, 0 when there is none.
// Counts are deployment-wide; no tenant's data is exposed.
type MonitoringPipeline struct {
// ReversePending counts reverse-screen jobs queued and not yet started.
ReversePending int `json:"reverse_pending"`
ReversePendingOldestS int64 `json:"reverse_pending_oldest_s"`
// ReverseProcessingOverHeartbeat counts jobs marked running that have
// committed no progress for over ten minutes: a stalled worker.
ReverseProcessingOverHeartbeat int `json:"reverse_processing_over_heartbeat"`
ReverseProcessingOverHeartbeatOldestS int64 `json:"reverse_processing_over_heartbeat_oldest_s"`
// ReverseFailed counts jobs that stopped on an error before screening
// every name in their delta, after three retries (1, 5 and 15 minutes
// apart) failed too. A job waiting out a retry counts in ReversePending.
ReverseFailed int `json:"reverse_failed"`
ReverseFailedOldestS int64 `json:"reverse_failed_oldest_s"`
// ReverseSkipped counts jobs held for operator review instead of
// screened. A delta over 5,000 names is split into several jobs, not
// held; only a single designation with more names than one job holds,
// which no list publishes, is.
ReverseSkipped int `json:"reverse_skipped"`
ReverseSkippedOldestS int64 `json:"reverse_skipped_oldest_s"`
// ReverseEncryptedSkipped counts the Confidential Portfolio customers
// whose encrypted portfolio the most recently finished reverse-screen job
// could not screen in full, because the customer's key is disabled or
// destroyed, the key service kept failing for that key through every
// retry (about 21 minutes), or a stored record does not decrypt. 0 in
// steady state; a customer that revoked its key through DELETE
// /v1/portfolio/key is not counted, since nothing of its portfolio is
// left to screen. A brief key service outage is not counted either: the
// job waits and retries, and shows in ReversePending. ReverseEncryptedSkippedOldestS is how long, in
// seconds, the longest-skipped of those customers has been skipped by
// every job without a break.
ReverseEncryptedSkipped int `json:"reverse_encrypted_skipped"`
ReverseEncryptedSkippedOldestS int64 `json:"reverse_encrypted_skipped_oldest_s"`
// WebhookPendingOver5m counts alert events awaiting webhook delivery for
// over five minutes, including events retrying against an endpoint that
// is refusing them. WebhookUnattemptedOver5m is the subset never
// attempted at all. WebhookPendingOldestS is the oldest pending event.
WebhookPendingOver5m int `json:"webhook_pending_over_5m"`
WebhookUnattemptedOver5m int `json:"webhook_unattempted_over_5m"`
WebhookPendingOldestS int64 `json:"webhook_pending_oldest_s"`
// DeltaPendingOver15m counts list changes imported over
// ListMonitoringDelayAfter ago and not yet queued for screening (the
// same condition as SanctionsListVersion.Monitoring "delayed").
// DeltaPendingOldestS is the oldest unqueued change.
DeltaPendingOver15m int `json:"delta_pending_over_15m"`
DeltaPendingOldestS int64 `json:"delta_pending_oldest_s"`
}
// StatusComponents reports health of individual subsystems.
type StatusComponents struct {
// Database connectivity
Database ComponentStatus `json:"database"`
// Name screening on the server that answered: "operational" when its
// sanctions-list index was confirmed current against the database
// within the last minute; "degraded" when it is still screening but has
// not confirmed that for over a minute (every screening still states
// its list_versions); "outage" when it refuses name screening with 503
// coverage_unavailable — no index loaded, or not confirmed current
// within the staleness bound — or the database is unreachable. A
// screening outage with the database up makes the overall status
// "degraded", not "outage": the rest of the API is serving, and
// /status answers 200.
Screening ComponentStatus `json:"screening"`
// Sanctions list ingestion freshness, from the same computation as
// GET /v1/lists: "operational" when every deployed list's status is
// "ok", "degraded" when any list is "degraded" or "stale" — screening
// continues against the last imported version; query GET /v1/lists for
// per-list status. "outage" when freshness cannot be determined
// (database unreachable). A degraded lists component degrades the
// overall status.
Lists ComponentStatus `json:"lists"`
// EmbargoTable is the review freshness of the comprehensive-embargo
// jurisdiction set behind jurisdiction_risk: "operational" when every
// entry has been reconciled against OFAC's published programs within the
// review window, "degraded" when the oldest review has aged past it.
//
// Unlike the other components this measures a HUMAN process, not a
// machine one. Sanctions lists arrive as feeds and go stale when a poll
// fails; comprehensive embargo programs are established and revoked by
// executive order with no feed to poll, so the table goes wrong when
// nobody reads the Federal Register. Degraded here means the set may no
// longer match current law — screening continues unchanged, and
// GET /v1/jurisdictions reports each entry's last review.
EmbargoTable ComponentStatus `json:"embargo_table"`
}
// ComponentStatus is the health of a single component.
type ComponentStatus struct {
// Status: "operational", "degraded", "outage"
Status string `json:"status"`
// Response time in milliseconds (where measurable)
LatencyMs *int64 `json:"latency_ms,omitempty"`
}
// Status constants for system health reporting.
const (
StatusOperational = "operational"
StatusDegraded = "degraded"
StatusOutage = "outage"
)
// =============================================================================
// Headers
// =============================================================================
//
// X-API-Key (required for /v1/* endpoints): API key for authentication.
// Keys use the format: noble_live_ + 32 hex characters.
//
// Screening API tiers:
// Free: 100 screenings/day ($0/mo)
// Standard: 5,000 screenings/mo ($199/mo)
// Premium: 25,000 screenings/mo ($499/mo)
// Enterprise: 100,000+ screenings/mo (custom pricing)
//
// Portfolio Monitoring: per-entity add-on, available on any paid tier.
//
// X-Trace-ID (optional): Client-provided trace ID for audit logging.
// Will be included in logs and database query comments.
//
// X-Noble-Client (optional): Identifies the official Noble client making the
// request. Currently recognized values:
// mcp — the `noble mcp` Model Context Protocol
// server. When this header is present, the
// API key must carry the "mcp" scope or
// the request is rejected 403
// (code: scope_required).
// Third-party clients should not set this header.
// Setting it without the matching scope is harmless
// but produces a 403 instead of normal access.
//
// Response headers on every request:
// X-Request-Id: Server-generated request ID (req_ + 16 hex chars).
// Server-Timing: The server's own measurement of the request, as
// W3C Server-Timing metrics in milliseconds. Every
// /v1/ response, errors included, carries
// "total;dur=<ms>". POST /v1/screen also reports
// the stages that ran, in pipeline order, so a slow
// screening shows where the time went:
// scan candidate search — the sanctions-list
// scan, watchlist, identifier probes and
// deep-screen name forms
// score scoring and ranking of candidates,
// attribute comparison
// enrich match enrichment, ownership analysis,
// list-version lookup
// persist the audit-trail write
// e.g. "total;dur=412.5, scan;dur=247.1,
// score;dur=7.2, enrich;dur=61.0, persist;dur=5.3".
// A stage is present only when it ran; stages are a
// breakdown of total, not additions to it, and need
// not sum to it (request parsing, alerting and the
// response write are in total only). These four
// names are stable; a stage may be added but never
// renamed or removed under the current version.
//
// Response headers on authenticated requests (omitted for a key with no
// quota — "unlimited": true on GET /v1/usage):
// X-RateLimit-Limit: Request limit for this key (daily or monthly).
// X-RateLimit-Remaining: Requests remaining in current window.
// X-RateLimit-Window: "day" (Free) or "month" (paid tiers).
// X-RateLimit-Reset: Unix timestamp when the rate limit window resets.
//
// Response headers on 429 (rate limit exceeded):
// Retry-After: Seconds until the rate limit window resets.
//
// Response headers on 503 coverage_unavailable from name screening
// (POST /v1/screen, POST /v1/batch, POST /v1/export/replay):
// Retry-After: Seconds to wait before retrying.
//
// Response headers on requests authenticated by a trial/comp key:
// X-Trial-Ends-At: RFC 3339 timestamp when the trial expires.
// X-Trial-Days-Remaining: Whole days until trial expiry (0 on the final day).
//
// Response on 402 (trial expired):
// Error code: trial_expired. The customer's trial_ends_at has passed and a
// nightly job has flipped the key's status to "expired". Contact sales to
// convert or extend.
Changelog
Recent API changes. Subscribe by polling GET /v1/changelog — public, no API key required, returns the same entries as machine-readable JSON.
| Date | Category | Change |
|---|---|---|
2026-11-14 |
changed |
Ownership alerts: an open alert is reused only when it was raised under a regime behind the current determination, so a screening no longer names an alert whose evidence is the retired pre-regime shape; both timelines note the supersession
/v1/screen
One open ownership alert per determined entity and change type (#163, #706) reused an alert whatever determination it was raised on. Since the regime model shipped on 2026-11-05, a screening of an entity whose alert predates it reads blocked under us on today's chain while ownership_alert_id names an alert carrying the retired legacy shape at another percentage and confidence, and nothing on the alert said it had moved on (Apex Development and Projects LLC, alert 48883, nepdave/noble#832). The dedup key now includes the regimes behind the alert (the regimes that blocked, or for a review alert the regimes that read review): an open alert raised under at least one of them is reused as before; one raised under none, such as legacy, is left as it stands, a new alert is raised with the current determination, and a note on each timeline names the other (Alert.Activity, actor system:ownership). No alert is closed by the system: the older one stays open for the analyst, who closes it under the ordinary rules. A review alert and a later blocking alert on the same entity remain two cases; the open review alerts raised before the regime model carry their regimes in their evidence and are reused as before. Amended the same evening, after the deploy left Apex on alert 48883: evidence written before the regime model (schema 1) records no regimes at all, and the first cut read that as an alert matching every regime; it now reads as legacy, exactly as GET /v1/alerts renders it, and is not reused. |
2026-11-14 |
changed |
Ownership: the ownership_review alert is decided regime by regime, so a party listed only by a foreign authority that a designated owner reaches under us raises its review alert again; overall.status keeps ranking the listing above the review
/v1/screen
The entry below of the same day (#818) made overall.status read designated for a party itself listed under a selected regime, and stopped the ownership_review alert with it. Royal Bank's corpus canary B6-02 (Volga Group) showed the cost the same afternoon: Canada lists Volga Group, so overall read designated, and the review under us, uk, eu and au (a chain to a designated party at an undisclosed stake) no longer reached any queue; a US bank's own regime read review silently. Ruling of 2026-11-14 (nepdave/noble#829, same-regime rule): a designation answers a review under the same regime, where the determination already reads designated, and answers nothing under another regime, whose analyst is bound by its own rule. The alert is therefore decided over the determinations of the regimes the request selected: ownership_blocked when any reached its consequence word, else ownership_review when any reads review, whatever overall says. Rosneft Trading SA (on OFAC's SDN list, review under uk) raises its uk review alert again for a tenant that selected uk; a party designated under a regime and clean under every other still raises none. overall.status and overall.regimes are unchanged; portfolio monitoring and batch items decide the same way through one function, so a monitored Volga Group raises the review alert at the next pass. Dedup is unchanged: one open alert per entity and change type, so a review alert that was open before #818 is reused, not doubled. |
2026-11-14 |
fixed |
Screening: a company's or vessel's alias on the France list is matched as one whole name, so a one-word query equal to its legal form ("ООО", "LLC", "Limited") no longer scores 100 against it; Canada's 34 bare legal-form aliases are removed
/v1/screen
France publishes an entity's alias legal form first ("ООО МУВЕРС ГРУПП" for Movers Group LLC), and the importer split every alias into a first name (its first word) and a last name (the rest), as it does for a person so a surname can be met on its own. The engine therefore met "ООО", "LLC" and "Limited" as first names, scored a one-word query equal to one at 100, called it confirmed_match and raised an alert (FR-11275, FR-3575, FR-7313 on 2026-11-14). A company's or a vessel's alias is now stored and matched as one name; a person's is split as before. The 4,549 entity alias rows the importer had split are collapsed in place (the searchable full name is identical before and after, so no record is re-published), and Canada's 34 aliases that are only a legal form, which the #778 filter never reached because the delta-aware import rewrites changed records only, are removed. A one-word query equal to one word of a person's multi-word alias on other lists ("Mohammed" against 54 UK records) is the same class and is tracked on nepdave/noble#820 for a matching-rule decision with an engine-diff; this entry changes list data only. |
2026-11-14 |
fixed |
Ownership: a name whose top match is a designated record at or above the alert threshold reads designated under that record's regime, never clean or unknown, whichever graph node the name resolved to; the control now reads the match engine's finding beside its own name index
/v1/screen
The ownership control resolved a screened name through its own name index alone. Sky Aviator hit OFAC SDN 39689 at 100 and raised a name alert while the ownership object read clean under every regime, because the name resolved exactly to a node list text had minted for the same company and no designation sat on that node; Arzamas Machine-Building Plant hit EU-138938 at 100 and read unknown, because the screened spelling was not exactly one of the designation's indexed names. The two halves of one screening disagreed about one party. Now the list records the screening's top matches hit, when their score reaches the tenant's alert threshold (the default when a tenant has none), travel with the name into the ownership control, and each designated record among them is reported as the party the name is, designated under its lists' regimes, exactly as an exactly-named record already was (#748): on the extracted node, on a fuzzy resolution to the record itself, and on a name the graph has no node near at all (then the record is the entity and every other regime reads unknown, since nothing of the party was evaluated). A block or a review the resolved node carries still outranks the designation under its regime; a record of OFAC's non-SDN Consolidated list alone is designated and marked non-blocking as before. Batch screening passes its items' matches the same way, and portfolio monitoring screens each name through the same engine before deciding it, so a monitoring alert's ownership evidence stays identical to what POST /v1/screen returns for the name. nepdave/noble#809. |
2026-11-14 |
fixed |
Ownership identity: two records that cite one published reference number but are held apart by a birth-year gap are shown as a possible same party on the ownership they carry (review, never clean), and a record of blank kind with a date of birth is a person for the registry-number rule
/v1/screen
Since 2026-11-11 no evidence short of an analyst's verdict joins two records whose birth years are two or more apart. That veto also split pairs a UN committee had joined under one reference number ("Between 1958 and 1960" against 1962), and the split was silent: the pair sat in the analyst queue, and a company one of the two records owns read clean under the regime that designates the other, because the owner was no longer that party. Ruling of 2026-11-14 (nepdave/noble#813, #712): the identity rules frozen on 2026-11-12 stand, and the split pair now reaches the ownership surface. Its queue row carries the reference as shared_reference evidence beside the birth-year conflict, and what the owner holds reads review with reason possible_same_party, the hop listing the other record and both facts, until an analyst's merge or separate verdict settles it. Separately, a record whose list left the type field blank but which publishes a date or year of birth is a person for the registry-number rule (companies and hulls are not born), so two such records sharing a name and a full date of birth link strong whatever their national id numbers; a blank-kind pair with no birth data still conflicts on differing numbers. No merge rule changes; the next identity run rewrites the queue's evidence. |
2026-11-14 |
fixed |
Ownership: a same-name pair the identity resolver has positively found to be two parties (registry numbers of one kind that differ, or birth years two or more apart) no longer puts what the owner holds under possible_same_party review
/v1/screen
Since 2026-11-10 a company reads review with reason possible_same_party when its owner's record shares a name with a designated record on another list that the identity resolver did not link, and the hop lists the evidence for and against the two being one party. The queue that feeds it also held pairs the resolver had positively split: two tankers named OKEANSKY PROSPECT with different IMO numbers, companies with differing OGRN numbers, people born a decade apart. Their evidence carried identifier_conflict or birth_year_conflict with supports false, and the hop still read review, so the resolver contradicted itself: it had found two parties and then asked whether they were one. Ruling of 2026-11-14 (nepdave/noble#814, #712): a pair whose evidence carries identifier_conflict, or birth years two or more apart on every reading (the resolver's own bar: a year apart is a typo the lists make, a decade two people), is no twin. The pair stays in the analyst queue with its evidence; what the owner holds reads as the regime's rule finds it without that pair. A pair whose birth years differ by one year, or whose only conflict is a full date or a programme, still raises review as before, and an analyst's merge verdict still blocks on the merged entity at the next computation. |
2026-11-14 |
fixed |
Ownership: a possible_same_party review on an entity the previous computation had blocked under us keeps its block (status blocked, reason possible_same_party); the contract said always review, the engine and the ruling say a block never lapses on an unreviewed identity re-run
/v1/screen
A company reads review with reason possible_same_party when its owner's record on one list is designated under the regime and the owner's own record is not, and the two are not shown to be one party. Since 2026-11-10 the contract said such a review is never blocked. The engine's sticky rule (us, OFAC FAQ 402: a block never auto-clears) kept the block anyway when the identity resolver's nightly run separated two records it had joined before, and the two disagreed. Ruling of 2026-11-14 (nepdave/noble#812, #712): the engine is right. Nothing a bank blocked yesterday is unblocked tonight by an identity re-run nobody reviewed; the row stays blocked with reason possible_same_party, blocked_since unchanged, and the hop carries the twin's evidence, so the analyst sees exactly why the block is now in question. Under a regime that is not sticky (uk, eu, ca) the row becomes review as before, and an entity with no prior block is a plain review. An analyst's merge or separate verdict on the pair settles it either way at the next computation. No live determination changes: the ruling records what the engine already does. |
2026-11-14 |
fixed |
Ownership: overall.status ranks a party's own designation above a review it is under elsewhere (blocked, designated, review, clean, unknown), so an entity itself on a list no longer reads overall review or raises an ownership_review alert beside its name alert
/v1/screen
overall summarised the selected regimes as blocked, else review, else designated. A party itself designated under one regime and under review under another (Rosneft Trading SA: on OFAC's SDN list, reviewed under uk for an undisclosed stake) therefore read overall review and raised an ownership_review alert beside the name alert its own listing raises, and an analyst could read the party as a pending question when its listing had answered it. A review asks whether a designated owner reaches the party; the party's own designation is the strongest ownership finding there is. overall.status is now designated whenever the party is itself designated under a selected regime and no regime blocked it, overall.regimes lists the designating regimes, and the review stays on its own regime's determination with its chains. Blocked still outranks everything. Ruling of 2026-11-14 on nepdave/noble#818 and #712. Amended the same day (#829, the entry above): this entry also stopped the ownership_review alert for such a party, and that half is reversed; the alert is decided regime by regime, so Rosneft Trading SA raises its uk review alert for a tenant bound by uk while overall still reads designated. |
2026-11-14 |
fixed |
Ownership: a parent company named by the leading word of its subsidiary's name ("Rusal" in a record of Rusal Armenal) stays the parent when another record already cites it, so the stake between them is kept
/v1/screen
Since 2026-11-10 a record's text that names its own subject by a short form ("GSK" for GSK Advance Company Ltd) is read as that subject. A parent's name is also a leading run of its subsidiary's name, and a parent no list designates has no designation to answer for it, so the rule read the parent as the subsidiary itself: the owner was keyed to what it owns and the edge between them, and every chain through it, was lost. A short form that another record's assertion already cites as a party of its own now stays that party; a short form only the record's own text ever used is still the subject. No production assertion had been collapsed this way when the fix shipped (three self-keyed statements existed, all true self-references); the extraction replay re-keys any that would have been. |
2026-11-14 |
fixed |
GET /status and GET /v1/jurisdictions: the comprehensive-embargo jurisdiction set was reconciled against OFAC's published programs on 2026-11-14 (no change to any entry), so /status returns to operational after reading degraded since 2026-11-13
/status
Every entry of the jurisdiction registry carries the date a human last reconciled it against OFAC's program index, and /status reports the set degraded once that date is more than 90 days old (the alarm that would have caught Syria's 2025 revocation, which the table carried for thirteen months). The 2026-08-15 review aged out on 2026-11-13. The 2026-11-14 review found no change: Cuba, Iran and North Korea remain comprehensive programs (Cuba's E.O. 14404 of May 2026 added secondary sanctions, not a change to the territorial embargo); Syria stays list-based; Crimea and the so-called DNR and LNR are unchanged; no covered-region determination under E.O. 14065 names Kherson or Zaporizhzhia; no new country-wide program in 2026. The reviewed_at date on every /v1/jurisdictions entry moves to 2026-11-14; Syria's known_to and the Kherson/Zaporizhzhia known_from (the table's own knowledge dates, used by as_of screenings and not fields of /v1/jurisdictions) keep 2026-08-15, the day the table learned those facts. |
Full feed: GET /v1/changelog
Auth
Every request requires an API key. Create one with your client ID, pass it in the X-API-Key header, and you're screening. Keys are prefixed noble_live_ for easy identification in your code.
POST /v1/keys
Invite-only: requires an invite_code issued by Noble Sight. Contact sales@noblesight.io for access. Rate limited to 10 requests per minute per IP.
curl -X POST https://noblesight.io/v1/keys \
-H "Content-Type: application/json" \
-d '{"client_id": "acme-bank", "name": "Production Key", "accept_terms": true, "invite_code": "noble_inv_..."}'
Response:
{
"key": "noble_live_a1b2c3d4e5f6...",
"key_prefix": "noble_live_a1b2c",
"client_id": "acme-bank-3f9c02ab",
"tier": "free",
"rate_limit_per_day": 100,
"terms_version": "1.0"
}
The full key is shown once. Store it securely — it cannot be retrieved again.
The client_id you send is a label. Noble assigns the key its own client_id: your label, then a hyphen and 8 random hex characters. Every signup creates a new customer, even if another customer used the same label, and the response is the same either way. Use the returned client_id (also reported by GET /v1/account) when you contact Noble about your account. To add a key to an existing account, contact support@noblesight.io.
accept_terms must be true. This confirms your institution acknowledges that screening results are informational only and do not constitute legal or compliance advice. The terms_version in the response records which version was accepted for your audit trail.
GET /v1/usage
Check how many screenings you've used in the current rate limit window.
curl https://noblesight.io/v1/usage \ -H "X-API-Key: $NOBLE_API_KEY"
Response:
{
"tier": "free",
"used": 42,
"limit": 100,
"remaining": 58,
"unlimited": false,
"window": "day"
}
Tiers
| Tier | Price | Screenings | Window |
|---|---|---|---|
free | $0 | 100 | Per day |
standard | $199/mo | 5,000 | Per month |
premium | $499/mo | 25,000 | Per month |
enterprise | Custom | 100,000+ | Per month |
Rate Limit Headers
Every authenticated response includes rate limit headers, except on an Enterprise key with no quota, where there is no limit to report and GET /v1/usage returns "unlimited": true:
| Header | Description |
|---|---|
X-RateLimit-Limit | Request limit for this key |
X-RateLimit-Remaining | Requests remaining in current window |
X-RateLimit-Window | day (free) or month (paid) |
X-RateLimit-Reset | Unix timestamp when the window resets |
Retry-After | Seconds until reset (only on 429 responses) |
X-Request-Id | Server-generated request ID for debugging |
Screen
One call screens a name against 18,598 sanctioned entities, 24,526 aliases, and 89,117 AI-generated spelling variations. Every match shows exactly how it scored and why, down to the individual data source.
POST /v1/screen
Screen a name against all active sanctions lists. Add date of birth, country, or entity type to reduce false positives — each mismatch applies a transparent score penalty.
curl -X POST https://noblesight.io/v1/screen \
-H "Content-Type: application/json" \
-H "X-API-Key: $NOBLE_API_KEY" \
-H "X-Trace-ID: onboarding-customer-42" \
-d '{
"name": "Vladimir Putin",
"date_of_birth": "1952-10-07",
"country": "RU",
"entity_type": "individual",
"id_number": "E12345678",
"id_type": "Passport",
"lists": ["ofac", "uk", "eu"]
}'
Every screening response includes a meta.disclaimer field. This is the full legal disclaimer bounding Noble Sight's liability — present in every response so your audit trail captures it alongside each screening decision. The disclaimer text is defined in the API contract.
When a screening produces matches above the alert threshold, the response includes an alert_id field — the ID of the alert created for this screening. Use it to track the match through the alert lifecycle, receive webhook notifications, or poll for new alerts using cursor-based pagination.
Deadline. A screening answers within 10 seconds, or 25 seconds with deep_screen or deep_summary. If it cannot, it returns 504 with code screening_timeout and the request_id and trace_id it is stored under. It never leaves the connection open. Set your client timeout a few seconds above the deadline. A screening that fails after its input was accepted is still in the audit trail: GET /v1/export?request_id=… returns it with outcome: "failed". A failed screening has no result, so screen the name again.
The Model Cascade
The architecture follows the model cascade recommended by Federal Reserve research (FEDS 2025-092): fast fuzzy matching for routine screens, AI escalation for hard cases. Every request passes through two paths.
Allen & Hatfield (2025) found LLMs reduce false positives by 92% but are 10,000x slower than fuzzy matching. Their recommendation: a model cascade — fast matching for easy cases, AI escalation for hard ones.
Match Sources
Every match includes a match_sources array — the complete evidence trail. When an OFAC examiner asks "why did this name match?", the answer is already in the response.
| Source | What It Matches Against | Example |
|---|---|---|
ofac_sdn |
Primary SDN entry names. Trigram similarity against full name, first name, and last name. | "Vladimir Putin" matches "Vladimir Vladimirovich PUTIN" |
ofac_aka |
Known aliases from OFAC's AKA list. Same trigram + Soundex matching. | "Abu Bakr al-Baghdadi" matches AKA "Ibrahim Awwad Ibrahim al-Badri" |
ofac_ai_variation |
89,117 Gemini-generated spelling, transliteration, and cultural variations. Pre-computed at import time with audit reasons. | "Qasem Soleimani" matches "Qassem Suleimani" (reason: "Common Farsi-to-English transliteration") |
ofac_cons, ofac_cons_aka |
Primary names and aliases on OFAC's Consolidated (non-SDN) lists. Same trigram + Soundex matching as the SDN pathways. | A sectoral (SSI) entity's name or AKA |
ofac_native_script, uk_non_latin, un_original_script |
A name the publisher gives in the party's own script (Cyrillic, Arabic, Chinese). Trigram only — Soundex is Latin-only. | "Владимир Путин" matches the Cyrillic name on the record |
uk_designation, uk_alias, eu_designation, eu_alias, un_designation, un_alias, france_designation, france_alias, belgium_designation, belgium_alias, netherlands_designation, netherlands_alias, canada_designation, canada_alias, australia_designation, australia_alias |
Primary names and aliases on each non-OFAC list, named <list>_designation and <list>_alias. Same trigram + Soundex matching. A person's name or alias is also met on its surname alone; a company's or a vessel's alias is matched as one whole name, never on one of its words, so a bare legal form ("ООО", "LLC", "Limited") reaches no company. |
"Vladimir Putin" matches the UK designation "Vladimir Vladimirovich PUTIN" |
deep_screen |
Real-time Gemini expansion of the search input. Only when deep_screen: true. |
"Димитрий Медведев" expands to "Dmitry Medvedev", "Dmitri Medvedev" |
ofac_id |
Exact match against OFAC ID numbers (passports, tax IDs, cedulas). Normalized: case-insensitive, strips spaces/dashes/dots. Score: 100. | Passport "E12345678" matches OFAC id_list entry for a sanctioned individual |
uk_id, eu_id, un_id, france_id, belgium_id, canada_id |
Exact match against that list's identification numbers (passports, national IDs, IMO numbers). Same normalization as OFAC. Score: 100. | A vessel's IMO number matches a UK or Canada designated ship |
internal_watchlist |
Trigram + Soundex match against your tenant's internal watchlist entries (SAR subjects, exited customers, etc.). Same scoring formula as sanctions matching. | "John Doe" matches your watchlist entry "Jon Doe" (list: "Exited Customers") |
Each source entry includes its own trigram_score and soundex_match flag. The entity's final score uses the best-scoring source.
The name you submit is screened as submitted and, where it differs, in a few derived forms; the score is the best of them, so a derived form can add a match but never lower one. A name with a bracketed part is also screened without it ("Bank Melli Iran (Tehran Branch)" as "Bank Melli Iran"). A company name with a legal form before or after it is also screened without the form: "PJSC AFK Sistema" as "AFK Sistema", "Testkomplekt LLC" as "Testkomplekt", spelled-out forms such as "Joint Stock Company" and "Aktsionernoe Obshchestvo" too. A form that is also a person's name ("Ao", "Sa") is dropped only when two words remain, and a single word is left only if it has five letters or more. A name that reads as mis-decoded text is also screened repaired.
The Scoring Formula
Character similarity and phonetic agreement combine into one number:
score = MIN(1.0, trigram_score + soundex_boost × (0.5 + 0.5 × trigram_score)) × 100
The trigram score measures character-level similarity (0.0–1.0) across the full name, first name, and last name fields. The engine takes the highest. Minimum threshold: 0.15.
The Soundex boost rewards phonetic agreement. Last name match: 0.30. Both first and last: 0.15 additional. Half the boost applies unconditionally and half in proportion to the character similarity it corroborates, so phonetic agreement amplifies a literal match rather than manufacturing one: at a trigram score of 0.60 a full 0.45 boost adds 0.36.
The score is capped at 100. The entity's final score is the best across all of its match sources.
Soundex handles reversed name order — "Maduro Nicolas" matches "Nicolas MADURO MOROS." AI variations do not receive a Soundex boost because they are already expanded forms.
What the Score Means
| Range | Meaning | Typical Action |
|---|---|---|
90–100 |
Strong match — near-exact name or phonetic equivalent | Escalate for review |
70–89 |
Moderate match — likely a transliteration or variant spelling | Review with context |
50–69 |
Weak match — partial similarity only | Low priority review |
Reducing False Positives
A missed sanction is a federal violation. Too many false positives cause alert fatigue — analysts stop looking carefully, which leads to the same outcome. The score has to be right.
When you provide entity_type, date_of_birth, or country, Noble Sight cross-references them against OFAC data for each match. Mismatches reduce the score using multiplicative penalties. The match is never hidden — the original score and every penalty reason are always in the response.
Entity Type
| Condition | Multiplier | A 96.7 becomes... |
|---|---|---|
| Entity type matches (or not provided) | 1.0 — no penalty | 96.7 |
| Entity type mismatch (e.g., individual vs. vessel) | 0.5 | 48.4 |
Date of Birth
| DOB Difference | Multiplier | A 96.7 becomes... |
|---|---|---|
| Exact match (within 30 days) | 1.0 — no penalty | 96.7 |
| Near miss (within 1 year) | 0.8 | 77.4 |
| Mismatch (within 5 years) | 0.6 | 58.0 |
| Far mismatch (over 5 years) | 0.4 | 38.7 |
Country
| Condition | Multiplier | A 96.7 becomes... |
|---|---|---|
| Country matches OFAC nationality | 1.0 — no penalty | 96.7 |
| Country does not match | 0.7 | 67.7 |
Penalties are multiplicative and applied in order: entity type, then date of birth, then country. A name scoring 96.7 with matching entity type, a 15-year DOB mismatch, and wrong country:
96.7 × 1.0 × 0.4 × 0.7 = 27.1
The dismissal_reasons array shows exactly which penalties were applied and why.
Entities without OFAC attribute data are never penalized. Absence of data is not evidence of mismatch.
Jurisdiction Risk
Scoring penalties are only half of what country does. A comprehensive OFAC embargo prohibits most dealings with a whole jurisdiction, whether or not any name matches a list — so a clean name with an Iran nexus is a compliance event that name screening alone will never surface.
When the geography you declare touches a comprehensively embargoed jurisdiction, the response carries a jurisdiction_risk block naming the sanctions program and its regulatory authority. It is advisory: it never blocks, and it never changes a match score. The licensing and exemption determination belongs to your compliance program, not to an automatic decision by us.
Declaring a region
The embargoes covering Crimea, Sevastopol, and the so-called DNR and LNR regions apply to regions, and those regions have no ISO 3166-1 country code. Ukraine itself is not embargoed, so country: "UA" is both correct and insufficient for a party in Sevastopol. Use the location object:
{
"name": "Example Shipping Company",
"location": {
"country": "UA",
"region": "UA-40",
"city": "Sevastopol"
}
}
region takes an ISO 3166-2 subdivision code or a common region name. Detection reads the region first, then the location's country, then the top-level country field, stopping at the first that resolves to a jurisdiction we have a determination about. So {"country": "UA", "region": "UA-40"} reports Sevastopol rather than unembargoed Ukraine, and {"country": "IR", "region": "IR-07"} still reports the Iran embargo — an ordinary province is not a determination, so it defers to its country. Supplying more precise geography never removes a signal.
location is evaluated for this advisory only and never contributes to scoring — declaring a nexus cannot reduce your own match scores. location.country must be an ISO 3166-1 alpha-2 code; anything else returns a 400 naming the field. region is deliberately not checked against the embargo list: "California" and "Nizhny Novgorod Oblast" are recorded and simply return no advisory, because failing your screening over a supplementary signal — or failing a ten-thousand-name batch over one ordinary item — would be the worse outcome. The one region we reject is a contradiction: a subdivision code that is not inside the country you declared.
What is covered
Cuba, Iran, North Korea, and the embargoed regions of Ukraine. Syria is deliberately absent: Executive Order 14312 revoked its sanctions program effective 1 July 2025. Kherson and Zaporizhzhia are also absent — E.O. 14065 covers regions "as may be determined by the Secretary of the Treasury", and no such determination has been made.
GET /v1/jurisdictions publishes the whole record, including effective dates and the jurisdictions we evaluated and excluded. It accepts as_of, so you can establish what was embargoed on the date of a past transaction, and GET /v1/jurisdictions/{code} accepts every token screening accepts — UA-43, CRIMEA, DPRK.
An as_of screening reports the embargo that was in force on that date, not the one our table happened to name then: screening an Iranian counterparty as of 2020 returns the 31 CFR Part 560 advisory, because Iran has been comprehensively embargoed since 1995. The complementary question — what a particular stored screening was actually told — is what POST /v1/export/replay answers, and it reproduces the advisory as issued even if our table has since been corrected.
What was evaluated
The advisory tells you what was found. Every response that declares geography also carries jurisdiction_nexus, telling you what was looked at:
{
"jurisdiction_nexus": {
"evaluated": "Crimea Republic",
"source": "location.region",
"status": "no_determination"
}
}
status is one of embargoed (always paired with a jurisdiction_risk block at level comprehensive_embargo), possible (a word in address or location.city names an embargoed region but the declared country places the subject elsewhere — a Crimean town is also a street name in Sydney; conflicts names the contradicting field, and the paired jurisdiction_risk is at level possible_embargo_nexus), evaluated_not_embargoed (we hold a determination for this place and it is not an embargo — Kherson, for instance), or no_determination (we hold none for the value you sent).
That last status is the one to check if you rely on declaring a nexus. Without it, a mistyped region and a region we evaluated and cleared return the same empty answer, and a typo looks exactly like a clean result. evaluated also makes the fall-through visible: declare {"country": "IR", "region": "IR-07"} and it reports IR, because we hold no determination about that province and the country embargo stands.
The advisory is disclosure-based. A nexus you do not declare is not detected — we never parse names for region words.
ID Number Matching
When you provide id_number, Noble Sight performs an exact match against sanctions ID tables across all supported lists — passports, tax IDs, cedulas, and other government identifiers. This catches the most dangerous evasion pattern: a sanctioned individual who changes their name but reuses an identity document.
ID numbers are normalized before matching: spaces, dashes, dots, and slashes are stripped, and the comparison is case-insensitive. An ID match always scores 100 — a deterministic identifier hit is the strongest possible signal.
If the same entity is found by both name and ID, the results are merged: the score stays at 100, and both source types (ofac_sdn + ofac_id) appear in match_sources. No duplicates.
Optionally provide id_type (e.g., "Passport", "National ID") to narrow the search to a specific document type.
List Selection
By default, every screening runs against all nine live sanctions lists: OFAC, UK, EU, UN, France, Belgium, Netherlands, Canada, and Australia. Use the lists parameter to restrict screening to specific lists — a US broker-dealer might only need OFAC, while an EU bank might screen against OFAC + EU + member states.
Valid values: ofac, uk, eu, france, belgium, netherlands, un, canada, australia. The response always includes a lists_screened field showing which lists were actually queried — populated even when you don't specify a filter, and never listing coverage that isn't loaded.
Every response also carries a coverage object — the explicit coverage assertion: {degraded, requested, expected, screened, issues[]}. Three conditions make it degraded. Two concern the lists: a screened list whose ingestion-freshness verdict is stale (the same verdict GET /v1/lists reports), and screened being a proper subset of expected. A screening degraded on either is refused by default with 503 coverage_degraded, naming the lists and the opt-in: pass allow_degraded_coverage: true to receive the reduced answer with coverage.degraded: true and an issue per affected list. The opt-in is stored with the request on the audit record — the institution's knowing election. A response narrower than its coverage contract can never look complete. A list whose publisher is down (source_unavailable on GET /v1/lists) is the exception: it is screened at its last snapshot without an election, and the response carries coverage.degraded: true, a list_source_unavailable issue with the publisher's error, since when and the publish_id screened, and a list_source_unavailable warning. The third condition concerns the ownership control: when its determination could not be read, the response is returned with an ownership_unavailable issue (list: "ownership") and coverage.degraded: true with no election, because the name matches are complete and only the ownership question is unanswered.
Internal watchlist screening always runs regardless of the lists filter — it's your tenant's own data, not a government list.
Deep Screen
Deep screen adds real-time Gemini AI expansion. Instead of matching only the name you provide, it generates cultural, phonetic, and transliteration variations of your input — then screens each one. Use it for onboarding, investigations, or any situation where you need the highest possible recall.
curl -X POST https://noblesight.io/v1/screen \
-H "Content-Type: application/json" \
-H "X-API-Key: $NOBLE_API_KEY" \
-d '{"name": "Димитрий Медведев", "deep_screen": true}'
| Aspect | Default Screen | Deep Screen |
|---|---|---|
| Latency | 110 ms median target, server-side | +1-3 seconds (Gemini API call) |
| Matching | Input name vs. SDN + AKA + stored AI variations | Input name + AI-expanded variations vs. SDN + AKA + stored AI variations |
| Use case | Transaction screening, high-volume daily checks | Customer onboarding, due diligence, investigations |
| Tier | Free and above | Standard and above |
Ownership
Under OFAC's 50 Percent Rule, an entity owned 50% or more in the aggregate, directly or indirectly, by one or more blocked persons is itself blocked, even though it appears on no list. Every sanctioning authority has a rule of this kind, and they differ. Every live name screening carries an ownership object with Noble's determination for the screened name under each authority's own rule: one per regime, never a sum across authorities.
The determination is precomputed from an ownership graph built from the ownership statements sanctions lists publish, corroborated by GLEIF corporate-relationship data, and looked up by name when you screen. The screened name is resolved to the graph node whose indexed name is nearest under the matching fold, and the match engine's own finding travels with it: every list record your matches hit at or above your alert threshold is read as a party the name is, so a name whose top match is a designated record reads designated under that record's regime whichever node the name resolved to, and never clean there because the graph indexed the party under another spelling. An owner a list names in its narrative is matched to its designation by every name the list publishes for it, primary name and aliases alike, compared under the same fold the matching engine applies to screened names (case, diacritics, punctuation and spacing aside), with a trailing acronym in brackets ignored, so a stake stated under an a.k.a. reaches the designated owner. A record's text that names its own subject by a short form, its leading words or its initials ("GSK" in the record of GSK Advance Company Ltd), means that subject, so the stake is evidence on the designated company and never on a node named only by the short form. A short form another record's statement has already established as a party of its own (an undesignated parent named by the leading word of its subsidiary, "Rusal" in a record of Rusal Armenal) stays that party, so the stake between parent and subsidiary is kept. A party several lists designate is one entity in the graph, with every list's designation on it (see Identity across lists). It never changes match scores or the summary verdict, which is computed from match scores alone; summary.text adds one sentence naming a blocked, review, designated or unavailable determination, so the synthesis never reads as a clear on an entity the ownership control found blocked. It is absent on identifier-only requests and on as_of screenings, because the graph reflects current data only.
Status
| Status | Meaning | What to do |
|---|---|---|
| the regime's consequence word | blocked (us), owned_or_controlled (uk, eu, un), deemed_owned (ca) or controlled_asset (au): parties that regime designates hold the entity under that regime's rule. | Treat it as a designation under that regime. Noble raises an ownership alert when any regime you selected reaches it. |
designated | The entity is itself designated under this regime: the records are on determinations.<regime>.designations, whether the name resolved to that party or the record is the match engine's own finding for the name. Its designation is the finding under that regime; a blocked or review the resolved node already carries under it still outranks the designation, and the entity is still evaluated under the others. | Act on the designation: the name match carries the alert. |
review | An ownership or control link to a party this regime designates exists, but no source discloses the stake (a GLEIF consolidation parent, an OFAC "Linked To" pointer, an extracted control statement), or a stake that once blocked the entity has fallen below the threshold (reason says which). | Investigate the stake. Not a blocked state. |
clean | The computation evaluated this entity under this regime and found no ownership by parties the regime designates within the graph's sources. | Advisory input to your own programme, not an exhaustive all-clear. |
unknown | No conclusion: the name is not in the graph, or a near-identical name carries a determination this one does not. | Not a clean result. The same party under another spelling may be blocked. |
not_applicable | The regime has no derivative rule for the programme the owner is designated under. | Nothing under this regime. |
unavailable | The control did not run for this screening: the determination could not be read. Never an answer about the entity. The response also carries an ownership_unavailable warning and a coverage issue with list: "ownership", so the record never reads as a clean check when none ran. | Screen the name again. |
overall is derived from the determinations of the regimes your request selected: blocked when any of them reached its consequence word, else designated when the entity is itself designated under a selected regime, else review, else clean when every selected regime evaluated the entity, else unknown; overall.regimes names the regimes behind it. It carries no rule of its own. A party's own designation outranks a review it is under elsewhere: the review asks whether a designated owner reaches the party, and its own listing has answered the summary word; the review stays on that regime's own determination and, where that regime does not itself list the party, still raises its ownership_review alert (alerts are decided regime by regime; see Ownership alerts). When the control did not run it is not derived at all: unavailable, with every selected regime unavailable too.
Regimes
A regime is a sanctioning authority, not a feed. lists on the request selects regimes the way it selects lists for name matching: ofac selects us; uk selects uk; eu, france, belgium and netherlands select eu (the national registers mirror EU designations and add domestic ones; the national list stays visible as the designation's list); un, canada and australia select un, ca and au. A request without lists gets the regimes your account declares it is bound by (features.ownership_regimes on GET /v1/account, every regime until you set it with PATCH /v1/account), and portfolio monitoring raises ownership alerts under those regimes only. A bank bound by OFAC declares ["us"] once, or screens with lists: ["ofac"], and reads one determination under one rule, and is alerted only on it. ownership.regimes_from says which chose the regimes: "lists" or "account". It is kept on the screening record.
| Regime | Rule | Threshold | Aggregates designated owners' holdings | Control without a stake | Consequence | Source |
|---|---|---|---|---|---|---|
us | ofac_sdn_50_percent | 50% or more, direct or indirect, through intermediaries that are themselves blocked. Owners count when OFAC's SDN list designates them; a party on OFAC's non-SDN Consolidated list alone (SSI, NS-MBS, CMIC, HKAA and the like) is not blocked, so what it owns is not blocked through it: it reads review with reason: "owned_by_non_sdn_designee", and the hop's designation carries non_blocking: true. An entity owned 50% or more, alone or in the aggregate, by parties on the Sectoral Sanctions Identifications list reads review with reason: "ssi_owned" and program: "UKRAINE-EO13662" on the hop: the SSI directives restrict it, they do not block it | Yes, across programmes (FAQ 399, 401) | review (FAQ 398) | blocked; sticky: an entity blocked while ownership was 50% or more stays blocked when the stake later falls below it, until the relationship ends or a human clears it (FAQ 402) | OFAC FAQs 398, 401, 402; sham-transactions guidance, 2026-03-31 |
uk | uk_ownership_or_control | More than 50% | No: different designated persons' holdings are not summed (OFSI general guidance §4.1.4) | review | owned_or_controlled | OFSI general guidance, updated 2026-05-12; OFAC–OFSI comparison guide, 2026-06-23 |
eu | eu_ownership_or_control | 50% or more | Yes | review | owned_or_controlled | Council Best Practices, 2024-07-03 |
ca | ca_deemed_ownership | 50% or more | Yes | review | deemed_owned | Global Affairs Canada, deemed ownership, in force 2023-06-22 |
un | un_owned_or_controlled | None: owned or controlled, per resolution | — | review | review only: any relationship to a designated party, or to an entity designated parties hold by stated stakes summing to 50% or more or that a list's text says it controls (directly or through such entities), is for a human to assess. Review does not reach on through an entity that is itself only under review (owned_or_controlled is reserved) | UN Security Council resolutions |
au | au_owned_or_controlled | None: a factual question of ownership or control | — | review | review only (controlled_asset is reserved) | DFAT Sanctions Compliance Toolkit |
A 50/50 joint venture of two designated owners is therefore blocked under us, owned_or_controlled under eu and deemed_owned under ca, and clean under uk, and the response says all four. Two unrelated 25% holders: the same. A single 51% holder: every numeric regime attaches. Under un and au any ownership or control relationship to a designated party is review, and so is one to a company designated parties together hold 50% or more of, or that one controls; a chain of undisclosed links (an association, then another) is not. An entity designated under one regime is still evaluated under the others: an EU-listed company wholly owned by an OFAC-designated person reads designated under eu and blocked under us.
Fields
| Field | Description |
|---|---|
schema | 2. A screening record or alert persisted before November 2026 carries schema 1 and is rendered with its one determination under the legacy regime, rule pre_regime_union. |
overall | Derived over the regimes your request selected: status and the regimes behind it (above). |
determinations | One determination per selected regime, keyed us, uk, eu, un, ca, au. Each carries the fields below. |
determinations.<regime>.rule | The rule the determination was reached under (the Regimes table). |
determinations.<regime>.status | One of the statuses above: the regime's consequence word, or designated, review, clean, unknown, unavailable, not_applicable. |
determinations.<regime>.aggregate_percent | The stake held by parties this regime designates, as its rule counts it: the sum of each chain's percent where the rule aggregates (us, eu, ca), the largest single designated holding where it does not (uk). Absent on review-only chains. |
determinations.<regime>.control | true when the chains include a link with no disclosed stake. Such a link holds the determination at review until a human approves the assertion. |
determinations.<regime>.blocked_since | The date the entity was first determined blocked under this regime by an unbroken sequence of computations. |
determinations.<regime>.reason | ownership_reduced_after_block: the stake fell below the threshold after the entity was blocked. short_extracted_name: the rule would block an entity known only by a one-word name of fewer than six letters that a list's text gives it, spelled-out initials ("G.S.K.") and a company form ("Ltd") aside (France's record names one company "GSK"), so it reads review: a human tells the company the text meant from every other company of that name. Still blocked under us, review under the other regimes, never clean without a human verdict. blocked_government_candidate and controlled_by_blocked_government (us): see Persons blocked by programme definition. possible_same_party: an owner has a record on another list that shares its name, is not linked to it, and is designated under this regime while the owner is not: review, or blocked when a sticky regime (us) had already blocked the entity. The rule is under Identity across lists. |
determinations.<regime>.blocked_basis | The programme definition a us determination rests on when it rests on no designation and no stake (e.g. government_of_iran); present on a blocked-government person's own determination and on determinations whose chains reach one. |
determinations.<regime>.chains | Each ownership path from the screened entity up to an owner this regime designates, ordered by first-hop stake, highest first. A chain passes only through intermediaries that are themselves blocked under this regime. |
entity_name | The graph entity the screened name resolved to. Name resolution is fuzzy, so compare it with what you sent. Empty when unknown. |
entity_key | The graph key of the entity entity_name names, in the same key space as hops[].entity_key. It identifies the entity however its name was spelled; ownership alerts deduplicate on it. Empty when unknown. |
entity | The entity the screened name resolved to: its key, its primary name, its designations (every list's record of it, each with list, uid and the grade by which it joined the entity) and its identity_grade. Present with every determination, and also on unknown when the name is, under the matching fold, exactly a designated party's: such a party is not evaluated by the computation, and its designations are the finding. Three shapes: a resolved party with its designations; an extracted node (key starting xname:) with no designations of its own, while the record the match engine found for the name designates it on determinations.<regime>.designations; and absent, when the name resolved to no node, or approximately to a party that carries no determination, in which case a matched record's designations are still on the determinations. A match at or above your alert threshold is read as the name itself, never as a fuzzy resolution. |
name_similarity | Trigram similarity (0–100) between your normalized input and entity_name; 100 is an exact normalized match. |
chains[].percent | The stake the chain's first hop holds in the screened entity. Indirect ownership passes only through links that themselves clear the regime's threshold (OFAC FAQ 401), so a chain contributes its first-hop stake, never a product along the path. 0 on review chains. |
chains[].hops | The ownership steps, from the screened entity's direct owner upward. The last hop is the sanctioned party. |
hops[].entity_key | The owner's key in the graph: ent:12345 for a designated party, xname:<name> for a party known only from a list's narrative, lei:5493001KJTIIGC8Y1R12 for a GLEIF-registered company. Keys are opaque identifiers; compare them, never parse them. |
hops[].entity_name | The owner's primary name. |
hops[].percent_owned | This owner's stake in the entity one step below it. Absent when no source discloses it. |
hops[].is_sanctioned | Whether this owner is itself designated on any list. Which lists, and so which regimes count it, is designations. |
hops[].sanctioned_list | The designating lists, comma-separated (ofac,uk): the lists of designations. |
hops[].designations | The owner's designation set when it is sanctioned: one entry per list that designates it, with that list's uid and the grade by which the record joined the entity. A party four lists designate appears once, with all four. |
hops[].identity_grade | The grade of the owner's entity as a whole: singleton, reference, strong, corroborated or verdict (below). |
hops[].source | Who asserted this step: gleif, ofac_linked_to, or list_text:<list> (an ownership statement in that list's published text, kept verbatim in Noble's audit store). |
hops[].assertion_id | On a list_text:<list> hop, the extracted ownership statement it rests on: the row Noble's audit store keeps with the list's verbatim text, publish id and review status. Absent on other sources. |
hops[].assertion_ids | Every statement of the list that states this stake, assertion_id first. Two records of one list can state the same relationship, the owner's and the owned company's; the hop takes the highest stake either states and cites both. |
hops[].source_sentence | The verbatim sentence of the list's published text the stake was extracted from, present with assertion_id: the evidence an examiner reads against the percentage. |
hops[].possible_same_party | On a possible_same_party determination's hop: each unlinked record that may be this owner, with its list, uid, entity_key, name, and its evidence: {type, value, supports} items, where shared_reference (one published reference number, such as a UN reference), shared_name, shared_programme and birth_year support the two being one party and identifier_conflict (registry numbers of one kind that differ, written a / b), birth_date_conflict, birth_year_conflict and programme_mismatch do not. |
hops[].blocked_basis, hops[].program | On an owner blocked by programme definition rather than by a designation: its basis and, when known, the OFAC programme. Such a hop has is_sanctioned: false and no designations. |
hops[].confidence | high (explicit percentage from an authoritative source, a list's own published text included), medium (GLEIF consolidation relationship) or low (a relationship with no stated percentage: a designation linkage or an extracted statement without a number). Only a stated percentage counts toward a blocked status: a low hop, which states none, supports review and never a block. |
as_of | The date of the ownership computation behind these determinations: one computation for every regime. |
regimes_from | "lists" when the request's lists selected the regimes; "account" when your account's declared ownership_regimes did, for a request without lists and for portfolio monitoring. |
source_publish_ids | The snapshot of every source the computation read, so the determinations can be reproduced for an examiner. |
Identity across lists
Sanctions lists describe the same party independently, each under its own record. The ownership graph resolves those records to one entity per party before any stake is counted, so an owner OFAC, the EU, France and the UK all designate is one node with four designations, a stake it holds is counted once under each regime that designates it, and the hop's designations name every list that does. Two records are merged only on evidence of the grades below; a name alone, equal or fuzzy, never merges two records. Pairs that share only a name wait in Noble's identity review queue until an analyst records a verdict with a reason, so a parent and a subsidiary that share an alias remain two entities. Two people who share only a one-word name, such as a given name, are not paired at all. A merge is logged with its evidence and is reversible; withdrawing one list's designation removes that designation and leaves the entity.
| Grade | Evidence |
|---|---|
singleton | One list designates the entity. No merge took place. |
reference | The records cite the same published reference number, such as a UN reference. |
strong | A name equal under the matching fold on both records, corroborated by an equal date of birth, a shared identification number (passport, national id, registration number) or, for a company, two or more distinct name forms in common. No evidence short of an analyst's verdict joins two records whose registry numbers of one kind differ (two IMO numbers are two hulls, two OGRNs two legal entities), whose birth years are two or more apart, or whose kinds differ: such a pair waits in the analyst queue with both values. A record whose list left its type blank but which publishes a date or year of birth is a person for the registry-number rule. A pair that cites one published reference number but is held apart by a birth-year gap is also shown as a possible same party on any ownership it carries, so that ownership reads review, never clean, until an analyst rules. A shared number still outranks a date a month or a year off, which the lists mistype at that rate. A vessel links on its IMO number only, never on its name: hulls reuse names. A number a list publishes with its label inside the value ("Numéro d'enregistrement: 1165029051472") is compared by the number alone; a code many companies share, such as a Russian KPP, never counts. |
corroborated | The same primary name on both records, legal form aside, the same kind of party and an overlapping sanctions programme, with no conflicting date or year of birth. The name must be specific: a company's at least two words once its legal form is set aside, one of them more than a trade word ("Trading", "Bank"); a person's three words or more. Its precision is being measured against a human-verified sample. |
verdict | An analyst's recorded merge verdict on a pair the evidence left as a candidate. |
An entity's identity_grade is its weakest link: an entity merged on a reference number and extended by a verdict reports verdict. Each designation carries its own grade.
Possible same party. Two records that share a name but not the evidence above stay two entities, and Noble does not guess. When one of them owns a company and the other is designated under a regime the first is not, the company reads review under that regime with reason: "possible_same_party", never newly blocked. One exception: a company the previous computation had blocked under a sticky regime (us, FAQ 402) stays blocked with this reason when its owner's identity falls open, because an identity re-run nobody reviewed never unblocks what you blocked yesterday; the hop carries the twin's evidence all the same, and your analyst's verdict on the pair settles it either way. The owner's hop names the other record under possible_same_party with the evidence for and against their being one party. Your analyst decides: if they are one party, the ownership is blocking evidence under that regime's rule; Noble records an analyst's merge verdict and the next recomputation blocks on the merged entity. The review reaches only what the owner holds directly. A pair an analyst has separated, two people who share only a one-word name, and a pair the resolver has found to be two parties (registry numbers of one kind that differ, or birth years two or more apart) raise none: that pair stays in the analyst queue with its evidence, but the same resolver does not then hold the owner's stake in question on the hop.
Analyst review of extracted ownership. Every ownership statement Noble extracts from a list's text starts with status auto. An operator records a verdict on it through the localhost-only admin endpoint POST /v1/admin/ownership/assertions/{id}/verdict: approved or rejected, with a reason and who decided, kept with the time of the decision. A rejected statement drops out of every determination at the next recomputation, its edge is retired from the graph, and the same statement in a later publication of the list is never re-emitted. The assertion_id on a hop is the pointer an examiner follows to the sentence and to any verdict on it.
Ownership alerts
An overall.status of blocked raises its own alert, separate from any name-match alert on the same screening. Because overall is derived over the regimes your lists selected, a block only a foreign authority's rule reaches never alerts a request scoped to ofac. The response carries it as ownership_alert_id beside alert_id, with alert_reason: "ownership_control" when it is the only alert. In GET /v1/alerts it has source: "ownership" and a score of 100.
A review determination raises its own alert too, with alert_reason: "ownership_review", change_type: "ownership_review" and a score of 60: a relationship to a designated party with no disclosed stake is OFAC's red flag (FAQ 398), and an analyst sees it without polling. It sits below the blocking alert in severity, needs no second analyst to close, and is counted apart by its reason, so a programme can route or tune it on its own. Both alerts are decided regime by regime over the regimes your request selected, never from overall: a review under any selected regime raises its alert even when the party is itself listed under another selected regime and overall reads designated, because a Canadian listing does not answer the US question (Volga Group: listed by Canada, reviewed under us; ruling of 2026-11-14). A listing under the same regime does answer it: that regime reads designated, not review, and raises none, so a party listed under us and clean elsewhere raises only its name alert. One open alert per determined entity, change type and regime set: a review alert and a later blocking alert on the same entity are two cases, and an open alert raised under regimes none of which is behind today's determination (the pre-regime shape retired on 2026-11-05) is not reused: a new alert carries the current determination, a note on each timeline (activity, actor system:ownership) names the other, and the older alert stays open for your analyst to close.
The blocking alert is not gated on your alert threshold: the 50 Percent Rule is categorical, not a fuzzy score. Because it scores 100, closing it requires a second analyst under the four-eyes rule. A blocked determination whose alert cannot be written is never returned: the screening fails with 503 alert_unavailable (as does a name match that must alert), nothing of the attempt is committed, the attempt is recorded as failed under its request_id, and you retry.
The alert carries its evidence. GET /v1/alerts/{id} returns the determination it was raised on as ownership, chains included, exactly as it stood when the alert was created, together with the screening_id and trace_id of the screening record behind it (GET /v1/export?trace_id= returns that record): the screening that raised it, or for a recompute alert the monitoring decision. There is one open ownership alert per determined entity (entity_key) for as long as it is open: screening the same entity again, under any of its names, returns the open alert.
Ownership is monitored. When Noble's nightly ownership recompute newly determines an entity blocked, or newly places it under review, every monitored portfolio entity whose name screens blocked or review for it raises the corresponding ownership alert with its portfolio_entity_id and a trigger of kind ownership_change, delivered to your webhook like every alert.
Example
Illustrative, for a request without lists: two owners hold 30% and 25% directly. Both are OFAC-designated and one is UK-designated too, so us sums them to 55 and blocks, uk tests the one UK-designated holding of 30 alone and finds nothing, and the regimes that designate neither owner report clean.
"ownership": {
"schema": 2,
"entity_name": "Example Shipping Holdings LLC",
"entity_key": "xname:example shipping holdings llc",
"name_similarity": 100,
"overall": {"status": "blocked", "regimes": ["us"]},
"determinations": {
"us": {
"rule": "ofac_sdn_50_percent", "status": "blocked", "aggregate_percent": 55, "blocked_since": "2026-11-07",
"chains": [
{"percent": 30, "hops": [
{"entity_key": "ent:10001", "entity_name": "EXAMPLE OWNER ONE", "percent_owned": 30, "is_sanctioned": true,
"sanctioned_list": "ofac,uk", "designations": [{"list": "ofac", "uid": "10001", "grade": "strong", "programs": ["RUSSIA-EO14024"]}, {"list": "uk", "uid": "RUS0001", "grade": "strong"}],
"identity_grade": "strong", "source": "list_text:uk", "confidence": "high"}]},
{"percent": 25, "hops": [
{"entity_key": "ent:10002", "entity_name": "EXAMPLE OWNER TWO", "percent_owned": 25, "is_sanctioned": true,
"sanctioned_list": "ofac", "designations": [{"list": "ofac", "uid": "10002", "grade": "singleton", "programs": ["IRAN"]}],
"identity_grade": "singleton", "source": "list_text:uk", "confidence": "high"}]}
]
},
"uk": {"rule": "uk_ownership_or_control", "status": "clean"},
"eu": {"rule": "eu_ownership_or_control", "status": "clean"},
"un": {"rule": "un_owned_or_controlled", "status": "clean"},
"ca": {"rule": "ca_deemed_ownership", "status": "clean"},
"au": {"rule": "au_owned_or_controlled", "status": "clean"}
},
"as_of": "2026-11-07",
"source_publish_ids": {"list_text:uk": "<snapshot id>"}
},
"ownership_alert_id": 5120
Human review
A stake Noble reads from a list's own published text is the authority's statement, quoted verbatim on the hop (source_sentence): a stated percentage carries confidence: "high" and counts under the regime's rule without prior human approval; a relationship the text states without a percentage carries low and is review. Every extracted assertion sits in Noble's review queue, and an analyst's verdict is the correction: a rejected assertion is dropped from every determination at the next recompute, its edge is retired from the graph at the next import, and a later extraction of the same record never resurrects it. The verdict is recorded with the analyst, the reason and the time.
Persons blocked by programme definition
OFAC's blocked-person universe is wider than its lists. Some programmes, the Crimea region of Ukraine, Cuba, Iran, North Korea, Syria and Venezuela, block persons who meet the definition of a blocked government without a designation (FAQ 398; 31 CFR 560.304 reaches any entity owned or controlled by the Government of Iran). Under us Noble treats such a person as a blocked person on a blocked_basis rather than a designation: government_of_iran, government_of_north_korea, government_of_syria, government_of_venezuela, government_of_cuba or crimea_region, each with its regulation.
An unlisted owner a list's text names as such a state body is a candidate: its own us determination is review with reason: "blocked_government_candidate" and the sentence that names it, and everything it owns is review under the same reason, never clean. Noble's analysts confirm or reject the candidate. A confirmed person seeds the us regime at the next recompute: its own determination is blocked on its basis, a stake of 50% or more it holds blocks the owned entity with blocked_basis and program on the hop (is_sanctioned stays false: the regulation names the owner, no list does), and a relationship with no stated percentage is review with reason: "controlled_by_blocked_government", because definition-based blocking reaches controlled entities and the 50 Percent Rule's percentage test does not. Every decision is recorded with the analyst, the reason, the time and the regulation.
Coverage
The graph sees only the ownership its sources disclose: entities named by sanctions lists and GLEIF-registered relationships, not every company. Treat the determination as input to your institution's own 50 Percent Rule program, not a substitute for it.
Batch
Screen up to 10,000 names in a single request. Submit a batch, poll for status, and retrieve results when complete. Standard tier and above.
POST /v1/batch
Submit a batch of up to 10,000 names. Each name is screened independently against all active sanctions lists with the same matching engine as single screens, and carries the same ownership determination under the job's lists, with ownership_alert_id and alert_reason as a single screen does. A batch that is accepted answers 202 Accepted; poll GET /v1/batch/status, which answers 200 at every stage.
curl -X POST https://noblesight.io/v1/batch \
-H "Content-Type: application/json" \
-H "X-API-Key: $NOBLE_API_KEY" \
-d '{
"names": [
{"full_name": "Vladimir Putin", "date_of_birth": "1952-10-07", "country": "RU"},
{"full_name": "Ali Khamenei", "country": "IR", "id_number": "A12345678", "id_type": "Passport"},
{"full_name": "John Smith"}
]
}'
Response:
{
"id": 1234,
"status": "pending",
"total_names": 3,
"processed_names": 0,
"match_count": 0
}
GET /v1/batch/status
Check batch progress. When status reaches completed, the response includes per-name results with match counts and highest scores.
curl "https://noblesight.io/v1/batch/status?id=1234" \ -H "X-API-Key: $NOBLE_API_KEY"
Response (completed):
{
"id": 1234,
"status": "completed",
"total_names": 3,
"processed_names": 3,
"match_count": 2,
"items": [
{"full_name": "Vladimir Putin", "status": "screened", "match_count": 1, "highest_score": 97.5, "alert_id": 42},
{"full_name": "Ali Khamenei", "status": "screened", "match_count": 1, "highest_score": 94.2, "alert_id": 43},
{"full_name": "John Smith", "status": "screened", "match_count": 0, "highest_score": 0,
"enrollment": {"status": "enrolled", "portfolio_entity_id": 501}}
]
}
Batch statuses: pending, processing, completed, failed. A completed batch has a recorded result for every item. If any item's result cannot be recorded, the batch is failed with an error_message, never completed over an item still reading pending. Submit it again.
Each screened item carries enrollment, exactly as POST /v1/screen reports it. With the portfolio add-on the name is enrolled for monitoring with the item's date_of_birth and country: enrolled or already_enrolled, with its portfolio_entity_id. Without the add-on it is not_entitled and nothing is enrolled. A failure is failed, with an enrollment_failed warning on the item.
Alerts
Screening produces matches. Alerts turn matches into a compliance workflow — who reviewed it, what they decided, and why. Every status change, note, and resolution is recorded immutably. This is the audit trail an OFAC examiner expects to see.
Lifecycle
Alerts follow a strict state machine. Each transition is recorded in an immutable case activity log.
| Status | Meaning | Can Transition To |
|---|---|---|
new |
Alert created, awaiting triage | assigned, under_review, escalated, closed_false_positive, closed_true_match |
assigned |
Assigned to an analyst with SLA deadline | under_review, escalated |
under_review |
Active investigation | escalated, closed_false_positive, closed_true_match |
escalated |
Requires senior compliance review | closed_false_positive, closed_true_match |
closed_false_positive |
Dismissed — not a true match | under_review (reopen) |
closed_true_match |
Confirmed — sanctions match verified | under_review (reopen) |
GET /v1/alerts
List alerts for your organization. Filter by status, source, score range, assignee, portfolio entity, or date range to focus on what needs attention.
curl "https://noblesight.io/v1/alerts?status=new&min_score=80&limit=25" \ -H "X-API-Key: $NOBLE_API_KEY"
Query Parameters
| Param | Type | Description |
|---|---|---|
status | string | Filter by status (e.g., new, under_review) |
source | string | Filter by source (api, batch, monitoring, ownership, console for legacy alerts) |
min_score | number | Minimum score threshold (0-100) |
max_score | number | Maximum score threshold (0-100) |
assigned_to | string | Filter by assigned analyst email |
portfolio_entity_id | integer | Only alerts raised on one monitored portfolio record — the id from GET /v1/portfolio, which a monitoring alert carries as portfolio_entity_id |
from | string | Start date (YYYY-MM-DD) |
to | string | End date (YYYY-MM-DD) |
after | integer | Cursor: return alerts with ID greater than this value. Pass the id of the last alert in the previous page's data. Omit for the first page. |
limit | integer | Page size (default: 50, max: 100). Larger values are clamped. |
Cursor pagination only — keyset by id, ordered ascending. The response is the uniform { "data": [...], "has_more": bool } envelope: when has_more is true, request the next page with ?after=<id of the last item in data>. There is no page/offset and no total (use GET /v1/alerts/stats for queue counts). For compliance teams: because every alert has a monotonically increasing ID and pages never overlap or skip, your system can prove to an examiner that it processed every alert in sequence.
GET /v1/alerts/{id}
Retrieve full alert detail: the match payload, SDN entry data, complete case activity timeline, and final disposition. Every alert carries the trace_id of the event that raised it, and the screening_id of its screening record (a batch alert carries none yet). A monitoring alert also carries portfolio_entity_id and the trigger that opened it (see How Reverse Screening Works). An ownership alert carries its determination as ownership, chains included (see Ownership alerts).
curl "https://noblesight.io/v1/alerts/42" \ -H "X-API-Key: $NOBLE_API_KEY"
POST /v1/alerts/{id}/assign
Assign an alert to an analyst for investigation. SLA deadlines are set automatically: 24 hours for scores 90 and above, 72 hours for all others.
curl -X POST "https://noblesight.io/v1/alerts/42/assign" \
-H "Content-Type: application/json" \
-H "X-API-Key: $NOBLE_API_KEY" \
-d '{"assign_to": "analyst@yourcompany.com"}'
POST /v1/alerts/{id}/notes
Add an investigation note without changing the alert's status. Notes are immutable and become part of the audit trail.
curl -X POST "https://noblesight.io/v1/alerts/42/notes" \
-H "Content-Type: application/json" \
-H "X-API-Key: $NOBLE_API_KEY" \
-d '{"note": "Checked DOB against passport — different person."}'
POST /v1/alerts/{id}/escalate
Escalate an alert for senior compliance review. Optionally include a note explaining why.
curl -X POST "https://noblesight.io/v1/alerts/42/escalate" \
-H "Content-Type: application/json" \
-H "X-API-Key: $NOBLE_API_KEY" \
-d '{"note": "Name matches known alias pattern — needs MLRO sign-off."}'
POST /v1/alerts/{id}/resolve
Close an alert with a structured reason code. True match closures require a disposition — the action your institution took. The four-eyes rule is enforced for alerts scoring 90 or above.
curl -X POST "https://noblesight.io/v1/alerts/42/resolve" \
-H "Content-Type: application/json" \
-H "X-API-Key: $NOBLE_API_KEY" \
-d '{
"status": "closed_true_match",
"reason": "true_match",
"disposition": "blocked",
"note": "Transaction blocked per OFAC regulations."
}'
POST /v1/alerts/bulk/resolve
Resolve up to 200 alerts in a single request. Each alert gets its own result in the response — failures on individual alerts don't block the rest.
curl -X POST "https://noblesight.io/v1/alerts/bulk/resolve" \
-H "Content-Type: application/json" \
-H "X-API-Key: $NOBLE_API_KEY" \
-d '{
"alert_ids": [42, 43],
"status": "closed_false_positive",
"reason": "false_positive_name_only"
}'
GET /v1/alerts/activity
Export the case activity audit trail across all alerts. Built for OFAC examination preparation — every status change, note, assignment, and resolution with full attribution and timestamps.
curl "https://noblesight.io/v1/alerts/activity?from=2026-01-01&to=2026-03-01&limit=100" \ -H "X-API-Key: $NOBLE_API_KEY"
Query Parameters
| Param | Type | Description |
|---|---|---|
from | string | Start date (YYYY-MM-DD) |
to | string | End date (YYYY-MM-DD) |
alert_id | integer | Filter to a specific alert |
actor | string | Filter by actor email |
action | string | Filter by action type |
after | integer | Cursor: return activity rows with id greater than this (pass the last item's id from the previous page) |
limit | integer | Results per page (default: 50, max: 100) |
Cursor-paginated by activity id ascending; returns the { "data": [...], "has_more": bool } envelope. A full audit pull uses the async export job.
After a True Match
Screening finds the match. The alert workflow documents your decision. But what happens next? When your institution confirms a sanctions match, OFAC requires specific actions within specific deadlines. The disposition you choose determines your reporting obligation under 31 CFR Part 501.
| Disposition | OFAC Obligation | Deadline | Filed With |
|---|---|---|---|
blocked |
File a blocking report. Property or transactions must be frozen and reported. | 10 business days | OFAC Compliance Division |
rejected |
File a reject report. Wires, ACH, and trade transactions that were stopped. | 10 business days | OFAC Compliance Division |
permitted_gl |
No filing required, but maintain documentation of which General License applies and why. Cite the specific GL in the gl_citation field. |
N/A — document immediately | Internal records |
no_action_required |
No filing required. Match confirmed but no reportable transaction or property involved. | N/A — document immediately | Internal records |
Noble Sight stores the disposition, reason code, analyst attribution, and timestamp for every resolution. This is the evidence your compliance team will present during an examination.
GET /v1/alerts/{id}/ofac-report
For blocked and rejected dispositions, this endpoint assembles an OFAC-ready report — the screened name, SDN match details, sanctions programs, OFAC list version, and resolution audit trail in a single response. Only available on alerts closed as closed_true_match.
curl "https://noblesight.io/v1/alerts/42/ofac-report" \ -H "X-API-Key: $NOBLE_API_KEY"
Response:
{
"alert_id": 42,
"report_type": "blocking",
"generated_at": "2026-03-10T14:30:00Z",
"screened_name": "Vladimir Putin",
"sdn_match": {
"uid": "36095",
"first_name": "Vladimir",
"last_name": "PUTIN",
"programs": ["RUSSIA-EO14024"],
"score": 97.5,
"match_sources": [{"source": "ofac_sdn", "trigram_score": 100, "soundex_match": true}]
},
"screening": {
"screened_at": "2026-03-09T10:15:00Z",
"ofac_publish_id": "1234",
"ofac_publish_date": "2026-03-08",
"trace_id": "onboarding-customer-42"
},
"resolution": {
"status": "closed_true_match",
"disposition": "blocked",
"reason": "true_match",
"resolved_by": "analyst@yourcompany.com",
"resolved_at": "2026-03-10T14:00:00Z",
"note": "Transaction blocked per OFAC regulations."
},
"institution_fields": {
"transaction_description": null,
"transaction_value": null,
"instructions": "Complete transaction_description and transaction_value before filing with OFAC. Blocking reports must be filed within 10 business days (31 CFR 501.603)."
}
}
Returns 409 Conflict if the alert is not resolved as a true match with a blocked or rejected disposition. The institution_fields section contains null values your team must fill in — Noble Sight provides the sanctions match evidence, your institution provides the transaction context.
What OFAC Needs vs. What the Report Provides
| OFAC Requires | Report Field | Source |
|---|---|---|
| Name of blocked/rejected party | screened_name |
Noble Sight |
| SDN list entry matched | sdn_match.uid, sdn_match.first_name, sdn_match.last_name |
Noble Sight |
| Sanctions program | sdn_match.programs |
Noble Sight |
| Date of action | screening.screened_at |
Noble Sight |
| OFAC list version | screening.ofac_publish_id, screening.ofac_publish_date |
Noble Sight |
| Description of blocked property or rejected transaction | institution_fields.transaction_description |
Your institution |
| Value of blocked property or rejected transaction | institution_fields.transaction_value |
Your institution |
How to Contact OFAC
Different situations require different OFAC channels. Use the right one.
| Situation | OFAC Channel | Contact |
|---|---|---|
| "Is this a real match?" — questions about potential hits, list interpretation, or screening methodology | Compliance Hotline | ofac.treasury.gov/ofac-compliance-hotline |
| Filing a blocking or reject report | OFAC Compliance Division | ofac.treasury.gov/contact-ofac |
| Requesting a license to proceed with a blocked transaction | Licensing Hotline | ofac.treasury.gov/ofac-license-application-page |
| Reporting a potential violation your institution discovered | Voluntary Self-Disclosure Portal | ofac.treasury.gov/disclosure |
| Issues downloading or accessing OFAC sanctions lists | Technical Support | 1-800-540-6322 or O_F_A_C@treasury.gov |
Voluntary Self-Disclosure
If your institution discovers it processed a transaction involving a sanctioned party — even if the screening system flagged it correctly but the alert was mishandled — OFAC's Voluntary Self-Disclosure program provides significant penalty mitigation. Under OFAC's Enforcement Guidelines, voluntary self-disclosure is treated as a mitigating factor and can reduce civil monetary penalties by up to 50%.
Noble Sight's immutable audit trail — the full screening response, alert lifecycle, analyst attribution, and resolution — provides the documentary evidence your legal team needs to prepare a self-disclosure. Every decision is traceable. Nothing is reconstructed after the fact.
SDN List Removal Petitions
If your customer believes they have been incorrectly placed on the SDN list, OFAC accepts petitions for removal. This is a formal legal process — not a customer service request. Petitions must demonstrate that the listing criteria no longer apply or were applied in error.
Noble Sight's screening history can support a petition by documenting the entity's match history, score trends over time, and any secondary attribute mismatches that were flagged.
Dispositions
When closing an alert as a true match, you must record a disposition — the action your institution took. This maps to OFAC reporting obligations (31 C.F.R. Part 501).
| Disposition | Meaning | OFAC Reporting |
|---|---|---|
blocked |
Transaction or property blocked | Blocking report required within 10 business days |
rejected |
Transaction rejected (wire, ACH, trade) | Reject report required within 10 business days |
permitted_gl |
Permitted under a General License | Must cite the specific GL (e.g., "GL-2023-001") |
no_action_required |
Match confirmed but no reportable action | Maintain documentation |
When disposition is permitted_gl, the gl_citation field is required — documenting which General License authorizes the activity.
Four-Eyes Rule
Alerts scoring 90 or above require two different people to close. The analyst who last changed the status cannot be the one who resolves it. No single person can both investigate and dismiss a high-confidence match — the system enforces this at the API level.
Reason Codes
Structured reason codes replace free-text dismissals. Examiners can query and aggregate dismissal patterns across your entire alert history — showing that your compliance process is systematic, not ad hoc.
| Code | Meaning |
|---|---|
false_positive_name_only | Name similarity only, no corroborating data |
false_positive_dob_mismatch | Date of birth does not match |
false_positive_country_mismatch | Country or nationality does not match |
false_positive_entity_type_mismatch | Entity type mismatch (e.g., individual vs. vessel) |
false_positive_other | Other reason (include details in note) |
true_match | Confirmed sanctions match |
Webhooks
Screening finds matches. Alerts track decisions. Webhooks deliver them to you in real time. Register an HTTPS endpoint, and Noble Sight POSTs every new alert to it — signed with HMAC-SHA256 so you can verify authenticity. Retry delivery handles transient failures. Standard tier and above.
POST /v1/webhooks
Register a webhook URL to receive alert notifications. Provide a shared secret (minimum 32 characters) for HMAC-SHA256 signature verification. The secret is encrypted at rest with AES-256-GCM — Noble Sight never stores it in plaintext.
curl -X POST https://noblesight.io/v1/webhooks \
-H "Content-Type: application/json" \
-H "X-API-Key: $NOBLE_API_KEY" \
-d '{
"url": "https://your-app.com/webhooks/noble",
"secret": "your-shared-secret-minimum-32-characters-long"
}'
Response:
{
"id": 1,
"url": "https://your-app.com/***",
"status": "active",
"created_at": "2026-03-23T10:00:00Z"
}
URLs are masked in all responses after creation — only the host is shown. Maximum 5 active webhooks per tenant.
GET /v1/webhooks
List active webhooks for your tenant.
curl https://noblesight.io/v1/webhooks \ -H "X-API-Key: $NOBLE_API_KEY"
Response:
{
"data": [{
"id": 1,
"url": "https://your-app.com/***",
"status": "active",
"created_at": "2026-03-23T10:00:00Z"
}],
"has_more": false
}
DELETE /v1/webhooks
Disable a webhook. Soft delete — the record is preserved for audit trail, but no further deliveries are attempted.
curl -X DELETE "https://noblesight.io/v1/webhooks?id=1" \ -H "X-API-Key: $NOBLE_API_KEY"
Returns 204 No Content on success.
Event Payload
When an alert is created — from a screening, batch job, or portfolio monitoring hit — Noble Sight POSTs a JSON event to every active webhook for your tenant.
{
"id": "evt_a1b2c3d4e5f6g7h8",
"type": "alert.created",
"created_at": "2026-03-23T10:05:00Z",
"data": {
"id": 42,
"screened_name": "Vladimir Putin",
"score": 97.5,
"source": "monitoring",
"status": "new",
"trace_id": "3f9b2c71-0d4e-4a6b-8e2f-7c1a5b9d0e63",
"trigger": {
"kind": "list_change",
"list": "ofac_sdn",
"publish_id": 4031,
"publish_date": "2026-03-23",
"imported_at": "2026-03-23T10:01:12Z",
"screened_at": "2026-03-23T10:04:58Z",
"change_type": "added"
}
}
}
trigger is present on monitoring alerts and on ownership alerts raised by the ownership recompute, the same object GET /v1/alerts/{id} returns. Fetch the alert for the match detail.
Signature Verification
Every webhook delivery includes two headers: X-Noble-Signature (HMAC-SHA256) and X-Noble-Timestamp (Unix seconds). The signature covers timestamp + "." + body. Verify the signature, then reject deliveries where the timestamp is more than 5 minutes old to prevent replay attacks.
# Verify in your webhook handler:
# 1. Read X-Noble-Timestamp and the raw request body
# 2. Compute HMAC-SHA256 over timestamp + "." + body with your secret
# 3. Compare against the X-Noble-Signature header (constant-time)
# 4. Reject if timestamp is more than 5 minutes old (replay protection)
#
# Header format: sha256=<hex-encoded HMAC>
#
# Example (Go):
# timestamp := r.Header.Get("X-Noble-Timestamp")
# mac := hmac.New(sha256.New, []byte(secret))
# mac.Write([]byte(timestamp))
# mac.Write([]byte("."))
# mac.Write(body)
# expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
# if !hmac.Equal([]byte(expected), []byte(header)) { reject }
# ts, _ := strconv.ParseInt(timestamp, 10, 64)
# if time.Since(time.Unix(ts, 0)) > 5*time.Minute { reject }
Always use constant-time comparison (hmac.Equal in Go, crypto.timingSafeEqual in Node.js) to prevent timing attacks. The 5-minute window accommodates clock skew and retry backoff while stopping replay attacks.
Delivery and Retry
| Aspect | Detail |
|---|---|
| Attempts | Up to 8 delivery passes on an exponential backoff schedule spanning roughly 10 hours (30s → 6h between passes). Retry state is persisted, so retries survive server restarts — an endpoint down for a deploy or a multi-hour outage still receives its alerts. |
| Success | Any 2xx response. The delivery is marked delivered and no further attempts occur. With multiple endpoints registered, each endpoint stops receiving retries as soon as it accepts — retries continue only to endpoints that have not. |
| Failure | Non-2xx responses or network errors trigger the next pass. After all passes are exhausted, the delivery is marked failed. |
| Deduplication | Every attempt for an event carries the same X-Noble-Event-ID (matching the payload id). Delivery is at-least-once — treat the event id as your idempotency key. |
| Timeout | 10 seconds per attempt. Your endpoint must respond within this window. |
| Redirects | Not followed. Webhook URLs must resolve directly — this prevents SSRF via redirect chains. |
| Audit trail | Every delivery attempt is recorded: status, HTTP response code, attempt count, and error message. Available for compliance review. |
| URL validation | HTTPS required. Private IPs, loopback addresses, and localhost are blocked to prevent SSRF. |
Webhook delivery is notification only. If delivery fails after all retries, the alert still exists in your alert queue and is still visible via GET /v1/alerts. A webhook failure never suppresses, delays, or alters an alert. This matters for examination readiness: your compliance team can always demonstrate that every alert was created, recorded, and available for review regardless of notification channel status.
Webhooks vs. Polling
Two ways to consume alerts. Use whichever fits your architecture — or both.
| Approach | How | Best For |
|---|---|---|
| Webhooks | Register a URL. Noble Sight POSTs every alert to you in real time. | Real-time processing. Event-driven architectures. Minimal latency between alert creation and your team seeing it. |
| Polling | Call GET /v1/alerts?after=<last_id> on a schedule. Store the last-seen ID. |
Simpler infrastructure. No public endpoint needed. Firewall-friendly. Batch processing workflows. |
Portfolio
Add your customers to a monitored portfolio. When sanctions lists change, Noble Sight automatically re-screens them using reverse screening — only the changed sanctions entries are checked against your portfolio, not the other way around. Fast, targeted, always current. Add-on for any paid tier.
GET /v1/portfolio
List all active entities in your monitored portfolio.
curl "https://noblesight.io/v1/portfolio?limit=25" \ -H "X-API-Key: $NOBLE_API_KEY"
Cursor-paginated by id ascending. When has_more is true, request the next page with ?after=<id of the last entity in data>.
Optional filters: q (case-insensitive name substring), min_score and max_score (0–100; a bound you send applies, 0 included). q matches a Confidential Portfolio entity's encrypted name the same as a plaintext one — encrypted names are matched in memory after decryption, never in the database. GET /v1/portfolio/stats accepts the same filters and its total always agrees with the filtered list.
Response:
{
"data": [
{
"id": 101,
"full_name": "Dmitry Medvedev",
"country": "RU",
"entity_type": "individual",
"highest_score": 94.2,
"average_score": 87.1,
"last_screened_at": "2026-03-09T12:00:00Z",
"created_at": "2026-01-15T09:30:00Z"
},
{
"id": 102,
"full_name": "Acme Trading LLC",
"entity_type": "entity",
"highest_score": 0,
"average_score": 0,
"last_screened_at": "2026-03-09T12:00:00Z",
"created_at": "2026-02-01T14:00:00Z"
}
],
"has_more": false
}
POST /v1/portfolio
Add an entity to your monitored portfolio. It is screened immediately against current sanctions lists, then re-screened automatically whenever lists change. The screening is the one POST /v1/screen runs, against every list, with the date_of_birth and country you send, and it is recorded and alerted the same way. A name already on a list is alerted now, not when its listed record next changes. The 201 response carries it under screening: the trace_id it is recorded under, the top_match (null when nothing matched), and the alert_id it raised (null when none).
The entity is written only after the screening succeeds. If the screening can't run (503 coverage_unavailable or 504 screening_timeout), nothing is enrolled; retry the same request. date_of_birth must be YYYY-MM-DD and country a two-letter ISO 3166-1 code; anything else is a 400 invalid_parameter.
curl -X POST https://noblesight.io/v1/portfolio \
-H "Content-Type: application/json" \
-H "X-API-Key: $NOBLE_API_KEY" \
-d '{
"full_name": "Dmitry Medvedev",
"date_of_birth": "1965-09-14",
"country": "RU"
}'
{
"id": 4821,
"full_name": "Dmitry Medvedev",
"name_fold": "dmitry medvedev",
"date_of_birth": "1965-09-14",
"country": "RU",
"entity_type": "individual",
"highest_score": 100,
"average_score": 71.4,
"last_screened_at": "2026-10-29T14:02:11Z",
"created_at": "2026-10-29T14:02:11Z",
"screening": {
"trace_id": "8f3c2a71-0d4e-4b8a-9a52-6f1e0c9b7d13",
"screening_id": 991204,
"screened_at": "2026-10-29T14:02:11Z",
"match_count": 7,
"top_match": { "uid": "36015", "score": 100, "...": "every field of a /v1/screen match" },
"alert_id": 30512,
"alert_reason": "score_threshold"
}
}
PUT /v1/portfolio
Update an existing portfolio entity, by the id the list returns. Use this when customer data changes (e.g., corrected name spelling or updated country). The new values are screened exactly as POST /v1/portfolio screens them, before anything changes, and the response carries that screening.
curl -X PUT "https://noblesight.io/v1/portfolio?id=4821" \
-H "Content-Type: application/json" \
-H "X-API-Key: $NOBLE_API_KEY" \
-d '{
"full_name": "Dmitrii Medvedev",
"date_of_birth": "1965-09-14",
"country": "RU"
}'
DELETE /v1/portfolio
Remove an entity from monitoring. It will no longer be re-screened when sanctions lists update. Historical screening records are retained for audit — nothing is deleted.
curl -X DELETE "https://noblesight.io/v1/portfolio?id=4821" \ -H "X-API-Key: $NOBLE_API_KEY"
How Reverse Screening Works
| Aspect | Detail |
|---|---|
| Trigger | Any of the nine lists publishes a new version. Noble detects the delta (added, modified, or removed entries). A change to Noble's matching rules (a new engine_version, announced in the changelog) re-screens every listed record the same way. |
| Direction | Each changed listed record is screened against all active portfolio entities, under every name the list publishes for it: aliases, spelling variations, and native-script forms. Removed entries don't trigger screening. |
| Matching | The same decision as POST /v1/screen. A monitoring hit for a customer and a listed party is the hit a screen of that customer's name returns for that party: the same score, match_sources, dismissal_signals, programs and identifiers. The customer's stored date_of_birth and country count as they would if sent on a screen. |
| Alerts | Matches generate alerts with the score, the publish ID of the list version that triggered it, and the hit in match_payload, in the same shape as a POST /v1/screen match; the hit's uid names the listed record (OFAC records also fill sdn_uid). Each alert carries portfolio_entity_id, the monitored record it was raised for, and a trigger saying why it opened: kind is list_change (the list published a change), engine_change (a re-screen after a change to Noble's matching or monitoring rules, with its engine_version; with list ownership, a re-screen against every blocked ownership determination, which never raises a pair that already has an ownership alert for the same entity), operator_reprobe (Noble re-screened the listed party on request), variation_added (Noble added spelling variations of its names), ownership_change (Noble's ownership recompute newly blocked an entity your customer's name resolves to under the 50 Percent Rule; list is ownership and publish_id the recompute run) or regimes_added (you added ownership regimes with PATCH /v1/account, and Noble checked your portfolio against every determination under them; list is ownership and publish_id the recompute run); list, publish_id and publish_date name the publish, as GET /v1/lists reports it; imported_at and screened_at say when Noble ingested it and when your customer was evaluated; and a list_change says whether the party was added or modified. A modified one also lists changes: what the publish changed in the designation, read from the list's record of it before and after (an alias, a name, a program or another field, each added, removed or changed), with caused_hit: true on the change your customer's match came through: the match's matched_text is a name that change added, whole or one part of it such as the alias's surname, never a name the designation already listed. An alert raised because a new alias matched reads differently from one where a name already listed matched and only a program changed. A later event that matches an open alert is added to its timeline as a list_event carrying its own trigger. The screening record behind the alert, returned by GET /v1/export, carries the same trigger; when your customer matched one listed record more than once, the record's trigger credits every match, and each match in it carries its own alert's trigger. |
| Enrollment | One active enrollment per client_id and exact full_name, after surrounding spaces are trimmed. Case counts: Ivan Petrov and IVAN PETROV are two enrollments. A screening or batch item enrolls the name with the date_of_birth and country it was screened with, so monitoring compares the customer you screened. A screening with no name, such as an identifier alone, enrolls nothing and reports no_name: identifiers are not monitored. |
| Dedup | One open alert per customer, listed record and list. Another name of the same record, or a later change to it, is added to the open alert's activity timeline as a list_event instead of opening a second alert. A re-screen after a rules change never raises a pair you closed as a true match again, and raises one you closed as a false positive only on a higher score or a new match pathway (prior_disposition says which). |
| Speed | Every list is checked every five minutes. Once Noble Sight detects a change, it is re-screened against your portfolio and any alert raised within 15 minutes (p95); a registered webhook receives the alert in the same window, and if you poll, it is on your next GET /v1/alerts page. This is measured on every change, not estimated: see the monitoring latency control. |
| Completion | Every list change is screened to the end. A job that fails retries itself after 1, 5 and then 15 minutes, resuming after the names already screened; a change over 5,000 names is split into several jobs. GET /status counts any job still failed under monitoring.reverse_failed, and Noble Sight is alarmed on it. Confidential Portfolio entities are decrypted for every job: if the key service is briefly unreachable the job waits and retries, so no change is screened for some customers and not others. If it still fails for one customer's key on the last retry, that customer alone is skipped and every other portfolio is screened. A customer whose key is disabled or destroyed, or whose stored record does not decrypt, is skipped too. Every skipped customer is counted under monitoring.reverse_encrypted_skipped. A customer that revoked its key with DELETE /v1/portfolio/key has nothing left to screen and is not counted. |
Pricing: $0.50/entity/mo (up to 10K), $0.35 (10K-50K), $0.20 (50K+).
Monitoring latency: the 15-minute proof
The monitoring_latency control on GET /v1/account/coverage measures the 15-minute promise for your account over the report window (the last 90 days, or ?from=YYYY-MM-DD&to=YYYY-MM-DD). Each list change is timed from the instant Noble Sight detected it to your first webhook delivery for it (basis: "delivered"), or, where you have no deliveries in the window, to the end of its portfolio re-screen (basis: "rescreened"), and held to a 900-second budget. A change still waiting for its re-screen is never left out: once it is older than the budget it is counted at its age so far, and the control cannot read active until it finishes. With no monitored portfolio the control is not_applicable.
curl -s https://api.noblesight.io/v1/account/coverage -H "X-API-Key: $KEY" \
| jq '.controls[] | select(.id=="monitoring_latency") | {status, latency}'
| Field | Meaning |
|---|---|
latency.changes | List changes measured in the window, including any unfinished change past the budget. |
latency.unfinished | Changes in the window not yet fully re-screened. 0 in a healthy state. |
latency.p50_s, p95_s, max_s | The distribution, in seconds. The promise is p95_s at or under budget_s (900), which sets within_budget. |
latency.canary | Noble Sight's own hourly proof: a feed it publishes and changes every hour, monitored by a Noble-held account whose webhook times each change end to end, from publish to delivery. within_budget is whether the latest one arrived inside 900 seconds. While the canary runs, the control passes only if the canary is in budget and every list is fresh (latency.lists_fresh), so a quiet day with no real list change still proves the chain. |
Each hop of a list's most recent change, with its duration, is on GET /v1/lists under last_change. Where a publisher exposes no reliable timestamp of its own (source_time: "unknown"), timing starts at detection; the canary is the controlled clock for the hop before it.
Watchlist
Government sanctions lists are public. The risks your institution has already identified are not. Every bank maintains internal lists — names from filed SARs, de-risked customers, law enforcement inquiries, and compliance investigations. These lists represent hard-won institutional knowledge that no government authority publishes. Noble Sight screens against them automatically, alongside OFAC, UK, and other government lists, in the same API call. Standard tier and above.
Two Kinds of Lists
Noble Sight screens against two categories of data in every request:
| Category | What It Is | Who Maintains It |
|---|---|---|
| Government lists | Public sanctions and regulatory designations — OFAC SDN, OFAC Consolidated, UK Sanctions, EU Sanctions, FinCEN 311 Special Measures, UN Consolidated List. Published by government authorities, machine-readable, updated continuously. | Noble Sight ingests these automatically. You don't upload anything — we check every source every five minutes, detect changes, and delta-import each one as soon as it is seen. |
| Internal watchlists | Your institution's own intelligence — SAR subjects, exited customers, 314(a) names, law enforcement inquiries, adverse media flags, correspondent risk. Confidential by nature, institution-specific, not available from any public source. | You manage these via the /v1/watchlist API. Noble Sight screens against them with the same matching engine used for government lists — trigram, phonetic, and AI-powered matching. |
Why Internal Watchlists Matter
A sanctions list tells you who the government has designated. An internal watchlist tells you who your institution has flagged — and that intelligence is often more actionable than a public list.
Consider: a customer was exited two years ago for structuring. They apply for a new account under a slightly different name. OFAC screening returns nothing — they're not sanctioned. But your internal watchlist catches the match because the name is still there, with the reason and case number attached. Without that list in your screening pipeline, the onboarding proceeds and the risk walks back in.
The FFIEC BSA/AML Examination Manual expects institutions to maintain systems that identify and monitor suspicious activity on an ongoing basis. Examiners will ask how you screen new customers against your own prior findings — not just government lists. A watchlist that lives in a spreadsheet or a separate system that nobody queries during onboarding is a control gap. A watchlist that is checked on every screening call, with the same fuzzy matching engine, is a control.
What Goes on an Internal Watchlist
These are sources of risk intelligence that are confidential, institution-specific, and cannot be published or aggregated by any third party. The only way to screen against them is for your institution to maintain them.
| Source | What It Is | Why It Matters |
|---|---|---|
| SAR Subjects | Individuals and entities named in your institution's Suspicious Activity Reports — filings submitted to FinCEN when you detect potential money laundering, fraud, terrorist financing, or other criminal activity. U.S. institutions file over 4 million SARs per year. These names are your own intelligence about suspicious behavior, and SAR confidentiality rules (31 USC 5318(g)(2)) prohibit sharing them outside your institution. | If you filed a SAR on someone, you should know if they — or someone with a similar name — attempt to open a new account or transact again. Most banks track SAR subjects in spreadsheets or siloed case management systems. Putting them in a watchlist that is screened automatically closes that gap. |
| Exited Customers | Customers whose accounts were closed due to suspicious activity, compliance violations, or risk appetite decisions. De-risking is a significant action — the decision was made for a reason. | Exited customers sometimes return under variant names, through different branches, or through correspondent relationships. If the original exit decision was risk-based, the risk hasn't changed because the account was closed. |
| FinCEN 314(a) Names | Section 314(a) of the USA PATRIOT Act authorizes FinCEN to send financial institutions lists of names on behalf of federal law enforcement agencies investigating money laundering and terrorism. Institutions must search their records and report matches within 14 days. These requests arrive roughly every two weeks and contain names of active investigative targets. 314(a) data is confidential — institutions cannot share or redistribute it. | 314(a) names are time-sensitive law enforcement intelligence. Adding them to your watchlist ensures they are screened not just once during the initial search, but on every future screening call — catching the target if they attempt new activity at your institution after the initial 314(a) search window closes. |
| Law Enforcement Inquiries | Names from subpoenas, grand jury requests, National Security Letters, or informal law enforcement inquiries. These indicate that a person or entity is under active investigation, even if they have not been charged. | An active investigation means elevated risk. Screening future transactions against these names provides early warning if the subject re-engages with your institution. |
| Adverse Media | Entities flagged through your adverse media monitoring program — news reports of fraud, corruption, money laundering, or other financial crime. A person may not appear on any government list but may be widely reported as under investigation or indictment. No single authoritative public list exists for adverse media — it depends on your institution's monitoring sources and risk criteria. | Adverse media often leads sanctions designations by months or years. Adding flagged names to your watchlist provides early screening coverage before the government acts. |
| Correspondent Risk | Financial institutions in high-risk jurisdictions, under regulatory action, or flagged by your correspondent banking due diligence process. | Screening wire originators and beneficiaries against your correspondent risk list catches transactions routed through institutions you've already identified as elevated risk. |
POST /v1/watchlist
Add an entry to your internal watchlist. The name is available for screening immediately. Phonetic codes are computed at insert time for fast fuzzy matching.
curl -X POST https://noblesight.io/v1/watchlist \
-H "Content-Type: application/json" \
-H "X-API-Key: $NOBLE_API_KEY" \
-d '{
"full_name": "John Doe",
"list_name": "SAR Subjects",
"reason": "SAR filed 2026-03-01, case #2026-0042",
"entity_type": "individual",
"country": "US"
}'
Response:
{
"id": 17,
"full_name": "John Doe",
"list_name": "SAR Subjects",
"reason": "SAR filed 2026-03-01, case #2026-0042",
"entity_type": "individual",
"country": "US",
"added_by": "apikey:royal_bank",
"created_at": "2026-03-16T19:00:00Z",
"status": "active"
}
Request Fields
| Field | Type | Required | Description |
|---|---|---|---|
full_name | string | Yes | Name to screen against (max 500 chars) |
list_name | string | No | Category label (default: "default"). Use it to organize entries by source: "SAR Subjects", "Exited Customers", "314a Names", etc. |
reason | string | No | Why this entity is on the list. Strongly recommended — this is what an examiner will ask about. |
id_number | string | No | Government identifier (passport, SSN, tax ID) |
id_type | string | No | Type of identifier (e.g., "Passport", "SSN") |
country | string | No | Country code (ISO 3166-1 alpha-2) |
entity_type | string | No | "individual" or "entity" (default: "individual") |
expires_at | string | No | RFC 3339 expiration date. Entry stops matching after this date. Useful for time-limited law enforcement requests. |
GET /v1/watchlist
List your watchlist entries. Filter by list category or status. Paginated.
curl "https://noblesight.io/v1/watchlist?list_name=SAR+Subjects&limit=25" \ -H "X-API-Key: $NOBLE_API_KEY"
Response:
{
"data": [
{
"id": 17,
"full_name": "John Doe",
"list_name": "SAR Subjects",
"reason": "SAR filed 2026-03-01, case #2026-0042",
"entity_type": "individual",
"country": "US",
"added_by": "apikey:royal_bank",
"created_at": "2026-03-16T19:00:00Z",
"status": "active"
}
],
"has_more": false
}
Query Parameters
| Parameter | Default | Description |
|---|---|---|
list_name | all lists | Filter by list category |
status | active | Filter by status: active or removed |
after | 0 | Cursor: return entries with id greater than this (pass the id of the last entry in the previous page's data) |
limit | 50 | Results per page (max 100) |
DELETE /v1/watchlist
Remove a watchlist entry. This is a soft delete — the entry is marked removed and excluded from future screening, but the record is preserved for audit trail. Nothing is ever hard-deleted.
curl -X DELETE "https://noblesight.io/v1/watchlist?id=17" \ -H "X-API-Key: $NOBLE_API_KEY"
Returns 204 No Content on success. Returns 404 if the entry doesn't exist or belongs to a different tenant.
How Watchlist Screening Works
| Aspect | Detail |
|---|---|
| Automatic | Every POST /v1/screen request checks your watchlist alongside all active government lists. No opt-in flag, no separate API call. One request screens everything. |
| Matching | Same trigram + Soundex engine as sanctions screening. A slightly misspelled name on your watchlist still matches — because the same person with a typo is still the same risk. |
| Scoring | Same formula as sanctions matches. An exact watchlist hit scores 100. Partial matches score proportionally. |
| Source | Watchlist matches appear with source: "Internal Watchlist" and match_sources[].source: "internal_watchlist". The list name and reason are included in the match remarks. |
| Expiration | Entries with an expires_at date are automatically excluded from screening after that date. No manual cleanup needed. |
| Tenant isolation | Each API key screens against its own watchlist only. Your entries are never visible to other tenants. |
| Alerts | Watchlist matches generate alerts through the same workflow as sanctions matches — same state machine, same four-eyes rule, same audit trail. |
Lists
GET /v1/lists tells you which version of each sanctions list Noble Sight is screening against, and whether that version is current. It is public — no API key, no quota — so a status dashboard or a compliance agent can check freshness before relying on a result.
curl -s https://noblesight.io/v1/lists | jq '.lists[] | {list, publish_date, last_checked, status, monitoring}'
One entry per list, ordered by list. The same version information is recorded on every screening in list_versions, so each decision names the list versions it was made against.
Fields
| Field | Description |
|---|---|
list | The list's identifier, as accepted in the lists field of POST /v1/screen: ofac, uk, eu, un, france, canada, australia, belgium, netherlands. |
display_name | Human-readable list name. |
publish_id | Identifier of the imported list version — the same value a screening records in list_versions. |
publish_date | The date the publisher released this version (YYYY-MM-DD), as the source states it. |
record_count | Number of entries in this version. |
imported_at | When Noble Sight loaded this version (RFC 3339, UTC). |
history_from | Where point-in-time history for this list begins. An as_of screening at or after it screens the list as it stood then; one before it cannot. |
last_checked | When Noble Sight last polled the publisher. It advances on every poll, even when nothing changed, so a recent value is the proof you are on the current published version. For OFAC it is the older of the SDN and Consolidated checks. |
last_import | When the publisher's content last changed and was loaded. Empty if it has not changed since monitoring of the list began. |
status | Freshness verdict: ok, degraded, stale or source_unavailable (below). |
fresh_within_s | The longest, in seconds, last_checked may lag with status still ok. |
stale_after_s | The age of last_checked, in seconds, beyond which status is stale. |
source_error | The publisher's answer to Noble Sight's last poll, for example http_500. Present when status is source_unavailable. |
source_unavailable_since | When Noble Sight first saw the publisher fail after its last successful poll. Present when status is source_unavailable. |
escalate_after_s | How long, in seconds, a publisher outage of this list may last before it is escalated: the list's median gap between publications, at least one day and at most seven. Screening never refuses on it. |
escalated | true when the publisher outage has lasted longer than escalate_after_s. Every screening then warns that the snapshot may be missing designations made since. |
monitoring | Whether portfolio monitoring has caught up with this list's changes: ok or delayed (below). |
last_change | The hop-by-hop timeline of this list's most recent content change: the publisher's own instant (source_last_modified, with source_time "unknown" when the publisher exposes none), when Noble detected and imported it, when its own portfolio re-screen was queued and finished (a later engine re-screen or reprobe of the same list version never moves it), and — scoped to your tenant when you send your API key to this otherwise-public endpoint — your first alert and first webhook delivery, each hop with its duration in whole seconds (detected_after_s, queued_after_s, rescreened_after_s, delivered_after_s). Tenant hops you don't have carry a null_reason. null until a list records its first change after this feature shipped. |
Freshness
Every list is polled every five minutes. status is measured from last_checked against the list's own thresholds — today fresh_within_s is 1800 (six polls) and stale_after_s is 7200 (24 polls). Read the thresholds from the response rather than hard-coding them. A poll that fails transiently — a connection reset, a server error or a maintenance page from the publisher — is retried within the same poll, up to three more times with at most 90 seconds of waiting between attempts, so a brief publisher outage does not cost a poll.
| status | Meaning | What to do |
|---|---|---|
ok | last_checked is within fresh_within_s. The list is being polled and the version shown is current. | Nothing. |
degraded | Several polls in a row have failed: last_checked is older than fresh_within_s but within stale_after_s. Noble Sight is alerted and retrying. Screening continues against the version shown, which may miss a publisher update from the last hour or so. | Expect it to recover; note it if a decision depends on a designation published very recently. |
stale | last_checked is older than stale_after_s, or unknown, and Noble Sight cannot show the publisher is at fault. POST /v1/screen refuses a live screening that includes the list (503 coverage_degraded) unless it sets allow_degraded_coverage. | Treat ingestion for this list as broken. Do not rely on its results until it returns to ok; contact support@noblesight.io. |
source_unavailable | The publisher is down, not Noble Sight's ingestion: last_checked is older than stale_after_s, the watcher is still polling, the publisher answers every poll with its own server error (source_error), and other lists poll normally. Nobody can obtain a newer copy of the list than the publisher serves, so screening continues against the version shown, and every screening that includes the list carries a list_source_unavailable coverage issue and warning naming the snapshot screened. | Nothing is needed to keep screening. Record the outage window with any decision it touches; once escalated is true, check designations the publisher has announced elsewhere since source_unavailable_since. |
The verdict fails closed: when freshness cannot be proven, it reports stale rather than implying a current list. Only the publisher's own server error earns source_unavailable: a timeout, a connection, DNS or TLS failure, any 4xx answer, or a response that is not the list stays stale, because each may be Noble Sight's to fix. For the EU list, Noble Sight also reads the Commission's own feed of its sanctions files on every poll: it supplies the current download link, and when downloads fail but the feed shows nothing published since the last confirmed poll, the version shown is confirmed current and the list stays ok. If the feed announces a newer version that cannot be downloaded, the outage is escalated at once. GET /status summarizes the same computation as its lists component — operational when every list is ok, degraded when any list is not — and its message says what screening does in that state.
Monitoring
| monitoring | Meaning |
|---|---|
ok | Every change imported from this list has been queued for screening against monitored portfolios. |
delayed | A change imported more than 15 minutes ago is not yet queued. Noble Sight keeps retrying; the change is recorded durably, so its monitoring alerts arrive late, not never. POST /v1/screen is unaffected — it already screens the imported version. |
Audit
Every screening decision is stored immutably — the full request, full response, list version, and trace ID. No record is ever modified or deleted. Designed for OFAC's 10-year recordkeeping requirement and SOC 2 audit readiness.
What Gets Stored
Every call to /v1/screen creates an immutable record. Pass your own trace ID via the X-Trace-ID header to link screening decisions to your internal workflows:
curl -X POST https://noblesight.io/v1/screen \
-H "Content-Type: application/json" \
-H "X-API-Key: $NOBLE_API_KEY" \
-H "X-Trace-ID: onboarding-customer-42" \
-d '{"name": "Test Name"}'
| Field | Description |
|---|---|
trace_id |
Your X-Trace-ID header value, or auto-generated UUID |
request |
Full screening request (name, DOB, country, deep_screen flag) |
response |
Complete match results with scores and match sources |
ofac_publish_id |
The exact OFAC SDN list version used for this screening |
screened_at |
UTC timestamp of the screening decision |
GET /v1/export
Export a single screening decision by trace ID. Standard tier and above.
curl "https://noblesight.io/v1/export?trace_id=onboarding-customer-42" \ -H "X-API-Key: $NOBLE_API_KEY"
GET /v1/export/bulk
Bulk export screening decisions by date range for regulatory audits. Requires from and to (YYYY-MM-DD; to inclusive).
curl "https://noblesight.io/v1/export/bulk?from=2026-01-01&to=2026-03-01&limit=100" \ -H "X-API-Key: $NOBLE_API_KEY"
Cursor-paginated by record id ascending; returns the { "data": [...], "has_more": bool } envelope. When has_more is true, pass ?after=<id of the last record in data>. A full audit pull uses the async export job.
OFAC List Version Tracking
Every screening result records which OFAC list version was active at the time of the screen. When an examiner asks "what list were you screening against on March 1?" — the answer is in the audit record, not a reconstruction.
Webhook Delivery Records
Every webhook delivery attempt is recorded with status, HTTP response code, attempt count, error message, and timestamps. These records are part of the audit trail — when an examiner asks "how was your compliance team notified of this alert?", the delivery log provides the answer: which endpoint received the notification, when it was delivered, and whether retries were needed.
Pricing
Screen any name against 18,598+ sanctioned entities. Every tier includes explainable scores and immutable audit trails. Pay only when you need more volume or deeper analysis.
| Feature | Free | Standard | Premium | Enterprise |
|---|---|---|---|---|
| Price | $0/mo | $199/mo | $499/mo | Custom |
| Screenings | 100/day | 5,000/mo | 25,000/mo | 100,000+/mo |
| Sanctions screening | Yes | Yes | Yes | Yes |
| Explainable scores | Yes | Yes | Yes | Yes |
| Match source breakdown | Yes | Yes | Yes | Yes |
| Alert management | Yes | Yes | Yes | Yes |
| Audit trail persistence | Yes | Yes | Yes | Yes |
| Deep screen (AI expansion) | — | Yes | Yes | Yes |
| Batch screening | — | Up to 1,000 | Up to 5,000 | Up to 10,000 |
| Webhook notifications | — | Yes | Yes | Yes |
| Compliance exports | — | Yes | Yes | Yes |
| Portfolio monitoring | — | — | Yes | Yes |
| Dedicated support | — | — | — | Yes |
| Custom integration | — | — | — | Yes |
What every tier includes
Three layers of matching across every live sanctions list: character similarity, phonetic matching, and 89,117 pre-computed AI name variations. Secondary attribute scoring — date of birth and country — suppresses false positives automatically. Every result includes the score, the match sources, the dismissal reasons, and the list version. Persisted for 10 years.
Most vendors charge thousands per month for less transparency than the free tier provides.
Standard — $199/mo
5,000 screenings per month. Batch screening up to 1,000 names per job. Deep screen sends your search input through real-time Gemini AI expansion — catching transliterations and cultural variants that pre-computed variations miss. Webhook notifications deliver alerts to your endpoint in real time with HMAC-SHA256 signed payloads. Compliance exports let you pull screening decisions by trace ID or date range for regulatory audits.
Premium — $499/mo
25,000 screenings per month. Batch screening up to 5,000 names per job. Everything in Standard, plus portfolio monitoring — register customer names and get automatically re-screened when sanctions lists update. When OFAC adds a new SDN entry, the change is re-screened against your customers and any match is alerted within 15 minutes of Noble Sight detecting it (p95), with every list checked every five minutes. Not days. Minutes.
Enterprise
100,000+ screenings per month. Batch screening up to 10,000 names per job. Dedicated support, custom integration, and volume pricing. Contact sales@noblesight.io.
Upgrade via API
No sales calls required for Standard or Premium. One API call creates a Stripe Checkout session. See Account for the endpoint.
Account
View your tier, usage, and billing status. Upgrade from free to a paid plan without contacting sales.
GET /v1/account
Returns your current tier, usage within the rate limit window, billing status, and which features are available. One call instead of guessing.
curl https://noblesight.io/v1/account \ -H "X-API-Key: $NOBLE_API_KEY"
{
"client_id": "acme-bank-3f9c02ab",
"key_prefix": "noble_live_a1b2c",
"tier": "free",
"billing_status": "none",
"usage": {
"used": 42,
"limit": 100,
"remaining": 58,
"unlimited": false,
"window": "day"
},
"features": {
"screening": true,
"deep_screen": false,
"batch_screening": false,
"portfolio_monitoring": false,
"compliance_exports": false,
"alert_management": true,
"max_batch_size": 0,
"mcp": true,
"confidential_portfolio": false,
"alert_threshold": 80,
"ownership_regimes": ["us", "uk", "eu", "un", "ca", "au"],
"ownership_regimes_declared": false
},
"scopes": ["api", "mcp"]
}
PATCH /v1/account
Declare the ownership regimes your institution is bound by. A screening without lists then determines those regimes only, and portfolio monitoring raises ownership alerts under them only. lists on a request still selects per call. The setting applies to every key on the account from its next request. Regimes are us, uk, eu, un, ca and au. At least one is required, and anything else is 400 invalid_parameter. Send "ownership_regimes": null to go back to the default: bound by every regime, including any Noble Sight adds later, which an explicit list of today's six is not. ownership_regimes_declared on GET /v1/account is false on the default and true once you declare. The response is the account as GET /v1/account returns it. Every change is recorded with the value before and after (null for the default), the key that made it and the trace id. Setting the value you already hold records nothing.
Adding a regime back re-checks your portfolio under it. Monitoring decides each ownership determination under the regimes you declare when it changes, so an entity blocked under a regime while you had it off raised no alert for you. A change that adds regimes (["us"] to ["us","eu"], or to null) checks every current blocked or review determination under them against your portfolio, Confidential Portfolio entities included, and the response carries ownership_recheck: the regimes added and the number of entities checked. Alerts it raises carry a trigger of kind regimes_added and typically appear within minutes. A pair whose ownership alert, open or closed, already reached it under every regime that now reaches it, at the same finding or a stronger one, is noted on that alert, not raised again; a regime the alert did not name, or a review that is now a block, raises a new alert. Removing a regime closes no alert.
curl -X PATCH https://noblesight.io/v1/account \
-H "X-API-Key: $NOBLE_API_KEY" -H 'Content-Type: application/json' \
-d '{"features":{"ownership_regimes":["us"]}}'
# back to the default: every regime, including future ones
curl -X PATCH https://noblesight.io/v1/account \
-H "X-API-Key: $NOBLE_API_KEY" -H 'Content-Type: application/json' \
-d '{"features":{"ownership_regimes":null}}'
DELETE /v1/account/keys/{key_prefix}
Revoke one of your account's keys, for example one that leaked into a log or the old key after a rotation. key_prefix is the key's first 16 characters, as GET /v1/account shows it, and confirm must repeat it, so a stray request revokes nothing. A key can revoke itself or any key on the account issued before it, so after a rotation the new key retires the old one, and a leaked old key cannot revoke its replacement (403 api_key_revoke_forbidden). Revocation is permanent and applies on the key's next request, which is answered 401 api_key_revoked. The key's screenings, alerts and usage stay on the account. This call never counts against your quota, so a key that has used up its quota can still be revoked. An optional reason is recorded with the revocation.
curl -X DELETE "https://noblesight.io/v1/account/keys/noble_live_9f3e1?confirm=noble_live_9f3e1&reason=leaked" \ -H "X-API-Key: $NOBLE_API_KEY"
{
"key_prefix": "noble_live_9f3e1",
"status": "revoked",
"revoked_at": "2026-10-27T14:02:11Z",
"already_revoked": false,
"active_keys_remaining": 1
}
Repeating the call returns the original revocation with already_revoked: true. Revoking your last active key is allowed: active_keys_remaining is 0 and a warning says so; contact support@noblesight.io for a new key. A prefix that is not one of your keys returns 404. Revoking a key stops the credential but does not undo what it did: after revoking a leaked key, check GET /v1/webhooks for endpoints you did not register.
POST /v1/account/checkout
Create a Stripe Checkout session to upgrade your API key to a paid tier. Returns a URL — redirect your user or open it in a browser.
curl -X POST https://noblesight.io/v1/account/checkout \
-H "Content-Type: application/json" \
-H "X-API-Key: $NOBLE_API_KEY" \
-d '{"tier": "standard"}'
{
"checkout_url": "https://checkout.stripe.com/c/pay/..."
}
On successful payment, your API key tier is upgraded automatically. No downtime, no key rotation. See Pricing for tier details.
Support
Integration help, compliance questions, or paid tier inquiries. We respond within one business day.
support@noblesight.io · sales@noblesight.io for paid tiers · Bluesky
System Status
Monitor Noble Sight's availability programmatically. No authentication required.
curl https://noblesight.io/status | jq
Returns 200 when operational, 503 during outages. Includes database latency and component health. Point your uptime monitor here.