Personnel

Returns a paginated list of personnel contacts matching your filters.

Pagination & format

Common to all endpoints — see Pagination and Response Modes.

Basic response fields

Filters

Example

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

{
  "ok": true,
  "data": [
    {
      "id": "per_8a3f21c",
      "first_name": "Jennifer",
      "last_name": "Smith",
      "full_name": "Jennifer Smith",
      "title": "VP of Human Resources",
      "job_description": "Oversees HR and benefits administration",
      "seniority": "VP-Director",
      "email_address": "jennifer.smith@pacifichealthsystems.com",
      "email_status": "verified",
      "person_linkedin_url": "https://linkedin.com/in/jsmith",
      "lead_type": "company",
      "company_name": "PACIFIC HEALTH SYSTEMS INC",
      "company_ein": "84629153",
      "company_city": "SAN FRANCISCO",
      "company_state": "CA",
      "company_industry": "Hospitals",
      "company_website": "pacifichealthsystems.com",
      "company_linkedin": "https://linkedin.com/company/pacific-health-systems",
      "broker_name": null,
      "broker_office_id": null,
      "broker_office_city": null,
      "broker_office_state": null,
      "form5500_role": "Plan Administrator",
      "person_city": "San Francisco",
      "person_state": "CA",
      "person_dma": "SAN FRANCISCO",
      "crm_status": [],
      "lead_source": {
        "source": "hillwinds",
        "retrieved_at": "2026-06-24T14:16:00Z"
      }
    }
  ],
  "meta": {
    "total_count": 2891,
    "page": 0,
    "page_size": 1,
    "returned": 1,
    "has_more": true,
    "response_tier": "basic",
    "key_tier": "advanced",
    "credits_charged": 0.50
  }
}

Find contacts for multiple companies at once. Provide up to 50 company EINs and standard filters (lead_type, seniority, has_email, etc.); the API returns up to page_size contacts per company.

mode, fields, and format are accepted as query string parameters (not body fields) — same semantics as on the list endpoint.

curl -X POST -H "Authorization: Bearer ss_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "company_eins": ["123456789", "987654321"],
    "lead_type": "company",
    "page_size": 5
  }' \
  "https://api.hillwinds.ai/v1/personnel/batch?mode=full"

Returns a single contact by ID. Unlike the other detail endpoints, the spec lists mode, fields, format, and (required) lead_type here — pass lead_type=company|broker matching the contact's record, or the call returns 400.

curl -H "Authorization: Bearer ss_live_..." \
  "https://api.hillwinds.ai/v1/personnel/per_a1b2c3d4?lead_type=company&mode=full"

Returns the tags you've assigned to a single contact — the per-entity read of the tags you write with POST /v1/tags (entity_type=personnel). The same tags also appear inline as the tags field on GET /v1/personnel/:id?mode=full, and drive the tags= list filter. User-scoped: only your (or your API key's) tags are returned.

curl -H "Authorization: Bearer ss_live_..." \
  "https://api.hillwinds.ai/v1/personnel/per_a1b2c3d4/tags"

{
  "ok": true,
  "data": [
    {
      "id": "tag_9f2b",
      "entity_id": "per_a1b2c3d4",
      "entity_type": "personnel",
      "tag": "q1-outreach",
      "created_at": "2026-07-01T18:22:00Z"
    }
  ],
  "meta": { "returned": 1, "total_count": 1, "has_more": false }
}

Personnel has no dedicated /lookup endpoint. To find a single contact by a unique identifier you already have — a verified email or a person's LinkedIn URL — use the list endpoint with a cf[column]= exact-match filter on the response field of the same name. Useful for CRM enrichment when the inbound row has an email or LinkedIn URL but no Hillwinds ID.

# By email
curl -H "Authorization: Bearer ss_live_..." \
  "https://api.hillwinds.ai/v1/personnel?lead_type=company&cf%5Bemail_address%5D=jennifer.smith%40pacifichealthsystems.com&page_size=1"

# By LinkedIn URL (URL-encode the value — / and : must become %2F and %3A)
curl -H "Authorization: Bearer ss_live_..." \
  "https://api.hillwinds.ai/v1/personnel?lead_type=company&cf%5Bperson_linkedin_url%5D=https%3A%2F%2Flinkedin.com%2Fin%2Fjsmith&page_size=1"

Match semantics. cf[email_address]= and cf[person_linkedin_url]= are exact-equality filters — case-sensitive, full string. Mistype a character and you get an empty list (not a 404). For a fuzzy name match, use ?search= on full_name instead.

For bulk CRM enrichment

If you have a list of emails or LinkedIn URLs to reverse-lookup, loop the request per-row — there's no batched email/LinkedIn lookup. For employer-side bulk enrichment (multiple EINs), use POST /v1/personnel/batch instead.

Returns a CSV. Accepts the same filters as List Personnel. Max 2,000 rows per export.

curl -H "Authorization: Bearer ss_live_..." \
  -o contacts.csv \
  "https://api.hillwinds.ai/v1/personnel/export.csv?lead_type=company&states=CA&seniority=VP-Director&has_email=true"

Typeahead suggestions. Full cross-resource reference + per-resource matrix on the Autocomplete reference. Personnel-specific notes:

• column= allowlist: full_name (default), title. Other values (first_name, last_name, email_address, company_name) return 400.
• query requires ≥ 2 characters; missing or 1-char → 400. Alias: search.
• lead_type=company|broker is accepted to restrict results to one side. The autocomplete endpoint does not require it (unlike the list endpoint) but passing it produces sharper suggestions and is the right call when you're feeding the result back into a /v1/personnel?lead_type=…&search=… follow-up.
• id is returned as "" today. For name → ID, use the list endpoint with ?search= + a narrowing filter (lead_type, company_eins, etc.).

curl -H "Authorization: Bearer ss_live_..." \
  "https://api.hillwinds.ai/v1/personnel/autocomplete?search=smith&limit=5"

{
  "ok": true,
  "data": [
    {
      "id": "",
      "label": "Smitha Allapat",
      "resource": "personnel",
      "value": "Smitha Allapat"
    }
  ],
  "meta": { "credits_charged": 0, "returned": 1 }
}