Brokers

Returns a paginated list of brokers (parent firms). To query the local office locations underneath a broker, use the Broker Offices endpoint with broker_ids.

Pagination & format

Common to all endpoints — see Pagination and Response Modes.

Basic response fields

Filters

curl -H "Authorization: Bearer ss_live_..." \
  "https://api.hillwinds.ai/v1/brokers?brokerage_class=regional+player&states=CA,NY&page_size=10"

Example response

{
  "ok": true,
  "data": [
    {
      "id": "brk_a1b2c3d4e5f6",
      "broker_name": "MARSH & MCLENNAN COMPANIES",
      "brokerage_class": "national player",
      "headquarters_city": "New York",
      "headquarters_state": "NY",
      "broker_dma": "NEW YORK",
      "total_clients": 8420,
      "total_offices": 87,
      "website": "marshmclennan.com",
      "crm_status": ["hubspot", "salesforce"],
      "lead_source": {
        "source": "hillwinds",
        "retrieved_at": "2026-06-24T14:16:00Z"
      }
    }
  ],
  "meta": {
    "total_count": 89,
    "page": 0,
    "page_size": 1,
    "returned": 1,
    "has_more": true,
    "response_tier": "basic",
    "key_tier": "advanced",
    "credits_charged": 1.00
  }
}

Returns a single broker by ID. The OpenAPI spec lists only id as a parameter — mode / fields / format don't apply here. For tier control, use GET /v1/brokers/lookup?name=… instead.

curl -H "Authorization: Bearer ss_live_..." \
  "https://api.hillwinds.ai/v1/brokers/brk_a1b2c3"

Exact-match lookup by broker name. Returns a single broker, 404 if no match, or 400 with suggestions if multiple match.

mode, fields, and format are optional and behave the same as on the list endpoint.

curl -H "Authorization: Bearer ss_live_..." \
  "https://api.hillwinds.ai/v1/brokers/lookup?name=Marsh+%26+McLennan"

Typeahead suggestions. Full cross-resource reference + per-resource matrix on the Autocomplete reference. Brokers-specific notes:

• column= allowlist: broker_name (default) only. Other values return 400.
• query requires ≥ 2 characters; missing or 1-char → 400. Alias: search.
• id is returned as "" today. For broker name → ID, prefer GET /v1/brokers/lookup?name=... — exact-match, returns 404 on miss or 400 with suggestions on ambiguous.

curl -H "Authorization: Bearer ss_live_..." \
  "https://api.hillwinds.ai/v1/brokers/autocomplete?search=marsh&limit=5"

{
  "ok": true,
  "data": [
    {
      "id": "",
      "label": "MARSH & MCLENNAN COMPANIES",
      "resource": "brokers",
      "value": "MARSH & MCLENNAN COMPANIES"
    }
  ],
  "meta": { "credits_charged": 0, "returned": 1 }
}