{"openapi":"3.1.0","info":{"title":"NexusCold — B2B Data Enrichment Engine API","description":"API for uploading CSV of company names, running multi-source parallel enrichment (16 sources, 20+ workers), and downloading enriched B2B data (website, email, phone, DUNS, EIN, RUC, VAT, CNPJ, RFC, RUT, NIF, ABN, CIN, employees, revenue). MCP server mirrors the same 8 tools for AI agent integration (Claude, Cursor, Cline). Built by AliceLabs LLC (Sheridan, Wyoming, USA).","version":"1.0.0","contact":{"name":"AliceLabs LLC","email":"hello@alicelabs.site","url":"https://alicelabs.site"},"license":{"name":"AL-1.0 (commercial use requires Enterprise tier license)","url":"https://alicelabs.site/licenses/al-1.0"}},"servers":[{"url":"https://nexus.alicelabs.site","description":"Production (cloud)"},{"url":"http://localhost:3000","description":"Local development"}],"tags":[{"name":"Upload","description":"CSV upload and batch management"},{"name":"Enrichment","description":"Job queue and enrichment status"},{"name":"Results","description":"Enriched result retrieval and export"},{"name":"Single","description":"Single-company enrichment (no batch needed)"},{"name":"Verify","description":"Tax ID verification"},{"name":"MCP","description":"MCP server endpoint (JSON-RPC 2.0)"}],"paths":{"/api/upload":{"post":{"tags":["Upload"],"summary":"Upload CSV file","description":"Accepts multipart/form-data with a 'file' field (CSV, max 50MB, UTF-8). Auto-detects columns and maps to canonical schema. Returns batch_id. Input CSV is deleted within 24h after enrichment completes.","operationId":"uploadCsv","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"CSV file with company_name column (required) + optional city, country."}},"required":["file"]}}}},"responses":{"201":{"description":"CSV uploaded successfully","content":{"application/json":{"schema":{"type":"object","properties":{"batch_id":{"type":"string"},"rows_detected":{"type":"number"},"columns_detected":{"type":"array","items":{"type":"string"}},"message":{"type":"string"}}}}}},"400":{"description":"Invalid input (missing file, wrong format, too large)"}}}},"/api/jobs/{id}":{"get":{"tags":["Enrichment"],"summary":"Get job status","description":"Returns job status: queued|processing|complete|failed. Includes progress (0-100), records_processed, sources_completed/pending, and error (if failed).","operationId":"getJobStatus","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Job ID returned from start_enrichment"}],"responses":{"200":{"description":"Job status","content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string"},"status":{"type":"string","enum":["queued","processing","complete","failed"]},"progress":{"type":"number","minimum":0,"maximum":100},"records_processed":{"type":"number"},"records_total":{"type":"number"},"sources_completed":{"type":"array","items":{"type":"string"}},"sources_pending":{"type":"array","items":{"type":"string"}},"error":{"type":"string","description":"Error message if status=failed"},"message":{"type":"string"}}}}}},"404":{"description":"Job not found"}}}},"/api/jobs/{id}/results":{"get":{"tags":["Results"],"summary":"Get enriched results","description":"Returns array of EnrichedCompany objects for a completed job. Format: json (default) or csv. Each result includes 12+ fields: company_name, website, email, phone, linkedin, duns, ein, vat, cnpj, employees, revenue, sic_code, company_number, accuracy (per-field confidence 0.0-1.0).","operationId":"getResults","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Job ID returned from start_enrichment"},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["json","csv"]},"description":"Output format (default: json)"}],"responses":{"200":{"description":"Enriched results","content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string"},"format":{"type":"string"},"results":{"type":"array","items":{"$ref":"#/components/schemas/EnrichedCompany"}},"total":{"type":"number"},"message":{"type":"string"}}}},"text/csv":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Job not found"},"409":{"description":"Job not yet complete"}}}},"/api/enrich/single":{"post":{"tags":["Single"],"summary":"Enrich single company","description":"Real-time enrichment of a single company name (no batch needed). Returns EnrichedCompany object with website, email, phone, linkedin, duns, ein (where available). Useful for ad-hoc lookups. Rate limited to 60 req/min. Person-level data (person_name, person_title, person_email, person_mobile) is on the roadmap — ships with Hunter + Apollo integrations.","operationId":"enrichSingle","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"company_name":{"type":"string","minLength":2,"description":"Required"},"country":{"type":"string","description":"Optional country hint (ISO 3166-1 alpha-2, e.g., US, UK, BR, MX)."}},"required":["company_name"]}}}},"responses":{"200":{"description":"Enriched company","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichedCompany"}}}},"400":{"description":"Invalid input (company_name < 2 chars)"},"429":{"description":"Rate limit exceeded (60 req/min)"}}}},"/api/verify/{taxId}":{"post":{"tags":["Verify"],"summary":"Verify a tax ID","description":"Verify a single tax ID against its official registry. Supported codes: DUNS, EIN, RUC, VAT, CNPJ, RFC, RUT, NIF, ABN, CIN, company_number, sic_code. Returns valid/invalid + company_name + address (where available). Routing: SAM.gov for EIN/UEI/DUNS, OpenCorporates for company_number, ReceitaWS for CNPJ, VIES/VATSense for EU VAT.","operationId":"verifyTaxId","parameters":[{"name":"taxId","in":"path","required":true,"schema":{"type":"string","enum":["DUNS","EIN","RUC","VAT","CNPJ","RFC","RUT","NIF","ABN","CIN","company_number","sic_code"]},"description":"Tax ID code (case-sensitive)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"value":{"type":"string","description":"The tax ID value to verify (raw or formatted)."}},"required":["value"]}}}},"responses":{"200":{"description":"Verification result","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"value":{"type":"string"},"valid":{"type":"boolean"},"company_name":{"type":"string","description":"Returned when valid=true"},"address":{"type":"string","description":"Returned when valid=true"},"message":{"type":"string"}}}}}},"400":{"description":"Invalid input (unsupported code, malformed value)"}}}},"/api/mcp":{"post":{"tags":["MCP"],"summary":"MCP server endpoint (JSON-RPC 2.0)","description":"HTTP MCP server with 8 tools for AI agent integration (Claude, Cursor, Cline). Methods: initialize, tools/list, tools/call. Tools: list_sources, upload_csv, start_enrichment, get_job_status, get_results, export_csv, enrich_single, verify_tax_id. Mirrors the REST API surface.","operationId":"mcp","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"type":["string","number"]},"method":{"type":"string","enum":["initialize","tools/list","tools/call"]},"params":{"type":"object","properties":{"name":{"type":"string","description":"Tool name (for tools/call)"},"arguments":{"type":"object","description":"Tool arguments (for tools/call)"}}}},"required":["jsonrpc","method"]}}}},"responses":{"200":{"description":"JSON-RPC response"}}},"get":{"tags":["MCP"],"summary":"MCP server info","description":"Returns MCP server metadata: name, version, description, protocol, transport, tools list, documentation URL, openapi URL.","operationId":"mcpInfo","responses":{"200":{"description":"Server metadata"}}}}},"components":{"schemas":{"EnrichedCompany":{"type":"object","properties":{"company_name":{"type":"string","description":"Original input column"},"website":{"type":"string","description":"Canonical company domain (e.g., stripe.com)"},"email":{"type":["string","null"],"description":"Verified email via 3-stage SMTP+MX check"},"phone":{"type":["string","null"],"description":"E.164 normalized phone"},"linkedin":{"type":["string","null"],"description":"LinkedIn company page URL (official API only)"},"duns":{"type":["string","null"],"description":"Dun & Bradstreet Number (9-digit)"},"ein":{"type":["string","null"],"description":"USA Employer ID (XX-XXXXXXX)"},"vat":{"type":["string","null"],"description":"EU VAT (e.g., DE123456789)"},"cnpj":{"type":["string","null"],"description":"Brazil (XX.XXX.XXX/XXXX-XX)"},"person_name":{"type":["string","null"],"description":"Roadmap — ships with Hunter + Apollo integrations. Decision-maker name."},"person_title":{"type":["string","null"],"description":"Roadmap — ships with Hunter + Apollo integrations. Decision-maker title."},"person_email":{"type":["string","null"],"description":"Roadmap — ships with Hunter + Apollo integrations. Verified decision-maker email."},"person_mobile":{"type":["string","null"],"description":"Roadmap — ships with Hunter + Apollo integrations. Direct-dial decision-maker mobile (E.164)."},"employees":{"type":["string","null"],"description":"Bucket or numeric (e.g., 1,000-5,000 or 8500)"},"revenue":{"type":["string","null"],"description":"Annualized USD (e.g., $14.4B)"},"sic_code":{"type":["string","null"],"description":"USA industry classification (4-digit)"},"company_number":{"type":["string","null"],"description":"UK Companies House (e.g., OC123456)"},"accuracy":{"type":"object","description":"Per-field confidence 0.0-1.0","additionalProperties":{"type":"number"}}},"required":["company_name"]}}}}