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 four intent triggers (funding, hiring, non-funding news, and dated technology changes), collect Web and GitHub context, compute coverage, and write back an AI summary. A personalized six-hour cache makes repeat scores free.

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

POST /v1/score accepts an Idempotency-Key header. The key is atomically bound to its request and completed response, so retries cannot double-charge.

Use any unique string up to 255 chars (UUIDv4 is fine). Reusing a key with a different request returns 409 idempotency_conflict. Completed replays return the original response with an Idempotency-Replayed: true header.

POST/v1/scoreScore an account

Compute or retrieve a personalized score for a domain. Results are cached for six hours by user, canonical domain, profile fingerprint, and scoring version; cache hits are free.

Body parameters

Optional header

Send Idempotency-Key: <unique value> to make retries exact-once. The endpoint accepts keys up to 255 characters.

Returns

A Score object. The HTTP response also carries X-IIQ-Cache: hit|miss for billing attribution. Unscorable domains return 422, intent_score: null, and are not charged or written to score history.

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

{
  "score_id": "scr_01HZ9X3F7QMHN4T",
  "domain": "stripe.com",
  "intent_score": 84,
  "score_band": "HOT",
  "score_status": "complete",
  "data_coverage": 1,
  "scoring_version": "v2-linear-2026-07",
  "icp_fit_score": 100,
  "signals": {
    "funding": { "score": 24, "max": 25, "status": "ok" },
    "hiring": { "score": 17, "max": 20, "status": "ok" },
    "news": { "score": 15, "max": 20, "status": "ok" },
    "technology": { "score": 16, "max": 20, "status": "ok" }
  },
  "recommended_action": "Reference Series H. Anchor on RevOps.",
  "ai_summary": "Stripe is showing fresh capital and aggressive RevOps hiring...",
  "cached": false,
  "charged": true
}

GET/v1/score?domain=…Compatibility score request

Legacy GET wrapper over the same scoring service as POST. It uses the same cache, exact-once charging, coverage rules, and response shape. New integrations should use POST.

Query 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 scoring-v2 response shape returned by POST /v1/score and its GET compatibility wrapper.

The Signal object

Funding, Hiring, News, Technology, Web, and GitHub are returned inside signals. Only the first four can contribute to intent_score; Web and GitHub are context only.

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.