> ## 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. # Screen a Name > Run a fast, deterministic knockout screen for one candidate name (beta) **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 ```bash theme={null} 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. | | `offices` | string\[] | Registering office codes such as `uspto` and `euipo`. 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. ```bash theme={null} 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. | | `clear` | No high- or medium-band conflict exists. Clear does not mean registrable. | 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. ## Response ```json theme={null} { "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"], "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`. ## SDK ```typescript theme={null} 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); } ```