API Reference

Filter Options

Discover the valid values for every filter.

Four shapes — pick the smallest one that answers your question

/v1/filter-options returns the full enum dump (one call, every filter). /v1/filter-options/{key} returns a single key as a flat array (best for agents). /v1/filter-options/{resource} returns the full filter schema scoped to one resource (best for UI generators). /v1/filter-options/{resource}/{filter} drills into one filter within one resource.

In the Swagger UI you'll see explicit per-resource paths

The OpenAPI spec lists the four per-resource calls as distinct operations (/filter-options/companies, /filter-options/personnel, /filter-options/brokers, /filter-options/broker-offices) rather than the parametric /filter-options/{resource} form we describe here. Behaviorally they're identical — we use the parametric form for brevity.

All Filter Options

GET/v1/filter-options0 credits

Returns valid values for every named filter across all resources — states, industries, employee bands, premium tiers, signals, and more. Useful for building a dynamic filter UI in one call. Every enum lives under data.enums (a single home — no top-level duplication), and data.resources carries the per-endpoint filter schema (including the cf_columns / eb_columns each resource accepts). The curated top-50 broker enum is named top_brokers; the namebrokers is reserved for the broker resource schema.

bash

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

json

{
  "ok": true,
  "data": {
    "enums": {
      "states": ["AL", "AK", "AZ", "..."],
      "industries": ["Hospitals", "Software Publishers", "..."],
      "employee_bands": [
        "Small Employers",
        "SMB Accounts",
        "Mid-market Accounts",
        "Large Mid-Market Accounts",
        "Enterprise Accounts",
        "Large Enterprise Accounts",
        "Jumbo Accounts"
      ],
      "premium_tiers": ["No Premiums", "Sub 100K", "101-500K", "501-999K", "1-5M", "6-25M", "26M+"],
      "signals": ["self_funded", "esop", "carrier_change", "..."],
      "top_brokers": [
        { "broker_id": "eb7e8b4c-b369-4747-a693-c040713796bc", "broker_name": "Gallagher" }
      ],
      "seniority": ["C-suite", "VP-Director", "Mid-Level", "Entry-Level"]
    },
    "resources": {
      "companies": {
        "endpoint": "/v1/companies",
        "filters": { "...": {} },
        "cf_columns": ["total_premiums", "participant_growth", "..."],
        "eb_columns": ["primary_broker", "health_carriers", "..."]
      }
      /* ... personnel, brokers, broker-offices ... */
    }
  }
}

Single Key (flat)

GET/v1/filter-options/{key}0 credits

Returns the values for a single filter as a flat array. Cheapest shape — preferred for agents that already know which filter they want to enumerate. Now covers all named filters including industries, signals, job_function, funding_status, and top_brokers. Use /filter-options/top_brokers for the curated broker list; /filter-options/brokers returns the broker resource schema.

bash

curl -H "Authorization: Bearer ss_live_..." \
  "https://api.hillwinds.ai/v1/filter-options/employee_bands"

json

{
  "ok": true,
  "data": [
    "Small Employers",
    "SMB Accounts",
    "Mid-market Accounts",
    "Large Mid-Market Accounts",
    "Enterprise Accounts",
    "Large Enterprise Accounts",
    "Jumbo Accounts"
  ],
  "meta": { "credits_charged": 0 }
}

industries?with_counts=true returns the enriched form — one object per value with its live company count and a deprecated flag — so you can skip values that currently match no rows without probing each one. The default (bare-string array) is unchanged.

json

// GET /v1/filter-options/industries?with_counts=true
{
  "ok": true,
  "data": [
    { "name": "Commercial Banking", "count": 1842, "deprecated": false },
    { "name": "Some Dead NAICS Label", "count": 0, "deprecated": true }
  ],
  "meta": { "credits_charged": 0 }
}

Resource-Scoped Schema

GET/v1/filter-options/{resource}0 credits

Returns the full filter schema for one resource — every accepted query parameter, its type, its description, and (where enumerated) its options. Use this when building a filter UI specific to one resource or when an agent needs to confirm exact parameter names + types. Resources: companies, personnel, brokers, broker-offices.

bash

curl -H "Authorization: Bearer ss_live_..." \
  "https://api.hillwinds.ai/v1/filter-options/personnel"

json

{
  "ok": true,
  "data": {
    "endpoint": "/v1/personnel",
    "filters": {
      "broker_office_ids": {
        "type": "list",
        "description": "Comma-separated broker office IDs."
      },
      "company_eins": {
        "type": "list",
        "description": "Comma-separated company EINs."
      },
      "crm_status": {
        "type": "scalar",
        "description": "CRM match status.",
        "options": ["in_hubspot", "in_salesforce", "in_both", "not_in_crm"]
      },
      "seniority": {
        "type": "list",
        "description": "Seniority bucket filter.",
        "options": ["C-suite", "VP-Director", "Mid-Level", "Entry-Level"]
      }
      /* ... one entry per filter on the personnel endpoint ... */
    }
  }
}

Single Filter Within Resource

GET/v1/filter-options/{resource}/{filter}0 credits

Returns the enumerated values for one filter scoped to one resource. Same flat array as /v1/filter-options/{key} but useful when the same filter name might have resource-specific allowlists (none today, but the endpoint is the future-proof way to enumerate).

bash

curl -H "Authorization: Bearer ss_live_..." \
  "https://api.hillwinds.ai/v1/filter-options/personnel/seniority"

json

{
  "ok": true,
  "data": ["C-suite", "VP-Director", "Mid-Level", "Entry-Level"],
  "meta": { "credits_charged": 0 }
}

DMAs are large (~210 Nielsen markets), so /v1/filter-options/{resource}/dmas returns a structured block — { type, description, resource, key, options: [...] } — rather than a bare array. Read data.options for the accepted values, which are exactly the strings the dmas= parameter accepts (round-trip safe).

PreviousIdentity Next Tags

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