REST API

Search, reveal and research from your own code with the Coldlytics API v3.

The Coldlytics REST API v3 exposes the same capabilities as the MCP server for your own code: search, lookups, reveals, contacts and research tasks.

Authentication

Create a named API key under Integrations → API & MCP in the dashboard and pick only the scopes it needs. Send it as a bearer token:

curl https://api.coldlytics.com/v3/account \
  -H "Authorization: Bearer cl_live_YOUR_KEY"

X-Api-Key: cl_live_YOUR_KEY works too. Keys are shown once at creation and can be revoked at any time. OAuth access tokens issued for MCP clients are accepted on every endpoint as well.

Conventions

  • JSON in and out; list endpoints return { "data": [...], "meta": { "page", "page_size", "total", "has_more" } }.
  • Errors are RFC 9457 application/problem+json with a stable code you can branch on: unauthenticated, invalid_key, insufficient_scope, forbidden_seat, validation_error, not_found, rate_limited, monthly_cap_reached, insufficient_credits (402), subscription_required, idempotency_key_reused, search_timeout.
  • Per-key burst limits are reported in X-RateLimit-* headers; searches also count against the account's monthly allowance (see GET /v3/account).
  • Credit-spending writes (POST /v3/reveal-runs, POST /v3/research-tasks) accept an Idempotency-Key header so a retried request never charges twice.

Example: owners of plumbing companies in Austin

curl https://api.coldlytics.com/v3/search/people \
  -H "Authorization: Bearer cl_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "plumbers",
    "filters": { "locations": ["Austin, TX, USA"] },
    "seniorities": { "include": ["OWNERS_FOUNDERS"] },
    "page_size": 25
  }'

Each person carries a contact_id; reveal one with POST /v3/reveals { "contact_id": 123, "include_dial": true }.

Delivery webhooks

Research tasks launched with a webhook_url receive a POST with the delivered contacts as JSON when the task completes. Every delivery carries:

  • Coldlytics-Event: research.delivered
  • Coldlytics-Delivery: <uuid>
  • Coldlytics-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, t + "." + rawBody)>

The secret is on Integrations → API & MCP. Verify the signature over the raw request body and reject timestamps older than five minutes.

Legacy v1/v2

The pre-2026 endpoints (/v1/tasks/enrich, /v2/tasks/enrich/companies, /v2/tasks/enrich/people, /v2/user, HTTP Basic with the account key) continue to work unchanged for existing integrations. New work should use v3.