Skip to main content
This guide walks you through three tiers. The first gets you a search result in 5 minutes. The second adds the TypeScript SDK, filters, and pagination. The third sets up portfolio monitoring with watches.

​
Tier 1: Your first search (5 minutes)

1

Get an API key

Sign up at app.signa.so and create an API key from the dashboard. Your key will look like this:
sig_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6
Test keys (sig_test_*) use sandbox data and have relaxed rate limits. Use them during development and switch to sig_live_* for production.
2

Set your API key as an environment variable

export SIGNA_API_KEY="sig_live_YOUR_KEY"
3

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"
For complex filter combinations or aggregations, use POST with a JSON body. See the Search guide for details.
4

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",
      "nice_classes": [9, 42],
      "owner_name": "Apple Inc."
    }
  ],
  "aggregations": {},
  "has_more": true,
  "pagination": {
    "cursor": "eyJpZCI6ImFiYyJ9"
  },
  "livemode": true,
  "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)

1

Install the TypeScript SDK

npm install @signa-so/sdk
Initialize the client:
import { Signa } from "@signa-so/sdk";

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

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. For comprehensive clearance searches, use all four: exact,phonetic,fuzzy,prefix.
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
  }'
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",
      "nice_classes": [9],
      "owner_name": "Nova Technologies LLC"
    }
  ],
  "aggregations": {
    "office_code": { "uspto": 412, "euipo": 189 },
    "nice_classes": { "9": 347, "42": 254 }
  },
  "has_more": true,
  "pagination": { "cursor": "eyJpZCI6Ing3eSJ9" },
  "livemode": true,
  "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.
3

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"}'
4

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"

{
  "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",
  "nice_classes": [9, 42],
  "owners": [
    { "id": "own_d4e5f6", "name": "Apple Inc.", "country_code": "US", "role": "owner" }
  ],
  "livemode": true,
  "request_id": "req_def456"
}
The detail level varies by endpoint: GET /v1/trademarks/{id} returns the full detail record, list endpoints return summary-level data, and suggest endpoints return compact data. See Response Tiers for field breakdowns.
5

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"

{
  "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" }
  ],
  "public_companies": [
    {
      "source": "sec",
      "source_id": "320193",
      "legal_name": "Apple Inc.",
      "ticker": "AAPL",
      "exchange": "NASDAQ",
      "entity_status": "active"
    }
  ],
  "stats": {
    "trademark_count": 1847,
    "registered_count": 1203,
    "pending_count": 312,
    "jurisdiction_count": 14,
    "registration_rate": 0.65,
    "top_classes": [{ "class": 9, "count": 458 }, { "class": 42, "count": 312 }, { "class": 35, "count": 189 }]
  },
  "livemode": true,
  "request_id": "req_ghi789"
}

​
Tier 3: Portfolio monitoring with watches (30 minutes)

1

Create a portfolio

Portfolios group trademarks for bulk monitoring and deadline tracking.
curl -X POST https://api.signa.so/v1/portfolios \
  -H "Authorization: Bearer $SIGNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Core Brand", "description": "Primary brand trademarks across all jurisdictions"}'

{
  "id": "ptf_n1o2p3",
  "object": "portfolio",
  "name": "Core Brand",
  "description": "Primary brand trademarks across all jurisdictions",
  "mark_count": 0,
  "created_at": "2026-03-24T12:00:00Z",
  "updated_at": "2026-03-24T12:00:00Z",
  "livemode": true,
  "request_id": "req_jkl012"
}
2

Add trademarks to the portfolio

Add trademarks by their IDs. You can add up to 100 trademarks in a single request.
curl -X POST https://api.signa.so/v1/portfolios/ptf_n1o2p3/trademarks \
  -H "Authorization: Bearer $SIGNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trademark_ids": ["tm_a1b2c3", "tm_x7y8z9", "tm_q4r5s6"]}'
To build a portfolio programmatically, search for your brand name, filter the results, and add matching trademark IDs in bulk.
3

Create a watch

Watches monitor for changes and generate alerts. Set up a watch with specific criteria and triggers.
curl -X POST https://api.signa.so/v1/watches \
  -H "Authorization: Bearer $SIGNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Core Brand Monitor",
    "watch_type": "competitor",
    "criteria": {
      "owner_name": "Your Company Inc."
    },
    "triggers": ["new_filing", "status_change", "any_change"],
    "scope_filters": {
      "offices": ["uspto", "euipo", "wipo"]
    },
    "delivery_channels": ["api"]
  }'
Available triggers:
TriggerFires when
new_filingA new trademark matching your criteria is published by an office
status_changeA watched mark moves to a new status stage (e.g., published, registered, abandoned)
any_changeAny field change on a matched mark (owner transfer, classification amendment, etc.)
4

Poll for alerts

Use the List Alerts endpoint to retrieve alerts generated by your watches. Poll periodically or on demand.
# List unacknowledged alerts
curl "https://api.signa.so/v1/alerts?watch_id=wat_v1w2x3&status=unacknowledged" \
  -H "Authorization: Bearer $SIGNA_API_KEY"
Example alert payload:
{
  "object": "list",
  "data": [
    {
      "id": "alt_Qn6sU0vW",
      "object": "alert",
      "watch_id": "wat_v1w2x3",
      "trademark_id": "tm_Yt9wX3zA",
      "event_type": "trademark.status_changed",
      "severity": "high",
      "status": "unacknowledged",
      "match_details": {},
      "summary": {
        "mark_text": "YOUR COMPANY TECH",
        "office_code": "uspto",
        "status_stage": "published"
      },
      "acknowledged_at": null,
      "acknowledged_by": null,
      "dismissed_at": null,
      "created_at": "2026-03-22T08:15:00Z"
    }
  ],
  "has_more": false,
  "pagination": {
    "cursor": null
  },
  "livemode": true,
  "request_id": "req_nG3xY9zA"
}
Webhooks and real-time alerts are planned for a future release. Use Trademark History to check for changes on specific marks.

​
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.