Lookalikes

Combines up to five seed profiles, retrieves candidates from the published V3 lookalike population, and returns the closest matches in ascending distance order. Seed IDs are always excluded from the result set.

Entity types and scopes

Example request

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

{
  "ok": true,
  "data": [
    {
      "id": "112233445",
      "rank": 1,
      "weighted_distance": 0.0831
    },
    {
      "id": "556677889",
      "rank": 2,
      "weighted_distance": 0.1174
    }
  ],
  "meta": {
    "returned": 2,
    "entity_type": "company",
    "lookalike_version": "v3",
    "credits_charged": 2,
    "base_credits": 2,
    "signal_credits": 0,
    "billable_rows": 2,
    "cached_rows": 0,
    "credit_balance_before": 1000,
    "credit_balance_after": 998
  }
}

Seed IDs are resolved through the normal entity read endpoints before the lookalike request is submitted. Use the same production key for discovery and lookalikes: test-key reads return sandbox entities, while POST /v1/lookalikes rejects test keys.

Company seed

Search by name or use the exact lookup endpoint, then copy data[].id. The company ID is its EIN.

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

Broker-office seed

Broker-office autocomplete returns populated IDs and is the lowest-cost direct name-to-ID path. Use the list endpoint with search and geographic filters when several offices have similar names.

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

Personnel seed

Personnel autocomplete suggestions do not currently contain usable IDs. Search the personnel list with lead_type, search, and narrowing filters, then copy data[].id. Include has_email=true because the personnel lookalike population is email-eligible.

curl -sS -H "Authorization: Bearer ss_live_..." \
  "https://api.hillwinds.ai/v1/personnel?lead_type=company&search=smith&has_email=true&page_size=5" \
  | jq '.data[] | {id, full_name, company_name}'

Omit weights to use adaptive V3 weighting derived from the seed profiles. When supplied, public categories are expanded into their underlying profile dimensions and normalized to a total weight of 1. Unknown categories, negative or non-finite values, empty objects, and all-zero sets return 400 VALIDATION_ERROR.

How relative weights affect ranking

Weight values are ratios, not percentages. Multiplying every value by the same number produces the same normalized weighting. A larger relative value gives that category more influence over weighted_distance; lower distance remains the closer match. A supplied zero removes that category's contribution, but at least one category must remain positive. Custom weights change ranking, not seed eligibility, the candidate population, the requested limit, or per-result billing.

The example above totals 6, so the API normalizes the values to 3/6, 2/6, and 1/6. Start by omitting weights. Add custom ratios only when the desired matching priorities are known, and compare the resulting ranks rather than treating the raw distance from two differently weighted requests as directly comparable.

Example starting points

Company weights

Broker-office weights

Personnel weights

lead_type is deliberately not a personnel weight. Personnel lookalikes search the email-eligible privacy-safe population across the supported personnel profiles.

• Live keys: exactly 1 credit per returned result.
• Test keys cannot call this endpoint. They return 400 PRODUCTION_KEY_REQUIRED and charge 0 credits.
• Validation, authentication, authorization, unavailable-seed, no-match, timeout, and internal-failure responses charge 0 credits.
• The endpoint does not use normal basic/advanced row pricing, cached-row discounts, or signal surcharges.