Core Concepts

Field Tiers

Every entity has basic and advanced fields. Your API key's field_tier setting determines which fields you can access and what credit cost applies.

What is the difference between basic and full fields?

Basic fields provide firmographic identity, while full fields add benefits intelligence such as brokers, carriers, premiums, plan funding, renewals, 401(k) data, and signals. Usemode=basic for the cheaper identity layer or mode=full when the workflow requires those advanced fields.

Basic vs. advanced

Basic = identity. Who and where the company is — name, address, industry, size, and website. This is the firmographic layer.

Advanced (mode=full) = benefits intelligence. Everything basic has, plus proprietary broker, carrier, premium, plan-funding, renewal, 401k, signal, and administrator data.

Advanced is a strict superset of basic. Upgrading never removes a basic field; it only adds fields.

Two independent knobs

Knob	Controls	Values
`mode`	Which fields you get and the credit cost	`basic` · `full`
`format`	The shape of the response	`json` (nested) · `flat` (one flat row)

These choices are orthogonal: mode is what data is returned; formatis how that data is laid out. The request value is mode=basic or mode=full. mode=advanced is invalid and returns 400, even though a full response reports meta.response_tier: "advanced".

Reproduce it in sandbox

Run both requests with an ss_test_ key. Sandbox reads use the production request contract, are capped at 100 rows, and charge zero credits.

Company 946157413

curl -H "Authorization: Bearer ss_test_YOUR_API_KEY" \
  "https://api.hillwinds.ai/v1/companies/946157413?mode=basic"

The basic response contains firmographics and attribution only. The advanced response contains those same keys unchanged, then adds benefits intelligence such as primary_broker, all_brokers_detail, all_carriers_detail, total_premiums, renewal_date, signals, and plan-administrator fields.

For agents

Need only to identify, locate, or deduplicate a company? Use mode=basic.
Need broker, carrier, premium, or plan data? Use mode=full.
Advanced already includes basic; never request both.
format=flat only reshapes the selected fields for CSV or spreadsheets.

Key access and billing

Basic keys — can only access basic fields. Requests for advanced-only fields or signal filters return 403 FORBIDDEN.
Advanced keys — can request either mode=basic (cheaper) or mode=full (all fields). The credit cost is determined by which mode you use, not which key you have.

Company fields

Basic (0.10 credits/row)

Field	Type	Description
`id`	string	Company EIN
`company_name`	string	Legal entity name
`company_state`	string	Two-letter state code
`company_city`	string	City
`company_zip`	string	ZIP code
`company_address`	string	Street address
`company_dma`	string	Designated Market Area
`company_industry`	string	Industry classification
`employee_band`	string	Employee count band
`total_number_of_employees`	integer	Exact employee count
`website`	string	Company website
`crm_status`	string[]	CRM sync status
`last_updated_at`	datetime string	Last upstream refresh time
`lead_source`	object	Response attribution and retrieval time

Advanced (1.00 credits/row) — requires advanced access

Field	Type	Description
`premium_tier`	string	Premium tier classification
`self_funded_or_fully_insured`	string	Funding status
`linkedin`	string	LinkedIn URL
`renewal_date`	datetime string	Benefits renewal timestamp
`filing_year`	integer	Filing year
`available_filings`	string[]	Filing types available
`signals`	string[]	Active signals (carrier_change, broker_change, etc.)
`participants`	integer	Plan participants
`total_premiums`	integer	Total annual premiums ($)
`medical_premiums`	integer	Medical-only premiums ($)
`primary_broker`	string	Primary broker name
`primary_broker_office`	string	Primary broker office
`broker_commission`	integer	Broker commission ($)
`broker_tenure_years`	integer	Years with current broker
`broker_commission_growth_pct`	number	YoY commission growth (%)
`primary_broker_compensation`	integer	Broker total compensation ($)
`primary_broker_address`	string	Broker street address
`primary_broker_city`	string	Broker city
`primary_broker_state`	string	Broker state
`all_carriers`	string[]	All carrier names
`all_brokers`	string[]	All broker names
`health_carriers`	string[]	Health insurance carrier names
`lines_of_insurance`	string[]	Insurance lines held
`carrier_by_line`	object[]	Carriers grouped by insurance line
`all_carriers_detail`	object[]	Carrier name, participants, premiums, benefit types
`all_brokers_detail`	object[]	Broker name, compensation, rank, benefit types
`broker_office_id`	string	Primary broker office ID
`participant_growth`	number	YoY participant growth (%)
`relationship_count`	integer	Total carrier/broker/provider relationships
`relationship_density`	string	Relationship density band
`assets_401k`	integer	401K assets ($)
`asset_tier_401k`	string	401K asset tier
`provider_401k`	string	401K provider name
`accounting_firm`	string	Accounting firm name
`administrator_linkedin`	string	Plan admin LinkedIn URL
`admin_name`	string	Plan administrator name
`admin_email`	string	Plan administrator email
`admin_phone`	string	Plan administrator phone

Personnel fields

Basic (0.50 credits/row)

Field	Type	Description
`id`	string	Contact ID
`first_name`	string	First name
`last_name`	string	Last name
`full_name`	string	Full name
`title`	string	Job title
`job_description`	string	Job description
`seniority`	string	Seniority level
`email_address`	string	Email address
`email_status`	string	Email verification status
`person_linkedin_url`	string	LinkedIn profile URL
`lead_type`	string	company or broker
`company_name`	string	Associated company
`company_ein`	string	Company EIN
`company_city`	string	Company city
`company_state`	string	Company state
`company_industry`	string	Company industry
`company_website`	string	Company website
`company_linkedin`	string	Company LinkedIn
`broker_name`	string	Associated broker
`broker_office_id`	string	Broker office ID
`broker_office_city`	string	Broker office city
`broker_office_state`	string	Broker office state
`form5500_role`	string	Form 5500 filing role
`person_city`	string	Person's city
`person_state`	string	Person's state
`person_dma`	string	Person's DMA
`crm_status`	string[]	CRM sync status

Advanced (2.00 credits/row) — requires advanced access

Field	Type	Description
`filing_year`	integer	Filing year
`available_filings`	string[]	Filing types available
`signals`	string[]	Active signals
`phone_number`	string	Phone number
`company_renewal_date`	string	Company renewal timestamp
`total_number_of_employees`	integer	Company employee count
`broker_coverage`	integer	Broker's client count (if broker lead)

Broker Office fields

Basic (1.00 credits/row)

Field	Type	Description
`id`	string	Broker office ID
`broker_name`	string	Parent brokerage firm name
`office_name`	string	Office name / branch name
`broker_office_id`	string	Broker office ID (alias for id)
`broker_id`	string	Parent broker ID
`broker_city`	string	Office city
`broker_state`	string	Office state
`broker_dma`	string	Office DMA
`brokerage_class`	string	national player, regional player, or local broker
`address`	string	Street address
`website`	string	Office or parent broker website
`crm_status`	string[]	CRM sync status

Advanced (2.00 credits/row) — requires advanced access

Field	Type	Description
`client_count`	integer	Number of clients serviced by this office
`client_count_band`	string	Client count band
`filing_year`	integer	Filing year
`available_filings`	string[]	Filing types available
`signals`	string[]	Active signals (e.g. commission_growth)
`total_commissions`	integer	Total commissions for this office ($)
`commission_tier`	string	Commission tier band
`total_premiums`	integer	Total premiums managed by this office ($)
`number_of_offices`	integer	Total offices for the parent broker
`funding_mix`	string	Self-funded vs fully insured mix
`top_industries`	object[]	Industry distribution of clients
`top_carriers`	object[]	Top carrier relationships
`employee_coverage`	string[]	Employee bands served
`office_states`	string[]	States this office covers

Broker fields

Basic (1.00 credits/row)

Field	Type	Description
`id`	string	Broker ID
`broker_name`	string	Broker/brokerage name
`brokerage_class`	string	national player, regional player, or local broker
`headquarters_city`	string	HQ city
`headquarters_state`	string	HQ state
`broker_dma`	string	HQ DMA
`total_clients`	integer	Total client count
`total_offices`	integer	Total office count
`website`	string	Broker website
`crm_status`	string[]	CRM sync status

Advanced (2.00 credits/row) — requires advanced access

Field	Type	Description
`client_count_band`	string	Client count band
`filing_year`	integer	Filing year
`available_filings`	string[]	Filing types
`signals`	string[]	Active signals
`total_commissions`	integer	Total commissions ($)
`total_premiums`	integer	Total premiums managed ($)
`funding_mix`	string	Self-funded vs fully insured mix
`top_carriers`	object[]	Top carrier relationships
`top_industries`	object[]	Client industry distribution
`employee_coverage`	string[]	Employee bands served
`office_states`	string[]	States with offices

Selecting fields manually

Use the fields parameter to request specific fields regardless of mode:

bash

GET /v1/companies?states=CA&fields=id,company_name,total_premiums,primary_broker

Requesting any advanced field triggers the advanced per-row credit cost. Requesting an advanced field with a basic-tier key returns 403.

PreviousEndpoint Index Next Filtering & Search

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