API Reference

Broker Offices

Query 200,000 benefits broker office locations. Each office is a local team servicing real client books — most prospecting workflows target broker offices rather than parent firms.

search= is single-token, not multi-token fuzzy

search= is a substring match against the office and broker names. Multi-token strings like MERCER SAN FRANCISCO return []. Use one token (the most distinctive), then filter the response by broker_city / broker_state client-side, or combine with states=.

Company rows can include broker_office_id

Company rows expose broker_office_id when the primary broker office can be resolved. If the value is missing on an older or incomplete row, query /v1/broker-offices?search=MERCER&states=CA and match on broker_city. See Recipe library for the fallback pattern.

List Broker Offices

GET/v1/broker-offices1.00 / 2.00 per row

Returns a paginated list of broker offices matching your filters.

Pagination & format

Common to all endpoints — see Pagination and Response Modes.

Parameter	Type	Description
`page`	integer	Page number (0-indexed)
`page_size`	integer	Results per page (max 500). Over-max → 400.
`sort_by`	string	Column to sort by — allowlist: office_name (default), client_count, total_commissions, total_premiums
`sort_dir`	asc \| desc	Sort direction
`mode`	basic \| full	Response verbosity. Advanced-only fields require advanced access.
`fields`	string	Comma-separated field list (id always included)
`format`	json \| flat	Response format (flat for Clay/spreadsheets)
`count_only`	boolean	Return only total count, no data rows (0 credits)
`include_count`	boolean	Include total_count in meta (default true; false skips per-page COUNT)
`dry_run`	boolean	Validate query and return estimated rows + credits (0 credits)

Basic response fields

Field	Type	Description
`office_name`	string	Office name. Also returned as broker_office_name (alias) — both hold the same value.
`broker_office_name`	string	Alias of office_name (same value).
`lead_source`	object	Attribution stamp: { source: "hillwinds", retrieved_at: ISO-8601 UTC }. retrieved_at is when this row was assembled for the response, not the same as last_updated_at, which is when the row was last refreshed upstream.

Filters

Parameter	Type	Description
`search`	string	Fuzzy name search across broker_name and office_name
`states`	string	Comma-separated state codes (e.g. CA,NY,TX)
`dmas`	string	Comma-separated DMA names
`geo_mode`	state \| dma	Geographic filter mode (default state)
`brokerage_class`	string	national player, regional player, local broker
`client_count_bands`	string	One Client, Two to Five Clients, … Fifty Plus Clients
`commission_tiers`	string	Low / Small / Medium / Large / Extra Large / Jumbo Commissions
`carrier_search`	string	Substring match on carrier name
`broker_ids`	string	Comma-separated parent broker IDs (drill from broker → its offices)
`signals`	string	Active signals (advanced tier only)
`signal_match`	any \| all	Match semantics when multiple signals= are passed (default any)
`tags`	string	Tag names (AND logic)
`crm_status`	string	in_hubspot \| in_salesforce \| in_both \| not_in_crm
`filing_year`	string	Filing year or 'latest' (default 'latest')
`long_tail`	boolean	Long-tail broker office flag
`cf[column]`	string	Column filter — supports gte:/lte: for numeric columns
`eb[column]`	boolean	Exclude blanks for column; only true is supported (false returns 400)

Numeric column filters

cf[client_count], cf[total_commissions], cf[total_premiums], and cf[number_of_offices] support numeric range syntax: gte:, lte:, or both.

bash

curl -H "Authorization: Bearer ss_live_..." \
  "https://api.hillwinds.ai/v1/broker-offices?states=CA,NY&brokerage_class=regional+player&client_count_bands=Twenty+to+Fifty+Clients,Fifty+Plus+Clients&page_size=25"

Example response

{
  "ok": true,
  "data": [
    {
      "id": "bo_8f3a2b1c",
      "broker_name": "Marsh & McLennan Companies",
      "office_name": "Marsh McLennan Agency — San Francisco",
      "broker_office_name": "Marsh McLennan Agency — San Francisco",
      "broker_office_id": "bo_8f3a2b1c",
      "broker_id": "brk_a1b2c3",
      "broker_city": "SAN FRANCISCO",
      "broker_state": "CA",
      "broker_dma": "SAN FRANCISCO",
      "brokerage_class": "national player",
      "address": "525 Market St",
      "website": "marshmma.com",
      "crm_status": ["hubspot"],
      "lead_source": {
        "source": "hillwinds",
        "retrieved_at": "2026-06-24T14:16:00Z"
      }
    }
  ],
  "meta": {
    "total_count": 218,
    "page": 0,
    "page_size": 1,
    "returned": 1,
    "has_more": true,
    "response_tier": "basic",
    "key_tier": "advanced",
    "credits_charged": 1.00
  }
}

Get Broker Office

GET/v1/broker-offices/:id1.00 / 2.00 per row

Retrieve a single broker office by ID. The OpenAPI spec lists only id as a parameter — returns the full record available to your key's field tier. If you need to scope the response or pin format=flat, query the list endpoint with ?cf[id]=<id> instead.

bash

curl -H "Authorization: Bearer ss_live_..." \
  "https://api.hillwinds.ai/v1/broker-offices/bo_8f3a2b1c?mode=full"

Export Broker Offices

GET/v1/broker-offices/export.csvPer-row (matches list cost)

Streams CSV with the same filters as the list endpoint. Charged per row at the same rate as a paginated query. Sync exports cap at 2,000 rows; Enterprise plans can request async exports up to 10,000.

bash

curl -H "Authorization: Bearer ss_live_..." \
  -o broker-offices.csv \
  "https://api.hillwinds.ai/v1/broker-offices/export.csv?states=CA&client_count_bands=Twenty+to+Fifty+Clients&format=flat"

Autocomplete

GET/v1/broker-offices/autocomplete0 credits

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

column= allowlist: office_name (default) only. Other values return 400.
query requires ≥ 2 characters; missing or 1-char → 400. Alias: search.
id is populated — this is the only autocomplete endpoint suitable for direct name → ID resolution today.

bash

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

json

{
  "ok": true,
  "data": [
    {
      "id": "a804f56c-329f-4c1b-9e8e-839a5c98d4a3",
      "label": "Lockton Affinity, LLC - Lockton Affinity, LLC",
      "resource": "broker-offices",
      "value": "Lockton Affinity, LLC"
    },
    {
      "id": "5fed8ee3-85c1-4ac6-b869-49a993d9d841",
      "label": "Lockton Companies - Lockton Companies",
      "resource": "broker-offices",
      "value": "Lockton Companies"
    }
  ],
  "meta": { "credits_charged": 0, "returned": 2 }
}

PreviousPersonnel Next Lookalikes

Need a key?

Keys are issued by our team, not a signup form. Book a 25-minute walkthrough and you'll leave with sandbox and live credentials.

Get access Explore the platform