Getting Started

Authentication

All API requests require a Bearer token in the Authorization header.

http

Authorization: Bearer ss_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Key types

Prefix	Environment	Data	Credits
`ss_live_`	Production	Real company, personnel, and broker data	Deducted per row
`ss_test_`	Sandbox	Synthetic data	Free (0 credits)

Lookalikes require a production key

POST /v1/lookalikes is not available to ss_test_ keys. Test-key requests return 400 PRODUCTION_KEY_REQUIRED and charge zero credits.

Managing your keys

Use the API Keys endpoints to create, list, revoke, and rotate keys:

bash

# List your org's keys
curl -H "Authorization: Bearer ss_live_..." \
  "https://api.hillwinds.ai/v1/api-keys"

# Create a new key
curl -X POST -H "Authorization: Bearer ss_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Clay - Production", "scopes": ["read:companies", "read:personnel"], "field_tier": "advanced", "key_type": "live"}' \
  "https://api.hillwinds.ai/v1/api-keys"

# Revoke a compromised key
curl -X DELETE -H "Authorization: Bearer ss_live_..." \
  "https://api.hillwinds.ai/v1/api-keys/key_a1b2c3d4"

The full key is shown only once

When you create or rotate a key, store it securely. After creation, only the prefix (ss_live_a1b2c3) is visible in the key list.

Browser and CORS usage

Keep API keys on your server; do not embed them in public browser code. CORS is enabled for Hillwinds application origins and local development origins, while arbitrary customer origins are intentionally not allowed. Browser-based integrations should call their own backend, which then calls the Hillwinds API. Additional trusted origins can be configured by Hillwinds when required.

Scopes

Each key is created with specific scopes that control what it can access:

Scope	Grants access to
`read:companies`	List, get, lookup, autocomplete companies
`read:personnel`	List, get, autocomplete contacts
`read:broker-offices`	List, get, autocomplete broker offices
`read:brokers`	List, get, lookup, autocomplete brokers
`tags:read`	List tag names and tagged entities
`tags:write`	Create and delete tags
`writing:read`	Read writing resources, options, and jobs
`writing:write`	Create, edit, and delete plays, CTAs, and subjects
`writing:generate`	Generate email and LinkedIn writing jobs
`data-flags:write`	Submit and list review/data flags
`reports:write`	Submit API bug reports
`keys:read`	List API keys in the current credit account
`keys:write`	Create, revoke, and rotate child API keys
`credits:read`	Read the current credit balance
`usage:read`	Read credit usage history

Filter options, autocomplete, and health checks are free operations. CSV exports use the same resource read scopes as their parent list endpoint.

Requesting an endpoint without the required scope returns 403 FORBIDDEN.

Field tier

Each key has a field_tier setting — basic or advanced — that controls which fields are returned and what credit cost applies. See Field Tiers for details.

Errors

Status	Meaning
400	A production-only endpoint was called with a test key
401	Key is missing, malformed, expired, or revoked
403	Key is valid but lacks the required scope or field tier

PreviousQuick Start Next Sandbox Environment

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