Sugra Entity: KYB and sanctions screening as a signal, not a determination

Series: Sugra product directions (3 of 7)
Audience: developers integrating the Sugra API over HTTP
Live samples verified: 2026-07-24 against https://sugra.ai
Auth: x-api-key header on every data call

Standalone article. Entity is the compliance / know-your-business direction of the Sugra API.

Hard boundary: every screening response is a screening signal, not a compliance determination, not legal advice, and not a consumer report. Product UIs must show the disclaimer.

Essence

The full entity picture - KYB, sanctions, PEP - a screening signal, not a determination.

Sugra Entity composes:

Name screening (single and batch) against multi-jurisdiction sanctions lists
Crypto wallet and document-identifier screening
LEI / VAT-anchored KYB envelopes (profile, screening, ownership slices)
GLEIF corporate registry surface (search, parents, relationships)
PEP layer (Wikidata-derived; supplementary)

Zero commercial Tier C upstreams. Lists and registries are named: OFAC SDN, EU consolidated, UN Security Council, UK OFSI, Canada OSFI, Australia DFAT, Switzerland SECO, World Bank debarred firms, GLEIF (CC0), Wikidata PEP.

What this direction is not

Not this	Why
A determination that someone is “sanctioned for legal purposes”	Technology signal only
Legal advice or a law firm product	Disclaimer is mandatory
A full adverse-media terminal	Supplementary coverage only
Market data or ownership trading books	Finance / 13F is different
Person-level tracking for marketing	Compliance screening use cases only

Capability map

Category	Endpoints (approx.)	Coverage
Sugra Entity	9	Screen, batch screen, resolve, wallet/id screen, sources, composed envelope by anchor
Corporate Registry (GLEIF)	14	LEI records, fuzzy search, parents, relationships, ISIN mapping, catalogs

Live OpenAPI is authoritative for exact totals.

Why the response shape is useful

1. Status tri-state: hit / review / clear

Driven by score thresholds (threshold_hit default 0.9, threshold_review default 0.7). Live name screen for Rosneft + country RU returned status: hit with multi-list matches (OFAC, EU, UK OFSI, CH SECO, AU DFAT, CA OSFI, and more), each with:

list, program, restriction_type
matched_name, score, match_type
rationale array (why the score)
list_published

2. Mandatory disclaimer and audit hooks

"meta": {
  "product": "Sugra Entity",
  "disclaimer": "Screening signal, not a compliance determination. Sugra is a technology provider, not a consumer reporting agency or sanctions authority. ...",
  "list_freshness": { "ofac_sdn": { "stale": false, "age_hours": 5.02 } },
  "stale_screening": false,
  "lists_loaded": ["au_dfat", "ca_osfi", "ch_seco", "eu_consolidated", "ofac_sdn", "uk_ofsi", "un_sc", "wb_debarred", "wikidata_pep"],
  "lists_missing": []
}

Store screening_id (when present) with the case file for replay and audit.

3. Field provenance on KYB envelopes

LEI envelope for Deutsche Bank (7LTWFZYICNSX8D621K86) live: legal name, country DE, status ACTIVE, field_provenance per field (for example gleif), plus screening slice status review.

4. Wallet exact match with engine metadata

Live wallet screen returned hit for a known sanctioned address: match_type: wallet, matched_name: Lazarus Group, list ofac_sdn, rationale exact wallet match, plus fifty_percent_rule block and screening_id.

Developer path

export SUGRA_API_KEY="YOUR_API_KEY"

curl -X POST -H "x-api-key: $SUGRA_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Rosneft","country":"RU"}' \
  "https://sugra.ai/api/v1/entity/screen"

import os, requests
H = {"x-api-key": os.environ["SUGRA_API_KEY"]}
r = requests.post(
    "https://sugra.ai/api/v1/entity/screen",
    headers={**H, "Content-Type": "application/json"},
    json={"name": "Example Corp", "country": "US"},
    timeout=60,
)
r.raise_for_status()
body = r.json()
status = body["data"]["screening"]["status"]
disclaimer = body["meta"]["disclaimer"]

Use case 1: Counterparty name screen

Goal. Screen one legal or trade name before onboarding.

Call. POST /api/v1/entity/screen with name, optional country, dob, nationality, as_of.

What you get. hit / review / clear, match list with rationale, list freshness.

Strength. Multi-jurisdiction lists in one call; explainable scores.
Pitfalls. Fuzzy matches need human review at review status. Never auto-block without your policy.

Use case 2: Batch vendor list

Goal. Screen a CSV of counterparties.

Call. POST /api/v1/entity/screen/batch.

Strength. Throughput for onboarding queues.
Pitfalls. Rate limits; persist each row’s status and screening_id.

Use case 3: LEI-anchored KYB envelope

Goal. Identity + screening + ownership slices from one LEI.

Calls.

curl -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v1/entity/lei/7LTWFZYICNSX8D621K86"
# optional slice query params /include as documented

Strength. Composed envelope for case systems.
Pitfalls. LEI must be valid; use GLEIF search when you only have a name.

Use case 4: Wallet risk flag

Goal. Block or review transfers involving sanctioned addresses.

Call.

curl -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v1/entity/wallet/0x098B716B8Aaf21512996dC57EB0615e2383E2f96/screen"

Live result. status: hit, OFAC SDN, Lazarus Group, exact wallet match.

Strength. Exact-match clarity for wallet rails.
Pitfalls. Address formats and chains; false confidence on non-listed addresses is still only “clear signal,” not innocence.

Use case 5: Document identifier screen

Goal. Screen passport / ID-style identifiers when your workflow has them.

Call. GET /api/v1/entity/id/{id_type}/{value}/screen.

Strength. Same status model as names.
Pitfalls. Privacy and data-minimization: only send identifiers you are allowed to process.

Use case 6: Ownership / parent graph

Goal. Walk GLEIF direct and ultimate parents for ownership context.

Calls. /api/v1/gleif/lei-records/{lei}, /direct-parent, /ultimate-parent, /relationships/{lei}.

Strength. Registry-native corporate graph.
Pitfalls. GLEIF is legal-entity structure, not beneficial-owner ultimate opacity solutions.

Use case 7: Sources freshness gate

Goal. Refuse to trust a screen when lists are stale for your policy.

Call. GET /api/v1/entity/sources and/or read meta.list_freshness on every screen.

Strength. Degraded coverage is explicit (stale_screening, lists_missing).
Pitfalls. Define SLA thresholds in your product; Sugra reports ages, you decide risk.

Use case 8: Point-in-time replay

Goal. Re-run a check as_of a list snapshot date for evidence packs.

Call. Screen endpoints with as_of where supported.

Strength. Audit and dispute workflows.
Pitfalls. Historical snapshots depend on retained list versions.

Response strengths summary

Strength	Use
hit / review / clear	Map to your workflow states
rationale + score	Explainability UI
list_freshness	Ops and compliance gates
disclaimer always present	Legal posture in product
screening_id	Case audit trail
field_provenance	KYB field trust

Antipatterns

Treating clear as a legal determination
Hiding the disclaimer in UI
Ignoring review band (auto-approve fuzzy matches)
Skipping freshness checks
Logging raw PII/identifiers without retention policy

Scenarios where Entity alone is enough

KYB onboarding screeners
Payment pre-check for names and wallets
Compliance dashboards over GLEIF + sanctions
Agent tools that must return hit/review/clear with provenance

Not enough alone for: market risk (Finance), media adverse narrative depth (News), network IP fraud (NetAtlas - different signal class).

Live verification (2026-07-24)

Call	Result
POST `/entity/screen` Rosneft	200, hit, multi-list
GET `/entity/lei/7LTWFZYICNSX8D621K86`	200, Deutsche Bank, review
GET `/entity/sources`	200
GET wallet screen (sample address)	200, hit, Lazarus Group

Where to go next

Portal: Sugra Entity direction + sources
Recipe: compliance-screener
Cookbook: 07_entity_sanctions_screening.py
Series: Macro (previous), NetAtlas (next)

#	Direction	Status
1	Finance	Published
2	Macro	Published
3	Entity	This article
4	NetAtlas	Next
5-7	News, Earth, Research	Upcoming