API & MCP

New Pre-built Claude skills are here. Set up Claude and Kolvera end to end — then run your whole workflow just by chatting. Get the skills →

Four Ways to Connect

MCP Server 187 tools. Talk to Kolvera through Claude, Cursor, or any AI assistant in plain English.

REST API v2 60 JSON endpoints. Build integrations, connect to Zapier/Make, or sync with your tools.

Webhooks 18 real-time events. Get notified when prospects reply, credits run low, research completes.

CLI Tool 20 commands. Pipe JSON to jq, batch operations, automate with cron.

MCP Server Setup

Recommended

MCP (Model Context Protocol) lets AI assistants use Kolvera as a tool. You describe what you need in plain English — the AI calls the right tools behind the scenes.

Option A: Connector URL (claude.ai & Claude Desktop)

No API token needed. Add Kolvera as a connector and sign in once to authorise.

https://mcp.kolvera.io/mcp

Open Settings → Connectors in Claude
Click Add custom connector and paste the URL above
Sign in to Kolvera and click Authorise — done

Option B: API Token (Claude Code, Cursor, Windsurf)

For clients that use config files. Create a token at Settings → API Tokens, then add to your config:

{
  "mcpServers": {
    "kolvera": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.kolvera.io/mcp?token=kv_your_token"
      ]
    }
  }
}

File locations: Claude Desktop: claude_desktop_config.json (Settings → Developer → Edit Config). Claude Code / Cursor / Windsurf: .mcp.json in project root.
Requires: Node.js (any recent version) for npx mcp-remote.

All 187 MCP Tools

You don’t need to memorise these — describe what you want and the AI picks the right tool. Grouped by category below.

Contacts & Enrichment (13 tools)

search_contacts — search by name, title, email, company. Filter by has_email, has_phone, is_prospect

get_contact — full detail with company, email status, phone, LinkedIn, notes

create_contact — add a contact, optionally link to company and mark as prospect

update_contact — edit name, title, email, phone, location, notes, target role

delete_contact — permanently remove a contact and all linked records

find_contact_email — multi-source email enrichment (2cr on success)

find_contact_phone — phone enrichment: cached → native → directory (2-6cr on success)

verify_contact_email — verify an existing email address (free)

bulk_find_emails — find emails for multiple contacts at once (2cr each on success)

bulk_find_phones — find phones for multiple contacts at once (2-6cr each on success)

batch_find_contacts — find contacts at multiple companies in one call (2cr per contact found)

list_profile_suggestions — AI-suggested profile updates from meeting transcripts

Companies (9 tools)

search_companies — search by name, domain, industry, state, BD status, location

get_company — full detail with contact count, domain, ABN, phone

create_company — add a company with name, domain, industry, location

get_company_contacts — paginated list of contacts at a company

update_company — edit industry, phone, location, BD status, notes, do-not-contact flag

delete_company — permanently remove a company (requires confirm=true)

research_company — AI research: hiring signals, growth, industry context (1cr)

find_company_contacts — find contacts at a company via enrichment providers (2cr per found)

Campaigns & Outreach (20 tools)

list_campaigns — all campaigns with enrolled/sent/opened/replied stats

get_campaign — campaign detail with email steps, variants, and performance

get_campaign_stats — open rate, reply rate, bounce rate for a campaign

get_campaign_enrollments — list enrolled contacts with status and next send time

create_campaign — create a draft campaign, optionally link an ICP for AI context

update_campaign — edit name, settings, timezone, daily limits

delete_campaign — permanently remove a draft campaign

duplicate_campaign — clone a campaign with all email steps (no enrolments copied)

create_campaign_step — add an email step with subject, body, delay

update_campaign_step — edit subject, body, delay for a specific step

delete_campaign_step — remove a step from the sequence

generate_campaign_steps — AI-generate a multi-step email sequence using your ICP and business context (free)

get_campaign_generation_status — poll async step generation progress

enrol_contacts_in_campaign — add contacts by ID, with dedup and blocklist checks

unenrol_from_campaign — remove contacts from a campaign

activate_campaign — start sending (requires confirm=true, preview returned by default)

pause_campaign — stop sending (only works on active campaigns)

resume_campaign — restart sending (only works on paused campaigns)

list_inboxes — list connected SMTP inboxes available for campaigns

assign_inbox_to_campaign — assign sending inboxes to a campaign

Deep Research (4 tools)

trigger_deep_research — discover companies matching a brief. Link an ICP for tighter results. Runs async (6cr)

expand_deep_research — find MORE companies from the same brief, excluding duplicates (4cr)

get_research_report — results with discovered companies, market insights, and sources

list_research_reports — all past research reports

Ideal Client Profiles (17 tools)

list_icp_profiles — all ICP profiles with prospect counts

get_icp_profile — profile detail with company map and criteria

get_icp_readiness — at-a-glance desk readiness: profile / monitoring / companies / contacts / campaign chips (green/amber/red) plus a ready flag

list_icp_prospects — prospects linked to an ICP, with email status filter

create_icp_profile — define target industries, locations, company sizes, and titles manually. Accepts recruited_roles (the free-text "Roles I Recruit" field).

update_icp_profile — edit title, industries, locations, sizes, titles, keywords

generate_icp_profile — AI-generate from a brief: pain points, value prop, differentiators, objection handling (2cr)

archive_icp_profile — soft delete (prospects preserved, ICP hidden)

delete_icp_profile — permanent delete (prospects unlinked, company map deleted)

link_prospect_to_icp — link a prospect (buyer) to an ICP’s prospect list

bulk_link_prospects_to_icp — link multiple prospects to an ICP’s prospect list in one call

unlink_prospect_from_icp / bulk_unlink_prospects_from_icp — remove one / many prospects’ ICP link in a single call (max 500)

link_candidate_to_icp / bulk_link_candidates_to_icp — add candidates (placeable people) DIRECTLY to an ICP’s talent pool (no Reverse Market Profile needed; deduped; max 500). unlink_candidate_from_icp removes them.

link_company_to_icp — add a company to an ICP’s company map with tier

bulk_link_companies_to_icp — add multiple companies to an ICP’s company map in one call

unlink_company_from_icp — remove a company from an ICP’s company map

bulk_unlink_companies_from_icp — remove multiple companies from an ICP’s company map in one call

Prospects (buyers) belong on the ICP prospect list; candidates (placeable people) belong in the ICP talent pool (a direct candidate↔ICP membership). The link tools reject a wrong-type contact — only genuinely dual-role people may sit in both.

Linking — Recommended (2 tools)

link_entity — single facade for linking a contact, prospect, candidate, company, or ICP onto an ICP or Reverse Market Profile. Pass entity_type, entity_ids, target_type (icp / reverse_market_profile), target_id, and an optional tier

unlink_entity — the inverse of link_entity, same parameters

link_entity / unlink_entity are the recommended primary tools for all linking going forward. The individual link_*_to_icp / link_*_to_reverse_market_profile tools listed above and below (and their bulk_* / unlink_* counterparts) remain fully supported as deprecated aliases — existing integrations do not need to change.

Hot Lists (9 tools)

list_hot_lists — all curated lists with member counts

get_hot_list — list members with contact/company details, paginated

create_hot_list — create a new curated list

update_hot_list — edit hot list name and description

add_to_hot_list — add contacts, prospects, candidates, or companies by ID with optional tier, status, and notes

remove_from_hot_list — remove members from a hot list

delete_hot_list — permanently delete a hot list

update_hot_list_member — update tier (S/A/B), status (not_started → connected → lvm → replied → meeting_booked → converted), source, or notes

build_target_hotlist — build a hot list from ICP companies using Target Scoring (7-signal weighted composite, S/A/B tiers)

Reverse Market Profiles (17 tools)

list_reverse_market_profiles — all Reverse Market Profiles with company/candidate counts

get_reverse_market_profile — detail with must-haves, move triggers, disqualifiers

create_reverse_market_profile — define a target role manually. Accepts target_hiring_titles (the hiring-manager titles to map against).

update_reverse_market_profile — edit title, sectors, employers, locations, must-haves, disqualifiers, tone, ICP link

delete_reverse_market_profile — permanent delete

generate_reverse_market_profile — AI-generate from a role title: title variants, move triggers, objections, LinkedIn boolean (1cr)

regenerate_reverse_market_profile — re-run AI generation on an existing profile (1cr)

list_reverse_market_profile_candidates — list candidates in the pool

link_candidate_to_reverse_market_profile — link an existing contact as a candidate to a Reverse Market Profile

bulk_link_candidates_to_reverse_market_profile — link multiple existing contacts as candidates in one call (max 200)

unlink_candidate_from_reverse_market_profile — remove a candidate’s Reverse Market link

list_reverse_market_profile_prospects — mapped hiring-manager prospects

link_prospect_to_reverse_market_profile — map a hiring-manager prospect to a profile

unlink_prospect_from_reverse_market_profile — bulk-remove prospects from a profile

link_company_to_reverse_market_profile — add a company to the profile’s company map

bulk_link_companies_to_reverse_market_profile — add companies in bulk (tier: direct_fit / adjacent_fit / speculative)

unlink_company_from_reverse_market_profile — remove a company from the company map

Business Contexts (6 tools)

list_business_contexts — all business contexts with primary flag

create_business_context — add manually (name, what you sell, buyers, voice, pricing)

create_business_context_from_website — auto-generate from a URL — scrapes and extracts context

update_business_context — edit context fields

delete_business_context — remove a business context

set_primary_business_context — set which context is used by default for AI generation

Job Board Scraping (10 tools)

run_job_scrape — scrape SEEK, Indeed, LinkedIn, or Reed for live job listings. Optionally link an ICP for auto-config

run_saved_config — re-run an existing saved search config

get_scrape_progress — poll scrape status (percent, phase, new/skipped counts)

list_scrape_configs — all saved search configs

get_scrape_config — detail of a saved config with keywords, locations, excludes

update_scrape_config — edit keywords, locations, exclude terms, SEEK classification

archive_scrape_config — soft-archive a search config

delete_scrape_config — permanently delete a config (requires confirm=true)

analyze_scrape_quality — quality analysis of scraped job results with noise metrics

update_search_config_excludes — update exclude keywords and companies on a search config

Pipeline (3 tools)

search_pipeline_jobs — search scraped jobs by title, company, state, sector, source

get_pipeline_job — full job detail with salary, location, posting date

bulk_dismiss_pipeline_jobs — dismiss every relevant Pipeline Match for an ICP in one call

Lead Discovery (2 tools)

list_new_leads — the New Leads tab: keyword-matched quality roles at companies not yet mapped to a profile. Takes profile_id and profile_type (icp or reverse_market_profile)

dismiss_lead — dismiss a surfaced lead by job_id so it no longer appears under New Leads

Meetings & Fathom (7 tools)

list_meetings — upcoming or all meetings, with contact info

get_meeting — meeting detail with Google Meet link, contact, notes

create_meeting — schedule a meeting with title, time, contact, location

update_meeting — edit meeting title, time, notes, or status

delete_meeting — permanently delete a meeting

sync_fathom_meetings — sync meeting recordings from Fathom

list_fathom_notes — meeting summaries from Fathom, optionally filtered by contact

Credits & Enrichment Status (4 tools)

get_credit_balance — plan balance + addon balance + total

get_credit_history — paginated transaction log with action filter

get_bulk_enrichment_status — check progress of running bulk enrichment operations

get_enrichment_job — detailed status of a specific enrichment job by key

Terms of Business (4 tools)

generate_tob — draft a Terms of Business for a client from a template (fee, rebate, payment terms)

send_tob — send the TOB to the client for signature

get_tob_status — track sent, viewed, and signed status

list_tob_templates — list available TOB templates

Reference Checks (4 tools)

create_reference_form — build a reference questionnaire for a candidate

send_reference_requests — email the form to nominated referees

get_reference_status — track which referees have responded

compile_reference_report — assemble completed responses into a shareable report

Meeting Prep (4 tools)

generate_meeting_prep — AI brief for an upcoming client/prospect meeting

get_meeting_prep — retrieve a generated meeting brief

generate_candidate_call_prep — AI brief for a candidate call

get_candidate_call_prep — retrieve a generated candidate-call brief

Post-call Processing (1 tool)

process_post_call — turn a call transcript into structured notes, next actions, and profile suggestions

Review Queue / Action Inbox (6 tools)

list_pending_actions — the Action Inbox (reached in-app via the Command Station on the dashboard, not the sidebar): AI-proposed actions awaiting approval

get_pending_action — get a single pending action

approve_pending_action — execute a pending action

dismiss_pending_action — clear a pending action

run_reengagement_sweep — queue re-engagement actions for stale records

list_stale_candidates — list candidates due for re-engagement

Report Sharing (2 tools)

enable_report_sharing — mint a public share link for an Intelligence or candidate report

disable_report_sharing — revoke a report share link

Profile Suggestions (3 tools)

list_profile_suggestions — AI-suggested ICP/profile updates surfaced from calls

apply_profile_suggestion — apply a suggested update

dismiss_profile_suggestion — dismiss a suggestion

Real-World Use Cases

Build a target list and start outreach in one conversation

Method: MCP Server (Claude Desktop, claude.ai, or Claude Code)
You say: “Research Australian fintech companies in Melbourne with 20-50 employees. Create an ICP profile called Q3 Fintech, add the top companies to a hot list, find emails for all contacts, then enrol anyone with a verified email in my Q3 Campaign.”

What happens behind the scenes:

Claude calls trigger_deep_research with your brief (6cr)
Polls get_research_report until research completes
Creates ICP via create_icp_profile
Creates hot list via create_hot_list and adds companies via add_to_hot_list
Calls batch_find_contacts on the companies (2cr per contact found)
Enrols verified contacts via enrol_contacts_in_campaign

Result: A targeted campaign running against researched, enriched contacts — from one prompt.

Daily morning briefing via Claude

Method: MCP Server
You say: “Give me a morning rundown — how are my campaigns performing, do I have any meetings today, and what’s my credit balance?”

Claude calls list_campaigns (shows open/reply rates), list_meetings with upcoming_only, and get_credit_balance. Returns a summary like:

“Your Q2 .NET Campaign has a 42% open rate and 8% reply rate across 120 sends. You have 3 meetings today. Credit balance: 847 plan + 150 addon = 997 total.”

Ping Slack when a prospect replies

Method: Webhooks
Setup: Create a webhook for campaign.replied pointing at a Slack incoming webhook URL (or Zapier/Make trigger). Every time a prospect replies, Kolvera instantly sends their name, email, and campaign to your channel.

curl -X POST https://www.kolvera.io/api/v2/webhooks \
  -H "Authorization: Bearer kv_your_token" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.slack.com/your-hook",
       "events": ["campaign.replied", "campaign.bounced"],
       "secret": "my_signing_key"}'

Cost: Free. Webhooks never consume credits.

Ask Claude to manage your pipeline

Method: MCP Server
You say: “Show me all Python developer jobs in NSW, then find the companies posting them and check if we have contacts there.”

Claude calls search_pipeline_jobs with query “python” and state filter NSW, then for each unique company calls search_companies to find matches and get_company_contacts to show who you already know. Gives you a prioritised list of warm leads vs cold outreach targets.

Batch enrich contacts from a script

Method: REST API (Python example)

import requests, time

API = "https://www.kolvera.io/api/v2"
HEADERS = {"Authorization": "Bearer kv_your_token"}

# Get contacts missing emails
r = requests.get(f"{API}/contacts", headers=HEADERS,
                 params={"has_email": "no", "per_page": 50})
contacts = r.json()["contacts"]

for c in contacts:
    result = requests.post(
        f"{API}/contacts/{c['id']}/find-email",
        headers=HEADERS
    ).json()
    if result.get("email"):
        print(f"Found: {c['first_name']} {c['last_name']} -> {result['email']}")
    time.sleep(2)  # respect rate limits

Cost: 2cr per email found. Contacts where no email is found are free.

Get alerted when credits run low

Method: Webhooks
How: Subscribe to credit.low. When your balance drops below 10, Kolvera sends a webhook to your Slack channel or email so you can top up before your next enrichment run.

Weekly export of enriched contacts

Method: CLI + cron job

# Every Monday at 8am
0 8 * * 1 python kolvera_cli.py contacts search --has-email yes --per-page 500 | jq '.contacts' > weekly_contacts.json

Cost: Free. Reading data never uses credits.

REST API v2 — 60 Endpoints

Base URL: https://www.kolvera.io/api/v2
Auth: Authorization: Bearer kv_your_token (or OAuth access token)

v2 is Kolvera's public REST API — the one to build against. (/api/v1/ is the internal API used by the Kolvera Chrome extension, not a deprecated predecessor — it is not documented for external use.)

Contacts (7)

GET	`/contacts`	Search (?q=, &has_email=, &has_phone=, &is_prospect=, &sort=, &page=)
GET	`/contacts/:id`	Contact detail with company info
POST	`/contacts`	Create contact (auto-links or creates company)
PATCH	`/contacts/:id`	Update fields
DELETE	`/contacts/:id`	Delete contact
POST	`/contacts/:id/find-email`	Find email (2cr on success)
POST	`/contacts/:id/find-phone`	Find phone (2-6cr on success)

Companies (6)

GET	`/companies`	Search (?q=, &industry=, &state=, &bd_status=)
GET	`/companies/:id`	Company detail + contact count
GET	`/companies/:id/contacts`	Contacts at company (paginated)
PATCH	`/companies/:id`	Update fields
POST	`/companies/:id/research`	Run AI research on company (1cr)
POST	`/companies/:id/find-contacts`	Find contacts at company (2cr per found)

Campaigns (7)

GET	`/campaigns`	List with stats (?status=active)
GET	`/campaigns/:id`	Detail + email steps + stats
GET	`/campaigns/:id/stats`	Open / reply / bounce rates
POST	`/campaigns/:id/activate`	Activate a draft campaign
POST	`/campaigns/:id/pause`	Pause sending
POST	`/campaigns/:id/resume`	Resume sending
POST	`/campaigns/:id/enrol`	Enrol contacts `{contact_ids: [...]}`

Hot Lists (5)

GET	`/hot-lists`	List all hot lists
GET	`/hot-lists/:id`	Members with contact details (paginated)
POST	`/hot-lists`	Create `{name, description}`
POST	`/hot-lists/:id/members`	Add members `{source_ids: [...]}`
DELETE	`/hot-lists/:id/members/:mid`	Remove member

ICP Profiles (5)

GET	`/icp`	List all ICP profiles
GET	`/icp/:id`	Profile + company map + prospect count
POST	`/icp`	Create `{title, target_industries, target_locations, ...}`
POST	`/icp/generate`	AI-generate ICP profile (2cr)
PATCH	`/icp/:id`	Update profile criteria

Meetings (4)

GET	`/meetings`	List (?status=, &upcoming=true)
GET	`/meetings/:id`	Meeting detail + Google Meet link
POST	`/meetings`	Create `{title, starts_at_utc, duration_minutes, ...}`
PATCH	`/meetings/:id/status`	Update status (booked / attended / no_show / cancelled)

Pipeline & Research (5)

GET	`/pipeline`	Search jobs (?q=, &status=, &state=, &sector=)
GET	`/pipeline/:id`	Job detail
GET	`/research`	List research reports
GET	`/research/:id`	Report + discovered companies
POST	`/research`	Trigger Deep Research `{brief: "..."}` (6cr)

Credits & Webhooks (5)

GET	`/credits`	Plan + addon balance
GET	`/webhooks`	List webhook subscriptions
POST	`/webhooks`	Create `{url, events, secret}`
PATCH	`/webhooks/:id`	Update subscription
DELETE	`/webhooks/:id`	Remove subscription

Quick Test

curl -H "Authorization: Bearer kv_your_token" \
  "https://www.kolvera.io/api/v2/credits"

# Response:
# {"ok": true, "plan_balance": 847, "addon_balance": 150, "total": 997}

Webhooks — 18 Real-Time Events

Instead of polling the API, Kolvera sends a POST request to your URL the moment something happens. Connect to Slack, Zapier, Make, or your own server.

All 18 Events

Event	When It Fires	Data Included
`contact.created`	New contact added	Full contact object
`contact.updated`	Contact fields changed	Contact ID + changed fields
`contact.enriched`	Email or phone found	Contact ID, type, found data
`company.created`	New company created	Company ID + name
`company.updated`	Company fields changed	Company ID + changed fields
`campaign.activated`	Campaign started or resumed	Campaign ID + name
`campaign.paused`	Campaign paused	Campaign ID + name
`campaign.completed`	Contact finishes all steps	Campaign ID, contact ID
`campaign.replied`	Prospect replies	Campaign ID, contact details
`campaign.bounced`	Hard bounce detected	Campaign ID, email, error
`meeting.created`	Meeting scheduled	Full meeting object
`meeting.status_changed`	Status updated	Meeting ID, new status
`research.completed`	Deep Research finishes	Report ID, companies found
`credit.low`	Balance drops to 10 or below	Current balance, action
`email.opened`	Recipient opens a campaign email	Campaign ID, contact ID
`link.clicked`	Recipient clicks a tracked link	Campaign ID, contact ID, URL
`enrolment.complete`	Contact completes campaign enrolment	Campaign ID, contact ID
`scrape.complete`	Job-board scrape finishes	Config ID, new lead count

Verifying Signatures

If you set a secret, every webhook includes an X-Kolvera-Signature header (HMAC-SHA256 of the body):

import hmac, hashlib

def verify_signature(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Subscriptions auto-disable after 10 consecutive delivery failures.

CLI Tool — 20 Commands

Outputs JSON. Pipe to jq for formatting, save to files, or chain in shell scripts.

Setup

# Linux / Mac
export KOLVERA_API_KEY=kv_your_token

# Windows PowerShell
$env:KOLVERA_API_KEY = "kv_your_token"

Contacts

# Search with filters
python kolvera_cli.py contacts search "developer" --has-email yes --sort updated_at

# Get full contact detail
python kolvera_cli.py contacts get <contact_id>

# Find email (2cr if found)
python kolvera_cli.py contacts find-email <contact_id>

# Find phone (2-6cr if found)
python kolvera_cli.py contacts find-phone <contact_id>

Companies

# Search by industry and state
python kolvera_cli.py companies search "recruitment" --state VIC --industry "Staffing"

# List contacts at a company
python kolvera_cli.py companies contacts <company_id>

Campaigns, Research & Credits

# List active campaigns
python kolvera_cli.py campaigns list --status active

# Trigger Deep Research (6cr)
python kolvera_cli.py research trigger "AU fintech companies in Melbourne"

# Check credit balance
python kolvera_cli.py credits

OAuth 2.0 — For App Developers

Building an app that connects to Kolvera on behalf of other users? Use OAuth instead of API tokens.

Endpoints

Authorise	`GET /oauth/authorize`
Token	`POST /oauth/token`
UserInfo	`GET /oauth/userinfo`
Revoke	`POST /oauth/revoke`
Discovery	`GET /oauth/.well-known/openid-configuration`

23 Permission Scopes

contacts:read — view contacts

contacts:write — create/edit contacts

contacts:enrich — find emails/phones

companies:read — view companies

campaigns:read — view campaigns

campaigns:write — manage campaigns

pipeline:read — view jobs

pipeline:write — run scrapes & configs

research:read — view reports

research:write — run research

hot_lists:read — view lists

hot_lists:write — manage lists

icp:read — view ICP profiles

icp:write — manage ICP profiles

reverse_market_profile:read — view Reverse Market Profiles

reverse_market_profile:write — manage Reverse Market Profiles

meetings:read — view meetings

meetings:write — create meetings

webhooks:manage — manage webhooks

credits:read — view balance

settings:read — view settings & business contexts

settings:write — update settings & automations

profile:read — view user info

PKCE (S256) supported for public clients. Access tokens expire after 1 hour. Refresh tokens last 30 days.

Rate Limits & Credit Costs

Action	Rate Limit	Credit Cost
Search / list / view (any GET)	60-120/min	Free
Create / update / delete	10-30/min	Free
Find Email	30/min	2cr on success
Find Phone (direct dial)	30/min	6cr on success
Find Phone (company line)	30/min	2cr on success
Deep Research	5/min	6cr per run
Expand Research	5/min	4cr per run
Generate ICP Profile	10/min	2cr
Generate Reverse Market Profile	10/min	1cr
Company Research	10/min	1cr
Webhooks (receiving)	Unlimited	Free

Credits are only charged when data is actually found. Failed lookups are free. Check your balance anytime: GET /api/v2/credits or ask Claude “check my Kolvera credits.”