> ## 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.

# Entities & owners

> Owners, resolved entities, and how Signa links company records across offices

An **owner** is one office's record of an applicant or registrant, exactly as that office filed it. An **entity** is the same company's identity across every office: it links together the owner records that belong to it.

## Party types

| Type         | Prefix  | What it is                                                                           |
| ------------ | ------- | ------------------------------------------------------------------------------------ |
| **Entity**   | `ent_`  | The cross-office identity linking the owner records that belong to the same company. |
| **Owner**    | `own_`  | A single office's applicant/registrant record, as that office filed it.              |
| **Attorney** | `att_`  | Named attorney of record on a trademark.                                             |
| **Firm**     | `firm_` | Law firm associated with the attorney.                                               |

Attorneys and firms appear on the trademark records they're associated with. Owners and entities each have their own API surface, described below.

## Owner or entity?

Use **owners** when you need the exact per-office record: the name as filed, the office, the address on file. Use **entities** for company-level questions, such as "everything this company owns, everywhere."

```bash theme={null}
GET /v1/owners/own_abc123
GET /v1/entities/ent_R3jK9mN2
```

Every owner also has an entity view, even before it has been linked to anything else: if it isn't linked yet, its entity has exactly one member (itself). Once it is linked, the same request returns the combined entity instead, so you can always traverse from a mark to its company-level identity without checking whether a link exists first.

## Endpoints

| Endpoint                                                                       | Purpose                                   |
| ------------------------------------------------------------------------------ | ----------------------------------------- |
| [`GET /v1/entities`](/api-reference/parties/list-entities)                     | Search and filter resolved entities       |
| [`GET /v1/entities/{id}`](/api-reference/parties/get-entity)                   | One entity with members and link evidence |
| [`GET /v1/entities/{id}/trademarks`](/api-reference/parties/entity-trademarks) | Global portfolio across all members       |
| [`GET /v1/entities/{id}/family`](/api-reference/parties/entity-family)         | GLEIF corporate parent and subsidiaries   |
| [`GET /v1/owners`](/api-reference/parties/list-owners)                         | Search and filter owners                  |
| [`GET /v1/owners/{id}`](/api-reference/parties/get-owner)                      | A single per-office owner record          |

## How linking works

The same company often files under a different legal entity, a different language, or a different level of detail in each office. For example, Procter & Gamble's US, German, and Swiss records share almost no text a name match could use, but a shared Madrid registration number ties them together into one entity.

Signa **links owner records, it never merges them.** The per-office data is never rewritten, so `own_` IDs stay stable even as new links are added later. Two owners are linked only on specific, verifiable evidence: a shared applicant identifier, a shared Madrid international registration, or a shared public company. A name match alone is never enough, since two unrelated companies can share an identical name.

Each member on a resolved entity carries how it was linked:

```bash theme={null}
curl -s "https://api.signa.so/v1/entities/ent_R3jK9mN2" \
  -H "Authorization: Bearer sig_YOUR_KEY" | jq '.members[].link'
```

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

const signa = new Signa({ api_key: process.env.SIGNA_API_KEY });
const entity = await signa.entities.retrieve("ent_R3jK9mN2");
console.log(entity.name, entity.member_count, entity.tickers);
```

Each link exposes a `method` (`shared_identifier`, `international_registration`, `public_company`, `portfolio_overlap`, or `manual_review`), a coarse `match_strength` band, and whether it was `reviewed`.

Only entities can be superseded, never owners: if two resolved entities are later found to be the same company and combined, requesting the old `ent_` ID returns `410 Gone` with the successor ID in `merged_into` so you can update your reference.

## Public-company enrichment

Owners and entities can be linked to public-company facts from two sources:

| Source        | Coverage                        | Identifier              |
| ------------- | ------------------------------- | ----------------------- |
| **SEC EDGAR** | \~10,000 US-listed companies    | Ticker (CIK internally) |
| **GLEIF**     | \~2.5M legal entities worldwide | LEI                     |

These facts are aggregated onto the entity, so it carries a company's ticker even when only one member owner was matched. Filter either surface by them:

| Filter                 | Description                                                                                                              |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `ticker=AAPL`          | Linked to this stock ticker. Subsidiary-inclusive: `ticker=NKE` returns Nike and its subsidiary entities                 |
| `lei=HWUPKR0…`         | Linked to this LEI                                                                                                       |
| `publicly_traded=true` | Publicly listed: a confirmed active SEC ticker match, or the entity is itself listed or a subsidiary of a listed company |
| `has_lei=true`         | Has a confirmed GLEIF LEI match                                                                                          |

<Note>
  An entity that is a subsidiary of a listed company carries the inherited ticker on its `tickers` array, with the direct-vs-inherited provenance broken out in the entity's `listing` block (`status` is `listed` or `subsidiary_of_listed`, `source` is `direct` or `inherited`). See [Track any public company's trademarks](/guides/use-cases/public-company-trademarks) for the full recipe.
</Note>

```bash theme={null}
GET /v1/entities?publicly_traded=true&country_code=US&sort=-trademark_count
```

<Note>
  Owner-to-public-company matching is confirmed-positive only: a `false` or absent value means no match was found, not that the company is confirmed private.
</Note>

## Corporate families

Using GLEIF Level 2 relationship data, Signa connects an entity to its direct corporate parent and subsidiaries:

```bash theme={null}
GET /v1/entities/ent_R3jK9mN2/family
```

```typescript TypeScript theme={null}
const family = await signa.entities.family("ent_R3jK9mN2");
console.log(family.parent?.name, family.children.length);
```

<Note>
  GLEIF Level 2 covers LEI-reporting companies only. An absent edge does not imply the absence of a corporate relationship; see `coverage_caveat` on the response.
</Note>

## FAQ

<AccordionGroup>
  <Accordion title="Why did the entity ID I requested come back with a different id?">
    You requested an owner's single-member entity view before it was linked to anything else. Signa transparently resolves it to the real entity once a link exists and returns that `id`. This is expected: store the returned `id`.
  </Accordion>

  <Accordion title="Do owner IDs ever break?">
    No. Owners are linked, not merged, so `own_` IDs are stable. Only entities are ever combined; when that happens the old `ent_` ID returns `410 Gone` with a pointer to its successor in `merged_into`.
  </Accordion>
</AccordionGroup>