Search Trademarks

The canonical endpoint for discovering trademarks. Pass a text query to search by brand name with relevance ranking, or use filters to browse by office, status, class, date, and more. Every request must include at least one filter or a text query (q).

Query Parameters

string

Search query text (1-500 characters). When provided, results are ranked by relevance using multi-strategy matching (exact + fuzzy by default). Optional — omit for filter-only browsing.

strategies

string

default:"exact,fuzzy"

Search strategies to apply when q is provided, comma-separated. Any combination of exact, fuzzy, phonetic, prefix. Defaults to exact,fuzzy for fast results. Use exact,phonetic,fuzzy,prefix for comprehensive trademark clearance searches.

limit

integer

default:"20"

Results per page (1-100).

cursor

string

Opaque pagination cursor from a previous response.

include_total

boolean

default:"false"

When true, includes an accurate total count in pagination.total_count.

highlights

boolean

default:"false"

When true, includes highlight snippets for mark_text and owner_names fields.

Filters

All filter parameters are accepted at the top level of the query string. Arrays use comma-separated values. Date ranges use _gte and _lt suffixes.

offices

string

Office codes, comma-separated (e.g. ?offices=uspto,euipo).

jurisdictions

string

ISO jurisdiction codes, comma-separated (e.g. ?jurisdictions=US,EU).

nice_classes

string

Nice classification numbers 1-45, comma-separated (e.g. ?nice_classes=9,42).

status_primary

string

Primary status: active, pending, inactive, unknown. Comma-separated for multiple.

status_stage

string

Status stage, comma-separated (e.g. registered, published, examining).

mark_feature_type

string

Mark type: word, figurative, combined, three_dimensional.

filing_route

string

Filing route: direct_national, madrid_designation, direct_regional.

owner_id

string

Owner ID (own_...).

owner_name

string

Owner name substring match.

attorney_id

string

Attorney ID (att_...).

firm_id

string

Firm ID (firm_...).

filing_date_gte

string

Filing date lower bound (YYYY-MM-DD).

filing_date_lt

string

Filing date upper bound (exclusive).

registration_date_gte

string

Registration date lower bound.

registration_date_lt

string

Registration date upper bound.

expiry_date_gte

string

Expiry date lower bound.

expiry_date_lt

string

Expiry date upper bound.

has_media

boolean

true to require at least one image.

is_madrid

boolean

true to restrict to Madrid Protocol filings.

Show More filters

Parameter	Type	Description
`office`	string	Single office code shortcut
`vienna_codes`	string	Vienna figurative codes, comma-separated
`status_reason`	string	Status reason codes, comma-separated
`challenge_states`	string	Active challenge states, comma-separated
`mark_legal_category`	string	`standard`, `certification`, `collective`
`right_kind`	string	Right kind (e.g. `trademark`)
`scope_kind`	string	Territorial scope kind, comma-separated
`owner_country`	string	Two-letter owner country code
`goods_services_text`	string	Free-text search in G&S descriptions
`application_number`	string	Exact application number (requires `office`)
`registration_number`	string	Exact registration number (requires `office`)
`ir_number`	string	Madrid International Registration number
`origin_office_code`	string	Origin office code for Madrid filings
`renewal_due_date_gte`	string	Renewal due date lower bound
`renewal_due_date_lt`	string	Renewal due date upper bound
`publication_date_gte`	string	Publication date lower bound
`publication_date_lt`	string	Publication date upper bound
`termination_date_gte`	string	Termination date lower bound
`termination_date_lt`	string	Termination date upper bound
`updated_at_gte`	string	Record updated-at lower bound. Accepts `YYYY-MM-DD` (coerced to start of day UTC) or full ISO 8601 datetime (e.g. `2024-01-15T00:00:00Z`).
`updated_at_lt`	string	Record updated-at upper bound. Accepts `YYYY-MM-DD` or full ISO 8601 datetime.
`has_proceedings`	boolean	`true` to require at least one proceeding
`is_retracted`	boolean	`true` to restrict to retracted marks
`is_series_mark`	boolean	`true` to restrict to series marks
`renewal_due_before`	string	Alias for `renewal_due_date_lt`

Examples

curl -G "https://api.signa.so/v1/trademarks" \
  -H "Authorization: Bearer $SIGNA_API_KEY" \
  --data-urlencode "q=nike" \
  --data-urlencode "offices=uspto"

Response

{
  "object": "list",
  "data": [
    {
      "id": "tm_abc123",
      "object": "trademark",
      "mark_text": "NIKE",
      "relevance_score": 95,
      "match_explanation": {
        "strategies_matched": ["exact"],
        "boost_factors": [
          { "factor": "status_active", "weight": 1.2 }
        ]
      },
      "primary_image_url": null,
      "status": { "primary": "active", "stage": "registered" },
      "office_code": "uspto",
      "jurisdiction_code": "US",
      "filing_date": "1971-02-04",
      "registration_date": "1974-04-16",
      "classifications": [
        { "nice_class": 25, "goods_services_text": "Clothing, footwear, headgear" }
      ],
      "owner_name": "Nike, Inc."
    }
  ],
  "has_more": true,
  "pagination": {
    "cursor": "eyJpZCI6ImFiYyJ9",
    "total_count": 142,
    "total_count_approximate": false
  },
  "search_meta": {
    "search_id": "srch_abc123",
    "query": "nike",
    "strategies_used": ["exact", "fuzzy"],
    "total_results": 142,
    "total_count_exact": true,
    "total_count_approximate": false,
    "execution_time_ms": 15
  },
  "aggregations": {},
  "request_id": "req_xyz789"
}

data

object[]

Trademark summary records — the slimmer list shape with the fields most useful for result cards. See Get Trademark for the full record shape returned by single-record lookups.

has_more

boolean

Whether more results are available.

pagination.cursor

string

Pass this as ?cursor= to get the next page.

pagination.total_count

integer

Total matches. Only present when include_total=true. Canonical location — read this field across every list endpoint.

pagination.total_count_approximate

boolean

Emitted alongside total_count. false when the count is exact; true when OpenSearch capped the count at 10,000 for a deep search.

search_meta

object

Query metadata: search_id, query, strategies_used, execution_time_ms.

Show search_meta fields

search_meta.search_id

string

Unique search identifier.

search_meta.query

string | null

The query text used.

search_meta.strategies_used

string[]

Search strategies that were applied.

search_meta.total_results

integer

deprecated

Deprecated — use pagination.total_count instead. Will be removed in v1.1. Total matching results (same as pagination.total_count when include_total is true).

search_meta.total_count_exact

boolean

deprecated

Deprecated — use pagination.total_count_approximate (inverse of this flag) instead. Will be removed in v1.1. Whether the total count is exact.

search_meta.total_count_approximate

boolean

deprecated

Deprecated — use pagination.total_count_approximate instead. Will be removed in v1.1. Whether the total count is approximate.

search_meta.execution_time_ms

integer

Query execution time in milliseconds.

aggregations

object

Empty object {} on GET requests. Populated with faceted counts on POST when options.aggregations is provided.

relevance_score

number | null

Normalized relevance score. Present when q is provided, null for filter-only queries or when sort is specified.

match_explanation

object | undefined

Explains relevance scoring. Omitted when sort is specified.

Show match_explanation fields

match_explanation.strategies_matched

string[]

Array of strategy names that matched (e.g. ["exact", "fuzzy"]).

match_explanation.boost_factors

object[]

Array of {factor, weight} objects describing score adjustments.

primary_image_url

string | null

URL to the primary trademark image. Format: https://api.signa.so/v1/trademarks/{id}/media/{media_id}. Only present when has_media is true, null otherwise.

Sort

By default, results are ranked by relevance when q is provided. For filter-only queries (no q), results are returned in index order (fast, unordered). To explicitly sort results, use the sort parameter:

?sort=-filing_date          # newest filings first
?sort=expiry_date           # earliest expiry first
?sort=-filing_date,office_code  # multi-field (max 3)

Available sort fields: filing_date, registration_date, expiry_date, renewal_due_date, updated_at, publication_date, termination_date, office_code, jurisdiction_code.

When sort is specified alongside q, relevance scoring is bypassed — results are ordered purely by the sort field(s) and relevance_score will be null.

Errors

Status	Type	When
400	`validation_error`	No filter or query supplied, invalid date range, unknown sort field
401	`unauthorized`	Missing or invalid API key
429	`rate_limited`	Rate limit exceeded (details)

Advanced: POST with JSON body

For complex queries with aggregations or long filter lists, use POST /v1/trademarks with a JSON body. This accepts the same filters and returns the same response shape.

The Idempotency-Key header is recommended for POST requests (for safe retries and caching) but not required. GET does not need one.

POST-only features

options.aggregations — an array of field names to aggregate. Returns faceted counts for building filter UIs. Valid values: status_stage, office_code, jurisdiction_code, nice_classes, filing_year, mark_feature_type, mark_legal_category, filing_route, right_kind, scope_kind.
options.aggregations_only — return only counts, skip result documents

POST example

cURL

curl -X POST "https://api.signa.so/v1/trademarks" \
  -H "Authorization: Bearer $SIGNA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-search-1" \
  -d '{
    "query": "nova",
    "strategies": ["exact", "phonetic", "fuzzy", "prefix"],
    "filters": {
      "offices": ["uspto", "euipo"],
      "nice_classes": [9, 42],
      "status_stage": ["registered"],
      "filing_date": { "gte": "2020-01-01" }
    },
    "options": {
      "aggregations": ["office_code", "nice_classes", "status_stage"]
    },
    "limit": 20
  }'

Show Full POST body reference

Field	Type	Description
`query`	string	Search query text (1-500 chars). Optional.
`sort`	string	Sort field(s), same as GET `sort` parameter.
`strategies`	string[]	Search strategies. Default: `["exact", "fuzzy"]`.
`filters`	object	Same filters as GET, nested in an object. Arrays use JSON arrays, dates use `{"gte": "...", "lt": "..."}`.
`options.aggregations`	string[]	Faceted counts: `status_stage`, `office_code`, `jurisdiction_code`, `nice_classes`, `filing_year`, `mark_feature_type`, `mark_legal_category`, `filing_route`, `right_kind`, `scope_kind`.
`options.aggregations_only`	boolean	Return only counts, no documents. Default: `false`.
`options.include_total`	boolean	Include accurate total count. Default: `false`.
`options.highlights`	boolean	Include highlight snippets. Default: `false`.
`limit`	integer	Results per page (0-100). Default: `20`.
`cursor`	string	Pagination cursor from previous response.

Suggest Trademarks — typeahead autocomplete
Get Trademark — full detail for a single mark
Batch Get Trademarks — hydrate known IDs

Overview

Trademarks

Parties

Monitoring

Reference

Administration

Operational

Query Parameters

Filters

Examples

Response

Sort

Errors

Advanced: POST with JSON body

POST-only features

POST example

Overview

Trademarks

Parties

Monitoring

Reference

Administration

Operational

Documentation Index

​Query Parameters

​Filters

​Examples

​Response

​Sort

​Errors

​Advanced: POST with JSON body

​POST-only features

​POST example

​Related

Query Parameters

Filters

Examples

Response

Sort

Errors

Advanced: POST with JSON body

POST-only features

POST example

Related