> For the complete documentation index, see [llms.txt](https://doc.youverify.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.youverify.co/core-concepts.md). # Core concepts #### Entities An **entity** is any subject your team needs to track, verify or monitor: an individual or a business. It is the central object; everything else references an entity. An entity can be created from a full payload or from almost nothing. The only hard requirements are the entity type and a consent flag. For an individual, a name, phone and date of birth complete a basic profile; for a business, an incorporation name and number. The very thin case, creating an entity from **just an email**, is reserved for entities **tagged as downstream entities** (the payment-processor customer case). Entities carry an ent\_… ID and a lifecycle status (status, e.g. not\_approved/approved; profileStatus, e.g. pending). **Two ways to add an entity**, both producing a scored, tracked record: • **Manual**: you supply the data yourself. • **Authoritative government data**: you create the entity from an official source (national ID or company registry). This route also dynamically retrieves data from authoritative government sources: an individual’s identity data, and for a business its UBOs into the ownership graph. Adding an entity runs **CDD to compute a risk score** at creation (PEP, sanctions and adverse-media screening, combined per the weighted model). For a payment-processor customer with only an email, the platform scores on whatever is present and tightens as the entity is enriched. The outcome is always a **Created** entity, never an approve/reject decision. **Working with existing entities**. Once an entity exists you do not recreate it. Search for or fetch it and continue operating: run further checks, attach activities, post transactions, open a case. Any check or activity can **reference the entity’s ID** so its result folds into the 360 rather than living as an orphaned report. Create once, reference forever. #### Relationships Entities fall into two groups: **Base Entities** and **Relationship Entities**. Both resolve to an Individual or a Business; the difference is whether the entity stands on its own or relates to a parent. **Base Entities** (the subject in its own right): • Individual: a natural person. • Business: a legal entity, with incorporation details and an ownership graph. **Relationship Entities** (an Individual or Business that relates to a parent, **mapped to that parent via parentId**): • **UBO** **(Ultimate Beneficial Owner)**: a party that owns or controls a business. A UBO can itself be an **individual or a business**, mapped to the business it controls via parentId, alongside a designation and share data. This is what lets ownership chains be walked. • **Downstream Entity**: an individual or business that belongs to a **platform** customer rather than directly to you, mapped to the platform via parentId ([see here](/the-entity-360.md#the-platform-hierarchy)). This is the canonical name for the merchants and fintechs a payment processor or BaaS monitors. An entity can hold more than one classification at once: a business can be a Downstream Entity of a platform and have its own UBOs. **How UBOs arrive and their state**. Dynamic UBO retrieval is part of accessing authoritative government data: the authoritative-data (premium) business route retrieves UBOs from the official registry and appends them to Ownership, **listed but not yet verified or scored**. From there you either promote a UBO (make it its own entity and run KYC/KYB/AML so it gets verified and scored) or **initiate a data request** to the owner. Coverage is country-dependent (governed by [Get Supported Countries and Regions Endpoint](/api-reference/api-reference/entity-management/verify-entity-kyb/get-supported-countries-and-regions.md)); where dynamic retrieval is unavailable, **Add UBO** manually in the dashboard or API. Manually added UBOs follow the same lifecycle. Keeping creation and decisioning separate is what lets you start monitoring an entity, and building its history, before any onboarding decision has been made. Eight ideas that let you navigate the entire reference.

Entity

Any subject you track: an individual or business. The central object. Carries an ent_… ID and a lifecycle status. Can be created from a full payload, or from just an email if tagged as a downstream entity.

Add Entity (two routes)

Manual (you supply the data) or authoritative government data (profile populated from an official source). The authoritative route also dynamically retrieves an individual's data and/or a business's UBOs from authoritative government sources.

Risk score at creation

Adding an entity runs CDD (PEP, sanctions, adverse media) to compute an initial score from whatever data is present. Limited-data PSP customers are scored on what's available

Created, not approved

The outcome is a Created entity with a score and a 360 canvas, not an approve/reject decision. Approval runs separately as an automated AI-agent workflow.

Reference, don't recreate

Search or fetch an existing entity and keep operating on it. Any check or activity can reference the entity ID so its result tracks on the 360. Create once, reference forever.

Entity types

Four classifications: Individual and Business (base types), plus UBO and Downstream Entity (relationship types). A "payment-processor customer" is just a Downstream Entity, often created with only an email.

Downstream Entity

The merchants and fintechs a platform customer (PSP, aggregator, BaaS) monitors. A business/individual entity linked to its platform via parentId. UI alias: "Sub-merchant" (card) or "Partner" (BaaS).

Platform hierarchy (recursive)

"Platform" is a role, not a level. Via parentId the model nests to any depth: processor → fintech → that fintech's own customers. The 360 rolls up the chain.

UBO lifecycle

Authoritative business data lists UBOs under Ownership unverified and unscored. Pick one to process (promote to its own entity) or send it a data request. Dynamic retrieval is country-dependent; where unsupported, use Add UBO (dashboard or API).

Two meters: entities + tokens

Plans include a prepaid allowance of new entities per month plus a Vyra AI token allocation. Add Entity is the primary meter; reading and monitoring existing entities don't cost more. Overage applies past either bundle. See plans →

Verification

A check run on an entity under one of three frameworks: KYC, KYB or AML. Results attach to the entity instead of becoming a loose report.

Signals (umbrella)

The monitoring umbrella grouping Activities, Behavioural Insights, Transactions, Alerts and Cases for an entity. A signal is a detected event, pattern or trigger that warrants attention.

Behavioural insights

Patterns in how an entity behaves over time (transaction rhythm, channel, counterparties, device/access). The "user behaviours" layer of the 360.

Fraud Traps

The detection models and rules that decide when a signal or alert fires: velocity, structuring, mismatch, watchlist proximity, behavioural anomalies.

AI Agents (Vyra)

Deployable AI workflows that automate compliance end to end: Customer Onboarding and Transaction Monitoring agents built from verification templates. The entity approval workflow is itself an AI agent.

Activity

Any recorded interaction: a verification attempt, a case update, an entity change. Forms a traceable, immutable audit log.

Case

An investigation opened on an entity, with an AI-generated summary. The human-in-the-loop layer over signals and alerts.

Affiliates

The ownership graph (ubos[]) and relationships between entities. Lets investigators see a subject and its affiliates together.

Progressive enrichment

Create early, learn continuously. Each verification, transaction and signal adds to the record; potentialEntityMatch hints at duplicates to consolidate.

### The response envelope Every response shares one shape, so you write your client once. ```json { "success": true, "status_code": 200, "message": "Human-readable outcome.", "data": { }, "links": [] } ``` #### Entity lifecycle An entity moves through clearly separated stages: 1. **Created**: added(manually or from authoritative data)and scored at creation. This is a tracking state, not an approval. 2. **Enriched**: as more data and checks arrive (referencing the entity ID), the profile fills out and the score tightens. 3. **Decisioned**: approve / reject / restrict / escalate, driven by an **AI-agent workflow** ([see here](/monitoring-model.md#workflows-and-decisions)), escalating edge cases to a human or a case. 4. **Monitored**: the entity stays live; re-screening and transaction monitoring continue, raising signals and alerts over time. Keeping creation and decisioning separate is what lets you start monitoring an entity, and building its history, before any onboarding decision has been made. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://doc.youverify.co/core-concepts.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.