---
title: "Sugra Entity"
description: "KYB and entity screening: sovereign sanctions, PEP signals, LEI and VAT resolution - a signal, not a determination."
slug: sugra-entity
status: published
published_at: 2026-06-02
author: Arman Obosyan
author_url: https://sugra.systems/about
section: foundation
series_order: 3
primary_keyword: sugra entity sanctions screening
hero_image: /blog/images/posts/sugra-entity-hero.jpg
hero_alt: "Sugra Entity - Sugra API blog"
og_image: /blog/images/posts/sugra-entity-hero.jpg
tags:
  - entity
  - compliance
  - api
---

# 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

```json
"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

```bash
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"
```

```python
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.**

```bash
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.**

```bash
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

1. Treating `clear` as a legal determination  
2. Hiding the disclaimer in UI  
3. Ignoring `review` band (auto-approve fuzzy matches)  
4. Skipping freshness checks  
5. 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 |

---