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

# Related Trademarks

> Mark-to-mark relationships: Madrid designations, divisionals, seniority claims, and assignments

## Overview

Returns mark-to-mark relationships recorded for a trademark, such as Madrid designations of a basic mark, divisionals, seniority claims, partial assignments, and Article 4bis replacements. Relationships are sourced from the office gazette and the `trademark_relationship` table.

Use this endpoint to walk a Madrid family from the basic mark to its designations, find the divisional parent of a child application, or trace ownership lineage across mergers and partial transfers. Results are paginated and sorted by `effective_date`.

## Path Parameters

<ParamField path="id" type="string" required>
  Trademark ID prefixed with `tm_` (e.g. `tm_8kLm2nPq`).
</ParamField>

## Query Parameters

<ParamField query="relationship_type" type="string">
  Filter by a single relationship type. Omit to return every relationship for the mark. Valid values:

  * `madrid_designation_of`: this mark is a national designation of a Madrid IR basic mark
  * `based_on_basic_application`: Madrid IR built on a pending application
  * `based_on_basic_registration`: Madrid IR built on a registered mark
  * `seniority_claim`: EU mark claiming seniority from an earlier national right
  * `divisional_parent`: original application that this mark was divided from
  * `partial_assignment_from`: created by a partial assignment of an earlier mark
  * `merged_into`: superseded by a merger into another mark
  * `transformed_from`: Madrid transformation from a ceased IR
  * `replaces_under_4bis`: replaces an earlier national mark under Madrid Article 4bis
  * `partial_transfer_of`: partial transfer source mark
  * `continuation_of`: continuation of an earlier mark across re-filings
</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="Relationship object">
    <ResponseField name="related_trademark_id" type="string | null">
      Public ID of the related mark when Signa has it ingested. Null when the relationship points to a mark we have not yet captured (use `target_office_code` and `target_record_id` to identify it).
    </ResponseField>

    <ResponseField name="relationship_type" type="string">
      One of the values listed under `relationship_type` above.
    </ResponseField>

    <ResponseField name="effective_date" type="string | null">
      ISO date when the relationship took effect.
    </ResponseField>

    <ResponseField name="mark_text" type="string | null">
      Mark text of the related trademark when known.
    </ResponseField>

    <ResponseField name="office_code" type="string | null">
      Office code of the related trademark, lowercase (e.g. `uspto`, `euipo`, `wipo`).
    </ResponseField>

    <ResponseField name="status_stage" type="string | null">
      Status stage of the related trademark.
    </ResponseField>

    <ResponseField name="direction" type="string">
      Either `outgoing` (this mark relates to another) or `incoming` (another mark relates to this one).
    </ResponseField>

    <ResponseField name="target_office_code" type="string | null">
      Office code reported by the source data when the related mark is not yet ingested.
    </ResponseField>

    <ResponseField name="target_record_id" type="string | null">
      Office-native record number reported by the source data when the related mark is not yet ingested.
    </ResponseField>

    <ResponseField name="metadata" type="object | null">
      Office-specific extra fields (e.g. seniority country, partial transfer class scope).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="has_more" type="boolean">Whether more relationships 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": [
      {
        "related_trademark_id": "tm_Qr6nK9jL",
        "relationship_type": "madrid_designation_of",
        "effective_date": "2023-09-12",
        "mark_text": "AURORA",
        "office_code": "wipo",
        "status_stage": "registered",
        "direction": "outgoing",
        "target_office_code": null,
        "target_record_id": null,
        "metadata": null
      },
      {
        "related_trademark_id": null,
        "relationship_type": "seniority_claim",
        "effective_date": "2022-04-08",
        "mark_text": null,
        "office_code": null,
        "status_stage": null,
        "direction": "outgoing",
        "target_office_code": "dpma",
        "target_record_id": "30412345",
        "metadata": { "seniority_country": "DE" }
      }
    ],
    "has_more": false,
    "pagination": {
      "cursor": null
    },
    "request_id": "req_dW3mN9pQ"
  }
  ```
</ResponseExample>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -G "https://api.signa.so/v1/trademarks/tm_8kLm2nPq/related" \
    -H "Authorization: Bearer sig_YOUR_KEY_HERE" \
    --data-urlencode "relationship_type=madrid_designation_of" \
    --data-urlencode "limit=10"
  ```

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

  resp = requests.get(
      "https://api.signa.so/v1/trademarks/tm_8kLm2nPq/related",
      headers={"Authorization": "Bearer sig_YOUR_KEY_HERE"},
      params={"relationship_type": "madrid_designation_of", "limit": 10},
  )
  relationships = resp.json()["data"]
  ```

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

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

  const related = await signa.trademarks.related("tm_8kLm2nPq", {
    relationship_type: "madrid_designation_of",
    limit: 10,
  });

  for (const rel of related.data) {
    console.log(rel.relationship_type, rel.related_trademark_id, rel.effective_date);
  }
  ```
</CodeGroup>

## Errors

| Status | Type               | Description                                              |
| ------ | ------------------ | -------------------------------------------------------- |
| 400    | `validation_error` | Invalid `id` format or unsupported query parameter value |
| 401    | `unauthorized`     | Missing or invalid API key                               |
| 403    | `forbidden`        | API key lacks the `trademarks:read` scope                |
| 404    | `not_found`        | Trademark ID does not exist                              |
| 429    | `rate_limited`     | Rate limit exceeded                                      |

## Related Endpoints

* [Get Trademark](/api-reference/trademarks/get-trademark) -- full trademark detail
* [Trademark Coverage](/api-reference/trademarks/trademark-coverage) -- Madrid designation territories for an IR
* [List Trademarks](/api-reference/trademarks/list-trademarks) -- multi-strategy text and phonetic search