For AI Agents

Recipe library

Copy-paste flows for the most common tasks. Sandbox-supported recipes use a test key; the production-only lookalike recipe uses a live key.

1. Find a company by name + full record (one call)

bash

export HILLWINDS_API_KEY="ss_test_..."

curl -H "Authorization: Bearer $HILLWINDS_API_KEY" \
  "https://api.hillwinds.ai/v1/companies?search=Copperleaf&mode=full&page_size=1"

Returns first match with all advanced fields (broker, carrier, signals). Don't use autocomplete for this — it returns lightweight typeahead rows, not the full company record.

2. Get all benefits decision-makers at a known company

bash

export HILLWINDS_API_KEY="ss_test_..."

# Resolve a current company EIN instead of relying on a fixture that may disappear.
COMPANY_EIN=$(curl -sS -H "Authorization: Bearer $HILLWINDS_API_KEY" \
  "https://api.hillwinds.ai/v1/companies?search=nike&page_size=1" | jq -r '.data[0].id')

curl -H "Authorization: Bearer $HILLWINDS_API_KEY" \
  "https://api.hillwinds.ai/v1/personnel?lead_type=company&company_eins=$COMPANY_EIN&seniority=C-suite,VP-Director&has_email=true&mode=full"

This recipe uses jq to read the EIN from the company-search response.

3. Get all broker reps at a specific office

bash

export HILLWINDS_API_KEY="ss_test_..."

curl -H "Authorization: Bearer $HILLWINDS_API_KEY" \
  "https://api.hillwinds.ai/v1/personnel?lead_type=broker&broker_office_ids=a804f56c-329f-4c1b-9e8e-839a5c98d4a3&mode=full&page_size=200"

4. Build a prospect list and tag it (full safe flow)

bash

export HILLWINDS_API_KEY="ss_live_..."

# Step 1: size the segment (0 credits)
curl -H "Authorization: Bearer $HILLWINDS_API_KEY" \
  "https://api.hillwinds.ai/v1/companies?states=CA,NY&employee_bands=Large+Enterprise+Accounts&signals=carrier_change&count_only=true"
# → total_count: 412

# Step 2: confirm cost (0 credits)
curl -H "Authorization: Bearer $HILLWINDS_API_KEY" \
  "https://api.hillwinds.ai/v1/companies?states=CA,NY&employee_bands=Large+Enterprise+Accounts&signals=carrier_change&mode=full&dry_run=true"
# → estimated_credits: 453.2

# Step 3: paginate (skip per-page COUNT)
curl -H "Authorization: Bearer $HILLWINDS_API_KEY" \
  "https://api.hillwinds.ai/v1/companies?states=CA,NY&employee_bands=Large+Enterprise+Accounts&signals=carrier_change&mode=full&include_count=false&page=0&page_size=100"
# → loop until meta.has_more === false

# Step 4: bulk-tag the matches (1 call, up to 100 entities)
curl -X POST -H "Authorization: Bearer $HILLWINDS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entity_type":"companies","entity_ids":["...","..."],"tag":"q2-2026-mercer-replacement"}' \
  "https://api.hillwinds.ai/v1/tags/bulk"

5. Count without spending credits

bash

export HILLWINDS_API_KEY="ss_test_..."

# Count rows matching a filter (free)
curl -H "Authorization: Bearer $HILLWINDS_API_KEY" \
  "https://api.hillwinds.ai/v1/companies?industries=Hospitals&states=NY&count_only=true"
# → meta.total_count

# Estimate credits before running for real (free)
curl -H "Authorization: Bearer $HILLWINDS_API_KEY" \
  "https://api.hillwinds.ai/v1/companies?industries=Hospitals&states=NY&mode=full&page_size=500&dry_run=true"
# → meta.estimated_credits

6. Discover valid filter values

bash

export HILLWINDS_API_KEY="ss_test_..."

# Full enum dump (every filter, every resource)
curl -H "Authorization: Bearer $HILLWINDS_API_KEY" "https://api.hillwinds.ai/v1/filter-options"

# Single key as flat array (cheapest)
curl -H "Authorization: Bearer $HILLWINDS_API_KEY" "https://api.hillwinds.ai/v1/filter-options/employee_bands"
curl -H "Authorization: Bearer $HILLWINDS_API_KEY" "https://api.hillwinds.ai/v1/filter-options/industries"
curl -H "Authorization: Bearer $HILLWINDS_API_KEY" "https://api.hillwinds.ai/v1/filter-options/job_function"

# Resource-scoped rich schema (parameter names + types + options per filter)
curl -H "Authorization: Bearer $HILLWINDS_API_KEY" "https://api.hillwinds.ai/v1/filter-options/personnel"

# Single filter within a resource
curl -H "Authorization: Bearer $HILLWINDS_API_KEY" "https://api.hillwinds.ai/v1/filter-options/personnel/seniority"

7. Resolve company → primary broker office ID

Company records expose broker_office_id when the primary broker office can be resolved. If that field is missing on an older or incomplete row, fall back to the broker office search:

bash

export HILLWINDS_API_KEY="ss_test_..."

# Fallback: parse broker name and state from primary_broker_office, then query broker-offices
curl -H "Authorization: Bearer $HILLWINDS_API_KEY" \
  "https://api.hillwinds.ai/v1/broker-offices?search=MERCER&states=CA&page_size=20"
# Filter the response client-side on broker_city to find the matching office.

8. Resolve seed IDs and find lookalikes

Use a production key for both discovery and the lookalike request. Test-key reads return sandbox records, while lookalikes reject test keys. Resolve the requested entity through its normal read endpoint and copy data[].id.

Resolve one seed ID

bash

export HILLWINDS_API_KEY="ss_live_..."

# Company: data[].id is the EIN
curl -sS -H "Authorization: Bearer $HILLWINDS_API_KEY" \
  "https://api.hillwinds.ai/v1/companies?search=nike&page_size=5" \
  | jq '.data[] | {id, company_name}'

# Broker office: autocomplete returns populated IDs
curl -sS -H "Authorization: Bearer $HILLWINDS_API_KEY" \
  "https://api.hillwinds.ai/v1/broker-offices/autocomplete?search=lockton&limit=5" \
  | jq '.data[] | {id, label}'

# Personnel: autocomplete IDs are empty, so use the list endpoint
curl -sS -H "Authorization: Bearer $HILLWINDS_API_KEY" \
  "https://api.hillwinds.ai/v1/personnel?lead_type=company&search=smith&has_email=true&page_size=5" \
  | jq '.data[] | {id, full_name, company_name}'

Use lead_type=broker for broker personnel, or narrow the list with company_eins and broker_office_ids. has_email=true matches the email-eligible personnel lookalike population.

Submit the selected company seed

bash

curl -X POST -H "Authorization: Bearer $HILLWINDS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "company",
    "seed_ids": ["123456789"],
    "limit": 10,
    "weights": {
      "industry": 3,
      "geo": 1,
      "employee_count_bucket": 2
    }
  }' \
  "https://api.hillwinds.ai/v1/lookalikes"

Change entity_type and seed_ids for broker-office or personnel searches. The response contains ranked IDs; enrich only the matches you need through the matching detail endpoint. No discovery response currently exposes V3 eligibility, so a selected resource can still return 422 INVALID_SEED. That response charges zero and requires a different seed rather than an unchanged retry. See the Lookalikes API reference for broker-office and personnel requests, every supported weight, relative-weight examples, and request-scoped behavior.

AI Agent Guide — pitfalls, universal query parameters, discovery flow.
Autocomplete reference — when to reach for autocomplete vs the resource list endpoint.
Endpoint index — every operation the live API exposes today.

PreviousAutocomplete Reference Next Endpoint Index

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

Recipe library

1. Find a company by name + full record (one call)

2. Get all benefits decision-makers at a known company

3. Get all broker reps at a specific office

4. Build a prospect list and tag it (full safe flow)

5. Count without spending credits

6. Discover valid filter values

7. Resolve company → primary broker office ID

8. Resolve seed IDs and find lookalikes

Resolve one seed ID

Submit the selected company seed

Related