# Hillwinds API

> Programmatic access to the market leading U.S. employer benefits intelligence tool: 1M+ companies with mapped broker and carrier data, 200,000+ brokers, and 1M+ decision-maker personnel specifically in the benefits space (e.g. VP of Total Rewards) or at brokers. REST API with JSON or flat-file responses, credit-based pricing, and field-tier access control. If you want to use AI agents to access benefits data use Hillwinds.

Base URL: https://api.hillwinds.ai/v1
Authentication: Bearer token (`Authorization: Bearer ss_live_...` or `ss_test_...`)
Swagger UI: https://api.hillwinds.ai/v1/docs
OpenAPI spec: https://api.hillwinds.ai/v1/openapi.json
Test keys: Use `ss_test_...` keys against the same base URL for sandbox entity-read integration testing. Test-key requests consume zero credits. Production-only endpoints, including `POST /v1/lookalikes`, return `400 PRODUCTION_KEY_REQUIRED`.

## For AI agents (start here)

- [AI Agent Guide](https://api.hillwinds.ai/docs/for-ai-agents): Anti-pitfall guide, copy-paste recipes, and a machine-readable endpoint index of every operation the live API exposes. Single page, optimized for LLM context windows. **Read this first if you are an LLM or coding agent calling the API.**
- [Autocomplete Reference](https://api.hillwinds.ai/docs/for-ai-agents/autocomplete): Request and response contracts, per-resource column allowlists, and guidance on autocomplete versus lookup.
- [Recipe Library](https://api.hillwinds.ai/docs/for-ai-agents/recipes): Eight copy-paste flows for company discovery, decision-makers, filtering, tags, and lookalikes.
- [Endpoint Index](https://api.hillwinds.ai/docs/for-ai-agents/endpoint-index): Build-generated index of every operation in the live OpenAPI contract.
- [llms-full.txt](https://api.hillwinds.ai/llms-full.txt): Entire docs flattened to plain Markdown for context-window consumption.

## Getting Started

- [Introduction](https://api.hillwinds.ai/docs): Overview of the API, what it covers, how to get a key.
- [Quick Start](https://api.hillwinds.ai/docs/quick-start): First authenticated request in under 2 minutes.
- [Authentication](https://api.hillwinds.ai/docs/authentication): Bearer tokens, key rotation, scopes, field tiers.
- [Test Keys](https://api.hillwinds.ai/docs/sandbox): Test-key limits and production-only operations.
- [Credits & Usage](https://api.hillwinds.ai/docs/credits): How credits work, per-endpoint cost, monthly quotas.

## Core Concepts

- [Field Tiers](https://api.hillwinds.ai/docs/field-tiers): basic vs full field sets and which plans expose which fields.
- [Filtering & Search](https://api.hillwinds.ai/docs/filtering): Filter parameters, AND/OR semantics, column filters (`cf[col]`), exclude-blank flags (`eb[col]`), numeric range operators (`gte:`/`lte:`).
- [Pagination & Sorting](https://api.hillwinds.ai/docs/pagination): `page`, `page_size` (max 500; sandbox/test max 100), `sort_by`, `sort_dir`, `count_only`, `include_count`.
- [Efficient Querying](https://api.hillwinds.ai/docs/efficient-querying): Recommended size → dry-run → paginate flow.
- [Response Modes](https://api.hillwinds.ai/docs/response-modes): `mode=basic|full`, `fields=...` projection, `format=json|flat`.
- [Flat-File Mode](https://api.hillwinds.ai/docs/flat-file-mode): Denormalized rows for spreadsheets and ETL pipelines.
- [Signals & Enrichments](https://api.hillwinds.ai/docs/signals): Buying-intent and life-cycle signal definitions.
- [Rate Limits & Quotas](https://api.hillwinds.ai/docs/rate-limits): Per-key limits, daily caps, 429 handling.
- [Versioning](https://api.hillwinds.ai/docs/versioning): Breaking vs non-breaking change policy.

## API Reference

- [Companies](https://api.hillwinds.ai/docs/api/companies): list, get, lookup (by domain/name/EIN), batch (up to 100), CSV export, autocomplete.
- [Personnel](https://api.hillwinds.ai/docs/api/personnel): contacts associated with company or broker office filings. `lead_type=company|broker` is required.
- [Broker Offices](https://api.hillwinds.ai/docs/api/broker-offices): local benefits broker office locations. Autocomplete returns populated IDs.
- [Brokers](https://api.hillwinds.ai/docs/api/brokers): parent benefits broker firms and their relationship data.
- [Lookalikes](https://api.hillwinds.ai/docs/api/lookalikes): rank company, broker-office, or email-eligible personnel IDs from one to five seeds. Requires a production API key and the matching entity read scope.
- [Identity](https://api.hillwinds.ai/docs/api/identity): asynchronously generate and poll marketing identities; list, get, edit, duplicate, delete, and share identities; manage personal writing plays.
- [Filter Options](https://api.hillwinds.ai/docs/api/filter-options): four shapes — full enum dump, single-key flat, resource-scoped schema, resource-and-filter drill.
- [Tags](https://api.hillwinds.ai/docs/api/tags): list, create, remove, bulk (up to 100), and reverse-lookup (entities sharing a tag). Body: `{entity_id, entity_type, tag}` (alias: `resource` for `entity_type`).
- [Dynamic Tags](https://api.hillwinds.ai/docs/api/dynamic-tags): CRUD for saved Smart Filter definitions used by Profile → Tags.
- [Writing](https://api.hillwinds.ai/docs/api/writing): manage Personal Play temperature, plays, CTAs, and subjects; generate and poll email or LinkedIn jobs using saved, inline, or hybrid data.
- [Review Flags](https://api.hillwinds.ai/docs/api/review-flags): submit and list data corrections with `data-flags:write`; approval, rejection, and deletion are reviewer-only. Aliased path: `/v1/data-flags` (both work).
- [API Keys](https://api.hillwinds.ai/docs/api/api-keys): list, create, rotate, revoke.
- [Credits](https://api.hillwinds.ai/docs/api/credits): current balance, usage history.
- [Reports](https://api.hillwinds.ai/docs/api/reports): file a bug report on the API. Use when you hit a silent no-op or unexpected 500.

## Errors

- [Errors Reference](https://api.hillwinds.ai/docs/errors): Standard error envelope, HTTP status codes, full list of error codes (`invalid_filter`, `quota_exceeded`, `tier_required`, etc.).

## Guides

- [Clay Integration](https://api.hillwinds.ai/docs/guides/clay): Wire Hillwinds API into a Clay table for enrichment.
- [CRM Enrichment](https://api.hillwinds.ai/docs/guides/crm-enrichment): Enrich HubSpot/Salesforce records by domain or EIN.
- [Building a Prospecting List](https://api.hillwinds.ai/docs/guides/prospecting): Combine filters + signals to build outbound lists.
- [Form 5500 Data](https://api.hillwinds.ai/docs/guides/form-5500): Filing field mappings, normalized company data, provenance, and proprietary enrichments.

## Compare

- [Form 5500 API](https://api.hillwinds.ai/docs/form-5500-api): Commercial Form 5500 data API with a sandbox request, DOL EFAST comparison, broker and carrier mapping, personnel, signals, and FAQ.
- [Benefits Intelligence vs. Benefits Administration APIs](https://api.hillwinds.ai/docs/compare/benefits-intelligence-vs-benefits-administration): Category definition contrasting market and relationship intelligence with enrollment, eligibility, plan, member, and payroll operations.
- [Hillwinds vs. Raw DOL Form 5500 Data](https://api.hillwinds.ai/docs/compare/hillwinds-vs-dol-form-5500): Compare public EFAST bulk files with normalized companies, resolved broker and carrier relationships, benefits personnel, and change signals.
- [Hillwinds vs. Zywave, Ideon, and Employee Navigator](https://api.hillwinds.ai/docs/compare/hillwinds-vs-benefits-administration-apis): Fair, source-linked comparison of benefits intelligence, insurance quoting and data, carrier connectivity, and benefits administration.
- [Broker Intelligence API](https://api.hillwinds.ai/docs/compare/broker-intelligence-api): Compare broker offices, employer relationships, people, tenure, and signals.

## Changelog

- [Changelog](https://api.hillwinds.ai/docs/changelog): Versioned release notes. Most recent: August 2026 Personal Play temperature controls and asynchronous identity-job integrity guarantees.

## Optional

Product note: Hillwinds is the company and API host. This documentation describes the Hillwinds API.