> ## Documentation Index
> Fetch the complete documentation index at: https://docs.casexchange.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Firms & Directory

> How the CaseXchange Public API represents law firms, your own firm profile, and the available-firms directory

## Authentication

All firm endpoints require an API key passed via the `X-API-Key` header.

```bash theme={null}
curl -H "X-API-Key: cxp_ro_your_key_here" \
  https://api.casexchange.com/api/public/v1/firms/me
```

## Firm Object

The `Firm` object represents a law firm registered in CaseXchange. Key fields returned by `GET /firms/me` and `GET /firms/{id}`:

```json theme={null}
{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "name": "Smith & Associates",
  "phone": "+1-310-555-0199",
  "address": "123 Main St",
  "city": "Los Angeles",
  "state": "CA",
  "zip": "90001",
  "website": "https://smithassociates.com",
  "isInternal": false,
  "createdAt": "2024-01-15T08:30:00Z",
  "updatedAt": "2025-11-02T14:22:00Z"
}
```

| Field        | Type                   | Description                                                                                                                                     |
| ------------ | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`         | `string (uuid)`        | Unique identifier for the firm                                                                                                                  |
| `name`       | `string`               | Firm name                                                                                                                                       |
| `phone`      | `string \| null`       | Phone number                                                                                                                                    |
| `address`    | `string \| null`       | Street address                                                                                                                                  |
| `city`       | `string \| null`       | City                                                                                                                                            |
| `state`      | `string \| null`       | State                                                                                                                                           |
| `zip`        | `string \| null`       | ZIP / postal code                                                                                                                               |
| `website`    | `string (uri) \| null` | Firm website URL                                                                                                                                |
| `isInternal` | `boolean`              | Whether the firm is a CaseXchange-operated internal firm (most integrators can ignore this — filter to `false` if you only want external firms) |
| `createdAt`  | `string (date-time)`   | When the firm record was created                                                                                                                |
| `updatedAt`  | `string (date-time)`   | When the firm record was last updated                                                                                                           |

## AvailableFirm Object

The `AvailableFirm` object represents a firm that is available to receive referrals from your firm. It is returned by `GET /firms/available` and includes referral-specific metadata on top of basic firm info.

```json theme={null}
{
  "id": "e5f6a7b8-1234-56cd-ef78-9012abcdef34",
  "name": "Jones Legal Group",
  "description": "Multi-state personal injury and medical malpractice firm",
  "jurisdictions": ["CA", "NY"],
  "caseTypes": ["Personal Injury", "Medical Malpractice"],
  "referralInstructions": "Submit via portal; include police report if available.",
  "source": "private_network"
}
```

| Field                  | Type             | Description                                                                                         |
| ---------------------- | ---------------- | --------------------------------------------------------------------------------------------------- |
| `id`                   | `string (uuid)`  | Unique identifier for the firm                                                                      |
| `name`                 | `string`         | Firm name                                                                                           |
| `description`          | `string \| null` | Brief description of the firm                                                                       |
| `jurisdictions`        | `string[]`       | States / jurisdictions the firm covers                                                              |
| `caseTypes`            | `string[]`       | Resolved display names of accepted case types                                                       |
| `referralInstructions` | `string \| null` | Relationship-specific instructions if available, otherwise the firm's general referral instructions |
| `source`               | `string`         | How the firm is available to you — one of `private_network`, `public_directory`, or `both`          |

## Endpoints

| Method | Path               | Description                                              |
| ------ | ------------------ | -------------------------------------------------------- |
| `GET`  | `/firms/directory` | Browse all firms in the public directory                 |
| `GET`  | `/firms/me`        | Retrieve your own firm profile                           |
| `GET`  | `/firms/{id}`      | Retrieve a single firm by ID                             |
| `GET`  | `/firms/available` | List firms available to receive referrals from your firm |
| `PUT`  | `/firms/me`        | Update your own firm profile                             |

## Pagination & Filtering

List endpoints (`/firms/directory`, `/firms/available`) accept the following query parameters:

| Parameter | Default | Description                         |
| --------- | ------- | ----------------------------------- |
| `page`    | `1`     | Page number (1-indexed)             |
| `limit`   | `20`    | Results per page (max `100`)        |
| `search`  | —       | Filter by firm name (partial match) |

Example:

```bash theme={null}
curl -H "X-API-Key: cxp_ro_your_key_here" \
  "https://api.casexchange.com/api/public/v1/firms/available?page=2&limit=50&search=jones"
```

## Response Format

All firm endpoints return responses in the standard Public API envelope:

**List response (paginated):**

```json theme={null}
{
  "data": [
    { "id": "...", "name": "..." }
  ],
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-11-02T14:22:00Z"
  },
  "pagination": {
    "page": 1,
    "limit": 20,
    "totalPages": 5,
    "total": 94
  }
}
```

**Single resource response:**

```json theme={null}
{
  "data": {
    "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "name": "Smith & Associates"
  },
  "meta": {
    "requestId": "req_def456",
    "timestamp": "2025-11-02T14:22:00Z"
  }
}
```

## Usage Tips

* **Cache firm lists** to avoid hitting rate limits. Directory data changes infrequently.
* **Use `GET /firms/available`** to find referral partners — it combines your private network and the public directory in a single call.
* **Check the `source` field** on `AvailableFirm` to distinguish private-network partners from public-directory firms.
* **Use `jurisdictions` and `caseTypes`** on available firms to power user-facing filters and recommended matches.
* **Keep your profile current** with `PUT /firms/me` so other firms see accurate contact information.

## Examples

For working code samples, see the [Firms examples](/api-reference/examples/firms).