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

# Overview

Defendants represent parties named in a lawsuit. They are sub-resources of lawsuits, which are themselves sub-resources of events. The Defendants API allows you to create, retrieve, update, and delete defendant information for a specific lawsuit.

**Key Concepts:**

* Defendants belong to a lawsuit, accessed via the event path: `/events/{eventId}/lawsuit/defendants`
* Each defendant is either an insured (linked via `insuredId`) or a non-insured party (identified by `nonInsuredName`) — exactly one must be set
* Defendants can optionally be linked to an attorney and/or law firm
* Deleting a defendant is a soft delete — the record is preserved but no longer returned by GET or LIST

***

## API Endpoints

* **[List Defendants](/api-reference/defendants/list-defendants)** - Retrieve paginated list of defendants for a lawsuit
* **[Create Defendant](/api-reference/defendants/create-defendant)** - Create a defendant for a lawsuit
* **[Get Defendant](/api-reference/defendants/get-defendant)** - Retrieve a single defendant by ID
* **[Update Defendant](/api-reference/defendants/update-defendant)** - Update a defendant (send null to clear fields)
* **[Delete Defendant](/api-reference/defendants/delete-defendant)** - Soft delete a defendant

***

## Nullable Fields

The following fields may be `null` in the response:

| Field            | When null                              |
| ---------------- | -------------------------------------- |
| `insuredId`      | Defendant is a non-insured party       |
| `nonInsuredName` | Defendant is an insured                |
| `phoneNumber`    | Phone number not provided              |
| `email`          | Email not provided                     |
| `attorneyId`     | No attorney assigned                   |
| `lawFirmId`      | No law firm assigned                   |
| `createdAt`      | Timestamp not tracked (legacy records) |
| `updatedAt`      | Defendant has never been updated       |

***

## Filtering and Sorting

### Filter Parameters

| Parameter    | Type            | Description                         |
| ------------ | --------------- | ----------------------------------- |
| `id`         | string or array | Filter by specific defendant ID(s)  |
| `filterText` | string          | Text search across defendant fields |

### Sorting Parameters

| Parameter       | Type   | Default     | Description                                 |
| --------------- | ------ | ----------- | ------------------------------------------- |
| `sortBy`        | string | `createdAt` | Field to sort by (`createdAt`, `updatedAt`) |
| `sortDirection` | string | `desc`      | Sort direction (`asc` or `desc`)            |

### Pagination

| Parameter | Type    | Default | Description                         |
| --------- | ------- | ------- | ----------------------------------- |
| `page`    | integer | 1       | Page number (1-based, page size 50) |

**Response includes:**

* `items` - Array of defendants for the current page
* `totalCount` - Total number of matching defendants across all pages

***

## Permissions

Access to defendants requires the appropriate permissions based on your API key:

| Operation        | Required Permission    |
| ---------------- | ---------------------- |
| List Defendants  | `company.event:export` |
| Create Defendant | `company.event:export` |
| Get Defendant    | `company.event:export` |
| Update Defendant | `company.event:export` |
| Delete Defendant | `company.event:export` |

***

## Example Response

```json theme={null}
{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "companyId": "660e8400-e29b-41d4-a716-446655440000",
      "lawsuitId": "770e8400-e29b-41d4-a716-446655440000",
      "insuredId": null,
      "nonInsuredName": "John Doe",
      "phoneNumber": "+1-555-123-4567",
      "email": "john@example.com",
      "attorneyId": "880e8400-e29b-41d4-a716-446655440000",
      "lawFirmId": "990e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2026-02-15T10:30:00.000Z",
      "updatedAt": "2026-02-16T14:20:00.000Z"
    }
  ],
  "totalCount": 1
}
```

***