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

# Status Taxonomy

> Signa's 4-axis trademark status system across trademark offices

Every trademark office uses its own status codes. The USPTO has 167+ numeric codes. EUIPO uses 18 uppercase strings. CIPO has 10 text-based codes. Signa normalizes all of these into a unified 4-axis status taxonomy.

## The Four Axes

Every trademark status in Signa is described by four independent dimensions:

| Axis           | Field               | Purpose                                           |
| -------------- | ------------------- | ------------------------------------------------- |
| **Primary**    | `status.primary`    | High-level classification (3 values + unknown)    |
| **Stage**      | `status.stage`      | Where in the lifecycle the mark is (18 values)    |
| **Reason**     | `status.reason`     | Why the mark reached its current state (9 values) |
| **Challenges** | `status.challenges` | Active legal proceedings (6 values, array)        |

This multi-axis approach means you can filter with precision. A mark can be `active` + `registered` + `null` reason + `[opposition_pending]` -- meaning it is still active but has a pending challenge.

### Primary Status

The broadest classification. Every mark falls into one of:

| Value      | Meaning                                                    |
| ---------- | ---------------------------------------------------------- |
| `pending`  | Application in progress, not yet registered                |
| `active`   | Registration is alive and in force                         |
| `inactive` | Registration is dead (cancelled, expired, abandoned, etc.) |
| `unknown`  | Status could not be determined                             |

### Status Stage (18 values)

The specific lifecycle position:

**Pending stages:**

| Stage                  | Description                                       |
| ---------------------- | ------------------------------------------------- |
| `filed`                | Application received, not yet examined            |
| `examining`            | Under examination by the office                   |
| `pending_publication`  | Approved, awaiting publication                    |
| `published`            | Published in the official gazette                 |
| `opposition_period`    | Publication period for opposition is open         |
| `pending_opposition`   | An opposition has been filed and is under review  |
| `pending_cancellation` | A cancellation action has been filed              |
| `pending_issuance`     | Approved, awaiting formal issuance                |
| `allowed`              | Allowed (US-specific: Notice of Allowance issued) |

**Active stages:**

| Stage        | Description                   |
| ------------ | ----------------------------- |
| `registered` | Active registration, in force |

**Inactive stages:**

| Stage         | Description                                       |
| ------------- | ------------------------------------------------- |
| `abandoned`   | Applicant failed to respond or gave up            |
| `withdrawn`   | Applicant voluntarily withdrew                    |
| `surrendered` | Registrant voluntarily surrendered                |
| `refused`     | Office refused registration                       |
| `cancelled`   | Registration cancelled (by office or third party) |
| `invalidated` | Registration declared invalid                     |
| `expired`     | Registration expired (not renewed)                |

**Fallback:**

| Stage     | Description         |
| --------- | ------------------- |
| `unknown` | Could not be mapped |

### Status Reason (9 values)

Why the mark reached an inactive state. Only populated for inactive marks:

| Value         | Example Scenario                                    |
| ------------- | --------------------------------------------------- |
| `refused`     | Office examiner refused the application             |
| `withdrawn`   | Applicant withdrew the application                  |
| `abandoned`   | Applicant failed to respond to an office action     |
| `cancelled`   | Registration cancelled by office or via proceeding  |
| `invalidated` | Registration declared invalid after challenge       |
| `expired`     | Registrant did not renew                            |
| `surrendered` | Registrant voluntarily surrendered the registration |
| `revoked`     | Registration revoked (EU-specific)                  |
| `other`       | Reason does not fit standard categories             |

### Challenge States (6 values)

Active legal proceedings. This is an **array** because a mark can face multiple simultaneous challenges:

| Value                  | Description                          |
| ---------------------- | ------------------------------------ |
| `opposition_pending`   | An opposition has been filed         |
| `cancellation_pending` | A cancellation proceeding is pending |
| `invalidation_pending` | An invalidation action is pending    |
| `appeal_pending`       | An appeal is pending                 |
| `court_pending`        | A court proceeding is pending        |
| `other_pending`        | Another type of challenge is pending |

## Status Transitions

<Frame>
  ```mermaid theme={null}
  stateDiagram-v2
      [*] --> filed
      filed --> examining
      examining --> pending_publication
      examining --> refused
      examining --> abandoned

      pending_publication --> published
      published --> opposition_period
      opposition_period --> pending_opposition
      opposition_period --> pending_issuance
      pending_opposition --> pending_issuance
      pending_opposition --> refused

      pending_issuance --> registered
      published --> registered

      examining --> allowed
      allowed --> registered
      allowed --> abandoned

      registered --> expired
      registered --> cancelled
      registered --> surrendered
      registered --> invalidated

      filed --> withdrawn
      examining --> withdrawn
      published --> withdrawn
  ```
</Frame>

<Note>
  The diagram shows the most common transitions. Not all edges are shown -- some offices allow additional paths (e.g., direct registration without publication in certain jurisdictions).
</Note>

## Office-Specific Mappings

Each connector maps raw office codes to the canonical taxonomy. Here are examples from major offices:

### USPTO (167+ codes)

| Raw Code | Raw Label                              | Stage                 |
| -------- | -------------------------------------- | --------------------- |
| 100      | New Application - Record Initialized   | `filed`               |
| 161      | Abandoned - Failure to Respond         | `abandoned`           |
| 600      | Abandoned - After Examiner's Amendment | `abandoned`           |
| 681      | Published for Opposition               | `pending_publication` |
| 688      | Notice of Allowance - Issued           | `allowed`             |
| 800      | Registered and Renewed                 | `registered`          |
| 900      | Expired                                | `expired`             |

### EUIPO (18 codes)

| Raw Code               | Stage                |
| ---------------------- | -------------------- |
| RECEIVED               | `filed`              |
| UNDER\_EXAMINATION     | `examining`          |
| APPLICATION\_PUBLISHED | `pending_opposition` |
| REGISTERED             | `registered`         |
| WITHDRAWN              | `withdrawn`          |
| REFUSED                | `refused`            |
| CANCELLED              | `cancelled`          |
| EXPIRED                | `expired`            |

### WIPO

| Event Type | Stage                             |
| ---------- | --------------------------------- |
| BIRTH      | `filed` (new designation)         |
| PROCESSED  | `registered` (protection granted) |
| DEATH      | `cancelled`                       |
| PROLONG    | `registered` (renewed)            |

## Additional Status Fields

Beyond the four axes, the status object includes metadata:

| Field                   | Description                                                                                |
| ----------------------- | ------------------------------------------------------------------------------------------ |
| `status.effective_date` | When the status last changed                                                               |
| `status.source`         | How the status was determined: `explicit`, `event_derived`, `dispatch_derived`, `computed` |
| `status.raw_code`       | The office's original status code                                                          |
| `status.raw_label`      | The office's original status text                                                          |

## Filtering by Status

Use any combination of the four axes to filter trademarks:

<Tip>
  **"Live" marks (TESS equivalent).** `status_primary` accepts a single value *or* a comma-separated list. Pass `active,pending` to match every mark that is either registered or still in prosecution — equivalent to the USPTO TESS "Live" filter.
</Tip>

<CodeGroup>
  ```bash cURL theme={null}
  # All live marks (active OR pending) — TESS-style "Live" filter
  curl -s "https://api.signa.so/v1/trademarks?status_primary=active,pending" \
    -H "Authorization: Bearer sig_xxx"

  # All active, registered marks
  curl -s "https://api.signa.so/v1/trademarks?status_primary=active&status_stage=registered" \
    -H "Authorization: Bearer sig_xxx"

  # All marks with pending challenges
  curl -s "https://api.signa.so/v1/trademarks?challenge_states=opposition_pending" \
    -H "Authorization: Bearer sig_xxx"

  # All abandoned or withdrawn marks
  curl -s "https://api.signa.so/v1/trademarks?status_stage=abandoned,withdrawn" \
    -H "Authorization: Bearer sig_xxx"
  ```

  ```typescript TypeScript theme={null}
  // Live marks — active OR pending
  const live = await signa.trademarks.list({
    status_primary: ["active", "pending"],
  });

  // Active marks with pending opposition
  const marks = await signa.trademarks.list({
    status_primary: "active",
    challenge_states: "opposition_pending",
  });

  // All inactive marks with reason
  const inactive = await signa.trademarks.list({
    status_primary: "inactive",
    status_reason: "expired,cancelled",
  });
  ```

  ```python Python theme={null}
  # Live marks — active OR pending
  live = client.trademarks.list(
      status_primary=["active", "pending"],
  )

  # Active marks with pending opposition
  marks = client.trademarks.list(
      status_primary="active",
      challenge_states="opposition_pending",
  )

  # All inactive marks by reason
  inactive = client.trademarks.list(
      status_primary="inactive",
      status_reason="expired,cancelled",
  )
  ```
</CodeGroup>

## Search Aggregations

The search endpoint returns aggregation counts for `status_stage`:

<CodeGroup>
  ```bash cURL theme={null}
  curl -s -X POST https://api.signa.so/v1/trademarks \
    -H "Authorization: Bearer sig_xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "SIGNA",
      "options": { "aggregations": ["status_stage"] }
    }'
  ```

  ```typescript TypeScript theme={null}
  const results = await signa.trademarks.list({
    query: "SIGNA",
    options: { aggregations: ["status_stage"] },
  });
  console.log(results.aggregations.status_stage);
  // { registered: 4521, examining: 892, abandoned: 234 }
  ```

  ```python Python theme={null}
  results = client.trademarks.search(
      query="SIGNA",
      options={"aggregations": ["status_stage"]},
  )
  print(results.aggregations["status_stage"])
  # {"registered": 4521, "examining": 892, "abandoned": 234}
  ```
</CodeGroup>

## Practical Scenarios

<AccordionGroup>
  <Accordion title="How do I find marks that are at risk of cancellation?">
    Filter for marks with a cancellation challenge:

    ```bash theme={null}
    GET /v1/trademarks?status_primary=active&challenge_states=cancellation_pending
    ```
  </Accordion>

  <Accordion title="How do I distinguish between refused and abandoned applications?">
    Use `status_stage` directly: `abandoned` means the applicant failed to act, while `refused` means the office denied the application. The `status_reason` field provides additional context.
  </Accordion>

  <Accordion title="What if an office uses a code I haven't seen before?">
    If a connector encounters an unmapped raw code, it sets `status_stage` to `unknown` and populates `raw_code` and `raw_label` so you can still see the original office data. Unknown codes are logged and added to the mapping in subsequent releases.
  </Accordion>

  <Accordion title="Can a registered mark have challenges?">
    Yes. A mark can be `registered` (stage) with `active` primary status while simultaneously having `cancellation_pending` or `opposition_pending` in the challenges array. The mark remains registered until the challenge is resolved.
  </Accordion>
</AccordionGroup>