Skip to main content

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.

The SDK provides two ways to query trademarks: GET (simple filters via list()) and POST (structured search via search()). Both return a paginated SignaList — see Pagination for consumption patterns. Use search() for text queries with optional filters, strategies, and aggregations: 
const results = await signa.trademarks.search({
  query: 'SIGNA',
  strategies: ['exact', 'phonetic'],
  filters: {
    jurisdictions: ['US', 'EU'],
    nice_classes: [9, 42],
    status_primary: 'active',
  },
});

for (const hit of results.data) {
  console.log(hit.mark_text, hit.score);
}

​
Filter-Only Listing

Use list() when you don’t need text search — just filters and sorting: 
const page = await signa.trademarks.list({
  offices: ['uspto'],
  status_primary: 'active',
  filing_date_gte: '2024-01-01',
  sort: '-filing_date',
  limit: 50,
});

​
Search Strategies

Control how the text query is matched against mark names:
StrategyWhat it doesExample match for “SIGNA”
exactExact token match”SIGNA”
phoneticSounds-like matching”CYGNA”, “SYGNA”
fuzzyEdit-distance tolerance”SIGNAS”, “SINGNA”
prefixPrefix matching”SIGNAGE”, “SIGNATURE”
const results = await signa.trademarks.search({
  query: 'SIGNA',
  strategies: ['exact', 'phonetic', 'fuzzy'],
});
When no strategy is specified, the API uses exact by default. You can combine multiple strategies — results are deduplicated and ranked by relevance.

​
Filters

Both list() and search() support a rich set of filters. With list(), filters are top-level params. With search(), they go inside the filters object.

​
Status

// list() — top-level
await signa.trademarks.list({ status_primary: 'active' });
await signa.trademarks.list({ status_primary: ['active', 'pending'] }); // "live" marks
await signa.trademarks.list({ status_stage: 'registered' });

// search() — inside filters
await signa.trademarks.search({
  query: 'NIKE',
  filters: { status_primary: 'active', status_stage: ['registered', 'published'] },
});
FilterValuesDescription
status_primarypending, active, inactive, unknownCoarse status bucket
status_stagefiled, examined, published, registered, expired, abandoned, cancelledLifecycle stage
status_reasonVarious per officeDetailed reason code
challenge_statesopposition_pending, cancellation_pending, etc.Active challenges

​
Geography

await signa.trademarks.list({ jurisdictions: ['US', 'DE', 'GB'] });
await signa.trademarks.list({ offices: ['euipo', 'wipo'] });
await signa.trademarks.list({ owner_country: 'US' });
FilterDescription
jurisdictionsISO country codes (e.g., US, EU, DE)
officesOffice codes (e.g., uspto, euipo, wipo)
owner_countryOwner’s country of origin

​
Classification

await signa.trademarks.list({ nice_classes: [9, 42] });
await signa.trademarks.list({ vienna_codes: ['03.05', '26.01'] });

​
Mark Type

await signa.trademarks.list({ mark_feature_type: 'word' });
await signa.trademarks.list({ mark_legal_category: ['standard', 'certification'] });
await signa.trademarks.list({ filing_route: 'madrid' });
FilterValues
mark_feature_typeword, figurative, combined, three_dimensional, sound, colour, position, pattern, motion, hologram, other
mark_legal_categorystandard, collective, certification, defensive, well_known
filing_routedirect_national, madrid, eu_direct

​
Date Ranges

All date filters use _gte (inclusive start) and _lt (exclusive end) suffixes. Values are ISO 8601 dates or date-only strings. 
// Trademarks filed in 2024
await signa.trademarks.list({
  filing_date_gte: '2024-01-01',
  filing_date_lt: '2025-01-01',
});

// Expiring within the next 6 months
await signa.trademarks.list({
  expiry_date_gte: '2025-01-01',
  expiry_date_lt: '2025-07-01',
});
Available date fields: filing_date, registration_date, expiry_date, renewal_due_date, publication_date, termination_date, updated_at.

​
Entity Filters

await signa.trademarks.list({ owner_id: 'own_abc123' });
await signa.trademarks.list({ owner_name: 'Apple Inc.' });
await signa.trademarks.list({ attorney_id: 'att_def456' });
await signa.trademarks.list({ firm_id: 'firm_ghi789' });

​
Boolean Flags

await signa.trademarks.list({ has_media: true });
await signa.trademarks.list({ is_madrid: true });
await signa.trademarks.list({ has_proceedings: true });
FlagDescription
has_mediaHas associated images or media files
has_proceedingsHas oppositions or cancellations
is_madridFiled via Madrid Protocol
is_retractedHas been retracted
is_series_markIs part of a series

​
Number Lookups

Look up a specific trademark by its office-issued number: 
await signa.trademarks.list({
  application_number: '97123456',
  office: 'uspto',
});

​
Sorting

Use the sort parameter to control result order. Prefix with - for descending. Multiple fields can be comma-separated. 
// Most recently filed first (default when no text query)
await signa.trademarks.list({ offices: ['uspto'], sort: '-filing_date' });

// By registration date ascending
await signa.trademarks.list({ offices: ['euipo'], sort: 'registration_date' });
When a text query is present and no sort is specified, results are ranked by relevance score.

​
Aggregations

Get faceted counts alongside search results using search(): 
const results = await signa.trademarks.search({
  query: 'APPLE',
  options: {
    aggregations: ['office_code', 'nice_classes', 'status_stage', 'filing_year'],
  },
});

// { office_code: { uspto: 342, euipo: 156, ... } }
console.log(results.aggregations);
Available aggregation fields: status_stage, office_code, jurisdiction_code, nice_classes, filing_year, mark_feature_type, mark_legal_category, filing_route, right_kind, scope_kind.

​
Aggregations Only

To get only facet counts without any trademark results (useful for building filter UIs): 
const facets = await signa.trademarks.search({
  query: 'APPLE',
  options: {
    aggregations: ['office_code', 'nice_classes'],
    aggregations_only: true,
  },
});

console.log(facets.aggregations); // facet counts
console.log(facets.data);         // [] — empty

​
Search Metadata

Search responses include timing and total count information when requested: 
const results = await signa.trademarks.search({
  query: 'NIKE',
  options: { include_total: true, include_timing: true },
});

console.log(results.search_meta);
// { total: 4521, took_ms: 42 }

​
Batch Lookup

Look up multiple trademarks in a single request: 
// By Signa IDs
const result = await signa.trademarks.batch({
  ids: ['tm_abc123', 'tm_def456', 'tm_ghi789'],
});

// By office identifiers
const result = await signa.trademarks.batch({
  identifiers: [
    { application_number: '97123456', office: 'uspto' },
    { application_number: '018765432', office: 'euipo' },
  ],
});

console.log(result.found);    // successfully resolved trademarks
console.log(result.missing);  // IDs/identifiers that didn't match