Quickstart

This guide walks you through two tiers. The first gets you a search result in 5 minutes. The second adds the TypeScript SDK, filters, pagination, and the enriched owner view.

Tier 1: Your first search (5 minutes)

Get an API key

sig_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6

All keys use the format sig_{48 hex chars}. For development or CI, create a separate test organization in the dashboard with its own key so it stays isolated from production usage and billing.

Set your API key as an environment variable

export SIGNA_API_KEY="sig_YOUR_KEY"

// .env
SIGNA_API_KEY=sig_YOUR_KEY

Search for a trademark

Pass q for the query and comma-separated values for array filters.

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

const url = new URL("https://api.signa.so/v1/trademarks");
url.searchParams.set("q", "apple");
url.searchParams.set("offices", "US");

const response = await fetch(url, {
  headers: { "Authorization": `Bearer ${process.env.SIGNA_API_KEY}` },
});

const data = await response.json();
console.log(data);

For complex filter combinations or aggregations, use POST with a JSON body. See Search Trademarks for details.

Inspect the response

Search returns a list: results in data, has_more when there’s another page, and a request_id for support.

{
  "object": "list",
  "data": [
    {
      "id": "tm_a1b2c3",
      "object": "trademark",
      "mark_text": "APPLE",
      "relevance_score": 95,
      "status": {
        "primary": "active",
        "stage": "registered"
      },
      "office_code": "US",
      "filing_date": "1977-04-11",
      "classifications": [
        { "nice_class": 9, "goods_services_text": "Computer hardware; integrated circuits; semiconductors" },
        { "nice_class": 42, "goods_services_text": "Computer software design and development services" }
      ],
      "owners": [
        { "id": "own_d4e5f6", "name": "Apple Inc.", "country_code": "US" }
      ]
    }
  ],
  "aggregations": {},
  "has_more": true,
  "pagination": {
    "cursor": "eyJpZCI6ImFiYyJ9"
  },
  "request_id": "req_xyz789"
}

Switch to POST and add "options": { "aggregations": ["office_code", "status_stage", "nice_classes"] } to the request body to get faceted counts alongside results. This is useful for building filter UIs. Aggregations are POST-only because they don’t fit cleanly in a query string.

Tier 2: SDK, filters, and pagination (15 minutes)

Install the TypeScript SDK

npm install @signa-so/sdk

pnpm add @signa-so/sdk

bun add @signa-so/sdk

Initialize the client:

import { Signa } from "@signa-so/sdk";

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

Search with filters

Narrow results by office, Nice class, status, filing date, and filing route. q is ranked through the default similarity channels: identical, fuzzy, embedded, and lookalike. Pass similarity to choose the channels yourself. identical is always on.

curl -X POST https://api.signa.so/v1/trademarks \
  -H "Authorization: Bearer $SIGNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "nova",
    "similarity": ["identical", "fuzzy", "phonetic"],
    "filters": {
      "offices": ["US", "EM"],
      "nice_classes": [9, 42],
      "status_stage": ["registered"],
      "filing_date": { "gte": "2020-01-01" }
    },
    "options": { "aggregations": ["office_code", "nice_classes"] },
    "limit": 20
  }'

const results = await signa.trademarks.search({
  q: "nova",
  similarity: ["identical", "fuzzy", "phonetic"],
  filters: {
    offices: ["US", "EM"],
    nice_classes: [9, 42],
    status_stage: ["registered"],
    filing_date: { gte: "2020-01-01" },
  },
  options: { aggregations: ["office_code", "nice_classes"] },
  limit: 20,
});

console.log(`Found ${results.data.length} results on this page`);
console.log("Offices:", results.aggregations?.office_code);

The response includes aggregation counts you can use to build filter UIs:

{
  "object": "list",
  "data": [
    {
      "id": "tm_x7y8z9",
      "mark_text": "NOVA",
      "relevance_score": 89,
      "match": { "tier": "identical", "via": ["identical", "fuzzy"], "terms": [] },
      "status": { "primary": "active", "stage": "registered" },
      "office_code": "US",
      "filing_date": "2021-03-15",
      "classifications": [
        { "nice_class": 9, "goods_services_text": "Downloadable mobile applications for data analytics" }
      ],
      "owners": [
        { "id": "own_x7y8z9", "name": "Nova Technologies LLC", "country_code": "US" }
      ]
    }
  ],
  "aggregations": {
    "office_code": { "US": 412, "EM": 189 },
    "nice_classes": { "9": 347, "42": 254 }
  },
  "has_more": true,
  "pagination": { "cursor": "eyJpZCI6Ing3eSJ9" },
  "request_id": "req_abc123"
}

relevance_score (0 to 100) orders the results. It is not a likelihood of confusion. match.tier says how close the hit is (identical, near_identical, similar, or related), and match.via lists the channels that found it.

Similarity channels: identical for the same text after folding case, accents, punctuation, spacing, and trademark notices; fuzzy for spelling edits of one or two letters; embedded for the term inside a longer mark (NIKE in NIKE AIR); phonetic for sound-alikes like “NOVA” / “KNOVA” / “NOWA” (off by default); and lookalike for character substitutions like 0/O or Cyrillic homoglyphs. For a full clearance search, send all five. To filter on the literal text instead of ranking it, use the mark_text_* filters. See Similarity and Text filters.

Handle pagination

Results come in pages. The SDK walks them for you; with plain HTTP, pass pagination.cursor from one response into the next request. See Pagination.

for await (const mark of await signa.trademarks.list({ offices: "US" })) {
  console.log(mark.mark_text, mark.status.stage);
}

Get full trademark details

Retrieve a single trademark by ID to get the full record.

curl https://api.signa.so/v1/trademarks/tm_a1b2c3 \
  -H "Authorization: Bearer $SIGNA_API_KEY"

const mark = await signa.trademarks.retrieve("tm_a1b2c3");

console.log(mark.mark_text);           // "APPLE"
console.log(mark.status.stage);        // "registered"
console.log(mark.owners[0].name);      // "Apple Inc."
console.log(mark.classifications.map(c => c.nice_class)); // [9, 42]
console.log(mark.registration_date);   // "1978-10-31"

{
  "id": "tm_a1b2c3",
  "object": "trademark",
  "mark_text": "APPLE",
  "status": {
    "primary": "active",
    "stage": "registered"
  },
  "office_code": "US",
  "filing_date": "1977-04-11",
  "registration_date": "1978-10-31",
  "classifications": [
    {
      "nice_class": 9,
      "nice_edition": "12",
      "goods_services_text": "Computer hardware; integrated circuits; semiconductors",
      "goods_services_language": "en",
      "status": "accepted",
      "status_raw": { "code": "6", "label": null }
    },
    {
      "nice_class": 42,
      "nice_edition": "12",
      "goods_services_text": "Computer software design and development services",
      "goods_services_language": "en",
      "status": "accepted",
      "status_raw": { "code": "6", "label": null }
    }
  ],
  "owners": [
    { "id": "own_d4e5f6", "name": "Apple Inc.", "country_code": "US", "role": "owner" }
  ],
  "request_id": "req_def456"
}

The detail level varies by endpoint: GET /v1/trademarks/{id} returns the full record, list endpoints return a slimmer shape with the fields most useful for result cards.

Look up an owner

Every trademark detail response includes an owners[] array. Use the owner ID to get the full owner profile, including entity resolution data and filing statistics.

curl https://api.signa.so/v1/owners/own_d4e5f6 \
  -H "Authorization: Bearer $SIGNA_API_KEY"

const owner = await signa.owners.retrieve("own_d4e5f6");

console.log(owner.name);                     // "Apple Inc."
console.log(owner.country_code);             // "US"
console.log(owner.stats?.trademark_count);    // 1847
console.log(owner.stats?.registered_count);   // 1203
console.log(owner.companies?.[0].ticker);      // "AAPL"

{
  "id": "own_d4e5f6",
  "object": "owner",
  "name": "Apple Inc.",
  "canonical_name": "APPLE INC",
  "name_original_script": null,
  "country_code": "US",
  "legal_form": "corporation",
  "aliases": [
    { "name": "Apple Computer Inc.", "type": "former_name", "source_office_code": "US" }
  ],
  "companies": [
    {
      "source": "sec",
      "source_id": "0000320193",
      "legal_name": "Apple Inc.",
      "ticker": "AAPL",
      "exchange": "NASDAQ",
      "lei": null,
      "entity_status": "active"
    }
  ],
  "stats": {
    "trademark_count": 1847,
    "registered_count": 1203,
    "pending_count": 312,
    "jurisdiction_count": 14,
    "grant_rate": 0.65
  },
  "request_id": "req_ghi789"
}

What’s next

Search trademarks

Similarity channels, text filters, exclusions, and aggregations for trademark clearance.

Entity resolution

How Signa normalizes owner names, links corporate parents, and resolves aliases across offices.

Deadline rules

Jurisdiction-aware renewal and declaration deadlines, with every rule listed by GET /v1/deadline-rules.

API Reference

Complete documentation for all endpoints with interactive playground.

Getting started

Core concepts

Build with AI

Data

Monitoring

Working with the API

Use cases

Tier 1: Your first search (5 minutes)

What’s next

Search trademarks

Entity resolution

Deadline rules

API Reference

​Tier 1: Your first search (5 minutes)

​Tier 2: SDK, filters, and pagination (15 minutes)

​What’s next

Search trademarks

Entity resolution

Deadline rules

API Reference

Tier 1: Your first search (5 minutes)

Tier 2: SDK, filters, and pagination (15 minutes)

What’s next