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

Payees are entities that receive payments, such as law firms, experts, vendors, and other third parties. The Payees API allows you to programmatically create, read, update, and delete payee information within your company.

**Key Concepts:**

* Payees represent external entities that receive payments from insurance operations
* Each payee has a **type** (lawFirm, expert, vendor, other, financingCompany)
* Law firm payees can specify a **law firm type** (defense or plaintiff)
* Payees can have bank information for payment processing
* Only "saved" payees (isSaved: true) are returned by the API. A non-saved payee is one that was created via a UI flow but for which no transaction was ever completed.

***

## API Endpoints

* **[List Payees](/api-reference/payees/list-payees)** - Retrieve paginated list of payees with filtering and sorting
* **[Get Payee](/api-reference/payees/get-payee)** - Retrieve a single payee by ID
* **[Create Payee](/api-reference/payees/create-payee)** - Create a new payee
* **[Update Payee](/api-reference/payees/update-payee)** - Update an existing payee
* **[Delete Payee](/api-reference/payees/delete-payee)** - Soft delete a payee

***

## Payee Types

| Type               | Description                                 |
| ------------------ | ------------------------------------------- |
| `lawFirm`          | Law firm (can specify defense or plaintiff) |
| `expert`           | Expert witness or consultant                |
| `vendor`           | Third-party vendor or service provider      |
| `other`            | Other type of payee                         |
| `financingCompany` | Financing or premium finance company        |

***

## Law Firm Types

When `payeeType` is `lawFirm`, you can specify the `lawFirmType`:

| Type        | Description                              |
| ----------- | ---------------------------------------- |
| `defense`   | Defense counsel representing the insured |
| `plaintiff` | Plaintiff counsel (opposing party)       |

***

## Structured Address

The `addressStructured` field contains a detailed address object with the following fields:

| Field          | Type   | Description                              |
| -------------- | ------ | ---------------------------------------- |
| `streetNumber` | string | Street number                            |
| `streetName`   | string | Street name                              |
| `city`         | string | City name                                |
| `state`        | object | State with `short` and `long` properties |
| `postalCode`   | string | ZIP or postal code                       |
| `country`      | string | Country name or code                     |
| `county`       | string | County name                              |
| `neighborhood` | string | Neighborhood name                        |
| `sublocality`  | string | Sublocality or district                  |
| `timezone`     | string | Timezone identifier                      |
| `location`     | object | Geographic coordinates (`lat`, `lng`)    |

***

## Bank Information

The `bankInfo` field contains payment information:

| Field               | Type             | Description         |
| ------------------- | ---------------- | ------------------- |
| `bankAccountNumber` | string or number | Bank account number |
| `bankRoutingNumber` | string or number | Bank routing number |

***

## Nullable Fields

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

| Field               | When null                              |
| ------------------- | -------------------------------------- |
| `email`             | Email not provided                     |
| `alternateEmails`   | No alternate emails provided           |
| `phoneNumber`       | Phone number not provided              |
| `description`       | Description not provided               |
| `address`           | Unstructured address not provided      |
| `addressStructured` | Structured address not provided        |
| `lawFirmType`       | Payee is not a law firm                |
| `bankInfo`          | Bank information not provided          |
| `taxIdNumber`       | Tax ID not provided                    |
| `externalPayee`     | No external system reference           |
| `createdAt`         | Timestamp not tracked (legacy records) |
| `createdBy`         | Created by system or unknown user      |
| `updatedAt`         | Payee has never been updated           |
| `updatedBy`         | Never updated or updated by system     |

***

## Filtering and Sorting

List endpoints support comprehensive filtering and sorting options:

### Filter Parameters

| Parameter    | Type            | Description                    |
| ------------ | --------------- | ------------------------------ |
| `id`         | string or array | Filter by specific payee ID(s) |
| `payeeType`  | string          | Filter by payee type           |
| `filterText` | string          | Text search across payee name  |

### Sorting Parameters

| Parameter       | Type   | Default     | Description                                                               |
| --------------- | ------ | ----------- | ------------------------------------------------------------------------- |
| `sortBy`        | string | `createdAt` | Field to sort by (`createdAt`, `updatedAt`, `name`, `email`, `payeeType`) |
| `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 payees for the current page
* `totalCount` - Total number of matching payees across all pages

***

## Permissions

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

| Operation    | Required Permission    |
| ------------ | ---------------------- |
| List Payees  | `company.payee:read`   |
| Get Payee    | `company.payee:read`   |
| Create Payee | `company.payee:create` |
| Update Payee | `company.payee:create` |
| Delete Payee | `company.payee:create` |

***

## Example Response

```json theme={null}
{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "companyId": "660e8400-e29b-41d4-a716-446655440000",
      "name": "Smith & Associates Law Firm",
      "payeeType": "lawFirm",
      "email": "contact@smithlaw.com",
      "alternateEmails": ["billing@smithlaw.com"],
      "phoneNumber": "+1-555-123-4567",
      "description": "Defense law firm specializing in insurance litigation",
      "address": "123 Legal Plaza, Suite 500, New York, NY 10001",
      "addressStructured": {
        "streetNumber": "123",
        "streetName": "Legal Plaza",
        "city": "New York",
        "state": {
          "short": "NY",
          "long": "New York"
        },
        "postalCode": "10001",
        "country": "US"
      },
      "lawFirmType": "defense",
      "bankInfo": {
        "bankAccountNumber": "****1234",
        "bankRoutingNumber": "****5678"
      },
      "taxIdNumber": "12-3456789",
      "externalPayee": null,
      "createdAt": "2025-01-15T10:30:00.000Z",
      "createdBy": "880e8400-e29b-41d4-a716-446655440000",
      "updatedAt": "2025-01-16T14:20:00.000Z",
      "updatedBy": "880e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "totalCount": 42
}
```

***