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

# Search Citations

> Query examiner refusal citations across all marks by office, disposition, stage, and date

## When To Use This

Use this endpoint when the question spans marks rather than sitting on one record. Each row is one citation occurrence: one prior mark an examiner cited against one application in one office action. The corpus is a record of which marks an office has actually treated as a bar to registration, and what happened next.

Typical uses: pull every §2(d) citation an office issued in a date window, find every application a specific registration has been cited against, or resolve an office-printed registration number to the mark behind it.

For one mark at a time, use [Trademark Citations](/api-reference/trademarks/trademark-citations) and [Trademark Cited By](/api-reference/trademarks/trademark-cited-by).

<Note>
  **Coverage today is USPTO only.** Citations are extracted from USPTO office actions and cover §2(d) likelihood-of-confusion refusals. Requests filtered to any other office return an empty list, including offices whose examiners never cite prior marks at all. Check `capabilities.citations` on [List Offices](/api-reference/reference/list-offices) to see the state of any office programmatically, rather than inferring coverage from an empty response.
</Note>

## Freshness

Citations are extracted hourly from stored office actions. Dispositions are recomputed once a day, so a newly extracted citation carries `disposition: null` until the next daily refresh, which can be up to about 24 hours. A disposition can also change on a later run as prosecution continues. `disposition_as_of` is stamped when the current disposition was first derived or last changed, and deliberately does not move when a daily run re-derives the same value. An unchanged timestamp means the disposition has been stable, not that the refresh stopped running.

## Office Coverage And `capabilities.citations`

[List Offices](/api-reference/reference/list-offices) and [Retrieve Office](/api-reference/reference/retrieve-office) carry `capabilities.citations`, which is the programmatic answer to "should I expect anything here?".

| Value            | Meaning                                                                                                                                                                             |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `available`      | Live pipeline. Citations are being served for this office today.                                                                                                                    |
| `in_progress`    | A pipeline build is underway. Data is not complete yet.                                                                                                                             |
| `not_available`  | Signa serves no citations for this office. Either the office refuses on relative grounds and there is no pipeline yet, or its regime has not been classified. A gap that may close. |
| `not_applicable` | The office does not refuse on relative grounds ex officio, so it never issues a citation-bearing refusal at all.                                                                    |

`not_applicable` covers the opposition-only registries, where earlier-rights conflicts are left to third parties rather than raised by the examiner. Of the offices live today, the EUIPO (`EM`), INPI France (`FR`) and the Swiss IPI (`CH`) all work this way. WIPO (`WO`) is `not_applicable` for a narrower reason: the International Bureau does formalities only and never examines the mark, so substantive refusals come from the designated national offices under their own codes. An empty citation list for these offices is not a coverage gap, and it will not become non-empty.

## Query Parameters

All filters are optional and combine with AND. An unfiltered request is allowed and returns the newest citations across the corpus.

<ParamField query="office" type="string">
  Filter by issuing office, comma-separated (e.g. `US` or `US,EM`). Values are uppercase ST.3 office codes; legacy lowercase codes (e.g. `uspto`, and `eu` for EUIPO) are accepted as permanent aliases, and the two forms can be mixed in one list. Up to 100 values. An unrecognized code returns `200` with an empty list rather than an error, so polling for a not-yet-covered office is safe.
</ParamField>

<ParamField query="disposition" type="string">
  Filter by how the citation resolved, comma-separated. One or more of `citation_issued`, `maintained`, `withdrawn`, `abandoned_after`, `published`. Rows whose disposition has not been computed yet are excluded when this filter is supplied.
</ParamField>

<ParamField query="action_stage" type="string">
  Filter by the stage the citation reached, comma-separated. One or both of `nonfinal`, `final`. `final` includes citations first raised in a nonfinal action that a later final action maintained.
</ParamField>

<ParamField query="refusal_type" type="string">
  Filter by refusal ground, comma-separated. `2d` is the only value today, the USPTO §2(d) likelihood-of-confusion ground. This vocabulary is office-scoped rather than canonical across offices.
</ParamField>

<ParamField query="trademark_id" type="string">
  Restrict to citations issued against one citing application (`tm_...`).
</ParamField>

<ParamField query="cited_trademark_id" type="string">
  Restrict to citations naming one prior mark (`tm_...`). This matches on the resolved link and additionally on that mark's own application and registration numbers for unlinked citations from the same office, the same predicate [Trademark Cited By](/api-reference/trademarks/trademark-cited-by) uses, so the two views return the same rows.
</ParamField>

<ParamField query="cited_ref" type="string">
  Exact cited reference, as an application or registration number. Punctuation is ignored, digits are matched. **Requires `office`**: references are only unique within an office, so an office-less lookup is rejected with `400`. Use this to go from a number an examiner printed to the citations that name it, including citations Signa has not linked to a record.
</ParamField>

<ParamField query="action_date_gte" type="string">
  Office action date >= (`YYYY-MM-DD`).
</ParamField>

<ParamField query="action_date_lte" type="string">
  Office action date \<= (`YYYY-MM-DD`).
</ParamField>

<ParamField query="sort" type="string" default="-action_date">
  `-action_date` for newest first, `action_date` for oldest first. No other sort fields. Sort is bound into the pagination cursor, so it cannot be changed mid-walk.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Page size (1-100).
</ParamField>

<ParamField query="cursor" type="string">
  Opaque cursor from the previous response's `pagination.cursor`.
</ParamField>

Undated actions sort last in both directions, with `id` as the final tiebreaker.

## Response

<ResponseField name="object" type="string">Always `list`.</ResponseField>

<ResponseField name="data" type="object[]">
  <Expandable title="Citation object">
    <ResponseField name="id" type="string">Citation ID (`cit_...`).</ResponseField>
    <ResponseField name="object" type="string">Always `citation`.</ResponseField>
    <ResponseField name="office_code" type="string | null">Office that issued the action, uppercase ST.3 (e.g. `US`).</ResponseField>
    <ResponseField name="application_ref" type="string">Application number the office action was issued against, as printed by the office.</ResponseField>
    <ResponseField name="trademark" type="object | null">Summary of the citing application (`id`, `mark_text`, `office_code`, `application_number`, `registration_number`, `status_primary`). `null` when the citation carries no persisted link to a Signa record for that application, which is not the same as the application being absent from the register: resolution runs once, at extraction time.</ResponseField>
    <ResponseField name="cited_ref" type="string">The prior mark reference the examiner cited.</ResponseField>
    <ResponseField name="cited_ref_type" type="string">Whether `cited_ref` is a `registration` or an `application` number.</ResponseField>
    <ResponseField name="cited_trademark" type="object | null">Summary of the cited prior mark, same fields as `trademark`. `null` means the citation is matched by reference only, with `cited_ref` as the sole identifier.</ResponseField>
    <ResponseField name="refusal_type" type="string">Office-local refusal ground. `2d` is the USPTO §2(d) likelihood-of-confusion ground.</ResponseField>
    <ResponseField name="action_date" type="string | null">ISO date of the office action (`YYYY-MM-DD`).</ResponseField>
    <ResponseField name="action_stage" type="string | null">`nonfinal` or `final`. This is the stage the citation reached, not provenance about `source_document_id`. A citation first raised in a nonfinal action reads `final` once a later dated final action maintained the refusal, so `final` does not mean the row was extracted from a final action.</ResponseField>
    <ResponseField name="disposition" type="string | null">How the citation resolved. See the table below. `null` while pending the daily refresh.</ResponseField>
    <ResponseField name="disposition_as_of" type="string | null">ISO 8601 timestamp of when the current `disposition` was first derived or last changed. It does not advance when a daily run re-derives the same value, so a stale-looking timestamp means the disposition has been stable.</ResponseField>
    <ResponseField name="source_document_id" type="string | null">The office action the citation was extracted from (`med_...`), retrievable through [Trademark Documents](/api-reference/trademarks/records/documents) on the citing mark. Every citation served today carries one. The field is nullable so a citation derived without a stored source document can be represented. Documents are only addressable under a trademark, so when `trademark` is `null` there is no route that resolves this id.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="has_more" type="boolean">Whether more citations are available.</ResponseField>
<ResponseField name="pagination" type="object">Cursor for the next page.</ResponseField>
<ResponseField name="request_id" type="string">Unique request identifier for support and debugging.</ResponseField>

### Disposition Values

A citation carries exactly one disposition, derived from the citing application's later prosecution events and from whether the citation reappeared in subsequent office actions.

| Value             | Meaning                                                                                                                                   |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `published`       | The application published or registered after the citation date. The citation did not stop it.                                            |
| `maintained`      | The refusal reached a final office action. The citation held.                                                                             |
| `abandoned_after` | The application went abandoned after the citation date and was not revived.                                                               |
| `withdrawn`       | A later citation-bearing office action for the same application dropped this reference, with no publication yet. The examiner backed off. |
| `citation_issued` | No later signal yet. The application is still in prosecution, or its event record does not yet support a stronger label.                  |
| `null`            | Not computed yet. Filled on the daily refresh.                                                                                            |

When more than one signal applies, the strongest one wins, in this order: `published`, `maintained`, `abandoned_after`, `withdrawn`, `citation_issued`.

## Worked Example: Finding The Marks That Actually Block

A clearance search tells you which registrations look similar. It does not tell you which ones an examiner has ever used to refuse somebody. This endpoint does, and the disposition filter is what separates the two.

Ask for `disposition=maintained,abandoned_after`:

```bash theme={null}
curl -G "https://api.signa.so/v1/citations" \
  -H "Authorization: Bearer $SIGNA_API_KEY" \
  --data-urlencode "office=US" \
  --data-urlencode "disposition=maintained,abandoned_after" \
  --data-urlencode "action_date_gte=2023-01-01" \
  --data-urlencode "limit=100"
```

Those two values are the ones that matter, for different reasons:

* `maintained` means the examiner did not back down. The refusal was carried into a final office action, so the office has committed to the position that this prior mark bars the application. It is the cleanest evidence that a mark is a live obstacle.
* `abandoned_after` means the application died after being cited and was never revived. The applicant walked away rather than fight, which is the practical outcome a clearance search is trying to predict, even though the office never ruled.

And the ones to leave out, deliberately:

* `withdrawn` means the examiner dropped the citation in a later action. The prior mark was raised and then set aside, so it is weak evidence of blocking, and sometimes evidence of the opposite.
* `published` means the application went on to publish or register anyway. The cited mark did not stop it.
* `citation_issued` means prosecution has not produced a signal yet. Including it mixes unresolved cases into a set you are treating as resolved.

To turn that into a per-mark verdict during clearance, run it from the cited mark rather than across the corpus. Take a candidate conflict from a search, then ask how that mark has behaved as a prior right:

```bash theme={null}
curl -G "https://api.signa.so/v1/trademarks/tm_8kLm2nPq/cited-by" \
  -H "Authorization: Bearer $SIGNA_API_KEY" \
  --data-urlencode "disposition=maintained,abandoned_after" \
  --data-urlencode "limit=100"
```

Count distinct applications, not rows. A row is one citation occurrence in one office action, so an application cited in both a nonfinal and a final action contributes two rows. Group by `trademark.id`, falling back to `application_ref` when `trademark` is `null`. A registration that blocked a dozen distinct applications in the last three years is an owner whose mark the office reaches for routinely. One with none, despite years on the register and plenty of similar filings around it, is a much softer conflict. Pair it with the unfiltered `cited-by` set to get a rate rather than a raw number: a mark cited against twenty applications where eighteen citations were `withdrawn` or `published` is not the same risk as a mark cited against five where all five stuck.

Two caveats worth building around. Rows with `cited_trademark: null` are real citations that Signa could not link to a record, so count them; on the per-mark `cited-by` endpoint they are already matched by reference for you. And `abandoned_after` is a censored observation, not a ruling: the application stopped, and the citation is one plausible reason among several.

## Example Response

<ResponseExample>
  ```json theme={null}
  {
    "object": "list",
    "data": [
      {
        "id": "cit_0198c2f1-7e2a-7b34-9c11-3d5f8a2b4c6e",
        "object": "citation",
        "office_code": "US",
        "application_ref": "98123456",
        "trademark": {
          "id": "tm_019f34d6-2000-7777-8888-000000000001",
          "mark_text": "ACME BREW",
          "office_code": "US",
          "application_number": "98123456",
          "registration_number": null,
          "status_primary": "pending"
        },
        "cited_ref": "5567890",
        "cited_ref_type": "registration",
        "cited_trademark": {
          "id": "tm_8kLm2nPq",
          "mark_text": "ACME",
          "office_code": "US",
          "application_number": "87999999",
          "registration_number": "5567890",
          "status_primary": "active"
        },
        "refusal_type": "2d",
        "action_date": "2026-01-15",
        "action_stage": "final",
        "disposition": "maintained",
        "disposition_as_of": "2026-08-30T13:30:00.000Z",
        "source_document_id": "med_0198c2f1-7e2a-7b34-9c11-3d5f8a2b4c6e"
      }
    ],
    "has_more": true,
    "pagination": { "cursor": "eyJ2IjoxLCJ0IjoiY2l0YXRpb25zIn0" },
    "request_id": "req_cV2nL8pQ"
  }
  ```
</ResponseExample>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -G "https://api.signa.so/v1/citations" \
    -H "Authorization: Bearer sig_YOUR_KEY_HERE" \
    --data-urlencode "office=US" \
    --data-urlencode "disposition=maintained,abandoned_after" \
    --data-urlencode "limit=20"
  ```

  ```typescript TypeScript theme={null}
  import { Signa } from "@signa-so/sdk";

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

  // Comma-separated on the wire; the SDK accepts an array and joins it.
  const citations = await signa.citations.list({
    office: "US",
    disposition: ["maintained", "abandoned_after"],
    limit: 20,
  });

  for (const citation of citations.data) {
    console.log(citation.action_date, citation.cited_ref, citation.disposition);
  }
  ```

  ```python Python theme={null}
  import requests

  resp = requests.get(
      "https://api.signa.so/v1/citations",
      headers={"Authorization": "Bearer sig_YOUR_KEY_HERE"},
      params={
          "office": "US",
          "disposition": "maintained,abandoned_after",
          "limit": 20,
      },
  )
  ```
</CodeGroup>

### Resolve An Office-Printed Number

`cited_ref` plus `office` turns a number on an office action into the citations that name it, and into the mark behind it when Signa holds the record.

```bash cURL theme={null}
curl -G "https://api.signa.so/v1/citations" \
  -H "Authorization: Bearer sig_YOUR_KEY_HERE" \
  --data-urlencode "office=US" \
  --data-urlencode "cited_ref=5567890"
```

## Errors

| Status | Type               | Description                                                                                                                                                                                             |
| ------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | `validation_error` | `cited_ref` supplied without `office`, blank `cited_ref`, `action_date_gte` later than `action_date_lte`, bad enum value, a malformed `trademark_id` / `cited_trademark_id`, or unknown query parameter |
| 400    | `id_type_mismatch` | `trademark_id` or `cited_trademark_id` is a well-formed ID of another type (e.g. `own_...`) rather than a `tm_...`                                                                                      |
| 400    | `cursor_expired`   | Cursor is blank, expired, tampered with, or was issued for a different endpoint                                                                                                                         |
| 400    | `cursor_invalid`   | Cursor was issued under a different `sort` value. Restart pagination from the first page, or keep the `sort` the cursor was issued under                                                                |
| 401    | `unauthorized`     | Missing or invalid API key                                                                                                                                                                              |
| 403    | `forbidden`        | API key lacks the `trademarks:read` scope                                                                                                                                                               |
| 429    | `rate_limited`     | Rate limit exceeded                                                                                                                                                                                     |

An unrecognized `office` is not an error. It returns `200` with an empty list.

## Related Endpoints

* [Trademark Citations](/api-reference/trademarks/trademark-citations): prior marks cited against one application
* [Trademark Cited By](/api-reference/trademarks/trademark-cited-by): applications one mark was cited against
* [List Offices](/api-reference/reference/list-offices): per-office `capabilities.citations` state
* [Search Proceedings](/api-reference/proceedings/search-proceedings): contested proceedings, the third-party counterpart to examiner refusals
* [Use Case: Trademark Clearance](/guides/use-cases/trademark-clearance): where citation history fits in a clearance workflow