> 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/the-entity-360.md). # The Entity 360 The **Entity 360** is not a separate object; it is the entity viewed through everything attached to it. Retrieving an entity returns its profile and, for a business, its full ownership graph (UBOs, directors, shareholders, PSCs, with shares and designations). From the entity you traverse to its risk score, verifications, transactions, signals, activities and cases. The 360 is the *composition* of these reads, keyed to one identifier. {% columns %} {% column %}

{% endcolumn %} {% column %} Retrieve an entity for its profile and ownership graph, then traverse to its signals, activities, transactions and cases. Each shares the entity as its anchor, so nothing needs reconciling. * Profile: identifying data, enriched over time * Ownership: UBOs, directors, PSCs, share % * Verifications: every KYC/KYB/AML result * Transactions: activity + evaluations (KYT) * Signals & alerts: detected events to review * Activities: immutable audit log * Cases: investigations + AI summaries {% endcolumn %} {% endcolumns %} ### What that looks like for a business Retrieving a business entity returns its full ownership graph in one call. This is the first-class expression of **affiliates and relationships**: a subject and the people who own or control it, in one view. {% code overflow="wrap" %} ```json "ubos": [ { "designation": "PERSONS WITH SIGNIFICANT CONTROL", "principalOwner": true, "firstName": "DOE", "lastName": "JOHN", "entityId": "68752fe3...cfa" }, { "designation": "SHAREHOLDER", "sharesCount": 9990000, "firstName": "DOE", "lastName": "JANE", "entityId": "68752fe4...cfc" } ] ``` {% endcode %} ### Entity classification Entities fall into two groups. **Base Entities** (Individual, Business) stand on their own. **Relationship Entities** (UBO, Downstream Entity) are an individual or business that relates to a parent and are mapped to it via `parentId`.


_Base	Individual	A natural person.
_Base	Business	A legal entity, with incorporation details and an ownership graph.
_Relationship	UBO	An owner or controller of a business, linked through a mapping with designation and share data.
_Relationship	Downstream Entity	A business or individual that belongs to a platform customer (PSP/BaaS), linked via `parentId`.

### The platform hierarchy A **Downstream Entity** is a customer of your customer. Some businesses you serve are themselves platforms (a payment processor, aggregator or BaaS) that use Cowork to protect *their* merchants and fintechs. One field expresses the whole relationship: `parentId`. A downstream entity sets parentId to its platform; a top-level entity leaves it null. Because an entity can have both a parent and children, “platform” is a role any entity can play, and the structure nests to any depth: the processor or BaaS at the top, its merchants and fintechs as downstream entities, and a downstream fintech adding its own downstream entities in turn. Every entity keeps its own score, signals, transactions and cases, and the parentId chain lets a platform see everything beneath it. Localise the label per context (“Sub-merchant” for card/acquiring, “Partner” for BaaS) while the model name stays Downstream Entity. ```mermaid %%{init: {"flowchart": {"curve": "basis"}, "themeVariables": {"fontFamily": "Arial"}}}%% flowchart TB A("Processor / BaaS
PLATFORM · account root · parentId: null") B("Merchant
DOWNSTREAM ENTITY
scope: signals · cases") C("Fintech
DOWNSTREAM · also a PLATFORM
has its own downstream entities") D("Fintech's customer
DOWNSTREAM ENTITY") E("Customer
DOWNSTREAM") A -->|parentId| B A -->|parentId| C C -->|parentId| D C -->|parentId| E classDef platform fill:#2D849B,color:#fff,stroke:#2D849B,stroke-width:2px; classDef downstream fill:#EAF4F7,color:#1D3C46,stroke:#B7D6DF,stroke-width:1.5px; classDef note fill:#FFF8E1,color:#5D4A00,stroke:#E6C86E,stroke-width:1.5px; class A platform; class B,C,D,E downstream; class Note note; ``` > List a platform's whole book with `GET /v2/api/entities?parentId=ent_…` · walk the chain up or down for investigations. ### Worked example: PayCo → FinCo → ShopCo A processor, **PayCo**, onboards a fintech, **FinCo**, as a **Business** entity with full KYB and UBOs. FinCo takes on a merchant, **ShopCo**, but shares only ShopCo's email, so ShopCo is added as a Downstream Entity (`parentId` = FinCo), thinly known but tracked. In PayCo's 360: FinCo shows full profile + ownership + UBOs, with ShopCo as a dedicated downstream entity beneath it. > **Transaction attribution**. FinCo's own activity (e.g. a wallet cash-out from its PayCo balance) attaches to **FinCo**. ShopCo's activity (e.g. a card payment or P2P) attaches to **ShopCo**, even though it flows through FinCo. Both appear in PayCo's rolled-up 360, segmented by entity, so signals fire against the right party. --- # 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/the-entity-360.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.