Overview

Brokerages represent insurance agencies or brokers that sell insurance on behalf of an MGA or Insurer running their program on the AI Insurance platform. The Brokerages API allows you to programmatically create, read, update, and delete brokerage information, including commission payment settings.

Key Concepts:

• Brokerages are insurance agencies or brokers that sell insurance on behalf of an MGA or Insurer
• Each brokerage has a commission payment method that determines how commissions are handled
• Brokerages can have contact information including email, phone, and structured address
• A default commission percentage can be set for each brokerage

---

API Endpoints

• List Brokerages - Retrieve paginated list of brokerages with filtering and sorting
• Get Brokerage - Retrieve a single brokerage by ID
• Create Brokerage - Create a new brokerage
• Update Brokerage - Update an existing brokerage
• Delete Brokerage - Soft delete a brokerage

---

Commission Payment Methods

Each brokerage must have a commission payment method that determines how commissions are processed:

Method	Description
agencyBill	The brokerage collects premiums and remits net of commission to the carrier
directBill	The carrier bills the insured directly and pays commission to the brokerage
doNotHandle	Commissions are not processed through the system

---

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
niprBrokerageNumber	NIPR number not provided
email	Email not provided
addressStructured	Address not provided
phone	Phone number not provided
defaultCommissionPercentage	Default commission not configured
createdAt	Timestamp not tracked (legacy records)
updatedAt	Brokerage has never been updated

---

Filtering and Sorting

List endpoints support comprehensive filtering and sorting options:

Filter Parameters

Parameter	Type	Description
id	string or array	Filter by specific brokerage ID(s)
filterText	string	Text search across brokerage name and email

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 brokerages for the current page
• totalCount - Total number of matching brokerages across all pages

---

Permissions

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

Operation	Required Permission
List Brokerages	company.brokerage:read
Get Brokerage	company.brokerage:read
Create Brokerage	company.brokerage:create
Update Brokerage	company.brokerage:create
Delete Brokerage	brokerage:update

---

Example Response

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Acme Insurance Agency",
      "commissionPaymentMethod": "agencyBill",
      "niprBrokerageNumber": "12345678",
      "email": "[e-mail]",
      "addressStructured": {
        "line1": "123 Main Street",
        "line2": "Suite 100",
        "city": "New York",
        "state": "NY",
        "zip": "10001",
        "country": "US"
      },
      "phone": "[phone]",
      "defaultCommissionPercentage": 15,
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-16T14:20:00.000Z"
    }
  ],
  "totalCount": 42
}

---