Screen a Name

Run a fast, deterministic knockout screen for one candidate name (beta)

GET /v1/screening

Screen a Name

cURL

curl --request GET \
  --url https://api.signa.so/v1/screening \
  --header 'Authorization: Bearer <token>'

Beta. Requires the screening:read scope — granted to design partners during beta. This endpoint provides a risk signal, not legal advice.

Overview

GET /v1/screening answers “could this candidate name conflict with an existing mark?” Send a name and, optionally, its intended Nice classes or goods/services. Screening searches live register coverage, assigns each surfaced conflict a coarse band, and derives one request-level verdict.

The endpoint is synchronous, deterministic within its rules and corpus versions, and text-only. It never returns a numeric similarity score. A clear verdict means that no high- or medium-band conflict was found; it does not mean that the mark is registrable.

Each request is billed at 10 units.

Request

curl --get https://api.signa.so/v1/screening \
  --header "Authorization: Bearer $SIGNA_API_KEY" \
  --data-urlencode "q=KOFEE" \
  --data-urlencode "nice_classes=30,43" \
  --data-urlencode "jurisdictions=US,EU" \
  --data-urlencode "sensitivity=standard"

Parameter	Type	Notes
q	string	Candidate mark text; 2–200 non-whitespace characters. Exactly one of q or trademark_id is required.
trademark_id	string	Existing register record (tm_...) to use as the candidate. Exactly one of q or trademark_id is required.
nice_classes	number[]	Intended Nice classes, 1–45. Sent as a comma-separated list. Acts as a hard class filter.
goods_services	string	Free-text intended goods/services, up to 2,000 characters. Used for class inference when classes are omitted and for goods/services matching when supported by the active resolver.
jurisdictions	string[]	Territory codes such as US and EU. Default: all live-coverage jurisdictions. Screening always applies protection-scope expansion, and unlike Search Trademarks there is no territory_match opt-out: a request for a country pulls in EU-wide rights that protect there (a EUTM can block a French launch), and a request for a region (EU) pulls in both the regional register and every member state’s national register (a French national mark can block an EU launch). Screening always errs toward inclusion.
offices	string[]	Registering office codes, uppercase ST.3, such as US and EM. Default: all live offices.
include	live | all	live by default; all also includes dead marks.
sensitivity	strict | standard | broad	Match-tier admission threshold. strict admits exact/normalized matches; standard adds close fuzzy and strong phonetic matches; broad adds weaker fuzzy matches.
limit	number	Page size from 1–50. Default: 20.

Array query parameters use comma-separated values, without brackets.

Screen an existing mark

Use trademark_id instead of q for register-to-register discovery. Screening uses the record’s mark text and, when you omit both nice_classes and goods_services, its own Nice classes as the intended-use profile. The candidate’s collapsed family is removed before conflicts are banded, so it cannot appear as its own result.

curl --get https://api.signa.so/v1/screening \
  --header "Authorization: Bearer $SIGNA_API_KEY" \
  --data-urlencode "trademark_id=tm_0190f2d5-8e4b-7c1a-a8d3-123456789abc"

The response echoes the source in screening.candidate.trademark_id. Unknown records return 404 not_found; records without textual mark content, such as design-only marks, return 422 not_screenable.

Bands and verdicts

Every item in data[] is a screening_hit with one closed risk band:

Band	Meaning
high	Strongest combination of name match, goods/services overlap, and live status.
medium	A meaningful conflict signal that needs review.
low	A surfaced but lower-priority signal, including admitted dead-mark results.

The leading screening.verdict summarizes the full banded result set, not only the returned page:

Verdict	Rule
high_risk	At least one high-band conflict exists.
caution	No high-band conflict exists, but at least one medium-band conflict exists.
needs_review	No high- or medium-band conflict was found, but the screen could not be completed to the standard required to say clear. The usual cause is incomplete register coverage for a requested territory; a stale office corpus, a capped analysis horizon, a failed analysis lane, an unsupported language, low-confidence class inference, or a coverage assessment that could not be read at all produce it too. When a coverage assessment is present, the coverage block carries the details; it can be absent when the assessment itself failed.
clear	No high- or medium-band conflict exists and every requested territory’s register is covered live in Signa. Clear does not mean registrable.

Found conflicts always band high or medium regardless of coverage: observed risk is never suppressed. The coverage gate only ever downgrades a would-be clear, it never upgrades a genuine conflict. Treat needs_review as “we could not rule this out”, not as a weaker clear.

Hits also explain the coarse classification through reason_codes, mark_match, goods_services_match, jurisdiction_match, and a separate litigation_risk block. Reason codes and warnings are extensible; clients should tolerate values they do not yet recognize.

Coverage

A clearance verdict for a territory is only as trustworthy as the registers Signa can actually see there. If the national register that protects a requested territory is not connected live (for example a request scoped to DE when the German national register is dark), national-only marks in that territory are invisible, so a zero-conflict screen must not read as clear. The screening.coverage block reports exactly which registers gated the verdict.

"coverage": {
  "offices": [
    { "office": "US", "status": "complete", "as_of": "2026-07-20T00:00:00Z" },
    { "office": "EM", "status": "complete", "as_of": "2026-07-20T00:00:00Z" }
  ],
  "territories": [
    {
      "territory": "DE",
      "national_register": { "office": "DE", "covered": false },
      "regional_registers": [{ "code": "EU", "covered": true }],
      "complete": false
    }
  ],
  "complete_for_clear": false
}

This example is abridged to the coverage-gate axes. The served coverage object also always includes classes, lanes, language, and horizon, the other completeness inputs that can hold a verdict at needs_review.

• offices is the register-freshness axis. Each entry is a public office code in WIPO ST.3 form (US, EM for the EUIPO), with a status (complete / partial / stale / unavailable) and an as_of corpus watermark. It lists the offices that gated this verdict: the requested offices when offices was supplied, the national plus regional and member registers when jurisdictions was supplied, or every live office when the request is unscoped.
• territories is the protection-scope axis, present when jurisdictions was supplied. Codes here are jurisdiction codes (DE, EU), not ST.3 office codes. For each requested territory it reports its own national_register, the regional_registers that also protect there (a country belonging to EU shows an EU entry), and whether the whole set is complete.
• For a regional request (jurisdictions=EU) a territory entry adds member_registers: { total, uncovered[] }, summarizing how many member-state national registers are dark; regional_registers is still present but empty (the region is its own register). An EU screen stays needs_review while member registers are uncovered, and flips to clear only once they are live and fresh, the same principle as the DE example.
• complete_for_clear is the single boolean the verdict gate reads. When it is false, a would-be clear is downgraded to needs_review and screening.note names the dark register. coverage is present on every screened response. When the coverage assessment itself cannot be completed, the block fails closed with complete_for_clear: false and an empty offices, which signals that coverage could not be verified and forces the verdict to needs_review.

Response

{
  "object": "list",
  "screening": {
    "verdict": "high_risk",
    "summary": { "high": 1, "medium": 0, "low": 0, "truncated": false },
    "litigation_risk": { "high": 0, "medium": 0 },
    "candidate": { "mark": "KOFEE", "normalized": "kofee" },
    "rules_version": "screening-v1",
    "as_of": "2026-07-13T00:00:00.000Z",
    "admitted_match_levels": ["exact", "normalized", "fuzzy_1", "phonetic_strong"],
    "coverage": {
      "offices": [{ "office": "US", "status": "complete", "as_of": "2026-07-20T00:00:00Z" }],
      "territories": [
        { "territory": "US", "national_register": { "office": "US", "covered": true }, "regional_registers": [], "complete": true }
      ],
      "complete_for_clear": true
    },
    "warnings": []
  },
  "data": [
    {
      "object": "screening_hit",
      "risk_level": "high",
      "reason_codes": ["exact_mark", "same_nice_class", "live_status"],
      "mark_match": { "level": "identical", "admitted_match_levels": ["exact"] },
      "goods_services_match": { "level": "same_class", "matched_nice_classes": [30] },
      "jurisdiction_match": { "requested": ["US", "EU"], "matched": ["US"] },
      "litigation_risk": {
        "level": "unknown",
        "owner_publicly_traded": null,
        "owner_ticker": null,
        "prior_proceedings": null,
        "owner_portfolio_size": null
      },
      "trademark": { "id": "tm_…", "object": "trademark", "mark_text": "KOFEE" }
    }
  ],
  "has_more": false,
  "pagination": { "cursor": null },
  "request_id": "req_…"
}

screening.rules_version and screening.as_of identify the rules and corpus freshness behind the result. screening.inferred_nice_classes appears only when class inference ran (i.e. nice_classes was omitted from the request).

Warnings and limitations

• warnings is an open set. Handle known values and safely display or log new values rather than rejecting the response.
• A missing goods/services description may produce no_goods_services; the result then has less context for class and goods/services matching.
• summary.truncated: true means the analysis horizon was capped. It is separate from has_more, which describes response pagination.
• Screening v1 is text-only. It does not compare logos, designs, Vienna codes, or images.
• Backend failures return an error rather than a partial or false clear.
• Screening responses are served Cache-Control: private, no-store. A screening result reflects live register coverage at request time, so it is not safe to cache client-side, re-run the screen rather than replaying a stored response.

SDK

const result = await signa.screening.screen({
  q: "KOFEE",
  nice_classes: [30, 43],
  jurisdictions: ["US", "EU"],
  sensitivity: "standard",
});

console.log(result.screening.verdict);
for (const hit of result.data) {
  console.log(hit.trademark.mark_text, hit.risk_level);
}