Quickstart
You need an API key and a domain to score. Everything else is a single POST.
1. Create an API key
Sign in and open API keys. Keys start with vesperwise_ and are shown once when created; we store only a SHA‑256 hash. Put the key in your secret manager, for example as VESPERWISE_API_KEY.
2. Score your first company
We check four dated purchase triggers (funding, hiring, news and technology changes), collect website and GitHub context, and return the score with a summary and next step. Asking for the same company again within six hours returns the cached result without using a credit.
https://www.stripe.com/pricing is normalized to stripe.com, but other subdomains are not mapped back to the main domain.Authentication
Send your key as a bearer token: Authorization: Bearer vesperwise_…. Never put keys in URLs.
Every endpoint on this page accepts an API key. Revoking a key in API keys makes further requests with it return 401. To rotate, create the new key, deploy it, then revoke the old one.
Errors
Scoring endpoints return JSON with a stable code and a readable message. Other endpoints return { "error": "…" }.
field property names the problem field.credits_remaining.Idempotency-Key was reused with a different request.Retry-After header (2 seconds).intent_score is null and no credit is used.Limits
Credits are the main limit: one credit per company scored. The limits below apply per account.
Idempotency
POST /api/v1/score accepts an Idempotency-Key header, so a retried request never uses a second credit.
Use any unique string up to 255 characters (a UUID works). Reusing a key with a different request returns 409 idempotency_conflict. Replays of a completed request return the original response with Idempotency-Replayed: true.
POST/api/v1/scoreScore a company
Compute a score for a domain, personalized to your workspace profile. Results are cached for six hours per workspace and domain; cache hits are free.
Body parameters
Returns
A Score object. The response header X-IIQ-Cache is hit or miss.
GET/api/v1/score?domain=…Score (query string)
The same scoring as the POST endpoint, with parameters in the query string. It shares the cache, credit rules and response shape. Prefer POST for new integrations.
GET/api/v1/score/history?domain=…Score history
Your scores for one domain over the last 90 days, oldest first. Does not use credits.
Returns { domain, history: [{ score, score_band, score_status, data_coverage, icp_fit_score, created_at, … }] }.
GET/api/v1/score/personScore a person
Score a contact on seniority fit, recent job changes and their company's intent. Uses one credit.
Query parameters
Returns the person's intent_score, score_band, title, company, seniority, why_now, recommended_action and a suggested email_subject and talk_track.
POST/api/v1/prioritizePrioritize a CSV
Upload a CSV with a domain or company column as multipart field file. You get the same CSV back with your latest score columns added, sorted highest first. Only existing scores are used, so no credits are spent.
POST/api/v1/score/bulkBulk jobs
Queue up to 1,000 companies in one job, then poll GET /api/v1/score/bulk?job_id=… for status, completed and results.
GET/api/v1/watchlistList watchlist accounts
Returns { watchlist: [...] }: your active watchlist accounts, highest score first.
POST/api/v1/watchlistAdd an account
Body: { "domain": "stripe.com", "company_name": "Stripe" }. Returns the watchlist row with 201, or 403 when your plan's watchlist is full.
DELETE/api/v1/watchlist?domain=…Remove an account
Stops watching the domain. Score history is kept.
The Score object
Returned by POST /api/v1/score and its GET form.
The Signal object
Each entry in signals. Only funding, hiring, news and technology count toward intent_score; web and GitHub are context.