Quickstart

Get a real score back in under a minute. You'll need an API key (Settings → Developers) and a domain you want to score. Everything else is a single POST.

1. Get an API key

Open Settings → Developers and click Create key. Keys are shown once on creation, then stored as SHA‑256 hashes on our side — copy it into your secret manager. Test‑mode and live keys are separate: test keys are prefixed iiq_test_ and don't deduct credits.

2. Score your first account

Pick a domain. We'll fetch the five signals (funding, hiring, news, tech stack, web), compute a score, and write back an AI summary. Cold‑cache scores take ~1.4s; warm‑cache reads return in <200ms.

3. Hook it up

For real‑time pipelines, subscribe to the score.computed webhook and let VesperWise push deltas to you. For batch enrichment, queue a bulk job and poll its status.

Authentication

All requests are authenticated with a bearer token in the Authorization header. Keys are tied to a workspace, not a user — rotate them when seat holders leave.

Header format

Pass the key as Authorization: Bearer <key>. Keys never appear in URL parameters; never log them. Workspace ID is inferred from the key.

Test vs live mode

Test keys return synthetic but plausible scores against a fixed set of well‑known domains. They never call upstream vendors, never deduct credits, and never fire webhooks. Test responses include "mode": "test" at the top level.

Rotation & revocation

Create the new key, deploy it, then revoke the old one — zero downtime. Revoked keys 401 within ~5 seconds. We also auto‑revoke a key if we detect leakage on GitHub or a public paste.

Errors

Standard HTTP status codes. The body is always JSON with a type, a stable code, and a human message. We never leak credentials, request bodies, or stack traces.

Retry policy

Retry idempotent requests with exponential backoff: 1s, 2s, 4s, 8s — five attempts max. 5xx and 429 should retry; 4xx (except 429) should not.

Rate limits

Limits are per workspace, applied at the edge. If you're hitting them, you almost certainly want the bulk endpoint instead of a tight loop.

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.

Pagination

Cursor‑based on all list endpoints. Pass limit (max 100, default 20) and cursor (from the previous response's next_cursor).

Idempotency

All write endpoints accept an Idempotency-Key header. We store the response for 24 hours and replay it on conflict — safe to retry on flaky networks.

Use any unique string up to 255 chars (UUIDv4 is fine). If you reuse a key with a different body within the window, you get a 409 idempotency_conflict. Replays return the original response with an Idempotency-Replayed: true header.

POST/v1/scoreScore an account

Compute a fresh score for a domain. If we have a non‑stale cached score (younger than 7 days by default), we return it without deducting a credit — set force_refresh: true to bypass.

Body parameters

Returns

A Score object. The HTTP response also carries X-IIQ-Cache: hit|miss|refresh for billing attribution.

curl -X POST https://api.intentiq.dev/v1/score  \
  -H "Authorization: Bearer $IIQ_KEY"  \
  -H "Content-Type: application/json"  \
  -d '{ "domain": "stripe.com" }'

{
  "id": "scr_01HZ9X3F7QMHN4T",
  "domain": "stripe.com",
  "score": 94,
  "band": "HOT",
  "delta_30d": +12,
  "signals": {
    "funding": 96,
    "hiring":  88,
    "news":    92,
    "tech":    78,
    "web":     84
  },
  "action": "Reference Series H. Anchor on RevOps.",
  "summary": "Stripe is showing fresh capital, aggressive RevOps hiring...",
  "cached": false,
  "computed_at": "2026-05-28T14:02:11Z"
}

GET/v1/score/{id}Retrieve a score

Look up a previously computed score by its scr_ ID. Never deducts a credit. Returns the most recent score for the underlying domain.

Path parameters

POST/v1/score/bulkBulk score job

Submit up to 1,000 domains per job. Returns a job_ ID you can poll, or supply a webhook_url and we'll POST score.bulk.completed when the run finishes.

Body parameters

POST/v1/people/scoreScore a person

Score the human behind the logo. Provide an email or a LinkedIn URL — we enrich via Apollo with PDL fallback, then layer the underlying account's intent on top.

Body parameters

GET/v1/watchlistsList watchlists

Paginated list of watchlists in your workspace, ordered by most recently updated. Each entry includes a count of accounts and the current band distribution.

Query parameters

POST/v1/watchlistsCreate a watchlist

Pin up to 250 accounts (Starter), 1,000 (Team), or 10,000 (Scale). The moment any account crosses your band threshold, we fire account.band_changed.

Body parameters

PUT/v1/watchlists/{id}/accountsAdd accounts to a watchlist

Idempotent — adding a domain that's already on the list is a no‑op, not an error. Returns the full updated account list.

DELETE/v1/watchlists/{id}/accountsRemove accounts from a watchlist

Removes the domains in accounts from the watchlist. Does not delete the underlying score history.

Webhooks

We POST events to your endpoint as JSON. Deliveries are signed (HMAC‑SHA256), at‑least‑once, and retried on non‑2xx with exponential backoff for 24 hours. Subscribe in Settings → Webhooks.

Delivery contract

Respond 2xx within 5 seconds — do the work asynchronously. We send User-Agent: VesperWise-Webhook/1.0 and a X-IIQ-Signature header you should verify. Events carry a delivery_attempt integer so you can dedupe.

Event types

{
  "id":       "evt_01HZ9X3FK8M2P",
  "type":     "score.computed",
  "created":  "2026-05-28T14:02:11Z",
  "data": {
    "score": { /* Score object */ },
    "trigger": "watchlist_refresh"
  },
  "delivery_attempt": 1
}

Verify webhook signatures

Every delivery includes X-IIQ-Signature: t=<timestamp>, v1=<hmac>. Reject any request where the timestamp is older than 5 minutes (replay protection) and the HMAC does not validate against your signing secret.

The signing secret is shown once when you create the webhook endpoint, then stored hashed on our side — rotate it from the Webhooks settings page. The signed payload is the raw request body, not the parsed JSON.

The Score object

The canonical response shape. Returned by POST /v1/score, GET /v1/score/{id}, and nested inside score.computed webhooks.

The Signal object

Each of the five signals is returned as a nested object inside signals when you request include=signals.evidence.

The Person object

Returned by POST /v1/people/score and in person.scored webhook payloads.

Official SDKs

Thin wrappers around the REST API with retry/backoff, typed responses, and idiomatic ergonomics. Source on GitHub; bug reports welcome.

API changelog

We version the API by URL prefix (currently /v1). Breaking changes ship under a new version with at least 12 months of overlap. Additive changes ship anytime.