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

Brokers are individual agents or producers associated with a brokerage. The Brokers API allows you to programmatically create, read, update, and delete broker information within your company.

**Key Concepts:**

* Brokers are individual agents who work under a **brokerage**
* Each broker must be associated with an existing brokerage via `brokerageId`
* Brokers can have their own contact information, commission percentage, and producer number
* A broker may optionally have an associated **user ID** for portal access

***

## API Endpoints

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

***

## Broker vs Brokerage

| Entity        | Description                                                           |
| ------------- | --------------------------------------------------------------------- |
| **Brokerage** | An insurance agency or broker organization (company level)            |
| **Broker**    | An individual agent/producer who works for a brokerage (person level) |

A brokerage can have multiple brokers, but each broker belongs to exactly one brokerage.

***

## Structured Address

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

| Field     | Type   | Description                      |
| --------- | ------ | -------------------------------- |
| `line1`   | string | Street address line 1            |
| `line2`   | string | Street address line 2 (optional) |
| `city`    | string | City                             |
| `state`   | string | State or province                |
| `zip`     | string | ZIP or postal code               |
| `country` | string | Country code                     |

***

## Nullable Fields

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

| Field                         | When null                              |
| ----------------------------- | -------------------------------------- |
| `email`                       | Email not provided                     |
| `phone`                       | Phone number not provided              |
| `workPhone`                   | Work phone not provided                |
| `addressStructured`           | Address not provided                   |
| `defaultCommissionPercentage` | Default commission not configured      |
| `producerNumber`              | Producer number not assigned           |
| `userId`                      | Broker does not have portal access     |
| `createdAt`                   | Timestamp not tracked (legacy records) |
| `createdBy`                   | Created by system or unknown user      |
| `updatedAt`                   | Broker 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 broker ID(s) |
| `brokerageId` | string          | Filter by brokerage ID          |
| `filterText`  | string          | Text search across broker name  |

### Sorting Parameters

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

***

## Permissions

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

| Operation     | Required Permission     |
| ------------- | ----------------------- |
| List Brokers  | `company.broker:read`   |
| Get Broker    | `broker:read`           |
| Create Broker | `company.broker:create` |
| Update Broker | `broker:update`         |
| Delete Broker | `company.broker:create` |

***

## Example Response

```json theme={null}
{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "companyId": "660e8400-e29b-41d4-a716-446655440000",
      "brokerageId": "770e8400-e29b-41d4-a716-446655440000",
      "name": "John Smith",
      "email": "john.smith@acmeagency.com",
      "phone": "+1-555-123-4567",
      "workPhone": "+1-555-123-4568",
      "addressStructured": {
        "line1": "123 Main Street",
        "line2": "Suite 100",
        "city": "New York",
        "state": "NY",
        "zip": "10001",
        "country": "US"
      },
      "defaultCommissionPercentage": 15,
      "producerNumber": "PRD-12345",
      "userId": 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
}
```

***