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

# Parties and name keys

> Owners and representatives, how roles are merged, the primary owner, and how name keys make exact name filters work across spellings.

## Owners and representatives

Offices record the people and companies on a mark under different roles. The record groups current parties into two lists:

| List | Roles it contains |
| - | - |
| `parties.owners` | `owner`, `holder`, `applicant` |
| `parties.representatives` | `representative`, `correspondent` |

Offices disagree on where the current proprietor is recorded, and some (the United States, for example) record the responsible attorney only as the correspondent. Grouping by purpose means one filter finds a proprietor or a firm whatever the office called them.

Each party appears **once per name key and country**, with every role it holds. An applicant who is also the owner appears as one entry with `"roles": ["owner", "applicant"]`.

Owners are ordered owner, holder, applicant, then in the office's order. The first entry is the **primary owner**, which summaries carry as `primary_owner` and which the `primary_owner_*` filters use.

Earlier owners, holders and representatives are not in these lists. Ask for them with `include=previous_parties` on [retrieve](https://docs.pinakelai.com/api-reference/trademarks/retrieve.md) or [batch](https://docs.pinakelai.com/api-reference/trademarks/batch.md).

## Name keys

Party names are published inconsistently: with and without accents, punctuation and legal-form suffixes. Every party has a `name_key`, the normalized name the exact name filters compare against. To build it, Pinakel:

1. removes accents (`é` becomes `e`);
2. removes full stops, so `S.A.` becomes `SA`;
3. replaces other punctuation (hyphens, commas, apostrophes, brackets, slashes) with spaces;
4. upper-cases the name and collapses spaces;
5. drops trailing legal-form words such as `INC`, `LTD`, `LIMITED`, `GMBH`, `SA`, `SAS`, `AG`, `BV`, `SRL`, `LLC` and `CO`, repeatedly.

| Published name | `name_key` |
| - | - |
| `NIKE, Inc.` | `NIKE` |
| `L'Oréal S.A.` | `L OREAL` |
| `ESSITY PLD FRANCE SAS` | `ESSITY PLD FRANCE` |
| `Tencent Holdings Limited` | `TENCENT HOLDINGS` |
| `腾讯科技（深圳）有限公司` | `腾讯科技 深圳 有限公司` |

Name keys group spelling variants of the same name. They do not resolve different names of the same company: `TENCENT HOLDINGS` and `腾讯科技 深圳 有限公司` are different keys. Build your own list of keys for each company you track.

## Filtering by party

| Filter | Matches | Scope |
| - | - | - |
| `primary_owner_name` | Records whose **first owner** has the name key of the name you send | Any; fast across all registers |
| `primary_owner_key` | Records whose first owner has exactly this name key | Any; fast across all registers |
| `owner_name`, `owner_key` | Records where **any current owner, holder or applicant** has the key | Needs `jurisdiction`, up to 5 codes |
| `representative_name`, `representative_key` | Records where any current representative or correspondent has the key | Needs `jurisdiction`, up to 5 codes |
| `previous_owner_name`, `previous_owner_key` | Records where any previous owner or holder has the key | Needs `jurisdiction`, up to 5 codes |
| `owner_name_phrase`, `representative_name_phrase` | Records where a party's name contains the words, in order (see [Text matching](https://docs.pinakelai.com/concepts/text-matching.md)) | Needs `jurisdiction`, up to 5 codes |

The `*_name` filters normalize your value the same way, so `owner_name=L'Oréal S.A.` and `owner_name=L OREAL` are the same search. The `*_key` filters take a stored key verbatim; use them with a `name_key` copied from a record. Normalization is not idempotent for every input, so sending a key through a `*_name` filter can miss.

### primary owner or any owner?

`primary_owner_*` filters read one indexed column and return quickly over all registers, even for owners with tens of thousands of marks. They only see the first owner, so they miss co-owned marks where your owner is listed second, and applicants recorded next to a different owner. The `owner_*` filters see every current owner, holder and applicant, but must be limited to at most 5 registers.

A practical pattern: discover keys and coverage with `primary_owner_key` across all registers, then run `owner_key` per group of up to 5 registers where completeness matters.

```bash theme={null}
curl -G "https://api.pinakelai.com/v1/trademarks" \
  -H "Authorization: Bearer $PINAKEL_API_KEY" \
  --data-urlencode "owner_key=ESSITY PLD FRANCE" \
  --data-urlencode "jurisdiction=AD,AL,EM"
```

## Names, countries and addresses

* `name` is exactly as published, in its original script. `name_translated` holds a translation or romanization where the office or Pinakel provides one.
* `country` is an ISO 3166-1 alpha-2 code, or `null` when the record gives no country that can be resolved, even if the address names one.
* `address` is a single string as published. Address formats are not normalized.
* `entity` is the legal form or entity description as published, such as `SAS`.

## Name keys can change

When Pinakel improves normalization, some keys change, and the affected records are republished in the [changes feed](https://docs.pinakelai.com/guides/syncing.md). Refresh the keys you store from current records from time to time instead of keeping them forever.

## Personal data

Parties include individuals: applicants, owners and representatives, with the names and addresses the office published. See [Compliance & privacy](https://docs.pinakelai.com/data/compliance-and-privacy.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.