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

# Trademark Source

> Provenance metadata showing where a trademark record came from and when it was observed

## Overview

Returns provenance metadata for the latest raw-record version of a trademark: which office produced the data, when Signa observed it, the source format, and a content hash. Use this for auditing data lineage, verifying freshness, or proving where a particular field value originated.

For some records, no raw-record version is stored. In that case the endpoint falls back to the source metadata stored directly on the trademark record: the response is still `200 OK` but uses a reduced field set. `source_format` is synthesized as `bulk_xml`, `source_response_type` is `null`, and `source_locator` may be `null`. Clients should tolerate these reduced values rather than treating the response as an error.

The endpoint only returns `404` when the trademark itself does not exist.

This endpoint returns a single record. There is no pagination.

## Path Parameters

<ParamField path="id" type="string" required>
  Trademark ID (`tm_...`).
</ParamField>

## Response

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

<ResponseField name="trademark_id" type="string">
  Echo of the requested trademark ID.
</ResponseField>

<ResponseField name="office_code" type="string">
  Lowercase office code (e.g. `uspto`, `euipo`).
</ResponseField>

<ResponseField name="observed_at" type="string">
  ISO 8601 timestamp when Signa fetched and parsed this version of the source record.
</ResponseField>

<ResponseField name="source_format" type="string">
  Source data format (e.g. `xml_st96`, `xml_dtd`, `json`).
</ResponseField>

<ResponseField name="source_response_type" type="string">
  Provider response classification, when known (e.g. `daily_bulk`, `tsdr_api`, `weekly_zip`).
</ResponseField>

<ResponseField name="source_locator" type="string">
  Reference back to the originating file or URL (e.g. bulk file name, API endpoint path). May be `null` when no raw-record version is stored for this trademark.
</ResponseField>

<ResponseField name="payload_hash" type="string">
  SHA-256 hash of the raw payload, used for change detection and de-duplication.
</ResponseField>

<ResponseExample>
  ```json Full provenance theme={null}
  {
    "object": "trademark_source",
    "trademark_id": "tm_abc123",
    "office_code": "uspto",
    "observed_at": "2026-04-09T03:18:42Z",
    "source_format": "xml_dtd",
    "source_response_type": "daily_bulk",
    "source_locator": "apc20260408-20260408-01.zip",
    "payload_hash": "sha256:8f2a..."
  }
  ```

  ```json Synthesized (no raw-record version) theme={null}
  {
    "object": "trademark_source",
    "trademark_id": "tm_abc123",
    "office_code": "uspto",
    "observed_at": "2026-04-09T03:18:42Z",
    "source_format": "bulk_xml",
    "source_response_type": null,
    "source_locator": null,
    "payload_hash": "sha256:8f2a..."
  }
  ```
</ResponseExample>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.signa.so/v1/trademarks/tm_abc123/source" \
    -H "Authorization: Bearer sig_YOUR_KEY"
  ```

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

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

  const source = await signa.trademarks.source("tm_abc123");
  console.log(source.observed_at, source.source_format);
  ```
</CodeGroup>

## Errors

| Status | Type               | Description                                                                                                                                    |
| ------ | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | `validation_error` | Invalid trademark ID format                                                                                                                    |
| 401    | `unauthorized`     | Missing or invalid API key                                                                                                                     |
| 404    | `not_found`        | Trademark not found (the endpoint falls back to trademark-record metadata when no raw-record version exists, so it does not 404 for that case) |
| 429    | `rate_limited`     | Too many requests                                                                                                                              |

See [Errors](/api-reference/errors) for the full envelope.

## Related Endpoints

* [Get Trademark](/api-reference/trademarks/get-trademark): current parsed detail for the mark
* [Trademark Changes](/api-reference/trademarks/trademark-changes): diff history across versions
* [Data Freshness](/guides/data-freshness): how often each office is refreshed