> ## Documentation Index
> Fetch the complete documentation index at: https://docs.signa.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Entity Family

> GLEIF corporate parent and direct subsidiaries of a resolved entity

## Overview

Returns the **GLEIF-curated direct family** of an entity: its corporate parent and its direct subsidiaries, one level deep. This is the curated, direct-consolidation view of corporate structure — distinct from the raw, all-relationship-types graph at [Owner Related](/api-reference/parties/owner-related).

Family edges come from GLEIF Level 2 (the `IS_DIRECTLY_CONSOLIDATED_BY` relationship). Coverage is therefore limited to LEI-reporting companies — an **absent edge does not mean the entity has no parent or subsidiaries**, only that none is recorded in GLEIF. A derived singleton, or a materialized entity with no GLEIF edges, returns `{ parent: null, children: [] }` (a valid `200`, not a `404`).

<Note>
  "Family" is a **group-level** relationship — related companies in a corporate tree. It is never an identity claim: `Pfizer Inc (US)` and `Pfizer AG (CH)` are distinct entities connected by family, not the same entity.
</Note>

## Path Parameters

<ParamField path="id" type="string" required>
  Entity ID (e.g. `ent_R3jK9mN2`), including the derived `ent_<owner-uuid>` form.
</ParamField>

## Response

<ResponseField name="object" type="string">Always `entity_family`.</ResponseField>

<ResponseField name="parent" type="object | null">
  The corporate parent, or `null` when none is recorded.

  <Expandable title="Parent">
    <ResponseField name="id" type="string">Parent entity ID (`ent_*`).</ResponseField>
    <ResponseField name="object" type="string">Always `entity`.</ResponseField>
    <ResponseField name="name" type="string">Parent display name.</ResponseField>
    <ResponseField name="country_code" type="string | null">ISO country code.</ResponseField>
    <ResponseField name="relationship" type="string">Always `parent`.</ResponseField>
    <ResponseField name="source" type="string">Always `gleif`.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="children" type="object[]">
  Direct subsidiaries, sorted by name. Each carries `relationship: "direct_subsidiary"` and `source: "gleif"`.
</ResponseField>

<ResponseField name="source" type="string">Always `gleif`.</ResponseField>
<ResponseField name="coverage_caveat" type="string">A human-readable note that edges are GLEIF Level 2 and cover LEI-reporting companies only.</ResponseField>
<ResponseField name="request_id" type="string">Unique request identifier for support.</ResponseField>

<ResponseExample>
  ```json theme={null}
  {
    "object": "entity_family",
    "parent": {
      "id": "ent_parentAB",
      "object": "entity",
      "name": "8x8 Holdings",
      "country_code": "US",
      "relationship": "parent",
      "source": "gleif"
    },
    "children": [
      {
        "id": "ent_childEMEA",
        "object": "entity",
        "name": "8x8 EMEA Ltd",
        "country_code": "GB",
        "relationship": "direct_subsidiary",
        "source": "gleif"
      }
    ],
    "source": "gleif",
    "coverage_caveat": "Family edges are sourced from GLEIF Level 2 (IS_DIRECTLY_CONSOLIDATED_BY) and cover LEI-reporting companies only. An absent edge does not imply the absence of a corporate relationship.",
    "request_id": "req_xyz789"
  }
  ```
</ResponseExample>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.signa.so/v1/entities/ent_R3jK9mN2/family" \
    -H "Authorization: Bearer sig_YOUR_KEY_HERE"
  ```

  ```python Python theme={null}
  import requests

  resp = requests.get(
      "https://api.signa.so/v1/entities/ent_R3jK9mN2/family",
      headers={"Authorization": "Bearer sig_YOUR_KEY_HERE"},
  )
  family = resp.json()
  ```

  ```typescript TypeScript theme={null}
  import { Signa } from "@signa-so/sdk";

  const signa = new Signa({ api_key: process.env.SIGNA_API_KEY });
  const family = await signa.entities.family("ent_R3jK9mN2");
  console.log(family.parent?.name, family.children.length);
  ```
</CodeGroup>

<Tip>
  To list trademarks across the **whole** corporate group (parent + all descendants), use the `entity_group` filter on [List Trademarks](/api-reference/trademarks/list-trademarks) — `GET /v1/trademarks?entity_group=ent_...`.
</Tip>

## Errors

| Status | Type            | Description                                                                     |
| ------ | --------------- | ------------------------------------------------------------------------------- |
| 401    | `unauthorized`  | Missing or invalid API key                                                      |
| 403    | `forbidden`     | API key lacks the `trademarks:read` scope                                       |
| 404    | `not_found`     | Entity ID does not exist (or a derived id for a suppressed / merged-away owner) |
| 410    | `entity_merged` | The entity was fused into another; follow `merged_into`                         |

## Related Endpoints

* [Get Entity](/api-reference/parties/get-entity): entity detail with members
* [Entity Trademarks](/api-reference/parties/entity-trademarks): marks across all member owners
* [Owner Related](/api-reference/parties/owner-related): the raw owner-level GLEIF graph (all relationship types, both directions)