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 - Retrieve paginated list of brokers with filtering and sorting
• Get Broker - Retrieve a single broker by ID
• Create Broker - Create a new broker
• Update Broker - Update an existing broker
• 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

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "companyId": "660e8400-e29b-41d4-a716-446655440000",
      "brokerageId": "770e8400-e29b-41d4-a716-446655440000",
      "name": "John Smith",
      "email": "[e-mail]",
      "phone": "[phone]",
      "workPhone": "[phone]",
      "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
}

---