01
Stable JSON
--json on every command. Same fields, same shapes, every run. Your agent parses output instead of guessing at it.
ctc whois jane@acme.com --json
Agent-first B2B contact data
Find, verify, and enrich B2B contacts. One command per job.
ContactCTL is the contact-data CLI built for AI agents: stable JSON, exit codes you can branch on, hard cost caps. Install it once — your agent handles every lookup from there.
$ npm install -g contactctl
claude — ~/outbound
$ ctc find "Jane Smith" acme.com --json
{
"status": "found",
"contacts": [{
"value": "jane.smith@acme.com",
"status": "deliverable",
"confidence": 0.98
}],
"cost": { "actual_credits": 1 },
"run_id": "7c9e6679-7425-…"
}
$ ctc phone "Jane Smith" acme.com --estimate
estimated_credits: 10
charged only if found — a miss is free
$
01 — Built for agents
Six guarantees an agent can build on
An agent spending your money needs contracts, not vibes. Every ContactCTL command honors the same six.
02
Deterministic exit codes
Found, not found, bad input, out of credits — each maps to its own exit code. Branch in shell without reading prose.
ctc verify jane@acme.com; echo $?
03
Spend previews
--estimate prints what an action would cost and exits. Zero credits spent, no surprises on a 5,000-row file.
ctc find leads.csv out.csv --estimate
04
Hard cost caps
--max-cost stops a job before it can exceed the cap. The agent gets a budget instead of a blank check.
ctc phone in.csv out.csv --max-cost 50
05
No prompts, ever
Nothing waits for a keypress. Every command runs clean under cron, CI, and unattended agents.
ctc verify list.csv clean.csv
06
Self-describing
contactctl instructions is a ~60-line usage guide. An agent reads it once and knows the whole tool — no schemas in context.
ctc instructions
It is a native CLI, not an MCP server — instant startup, zero standing context cost, composable with pipes and cron. The reasoning is on the CLI vs MCP page; the full surface is on the CLI page.
02 — The surface
Every command, every printed price
One verb per job. Each command fans out across 20+ premium data sources in a waterfall — you see one command and one price.
| Command | Does | Credits |
|---|---|---|
| Single lookup | ||
ctc verify <email> | is this address deliverable? | 0.02 credits |
ctc find <name> <domain> | work email for a known person | 1 credit · miss free |
ctc find <name> <domain> --personal | personal email instead | 3 credits · miss free |
ctc phone <name> <domain> | mobile phone number | 10 credits · miss free |
ctc whois <email> | person and company behind an email | 1 credit · miss free |
| Bulk — CSV in, CSV out | ||
ctc find leads.csv enriched.csv | batch any lookup; row order preserved | same per-row rates · miss free |
| Search and lookalikes | ||
ctc search people --domain acme.com | people at a named company | 0.25 credits / search |
ctc search companies --industry <i> | companies by attributes | 0.25 credits / search |
ctc lookalike hubspot.com | similar companies | 0.35 credits / row |
ctc lookalike <linkedin_url> | similar people | 0.35 credits / row |
| Free helpers | ||
ctc search filters | accepted filter fields and values | free |
ctc instructions | the agent usage guide | free |
ctc usage | balance and recent spend | free |
Aliases contactctl and ctc are equivalent. Full flags, exit codes, and JSON shapes in the docs.
03 — Billing physics
Charged only when a result is found
find, phone, and whois charge only when a result is found. A clean miss costs nothing.
Most data tools bill the attempt. That punishes exactly the behavior you want from an agent: probing long-shot leads, sweeping a 500-row list, retrying with a second spelling.
ContactCTL bills the result. Your agent can be thorough on list building and CRM enrichment because the worst case of a lookup is a free answer: not found.
Combined with --estimate and --max-cost, spend is bounded before a batch starts and
audited after it ends — ctc usage prints the ledger.
| Lookup | Result found | Clean miss |
|---|---|---|
ctc find <name> <domain> | 1 credit | free |
ctc find ... --personal | 3 credits | free |
ctc phone <name> <domain> | 10 credits | free |
ctc whois <email> | 1 credit | free |
Misses are logged for fair use, never billed.
04 — How it works
You do steps one and two. Your agent does the rest.
01
Subscribe
Pick a plan — they differ only in credit volume. Your API key is on the dashboard, shown once.
See plans02
Install and authenticate
One npm package, two aliases: contactctl and ctc. The key is stored locally with 0600 permissions.
npm install -g contactctl contactctl auth <your_key>Install guide
03
Hand it to your agent
The agent reads the built-in guide once, then runs every lookup itself — single, batch, or scheduled.
contactctl instructionsRead the docs
05 — Where it fits
Pick your entry point
06 — Pricing
Three plans. The only variable is volume.
Same commands and same guarantees on every plan — only the monthly credit count and top-up rate change.
Starter
€9 /month
150 credits / month
For one agent doing real work.
- work emails
- 150
- or verifications
- 7,500
- or phone numbers
- 15
- top-up rate
- €0.060/credit
Growth
most common€55 /month
1,000 credits / month
For weekly list building and CRM upkeep.
- work emails
- 1,000
- or verifications
- 50,000
- or phone numbers
- 100
- top-up rate
- €0.055/credit
Scale
€250 /month
5,000 credits / month
For agencies and pipelines that run daily.
- work emails
- 5,000
- or verifications
- 250,000
- or phone numbers
- 500
- top-up rate
- €0.050/credit
EUR, monthly, cancel anytime. Same commands on every plan — only the credit count changes. Top-ups from €5.
Per-action costs, top-up rules, and the cancellation policy in plain words: pricing.
07 — Questions
Asked before subscribing
What is ContactCTL?
A command-line tool that finds, verifies, and enriches B2B contact data. You subscribe and install it once; from then on your AI agent — Claude Code, Codex CLI, Cursor, Gemini CLI, or anything that can run a shell command — handles contact lookups itself.
How does an AI agent actually use it?
The agent runs contactctl instructions once: about 60 lines covering every command, credit cost, and exit code. From then on it calls commands like ctc find and ctc verify directly, with --json for stable output, --estimate to preview cost before spending, and --max-cost to cap a batch.
How do credits work?
Every plan uses the same meter. A verification is 0.02 credits, a work email is 1 credit, a mobile phone is 10 credits. Plans start at €9/month for 150 credits, and the full per-action table is on the pricing page.
What happens when a lookup finds nothing?
find, phone, and whois charge only when a result is found. A clean miss costs nothing. Search is billed per request and lookalikes per returned row, exactly as printed in the cost table.
Is this an MCP server?
No, deliberately. A native CLI starts instantly, costs zero context window, and composes with pipes, files, and cron. It also runs fine alongside MCP-based stacks — any agent that can execute a shell command can use it. The full reasoning is on the CLI vs MCP page.
Where does the data come from?
Each lookup runs a waterfall across 20+ premium data sources behind one command, and verification checks deliverability before you ever send. We do not publish the supplier list; every result carries a confidence score and verification status you can act on.
What will it not do?
ContactCTL does not scrape websites, automate LinkedIn, or send outreach. It resolves contact data for people and companies you already know about, plus tightly scoped search and lookalikes, with a GDPR/CCPA-aware posture.
Do I need to be technical to use it?
If you can paste one block of text to your agent, no. The install page includes a copy-paste prompt; your agent installs the CLI, authenticates, and runs every lookup from there.
$ ctc find "your next customer"