REST API

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

• Base URL: https://api.coldlytics.com
• Reference: api.coldlytics.com/docs (interactive) and the OpenAPI 3.1 document

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 top-level code you can branch on: unauthenticated (401), invalid_key (401), insufficient_scope (403), forbidden_seat (403), validation_error (400), not_found (404), rate_limited (429), monthly_cap_reached (429), insufficient_credits (402), subscription_required (402), idempotency_key_reused (422), conflict (409), search_timeout (504), internal_error (500). Every response carries an X-Request-Id; quote it to support.
• Lookups and finds never 404 on a miss: they answer 200 with found: false and a reason, and nothing is charged. 404 is reserved for ids your account does not own.
• Credit-spending writes (POST /v3/reveal-runs, POST /v3/research-tasks) accept an Idempotency-Key header so a retried request never charges twice. Single reveals and finds are safe to retry too: a person you already own is a free receipt.

Rate limits

Limits are per API key (or OAuth connection) in fixed 60-second windows. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the window resets); a 429 rate_limited also sets Retry-After.

Searches also count against the account's monthly allowance (50 on free accounts, 5,000 on paid plans; see searches in GET /v3/account; monthly_cap_reached when it runs out). Lookups and finds do not. Email finds make at most 100 live verifications per account per day; past that they answer found: false, reason: daily_limit without charging. Need more? Email support@coldlytics.com.

What each call costs

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 }.

Example: one row at a time

For spreadsheets, Clay and Zapier the single-record endpoints answer one row per call, free on a miss:

# Company by domain: categories, size, Google listing, website signals, people on file
curl "https://api.coldlytics.com/v3/companies/lookup?domain=acme.com" \
  -H "Authorization: Bearer cl_live_YOUR_KEY"

# Person by email (or linkedin_url=…)
curl "https://api.coldlytics.com/v3/people/lookup?email=jane@acme.com" \
  -H "Authorization: Bearer cl_live_YOUR_KEY"

# The owner at a domain, with their verified email (1 credit when found)
curl https://api.coldlytics.com/v3/people/find \
  -H "Authorization: Bearer cl_live_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{ "domain": "acme.com", "seniorities": ["OWNERS_FOUNDERS"], "reveal": true }'

The Clay setups, with column references and output paths, are on Coldlytics in Clay.

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.