Response Tiers

Signa returns trademark data at three detail levels. Choose the right tier to balance payload size, latency, and the information you need.

Overview

The response tier is fixed per endpoint — there is no tier query parameter. Each endpoint always returns a specific tier based on its use case.

Tier	Fields	Typical Size	Latency
Compact	5 fields	~100 bytes	Fastest
Summary	22 fields	~500 bytes	Fast
Detail	All fields + nested arrays	2—10 KB	Slower

You do not need to specify a tier. Each endpoint returns the appropriate level of detail automatically: detail for single-record lookups, summary for list and search results, and compact for suggest/autocomplete.

When to Use Each Tier

Endpoint	Tier	What You Get
`GET /v1/trademarks/{id}`	Detail	Full record with all nested entities
`POST /v1/trademarks/batch`	Detail	Full records for each ID
`GET /v1/trademarks` (list)	Summary	Status, dates, owner, Nice classes
`POST /v1/trademarks/search`	Summary	Search results with relevance scores
`GET /v1/owners/{id}/trademarks`	Summary	Owner portfolio listing
`POST /v1/trademarks/suggest`	Compact	Autocomplete with minimal payload

Compact Tier

The minimal representation. Used by suggest endpoints and inline cross-references. 5 fields:

Field	Type	Description
`id`	string	Prefixed trademark ID (e.g., `tm_7d4e1f2a`)
`object`	string	Always `"trademark"`
`mark_text`	string \| null	The word mark as filed (null for pure design marks)
`office_code`	string	Office that processed the mark (e.g., `"uspto"`)
`status_stage`	string	Current lifecycle stage (e.g., `"registered"`)

{
  "id": "tm_7d4e1f2a3b8c9d0e",
  "object": "trademark",
  "mark_text": "SIGNA",
  "office_code": "uspto",
  "status_stage": "registered"
}

Summary Tier

The default for list and search endpoints. Enough information to render a useful search result or table row without fetching the full record. 22 fields:

Field	Type	Description
`id`	string	Prefixed trademark ID
`object`	string	Always `"trademark"`
`mark_text`	string \| null	Word mark as filed
`mark_feature_type`	string	Visual form: `word`, `figurative`, `combined`, etc.
`mark_legal_category`	string	Legal type: `standard`, `certification`, `collective`, etc.
`right_kind`	string	IP right category: `trademark`, `trade_name`, `geographical_indication`, etc.
`status`	object	`{ primary, stage, reason, challenges }`
`office_code`	string	Office code (e.g., `"euipo"`)
`jurisdiction_code`	string	Jurisdiction (e.g., `"EU"`)
`scope_kind`	string	`national`, `regional`, or `international_registration`
`filing_route`	string	How filed: `direct_national`, `madrid_ir`, `madrid_designation`, etc.
`application_number`	string \| null	Office application number
`registration_number`	string \| null	Office registration number
`filing_date`	string	ISO date
`registration_date`	string \| null	ISO date
`expiry_date`	string \| null	ISO date
`renewal_due_date`	string \| null	ISO date — the key actionable date
`nice_classes`	integer[]	Nice class numbers (e.g., `[9, 42]`)
`owner_name`	string \| null	Primary owner name
`has_media`	boolean	Whether mark images exist
`updated_at`	string	ISO timestamp of last update

{
  "id": "tm_7d4e1f2a3b8c9d0e",
  "object": "trademark",
  "mark_text": "SIGNA",
  "mark_feature_type": "word",
  "mark_legal_category": "standard",
  "right_kind": "trademark",
  "status": {
    "primary": "active",
    "stage": "registered",
    "reason": null,
    "challenges": []
  },
  "office_code": "uspto",
  "jurisdiction_code": "US",
  "scope_kind": "national",
  "filing_route": "direct_national",
  "application_number": "97123456",
  "registration_number": "6789012",
  "filing_date": "2024-03-15",
  "registration_date": "2025-01-20",
  "expiry_date": "2035-01-20",
  "renewal_due_date": "2035-01-20",
  "nice_classes": [9, 42],
  "owner_name": "Signa Technologies Inc.",
  "has_media": true,
  "updated_at": "2026-03-18T04:00:00Z"
}

Detail Tier

The complete record. Includes everything in the summary tier plus all nested child entities, computed deadlines, and data freshness metadata. Additional fields beyond summary:

Field	Type	Description
`mark_text_language`	string \| null	ISO 639-1 language code
`mark_text_script`	string \| null	ISO 15924 script code
`is_series_mark`	boolean	Whether this is a series mark (AU/NZ/UK/IE)
`series_count`	integer \| null	Number of marks in the series
`status.effective_date`	string \| null	When the current status took effect
`status.source`	string	How status was determined: `explicit`, `event_derived`, `dispatch_derived`, `computed`
`status.raw_code`	string \| null	Office’s original status code
`status.raw_label`	string \| null	Office’s original status text
`source_primary_id`	string	Office’s own identifier
`origin_office_code`	string \| null	Office of origin for Madrid marks
`ir_number`	string \| null	International registration number
`expiry_date_basis`	string	`reported`, `derived`, or `unknown`
`publication_date`	string \| null	Date of official publication
`priority_date`	string \| null	Earliest priority claim date
`termination_date`	string \| null	Date mark was terminated
`protection_effective_date`	string \| null	When protection started (Madrid)
`designation_date`	string \| null	When designation was filed (Madrid)
`dependency_period_end_date`	string \| null	Madrid dependency period end
`transformation_deadline_date`	string \| null	Madrid transformation deadline
`is_retracted`	boolean	Whether the office retracted this record
`owners[]`	array	Full owner objects with ID, name, country, entity type, role
`attorneys[]`	array	Attorney objects with ID, name, firm ID, firm name, role
`classifications[]`	array	Full Nice classification with goods/services text
`design_codes[]`	array	Vienna classification codes
`text_variants[]`	array	Translations and transliterations
`statements[]`	array	Disclaimers and descriptions of mark
`media[]`	array	Mark images with URLs and metadata
`priority_claims[]`	array	Paris Convention priority claims
`filing_bases[]`	array	US filing bases (Section 1(a), 1(b), etc.)
`publications[]`	array	Publication history with opposition windows
`office_extensions`	object	Office-specific data that does not fit the canonical model
`deadlines[]`	array	Computed deadlines with urgency and grace periods
`events_count`	integer	Total number of history events
`proceedings_count`	integer	Total number of proceedings
`coverage_count`	integer	Number of coverage records
`relationships_count`	integer	Number of related marks
`data_freshness`	object	`{ source_data_date, source_format, last_updated_at }`
`created_at`	string	When Signa first ingested this record

Unbounded child entities (events, proceedings) are returned as counts only in the detail tier. Use the sub-resource endpoints (e.g., GET /v1/trademarks/{id}/events) to paginate through the full data.

Code Examples

Fetching a Single Trademark

# Single trademark (returns detail tier)
curl -H "Authorization: Bearer sig_live_xxx" \
  "https://api.signa.so/v1/trademarks/tm_7d4e1f2a"

# List trademarks (returns summary tier)
curl -H "Authorization: Bearer sig_live_xxx" \
  "https://api.signa.so/v1/trademarks?limit=100"

Listing Trademarks (Summary Tier)

List endpoints return summary-tier data, which includes status, dates, owner, Nice classes, and more.

curl -H "Authorization: Bearer sig_live_xxx" \
  "https://api.signa.so/v1/trademarks?owner_id=own_abc123&limit=100"

Search Results (Summary Tier)

Search always returns the summary tier, which provides enough context for displaying results.

curl -X POST \
  -H "Authorization: Bearer sig_live_xxx" \
  -H "Content-Type: application/json" \
  "https://api.signa.so/v1/trademarks/search" \
  -d '{
    "query": "signa",
    "filters": {
      "offices": ["uspto", "euipo"],
      "nice_classes": [9, 42]
    }
  }'

Performance Guidance

Payload Size

The tier you choose directly affects payload size. For a list of 100 trademarks:

Tier	Approx. Payload	Relative Size
Compact	~10 KB	1x
Summary	~50 KB	5x
Detail	~500 KB — 1 MB	50—100x

Best Practices

List endpoints return summary tier

The summary tier is designed to provide everything a typical search result card or table row needs: mark text, status, owner, jurisdiction, dates, and Nice classes. List and search endpoints always return this tier.

Detail tier is for single records and batch

The detail tier includes nested arrays (classifications with full goods/services text, events counts, deadlines, filing bases, media) that increase both payload size and server-side query complexity. It is returned by GET /v1/trademarks/{id} and POST /v1/trademarks/batch.

Combine with ETags for caching

Detail-tier responses include ETags. Use If-None-Match headers to avoid re-transferring unchanged records:

# First request
GET /v1/trademarks/tm_abc
# Response includes: ETag: "v12-1710732000"

# Subsequent request
GET /v1/trademarks/tm_abc
If-None-Match: "v12-1710732000"
# Returns 304 Not Modified if unchanged

Do not call GET /v1/trademarks/{id} in a loop for large lists. Instead, use the list endpoint for summary data, identify the marks you need, and then use the batch endpoint to fetch up to 100 detail records at once.

Getting Started

Core Concepts

How Signa Works

Use Cases

Working with the API

Trust & Compliance

Overview

When to Use Each Tier

Compact Tier

Summary Tier

Detail Tier

Code Examples

Fetching a Single Trademark

Listing Trademarks (Summary Tier)

Search Results (Summary Tier)

Performance Guidance

Payload Size

Best Practices

Getting Started

Core Concepts

How Signa Works

Use Cases

Working with the API

Trust & Compliance

​Overview

​When to Use Each Tier

​Compact Tier

​Summary Tier

​Detail Tier

​Code Examples

​Fetching a Single Trademark

​Listing Trademarks (Summary Tier)

​Search Results (Summary Tier)

​Performance Guidance

​Payload Size

​Best Practices

Overview

When to Use Each Tier

Compact Tier

Summary Tier

Detail Tier

Code Examples

Fetching a Single Trademark

Listing Trademarks (Summary Tier)

Search Results (Summary Tier)

Performance Guidance

Payload Size

Best Practices