Quickstart - Signa Docs

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=uspto"

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

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 the Search guide for details.

Inspect the response

Search endpoints return a list with data array, has_more for paging, and request_id for debugging.

{
  "object": "list",
  "data": [
    {
      "id": "tm_a1b2c3",
      "object": "trademark",
      "mark_text": "APPLE",
      "relevance_score": 95,
      "status": {
        "primary": "active",
        "stage": "registered"
      },
      "office_code": "uspto",
      "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. By default, exact and fuzzy strategies run simultaneously. You can restrict or expand strategies with the strategies array.

curl -X POST https://api.signa.so/v1/trademarks \
  -H "Authorization: Bearer $SIGNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "nova",
    "strategies": ["exact", "phonetic"],
    "filters": {
      "offices": ["uspto", "euipo"],
      "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({
  query: "nova",
  strategies: ["exact", "phonetic"],
  filters: {
    offices: ["uspto", "euipo"],
    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,
      "status": { "primary": "active", "stage": "registered" },
      "office_code": "uspto",
      "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": { "uspto": 412, "euipo": 189 },
    "nice_classes": { "9": 347, "42": 254 }
  },
  "has_more": true,
  "pagination": { "cursor": "eyJpZCI6Ing3eSJ9" },
  "request_id": "req_abc123"
}

Search strategies: exact for full-text matches, phonetic to catch sound-alikes like “NOVA” / “KNOVA” / “NOWA”, fuzzy for typo tolerance (fuzziness is always AUTO internally), and prefix for starts-with matching. Omit strategies to use the default (exact and fuzzy). For comprehensive clearance searches, use all four: exact,phonetic,fuzzy,prefix.

Handle pagination

Results are cursor-based. Pass the cursor from one response as a query parameter or body field in the next request.

# First page
curl -X POST https://api.signa.so/v1/trademarks \
  -H "Authorization: Bearer $SIGNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "nova", "limit": 20}'

# Next page (use the cursor from the previous response)
curl -X POST https://api.signa.so/v1/trademarks \
  -H "Authorization: Bearer $SIGNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "nova", "limit": 20, "cursor": "eyJpZCI6Ing3eSJ9"}'

// Automatic pagination with async iterator (list endpoint)
const marks = await signa.trademarks.list({ offices: 'uspto' });
for await (const mark of marks) {
  console.log(mark.mark_text, mark.status.stage);
}

// Manual page-based pagination (list endpoint)
let page = await signa.trademarks.list({ offices: 'uspto', limit: 100 });
const allMarks = [...page.data];

while (page.has_more) {
  page = await page.getNextPage();
  allMarks.push(...page.data);
}

console.log(`Total: ${allMarks.length}`);

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": "uspto",
  "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",
      "class_status_raw": "6"
    },
    {
      "nice_class": 42,
      "nice_edition": "12",
      "goods_services_text": "Computer software design and development services",
      "goods_services_language": "en",
      "status": "accepted",
      "class_status_raw": "6"
    }
  ],
  "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, and suggest endpoints return a minimal shape for autocomplete.

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",
  "entity_type": "corporation",
  "aliases": [
    { "name": "Apple Computer Inc.", "type": "former_name", "source_office": "uspto" }
  ],
  "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 guide

Phonetic matching, fuzzy search, aggregations, and filtering strategies 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 rules for 21 jurisdictions.

API Reference

Complete documentation for all endpoints with interactive playground.

​Tier 1: Your first search (5 minutes)

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

​What’s next

Search guide

Entity resolution

Deadline rules

API Reference

Tier 1: Your first search (5 minutes)

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

What’s next