Hillwinds APIDocs
Getting Started

Quick Start

Get your first API response in under 2 minutes.

1. Get your API keys

When your account is set up, you'll receive two API keys:

  • Live key (ss_live_...) — queries real data, consumes credits.
  • Test key (ss_test_...) — validates read requests against the sandbox-supported API surface and charges zero credits. Lookalikes and other production-only endpoints require a live key.

Use a test key for this tutorial so the requests charge zero credits.

2. Make your first request

curl -H "Authorization: Bearer ss_test_YOUR_KEY_HERE" \
  "https://api.hillwinds.ai/v1/companies?states=NY&employee_bands=Mid-market+Accounts&page_size=3"

A sandbox key is expected to return Copperleaf Financial Co (EIN 737336823). Treat a non-2xx response or an empty result as a failed smoke test.

3. You'll get back something like this

json
{
  "ok": true,
  "data": [
    {
      "id": "737336823",
      "company_name": "Copperleaf Financial Co",
      "company_state": "NY",
      "company_city": "Albany",
      "company_industry": "Machinery, Equipment, & Supplies",
      "employee_band": "Mid-market Accounts",
      "total_number_of_employees": 481,
      "website": "copperleaffinancialco.example.com",
      "crm_status": []
    }
  ],
  "meta": {
    "page": 0,
    "page_size": 3,
    "returned": 1,
    "has_more": false,
    "response_tier": "basic",
    "key_tier": "basic",
    "credits_charged": 0
  }
}
Test keys are read-integration keys
Test-key reads use sandbox data and charge zero credits. Switch to an ss_live_ key for lookalikes, production-only metadata, and write-capable workflows.

4. Add more filters

bash
curl -H "Authorization: Bearer ss_test_YOUR_KEY_HERE" \
  "https://api.hillwinds.ai/v1/companies?states=CA,NY&industries=Hospitals,Software+Publishers&signals=carrier_change&sort_by=total_premiums&sort_dir=desc&page_size=10"

5. Try a different entity

Find VP-level contacts with email:

bash
curl -H "Authorization: Bearer ss_test_YOUR_KEY_HERE" \
  "https://api.hillwinds.ai/v1/personnel?lead_type=company&states=CA&seniority=VP-Director&has_email=true&page_size=5"

6. Check your credit balance

bash
curl -H "Authorization: Bearer ss_live_YOUR_KEY_HERE" \
  "https://api.hillwinds.ai/v1/credits"

Next steps

PreviousIntroductionNext Authentication