{"openapi":"3.1.0","info":{"title":"Cold Leads API","version":"1.0.0","description":"Headless e-mail verification and B2B e-mail discovery. Authenticate with an API key from Settings → API keys (Business plan). Node.js SDK: https://github.com/anttka4cz/coldleads-node-sdk · MCP server: https://github.com/anttka4cz/mcp-server-coldleads"},"externalDocs":{"description":"Node.js SDK (GitHub)","url":"https://github.com/anttka4cz/coldleads-node-sdk"},"servers":[{"url":"https://coldleads.app/api/v1"}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"VerifyResult":{"type":"object","properties":{"email":{"type":"string"},"status":{"type":"string","enum":["valid","risky","invalid"]},"score":{"type":"integer","minimum":0,"maximum":100},"reasons":{"type":"array","items":{"type":"string"}},"mx":{"type":["string","null"]},"catch_all":{"type":"boolean"},"disposable":{"type":"boolean"},"role":{"type":"boolean"},"checked_at":{"type":"string","format":"date-time"},"cached":{"type":"boolean"}}}}},"security":[{"apiKey":[]}],"paths":{"/verify":{"post":{"operationId":"verifyEmail","summary":"Verify one e-mail address (1 credit)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"timeout_ms":{"type":"integer","minimum":1000,"maximum":30000,"description":"Optional time budget; when exceeded the result is risky with reasons [timeout] and catch_all is not determined"}}}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyResult"}}}},"401":{"description":"Missing or bad API key"},"402":{"description":"No credits left"},"429":{"description":"Rate limited (120/min per key)"}}}},"/verify/bulk":{"post":{"operationId":"verifyBulk","summary":"Verify a list (up to 5000 e-mails); returns a job to poll","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["emails"],"properties":{"emails":{"type":"array","items":{"type":"string"}},"name":{"type":"string"}}}}}},"responses":{"202":{"description":"Job created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"total":{"type":"integer"},"poll":{"type":"string"}}}}}},"429":{"description":"Too many concurrent jobs (max 5)"}}}},"/verify/jobs/{id}":{"get":{"operationId":"getVerifyJob","summary":"Job status and bucket counts; results=1 includes per-e-mail results","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"results","in":"query","schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"Job","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["queued","running","done","failed"]},"total":{"type":"integer"},"done":{"type":"integer"},"counts":{"type":"object","properties":{"valid":{"type":"integer"},"risky":{"type":"integer"},"invalid":{"type":"integer"}}},"results":{"type":"array","items":{"type":"object"}}}}}}}}}},"/find":{"post":{"operationId":"findEmail","summary":"Find a person's e-mail by name and company domain (1 credit)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"first":{"type":"string"},"last":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"}}}}}},"responses":{"200":{"description":"Best candidate","content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":["string","null"]},"confidence":{"type":"integer"},"method":{"type":"string","enum":["verified","pattern","none"]},"catch_all":{"type":"boolean"},"candidates":{"type":"array","items":{"type":"object"}}}}}}}}}},"/leads":{"get":{"operationId":"searchLeads","summary":"Contacts already in your Cold Leads CRM at a company domain (no credits)","parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string"},"description":"Company domain, e.g. example.com"},{"name":"role","in":"query","required":false,"schema":{"type":"string","maxLength":80},"description":"Keyword matched against name, e-mail local part, tags, notes and type"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":10}}],"responses":{"200":{"description":"domain, count, source=crm, leads[] with email, name, company, phone, stage, tags, verification, do_not_contact"},"400":{"description":"domain_required"},"401":{"description":"Missing or bad API key"},"429":{"description":"Rate limited"}}}},"/credits":{"get":{"operationId":"getCredits","summary":"Plan and remaining credits","responses":{"200":{"description":"Credits","content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"string"},"limit":{"type":"integer"},"used":{"type":"integer"},"left":{"type":"integer"}}}}}}}}}}}