--- title: "Compose the KYB envelope for an entity" method: GET path: "/api/v1/entity/{anchor}/{value}" tags: ["Sugra Entity"] --- # Compose the KYB envelope for an entity `GET /api/v1/entity/{anchor}/{value}` Resolve an entity by `(anchor, value)` and compose the requested slices into the canonical KYB envelope. `anchor` is `lei` (via GLEIF) or `vat` (via the EU VIES service). Use `?include=` (comma list of `profile,screening,ownership`) to select slices; the default is all three. The `vat` anchor has no ownership graph (a VAT has no LEI) and a VAT whose identity is withheld is never screened `clear`. Fail-CLOSED: a screening failure returns 503, never a `clear`. `?as_of=YYYY-MM-DD` scopes ONLY the screening slice to the dated snapshot for that date (point-in-time); the identity / ownership / VIES slices are live external lookups with no historical snapshot and remain current. A malformed as_of returns 422; a date whose snapshot is absent returns 503 (fail-closed, never a live fallback). ## Path parameters - `anchor` string, required — Entity anchor type (`lei` or `vat`). - `value` string, required — Anchor value (e.g. the LEI code or the VAT number). ## Query parameters - `include` string, nullable — Comma list of slices to compose (profile, screening, ownership). - `as_of` string, nullable — Point-in-time date (YYYY-MM-DD) scoping the screening slice to the dated snapshot. Identity/ownership remain current. ## Response `200` Successful Response - EnvelopeEntityAnchorValueData - `data` EntityAnchorValueData, required - `entity` EntityEntity - `id` string, nullable - `anchor` EntityAnchor - `lei` string, nullable - `vat` string, nullable - `name` string, nullable - `country` string, nullable - `type` string, nullable - `status` string, nullable - `field_provenance` FieldProvenance - `name` string, nullable - `country` string, nullable - `status` string, nullable - `type` string, nullable - `validation` Validation - `is_valid` boolean, nullable - `source` string, nullable - `name_withheld` boolean, nullable - `unavailable` boolean, nullable - `screening` Screening - `status` string, nullable - `matches` Match[], nullable - `list` string, nullable - `program` string, nullable - `restriction_type` string, nullable - `matched_name` string, nullable - `score` union - integer - number - `match_type` string, nullable - `rationale` string[], nullable - `source_id` string, nullable - `list_published` string, nullable - `coverage_note` unknown - `incomplete_coverage` boolean, nullable - `hit_grade` boolean, nullable - `identity_conflict` boolean, nullable - `fifty_percent_rule` EntityFiftyPercentRule - `triggered` boolean, nullable - `ambiguous` boolean, nullable - `aggregate_pct` unknown - `sanctioned_owners` unknown[], nullable - unknown - `evidence` string, nullable - `ownership` Ownership - `direct_parent` DirectParent - `lei` string, nullable - `edge` string, nullable - `name` string, nullable - `country` string, nullable - `status` string, nullable - `reporting_exception` unknown - `ultimate_parent` DirectParent - `lei` string, nullable - `edge` string, nullable - `name` string, nullable - `country` string, nullable - `status` string, nullable - `reporting_exception` unknown - `psc` unknown[], nullable - unknown - `truncated` boolean, nullable - `cycle_detected` boolean, nullable - `adverse_media` AdverseMedia - `hits` Hit[], nullable - `title` string, nullable - `url` string, nullable - `source` string, nullable - `published` string, nullable - `matched_terms` string[], nullable - `snippet` unknown - `entity_confirmed` boolean, nullable - `count` union - integer - number - `precision` string, nullable - `disambiguation` string, nullable - `entity_match` EntityEntityMatch - `recognized` boolean, nullable - `type` string, nullable - `mid` string, nullable - `confirmed_hits` union - integer - number - `ambiguous` boolean, nullable - `geg_partial` boolean, nullable - `max_salience` union - integer - number - `coverage_note` string, nullable - `partial_coverage` boolean, nullable - `meta` SugraMeta, required — Metadata attached to every /api/v1/* response envelope. - `endpoint` string, required — Requested endpoint path. - `data_time` string, required — ISO 8601 UTC timestamp of the source data, not of the request. - `response_time` string, required — ISO 8601 UTC timestamp when this response was produced. - `provider` string, required — API name and version. - `source` string, nullable — Identifier of the primary upstream source used for this response. - `attribution` string, nullable — Human-readable attribution mandated by an upstream source (e.g. a securities regulator or self-regulatory organization). Present only on responses whose source requires the owner and source to be clearly identified. Do not remove or alter it when using the response. - `fallback_used` boolean, nullable — True when the primary source failed and a fallback produced the data. - `fallback_chain` string[], nullable — Ordered list of sources attempted, in the order they were tried. - `cached` boolean, nullable — True when this response was served from the internal cache. - `stale` boolean, nullable — True when the cached response was returned after the upstream rate-limited or errored. Clients can use this to detect degraded data. ## Other responses - `401` — Missing or invalid `x-api-key` header. JSON body with a stable `code` distinguishing `missing_api_key` (no header sent) from `invalid_api_key` (header sent, key not accepted); any other 401 source carries the generic `unauthorized` with its detail as `reason`. Plus `hint`. `plan` is always null on 401 - an unauthenticated request has no plan; quota exhaustion is 429, not 401. - `422` — Validation Error - `429` — Daily rate limit exceeded. Check `X-RateLimit-Reset` for the next window. - `503` — Upstream source is temporarily unavailable. Retry after a short delay. --- [API](https://skmtc.net/sugra/apis/sugra-api.md) · [All operations](https://skmtc.net/sugra/apis/sugra-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sugra/sugra-api/revisions/914af3d38c7c/schema)