Ready to work through the API and AI agents

Two kinds of keys, clear blast radius

Keys live in Settings → API keys and are created in a click. Website keys (lk_…) are public: they can only create contacts and are safe inside a form on your site. Secret keys (sk_…) unlock the verification API and the stage hook, are stored hashed, and can be paused, rotated or deleted at any time. Every key shows when it was last used.

The endpoints

Send the secret key in the x-api-key header. All responses are JSON; errors carry a short code such as rate_limited or bad_input.

POST /api/v1/verify            { "email": "jane@example.com" }
POST /api/v1/verify/bulk       { "emails": ["…"], "name": "expo-2026" }   → job id
GET  /api/v1/verify/jobs/{id}  → progress and valid / risky / invalid counts; ?results=1 adds per-address results
POST /api/v1/find              { "name": "Jane Doe", "domain": "example.com" }
GET  /api/v1/credits           → credits left this month
POST /api/hooks/lead           email, name, company, phone, message, tag   (lk_ website key)
POST /api/hooks/stage          { "email": "jane@example.com", "stage": "customer" }
GET  /api/v1/leads?domain=example.com   → contacts already in your own CRM (0 credits)
POST /api/mcp                  MCP for AI agents: search_leads, verify_email

Limits: 120 requests a minute per key · 5 parallel jobs · 5 000 addresses per job · 1 credit per verified address or finder call

Plug it into an AI agent

The spec at /api/v1/openapi.json (OpenAPI 3.1) describes the /api/v1 endpoints with schemas (the two hooks above are plain HTTP calls), so an agent can call them without custom code:

• ChatGPT: create a GPT, import the spec as an Action, set API-key authentication with the x-api-key header.
• Claude and any model with function calling: generate the tool definitions from the spec, add the lead hook, and let the model verify, find and push in one conversation.
• Copilot Studio, n8n, Make, Zapier: an HTTP node with the same header is enough; the bulk job id makes long lists a two-step flow.
• A typical agent run: take a list from a spreadsheet, verify it, drop the invalid addresses, push the valid ones with a tag, and move a contact to “customer” when the deal closes.

Node.js SDK and MCP server

Two open-source clients for this API are on GitHub under the MIT licence and install straight from there. The Node.js SDK is a typed client for Node 20 or newer. The MCP server lets Claude Desktop, Cursor, VS Code and other MCP clients that can start a local server use Cold Leads as a tool.

Agents that support MCP over HTTP can skip the install and connect to https://coldleads.app/api/mcp with a secret key in the Authorization: Bearer header.

• code Node.js SDK — github.com/anttka4cz/coldleads-node-sdk
• code MCP server — github.com/anttka4cz/mcp-server-coldleads

Automation after the call

Contacts pushed through a key can start an auto-campaign after a delay you set: the welcome or follow-up e-mail goes out from your own mailbox with dry run, daily limits and human pacing. The stage hook lets your billing or CRM system mark a contact as customer the moment a deal closes, so the funnel stays true without anyone editing records.

Plans and limits

Website keys work on every plan. Secret keys — the verification and discovery API and the stage hook — come with Business ($99/month) together with 10,000 credits a month; extra packs cost $5 per 1 000. Results are cached for 30 days (each check still costs 1 credit), and every check runs from Cold Leads' servers, never from your domain.

FAQ