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

# List Owners

> List trademark owners with filtering, public-company joins, and cursor pagination

## Overview

Returns a paginated, summary-tier list of trademark owners. Supports fuzzy name search, country and entity-type filters, plus virtual filters that join public-company enrichment to find owners with SEC ticker or GLEIF LEI matches. Suppressed owners (placeholder records, frozen entities) are always excluded.

<Info>
  **Owners or entities, which one do I use?** Owners are the raw office-level record parties: the same company appears once per office and per name variant, exactly as each office filed it. Use owners for provenance or exact-record display. For company-level questions ("everything this company owns, everywhere"), start with [Entities](/api-reference/parties/list-entities), the resolved real-world organizations that link these owner records together.
</Info>

## Query Parameters

<ParamField query="q" type="string">
  Fuzzy name search via trigram similarity. Tolerant of typos and word reordering.
</ParamField>

<ParamField query="country_code" type="string">
  Filter by ISO 3166-1 alpha-2 country code (e.g. `US`, `GB`).
</ParamField>

<ParamField query="entity_type" type="string">
  Filter by entity type (e.g. `corporation`, `individual`, `partnership`).
</ParamField>

<ParamField query="ticker" type="string">
  Virtual filter: matches owners linked to a public company with the given stock ticker (e.g. `AAPL`).
</ParamField>

<ParamField query="lei" type="string">
  Virtual filter: matches owners linked to a GLEIF Legal Entity Identifier.
</ParamField>

<ParamField query="publicly_traded" type="boolean">
  Virtual filter: `true` returns owners matched to an active SEC company with a ticker. `false` means no confirmed active ticker match, not confirmed private. Strict `true`/`false` only.
</ParamField>

<ParamField query="has_lei" type="boolean">
  Virtual filter: `true` returns owners matched to a GLEIF legal entity. `false` means no confirmed LEI match. Strict `true`/`false` only.
</ParamField>

<ParamField query="sort" type="string">
  Sort field with optional `-` prefix for descending. One of `-trademark_count`, `trademark_count`, `-grant_rate`, `grant_rate`, `-latest_filing`, `latest_filing`, `-name`, `name`. Default: `-trademark_count`.
</ParamField>

<ParamField query="include_total" type="boolean" default="false">
  When `true`, includes an accurate total count in `pagination.total_count`.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Page size, between 1 and 100.
</ParamField>

<ParamField query="cursor" type="string">
  Opaque cursor returned in the previous response's `pagination.cursor`.
</ParamField>

## Response

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

<ResponseField name="data" type="object[]">
  <Expandable title="Owner summary object">
    <ResponseField name="id" type="string">Owner ID prefixed with `own_`.</ResponseField>
    <ResponseField name="object" type="string">Always `owner`.</ResponseField>
    <ResponseField name="name" type="string">Display name of the owner.</ResponseField>
    <ResponseField name="canonical_name" type="string">Normalized name used for entity resolution and deduplication.</ResponseField>
    <ResponseField name="country_code" type="string | null">ISO 3166-1 alpha-2 country code.</ResponseField>
    <ResponseField name="entity_type" type="string | null">Entity type (e.g. `corporation`, `individual`).</ResponseField>
    <ResponseField name="trademark_count" type="integer">Total trademarks owned. Counts marks: a Madrid IR family counts once, matching the default grouped `GET /v1/trademarks` listings.</ResponseField>
    <ResponseField name="active_count" type="integer">Count of active trademarks (registered + pending). Always present; 0 when stats not yet computed.</ResponseField>
    <ResponseField name="entity_id" type="string">The id of the company profile this owner belongs to (`ent_*`), or a derived placeholder id when it isn't linked to one yet. See [Get Entity](/api-reference/parties/get-entity).</ResponseField>
    <ResponseField name="entity_id_type" type="string">`resolved` or `derived`. On the list, this can briefly show `derived` for an owner that's already linked elsewhere, until the list catches up; [Get Owner](/api-reference/parties/get-owner) detail always reflects the current link.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="has_more" type="boolean">Whether more owners are available.</ResponseField>
<ResponseField name="pagination" type="object">Cursor for the next page.</ResponseField>
<ResponseField name="request_id" type="string">Unique request identifier for support and debugging.</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
    "object": "list",
    "data": [
      {
        "id": "own_R3jK9mN2",
        "object": "owner",
        "name": "Apple Inc.",
        "canonical_name": "APPLE INC",
        "country_code": "US",
        "entity_type": "corporation",
        "trademark_count": 1847,
        "active_count": 1604,
        "entity_id": "ent_R3jK9mN2",
        "entity_id_type": "resolved"
      },
      {
        "id": "own_Yk8mN2pQ",
        "object": "owner",
        "name": "Alphabet Inc.",
        "canonical_name": "ALPHABET INC",
        "country_code": "US",
        "entity_type": "corporation",
        "trademark_count": 1521,
        "active_count": 1310,
        "entity_id": "ent_Yk8mN2pQ",
        "entity_id_type": "derived"
      }
    ],
    "has_more": true,
    "pagination": {
      "cursor": "eyJpZCI6Im93bl9SM2pLOW1OMiIsInNvcnQiOjE4NDd9"
    },
    "request_id": "req_xyz789"
  }
  ```
</ResponseExample>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -G "https://api.signa.so/v1/owners" \
    -H "Authorization: Bearer sig_YOUR_KEY" \
    --data-urlencode "country_code=US" \
    --data-urlencode "publicly_traded=true" \
    --data-urlencode "sort=-trademark_count" \
    --data-urlencode "limit=20"
  ```

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

  const signa = new Signa({ api_key: process.env.SIGNA_API_KEY });

  const owners = await signa.owners.list({
    country_code: "US",
    publicly_traded: true,
    sort: "-trademark_count",
    limit: 20,
  });

  for await (const owner of owners) {
    console.log(owner.name, owner.trademark_count);
  }
  ```
</CodeGroup>

## Errors

| Status | Type               | Description                                                                                  |
| ------ | ------------------ | -------------------------------------------------------------------------------------------- |
| 400    | `validation_error` | Invalid sort, unknown filter value, or non-strict boolean for `publicly_traded` or `has_lei` |
| 401    | `unauthorized`     | Missing or invalid API key                                                                   |
| 403    | `forbidden`        | API key lacks the `trademarks:read` scope                                                    |
| 429    | `rate_limited`     | Rate limit exceeded                                                                          |

## Related Endpoints

* [Get Owner](/api-reference/parties/get-owner): full owner detail
* [Owner Trademarks](/api-reference/parties/owner-trademarks): portfolio of marks owned
* [Owner Related](/api-reference/parties/owner-related): corporate parent and subsidiary relationships