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

# List Status Codes

> Decode office status codes into Signa's normalised status

## Overview

Every trademark carries the office's own status code in `status.raw.code`, next to Signa's normalised `status.primary`, `status.stage` and `status.reason`. This endpoint lists those office codes, each with the label the office publishes for it and the normalised status Signa maps it to. Use it to show the office's wording for a code, or to see which office codes land on a given stage.

`raw.label` is the office's own text, never a Signa description. It is `null` when we hold no verbatim office label for the code (for example USPTO codes today), including when the only text we hold is the code itself or wording Signa wrote.

## Query Parameters

<ParamField query="office_code" type="string">
  Filter by office code (WIPO ST.3, e.g. `US`, `EM`). Legacy codes (`uspto`, `euipo`) and `EU` are accepted as aliases. Omit to return every office. Unknown query parameters are rejected with `400`.
</ParamField>

<ParamField query="limit" type="integer" default="100">
  Max results per page (max 500).
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor from `pagination.cursor` of the previous page.
</ParamField>

## Response

This endpoint is publicly cacheable, so the response never includes `request_id`.

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

<ResponseField name="data" type="object[]">
  <Expandable title="Status code object">
    <ResponseField name="object" type="string">Always `status_code`</ResponseField>
    <ResponseField name="office_code" type="string">Uppercase ST.3 office code (e.g. `EM`)</ResponseField>

    <ResponseField name="raw" type="object">
      The office's code and label, as on a trademark's `status.raw`.

      <Expandable title="raw">
        <ResponseField name="code" type="string">The office's status code</ResponseField>
        <ResponseField name="label" type="string | null">The office's label for the code, verbatim; `null` when we hold no verbatim office label for it</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="primary" type="string">Normalised primary status: `pending`, `active`, `inactive` or `unknown`</ResponseField>
    <ResponseField name="stage" type="string">Normalised lifecycle stage (see the [status taxonomy](/guides/trademarks))</ResponseField>
    <ResponseField name="reason" type="string | null">Normalised reason for an inactive status (e.g. `refused`, `expired`), otherwise `null`</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="has_more" type="boolean">Whether more pages are available.</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="Pagination">
    <ResponseField name="cursor" type="string | null">Cursor for the next page, or `null` on the last page.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json theme={null}
  {
    "object": "list",
    "data": [
      {
        "object": "status_code",
        "office_code": "US",
        "raw": { "code": "700", "label": null },
        "primary": "active",
        "stage": "registered",
        "reason": null
      },
      {
        "object": "status_code",
        "office_code": "US",
        "raw": { "code": "710", "label": null },
        "primary": "inactive",
        "stage": "cancelled",
        "reason": "cancelled"
      }
    ],
    "has_more": true,
    "pagination": {
      "cursor": "US|710"
    }
  }
  ```
</ResponseExample>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.signa.so/v1/status-codes?office_code=US" \
    -H "Authorization: Bearer sig_YOUR_KEY"
  ```

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

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

  const codes = await signa.references.statusCodes({ office_code: "US" });
  for await (const code of codes) {
    console.log(code.raw.code, code.raw.label ?? "(no office label)", "->", code.stage);
  }
  ```
</CodeGroup>

## Errors

| Status | Type               | Description                                    |
| ------ | ------------------ | ---------------------------------------------- |
| 400    | `validation_error` | Unknown office code or unknown query parameter |
| 401    | `unauthorized`     | Missing or invalid API key                     |
| 403    | `forbidden`        | API key lacks `trademarks:read` scope          |
| 429    | `rate_limited`     | Too many requests                              |

## Related Endpoints

* [Retrieve Trademark](/api-reference/trademarks/retrieve-trademark), where `status.raw.code` appears
* [List Event Types](/api-reference/reference/list-event-types), the same decoding for prosecution events
* [Trademarks & lifecycle guide](/guides/trademarks), canonical status stages