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

> Search and list law firms with trademark prosecution activity

## Overview

Returns a paginated list of law firms derived from attorney affiliations on ingested trademarks. Filter by country, attorney count, filing volume, and sort by activity metrics.

## Query Parameters

<ParamField query="q" type="string">
  Case-insensitive substring search on firm name.
</ParamField>

<ParamField query="country_code" type="string">
  ISO 3166-1 alpha-2 country code filter.
</ParamField>

<ParamField query="min_attorneys" type="integer">
  Minimum number of attorneys at the firm.
</ParamField>

<ParamField query="min_filings" type="integer">
  Minimum number of trademark filings handled.
</ParamField>

<ParamField query="sort" type="string" default="-trademark_count">
  Sort field. One of `-trademark_count`, `trademark_count`, `-attorney_count`, `attorney_count`, `-grant_rate`, `grant_rate`, `-name`, `name`.
</ParamField>

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

<ParamField query="cursor" type="string">
  Pagination cursor from a previous response.
</ParamField>

## Response

<ResponseField name="data" type="object[]">
  Array of firm summary records.
</ResponseField>

<ResponseField name="data[].id" type="string">
  Firm ID (`firm_...`).
</ResponseField>

<ResponseField name="data[].name" type="string">
  Display name of the firm.
</ResponseField>

<ResponseField name="data[].canonical_name" type="string">
  Normalized name used for entity resolution.
</ResponseField>

<ResponseField name="data[].country_code" type="string">
  Two-letter country code.
</ResponseField>

<ResponseField name="data[].attorney_count" type="integer">
  Number of distinct attorneys at the firm.
</ResponseField>

<ResponseField name="data[].trademark_count" type="integer">
  Total trademarks handled by the firm's attorneys. Counts marks: a Madrid IR family counts once, matching the default grouped `GET /v1/trademarks` listings.
</ResponseField>

<ResponseField name="data[].grant_rate" type="number">
  Share of concluded prosecutions (registered + expired + cancelled) that were ever granted (0-1).
</ResponseField>

<ResponseField name="data[].latest_filing" type="string">
  ISO date of the most recent filing handled.
</ResponseField>

<ResponseField name="data[].created_at" type="string">
  ISO 8601 timestamp when this firm record was created.
</ResponseField>

<ResponseExample>
  ```json theme={null}
  {
    "object": "list",
    "data": [
      {
        "id": "firm_2kLm9X",
        "object": "firm",
        "name": "Smith & Associates LLP",
        "canonical_name": "SMITH & ASSOCIATES LLP",
        "country_code": "US",
        "attorney_count": 42,
        "trademark_count": 15823,
        "grant_rate": 0.78,
        "latest_filing": "2026-04-08",
        "created_at": "2024-09-12T11:42:01Z"
      }
    ],
    "has_more": true,
    "pagination": { "cursor": "eyJpZCI6..." },
    "request_id": "req_xyz"
  }
  ```
</ResponseExample>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.signa.so/v1/firms?country_code=US&min_filings=500&sort=-trademark_count&limit=20" \
    -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 page = await signa.firms.list({
    country_code: "US",
    min_filings: 500,
    sort: "-trademark_count",
    limit: 20,
  });
  ```
</CodeGroup>

## Errors

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

## Related Endpoints

* [Get Firm](/api-reference/parties/get-firm): full firm detail with optional includes
* [Firm Attorneys](/api-reference/parties/firm-attorneys): attorneys at a firm
* [Firm Trademarks](/api-reference/parties/firm-trademarks): marks handled by a firm
* [List Attorneys](/api-reference/parties/list-attorneys): search attorneys instead