API & MCP — 383 AI Tools

Download developer guide

Keep the full Markdown guide to REST v2 endpoints, MCP setup, webhook events and payloads, signature checks, and retry rules.

Download Markdown developer guide

Qualified people sourcing pilot

When enabled, candidates and decision makers share an evidence-based search with an explicit role location and maximum credit charge. Candidate searches may span employers. Prospect searches require the current employer.

Read GET /api/v2/people/sourcing/quote, then submit POST /api/v2/people/sourcing/runs with a brief, a reusable idempotency_key and your approved max_credits. Poll GET /api/v2/people/sourcing/runs/{run_id} for evidence, delivery outcomes and exact charges. Resume a paused run with POST /api/v2/people/sourcing/runs/{run_id}/resume.

MCP: quote_person_sourcing, find_qualified_people, get_person_sourcing_run, resume_person_sourcing_run.

Prices come from the quote. Rejected or unconfirmed people attract no charge. Qualification purchases are reused across sourcing intents; a new valid email is a separate component. The existing Find Contacts API retains its existing billing.

Four Ways to Connect

MCP Server 383 tools for Claude, Cursor and other MCP clients.

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

Webhooks 18 event types. 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 call Kolvera tools from your plain-English instructions.

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 383 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 (20 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

upload_candidate_cv — attach a PDF or Word CV to a candidate using base64 content and an idempotency key

get_contact_activity — read prospect context and paginated outreach history; requires contact and conversation access

search_conversations — search what was said on calls and in meetings, and get back who said it

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 — cached → native → directory phone lookup (2cr fresh)

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 (2cr each fresh)

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

get_employment_processing — candidate processing status and actions

retry_employment_processing — retry with current revisions; preserve history

preview_employment_changes — compare proposed roles, evidence and saved history

review_employment_changes — apply user-approved changes, or dismiss

refresh_employment_review — refresh stale review without another AI call

Requires an enabled workspace pilot. Reads: contacts:read; changes: contacts:write. Retry requires verified email; transcript changes require human approval.

Companies (52 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)

merge_companies — fold a duplicate company into the one you keep (requires confirm=true)

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

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

list_client_jobs — roles you’re actively recruiting at client companies; include archived history when needed

get_agency_job_board — Read tenant branding and recruiter board-link IDs.

create_agency_job_board — Create a board link; does not publish jobs or send messages.

set_agency_board_colour — Tenant admin: set colour and exact HTTPS embed origin. Upload logos in Jobs.

get_job_board_listing — Read listing copy, approval and visibility for an accessible job.

save_job_board_listing — Save candidate-facing copy against an approved role brief; unlists prior copy. Approve after recruiter review.

set_job_board_visibility — Publish or unlist reviewed copy with its expected revision.

list_job_board_applications — Read applications and CV metadata for an accessible job. CV downloads require authenticated web access.

review_job_board_application — Set New, Reviewed or Declined; no messages or client submission.

list_job_applications — read application evidence and review or Person-link status for one accessible Job

review_job_application — set an application to New, Reviewed or Declined independently of client submission

preview_application_person_handoff — preview visible Person matches and accessible Desks before linking

link_application_to_existing_person — link a reviewed application to a selected visible Person and Desk; does not create a Person or submit to client

get_client_job — full detail for a client role, including its brief and commercial fields

prepare_candidate_submission — select or create a client job for a Desk candidate; keeps preparation private and off the job shortlist

list_client_job_role_brief_sources — accessible calls, messages, documents and email snippets for a role

generate_client_job_role_brief — create cited draft from selected sources

list_client_job_role_briefs — read draft and approved versions, source coverage and access status

revise_client_job_role_brief — edit draft with citation confirmation

review_client_job_role_brief — submit source-current draft for approval

approve_client_job_role_brief — freeze reviewed version after coverage and conflict acknowledgements

get_candidate_role_fit — read latest CV evidence assessment and stale state for one shortlisted candidate

assess_candidate_role_fit — explain supported, contradicted and unknown requirements with CV citations and screening questions

list_candidate_role_outreach — read role-specific email and LinkedIn drafts, queue state and sender choices

draft_candidate_role_outreach — generate reviewable copy from approved shareable facts, without queuing

enrol_candidate_role_outreach — approve a preview and manually queue one role outreach action

stop_candidate_role_outreach — cancel unsent role outreach and linked queue work

list_placement_follow_ups — read candidate and client actions linked to one confirmed placement

correct_placement_follow_up_dates — reschedule pending actions after a reviewed start or guarantee date correction

list_client_job_shortlist — visible candidate stage history for one client role

list_client_job_shortlist_events — visible append-only shortlist activity for one client role

add_client_job_shortlist_candidate — prepare candidate on linked Desk; review submission before client shortlist entry

update_client_job_shortlist_status — move a retained candidate through interview, submission, offer, placement, decline, or withdrawal

update_client_job_shortlist_notes — save private recruiter screening notes on a client role’s job file

withdraw_client_job_shortlist_candidate — retain history while marking a candidate withdrawn

remove_client_job_shortlist_candidate — remove a candidate after confirm=true while retaining audit history

restore_client_job_shortlist_candidate — restore a removed current outcome by its exact shortlist ID; does not resend

start_new_shortlist_outcome — reserved for a fresh outcome after reversal; writes are currently unavailable

get_today_candidate_pipeline — permission-scoped Submitted-to-Placed candidate Kanban for Today

create_client_job — add a client role with role requirements, placement details, and AUD fee terms

update_client_job — update a client role’s brief, placement details, or commercial fields

archive_client_job — archive a client role without changing its underlying status

create_client_job_role_desk — create one owned role Desk for an active client role

Offer Summaries (4 tools)

get_offer_onepager_options — read structured offer facts, visible recipients, owned inboxes and saved versions

create_offer_onepager_version — freeze a reviewed candidate PDF and email version without sending

get_offer_onepager_pdf — preview the exact saved PDF

send_offer_onepager — send one reviewed version to its saved client recipient

Notetaker and Reviewed Meeting Workflows (20 tools)

Meeting reads respect source access. Advanced reviewed workflows remain unavailable during the core pilot; registration does not grant access or authorise delivery.

get_conversation — Read an authorised conversation, transcript and summary.

get_notetaker_settings — Read calendar coverage and Notetaker consent settings.

list_meeting_notes — List authorised meeting notes, including unlinked conversations.

preview_private_profile_suggestion — Preview a source-bound profile suggestion for review.

preview_private_rmp_refresh — Preview a private Reverse Market Profile refresh.

approve_private_rmp_refresh — Approve an exact private profile refresh revision.

preview_private_rmp_targets — Preview targets from an authorised private profile.

select_private_rmp_targets — Select reviewed private profile targets.

review_private_rmp_matching — Review a private profile matching plan.

approve_private_rmp_matching — Approve an exact private matching revision.

dismiss_private_rmp_leads — Dismiss selected private profile leads.

generate_private_float_draft — Generate a private, source-bound Float draft.

edit_private_float_draft — Edit an exact private Float draft revision.

generate_private_post_call_plan — Generate a private post-call plan for review.

get_private_post_call_plan — Read an authorised private post-call plan.

edit_private_post_call_plan — Edit an exact private post-call plan revision.

dismiss_private_post_call_plan — Dismiss a private post-call plan.

get_private_float_draft — Read an authorised private Float draft.

generate_client_submission_email_draft — Generate a reviewed client-submission email draft.

approve_public_job_listing — Approve an exact job listing revision for publication.

Candidate Referral Offers (5 tools)

get_candidate_referral_offers — read status, programme terms, email defaults and saved offers

prepare_candidate_referral_offer — save an editable A$500 or A$1,000 email and matching programme PDF

get_candidate_referral_pdf — preview the exact saved programme PDF

send_candidate_referral_offer — send the saved email with its PDF after explicit review and approval

decline_candidate_referral_offer — record a declined offer without changing candidate pipeline stages

Campaigns & Outreach (21 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 a Desk 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 Desk 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

list_campaign_variables — every personalisation token that actually resolves, with labels, examples, aliases and the supported syntax (, conditionals, spintax). Call this before writing step copy

Deep Research (4 tools)

trigger_deep_research — discover companies matching a brief. Link a Desk 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

Desks (32 tools)

list_icp_profiles — all Desks 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. Returns a profile_id straight away and builds in the background (3cr)

get_icp_generation_status — poll an async desk generation: pending, complete (with the profile), or failed

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

activate_desk — upgrade an ICP into a live Desk: classifies its mapped companies so Discovery and the desk-health meters populate

diagnose_desk — health report explaining why a desk’s discovery queue is noisy (over-broad sectors, unsized companies)

list_icp_companies — companies on the desk’s company map — lean and paginated, no profile payload

list_icp_candidates — candidates in the desk’s Talent Pool

set_talent_pool_status — set one or more candidates’ Talent Pool status on a desk (sourced, applied, LVM, scheduled call back, interested, internal IV, client IV, offered, offer accepted, placed, not interested, rejected) — per desk, so it never changes their status on another client

copy_prospects_between_icps — link every prospect from one desk to another without passing hundreds of IDs

move_companies_between_icps — atomically move companies from one desk to another

split_icp — move matching companies (and their prospects) into a destination desk in one action

merge_desks — fold one desk into another, carrying companies, prospects, candidates and campaigns across

resolve_desk_company — confirm, dismiss, or reassign a company on a desk, same as the inline card action

update_icp_role — update a single role in the desk’s role taxonomy by role_key, without replacing the whole array

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.

Sub-Niches (6 tools)

suggest_sub_niches — AI-suggest 2-5 sub-niches from the desk profile and a sample of its companies, then auto-classify untagged companies (1cr)

add_sub_niche — add a chip to the desk’s sub-niche taxonomy

rename_sub_niche — rename a chip’s label only; the key stays stable so every filed company keeps its tag

retire_sub_niche — retire a chip from filing pickers while companies already filed under it keep their tag

set_company_sub_niche — file one desk company under a sub-niche, or clear its tag

bulk_set_company_sub_niche — bulk-file desk companies under one sub-niche, or bulk-clear their tags

Pipeline Orchestration (4 tools)

declare_pipeline — map a new target market from a one-line brief: creates the Desk, seeds the taxonomy, and starts populating (3cr)

pipeline_status — the whole-pipeline board: every segment’s stage with a plain stage_label, the recommended next step, and anything stalled

pipeline_advance — move one segment to its next pipeline stage once the current stage is done

refresh_pipeline — maintenance pass: sort newly landed companies into segments, expire stale hiring signals, suggest tiers

These are agent-facing: the stage names are an internal state machine, not user-facing vocabulary. There is no matching UI rail — use stage_label when showing progress to a person.

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 (23 tools)

list_reverse_market_profiles — all Reverse Market Profiles with company/candidate counts

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

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

delete_reverse_market_profile — permanent delete

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

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

link_icp_to_reverse_market_profile / unlink_icp_from_reverse_market_profile — link or unlink desks against a Reverse Market Profile (max 200). Deprecated aliases — prefer link_entity / unlink_entity

diagnose_rmp — health-check a Reverse Market Profile, the RMP twin of diagnose_desk

ingest_scraped_profiles — ingest a batch of LinkedIn-scraped people into the pipeline

generate_anonymised_profile — build a blind (anonymised) candidate profile and return a public share link

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 (13 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

get_icp_monitoring — read a desk’s Job Board Monitoring state

set_icp_monitoring — turn a desk’s Job Board Monitoring on/off and set its cadence

list_scrape_history — scrape history grouped by desk and date

Pipeline (4 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

update_pipeline_job — update a pipeline job’s status, notes, or follow-up date

Lead Discovery (6 tools)

list_new_leads — the Discovery 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

triage_discovery_queue — AI first pass over a desk’s Discovery queue: drop / keep / unknown buckets with reasons, proposals only (2cr)

action_new_leads — review-and-action New Leads in bulk for a desk or Reverse Market Profile

dismiss_all_new_leads — clear a profile’s New Leads in one call, dismissing everything except a keep list

hide_leads — hide New Leads from ONE desk’s queue without dismissing them everywhere else

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

Scheduling Links (9 tools)

list_scheduling_links — list your booking links, including archived links when requested

get_scheduling_link — inspect a booking URL, settings and effective availability

create_scheduling_link — create a link with a calendar, desk, meeting duration and optional availability override

update_scheduling_link — edit link settings, weekly windows, buffers and reminders; archive or restore a link

get_scheduling_availability — inspect shared availability, account timezone and connected calendar choices

update_scheduling_availability — set shared weekly windows, leave, booking horizon and minimum notice; overnight windows are supported

preview_scheduling_slots — preview available slots after calendar conflicts, leave, notice and buffers are applied

list_booking_brands — read your private and workspace booking brands and the inherited default

save_booking_brand — create or update an authorised brand, upload a validated logo, or set the workspace default as an admin

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

E-sign documents

list_esign_documents, list_esign_templates, list_esign_source_files, get_esign_document — discover your documents, reusable roles, existing attached PDFs and signing status.

create_esign_document, update_esign_draft, save_esign_template — prepare linked drafts and layouts without sending.

preview_esign_document, send_esign_document — review exact recipients and content, then send with the reviewed revision/hash and a retry key.

remind_esign_signer, void_esign_document, revise_esign_document, download_esign_document — follow up, correct or retrieve completed documents.

Scopes: esign:read, esign:write and esign:send. Existing attached PDFs also require contacts:read or companies:read for their source. Existing OAuth tokens need consent for newly requested permissions. Prepare from a template, an existing source_file_id, or PDF upload (bare base64 up to 10 MB); downloads return a URL requiring the owner's app login. No tool signs for a person.

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

create_reference_form — create a named questionnaire; search_forms, get_form and duplicate_form manage the library

list_form_submissions — page form responses with total count, submission IDs, UTC timestamps and status

get_form_submission — read submitted answers by field key and current question label, visible linked contact and protected attachment links; both submission tools require contacts:read

get_reference_questions — read current questions and version before editing

update_reference_questions — save a reviewed question set with version check

reset_reference_questions — restore standard questions after review

generate_reference_questions — draft role-specific questions for review without saving

repair_reference_questions — review and repair duplicate fields on a selected form

create_reference_link — create a standalone link; get_reference_link reads channel activity and delivery attempts

send_reference_requests — choose a named form and queue email, SMS or both for approval

get_reference_status — track outstanding requests; retry_reference_delivery queues eligible retries

list_reference_queue and update_reference_queue_task — review candidate-supplied referees and queue manual actions

get_reference_intake_message and review_reference_intake_message — inspect source evidence and resolve messages needing review

compile_reference_report — assemble completed responses into a shareable report

Meeting Prep (10 tools)

generate_meeting_prep — AI brief for an upcoming client/prospect meeting

get_meeting_prep — retrieve a generated meeting brief

get_evening_meeting_prep_settings — view your personal evening preparation settings and calendar connections

configure_evening_meeting_prep — configure the internal pilot with explicit personal consent, selected calendars and alert channels; disable consent at any time

get_evening_meeting_prep_report — retrieve your sourced next-day preparation and missing-context alerts

generate_candidate_call_prep — AI brief for a candidate call

get_candidate_call_prep — retrieve a generated candidate-call brief

generate_prospect_call_prep — BD call prep for a prospect or client contact: relationship status, company snapshot, org chart, pain-led angles, objection prep (2cr)

get_prospect_call_prep — retrieve the generated BD call prep as markdown

set_meeting_note — save a pre-meeting note; marks the prep stale so it regenerates with the note folded in

Post-call Processing (1 tool)

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

Review Queue / Action Inbox (7 tools)

list_pending_actions — the Review Queue (reached in-app from the Needs You zone on Today, not the sidebar): AI-proposed actions awaiting approval

get_pending_action — get a single pending action

approve_pending_action — execute a pending action

snooze_pending_action — defer a ready decision until a chosen time; nothing is executed

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

Native mail intake and report receipts (5 tools)

list_mail_intake — read your mailbox intake, filtered by category or unmatched sender

configure_mail_triage — explicitly enable or disable rules-based triage for your own connected mailbox; requires settings:write and mail:read

classify_mail_intake — change a classification, mark it done, or restore rules; requires mail:write

link_mail_intake — link an accessible person or explicitly create one from a reviewed sender; requires mail:write and contacts:write

list_brief_deliveries — read your daily or weekly delivery receipts; requires settings:read and never retries delivery

Mail permissions are separate from CRM permissions and require explicit consent. Existing tokens do not gain mail access automatically. Native triage requires mailbox-owner opt-in, does not send messages or change provider labels, and currently uses rules only; AI classification is unavailable.

Intelligence Reports (6 tools)

generate_market_intel_report — branded Market Intelligence Report for a target market. Pro/Scale only (23cr)

generate_segment_intel_report — branded Segment Intelligence Report: B2B buyer-side counterpart covering budget/spend, purchase triggers, incumbent alternatives and buyer voice. Pro/Scale only (23cr)

generate_role_intel_report — branded Role Intelligence Report for a candidate profile. Pro/Scale only (23cr)

get_intelligence_report — fetch a generated Market/Role report

list_intelligence_reports — all generated reports, newest first

delete_intelligence_report — permanently delete a report

Morning Brief & BD Brief (3 tools)

get_morning_brief — today’s prioritised digest: your day, the replies and people that need you, pipeline movement, campaign flags, tracked targets

refresh_morning_brief — recompose today’s brief from the latest data and return it. No credits, but real work each call — prefer get_morning_brief

get_bd_brief — the Living BD Brief for a target market: who you’re targeting, what’s been found, budget status, and report links, as markdown

Knowledge Base (2 tools)

list_knowledge_documents — documents attached to a business context or desk

get_knowledge_document — a document’s extracted text, paginated 8,000 characters per call

Call Runner (20 tools)

list_call_frameworks — list drafts and versions

get_call_framework — setup: include_setup=true; graph: summary=false

get_call_runner_context — preview a step; no dialling or logging

preview_call_framework_generation — free source/cost/change preview

generate_call_framework — desk research; preserves edits unless replacement requested (5 credits)

preview_call_booking — review recipient, calendar and slots; no invite

stop_contact_outreach — record an explicit opt-out and stop future managed outreach

schedule_call_callback — save a callback reminder with timezone and note; no invite

confirm_call_booking — book after explicit confirmation; retry-safe

get_call_framework_status — state, stage, time and recovery

log_runner_call — record outcome, notes and selected setup

create_call_framework — desk-based draft, title and setup; search, fractional TA and MPC

update_call_framework_node — edit one draft node without resending the graph

update_call_framework_response — edit one response by ID; preserves other branches

update_call_framework_graph — replace authored draft graph; validated on save

set_call_framework_setup — edit roles, buyers, terms, offers, hooks and motions

publish_call_framework — publish a new version

upgrade_call_framework — upgrade an older authored draft

archive_call_framework — archive a draft or version

delete_call_framework — delete an unused draft

Candidate Imports (3 tools)

get_candidate_import_address — your personal address for auto-importing candidates from forwarded emails (SEEK or any email with a CV)

list_candidate_imports — recent inbound imports with their source (SEEK or email) and status (received / processing / created / updated / skipped / failed)

rotate_candidate_import_address — regenerate the address. The old one stops working immediately — update any auto-forward rules

Automation Settings (2 tools)

get_automation_settings — which opt-in automations are enabled for the workspace

update_automation_settings — enable or disable an opt-in automation

LinkedIn Outreach (24 tools)

prepare_linkedin_rows — editable drafts; cost shown first

get_linkedin_preparation_status — job progress and completed drafts

enqueue_linkedin_rows — draft up to 100 pairs; DMs wait for acceptance

bulk_skip_linkedin_rows — skip your queued rows by IDs or filters

preview_linkedin_queue_replacement — free replacement preview

replace_linkedin_rows — confirm reviewed replacement atomically

list_linkedin_queue — your queue by stream and state

prepare_linkedin_action — prepare an approved recipient and exact message for browser execution when browser sync is enabled

claim_linkedin_action — reserve your sender account for one browser action

begin_linkedin_dispatch — recheck permission immediately before sending; permission can be used once

record_linkedin_action_result — record a verified send, proven non-send or uncertain result without sending again

sync_linkedin_conversation — reconcile observed messages; historical imports preserve newer outreach

get_linkedin_sync_status — review unresolved attempts and messages; unopened conversations are not covered

pin_linkedin_row — prioritise an eligible queued row

unpin_linkedin_row — restore automatic order

defer_linkedin_row — move a queued row to the end

skip_linkedin_row — remove from queue; keep history

edit_linkedin_note — edit queued outreach text

set_linkedin_split — candidate share of invitations and DMs

set_linkedin_queue_auto_fill — queue auto-fill; sending stays separate

set_linkedin_send_targets — safe daily/weekly targets and split

get_linkedin_account_status — usage, pending invites, limits and holds

resume_linkedin_automation — resume after a restriction or checkpoint

list_linkedin_activity — daily sends, skipped checks and sender heartbeat

Guides & Connection (2 tools)

get_guide — pull a Kolvera guide into the conversation with always-current content and live credit costs

check_connection_scopes — check granted permissions before preparing an operation; does not grant access or check record ownership

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 a Desk 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 Zapier/Make trigger or your HTTPS endpoint. Transform its campaign_id, contact_id, and enrollment_id payload into a Slack message. A direct Slack incoming webhook expects a different JSON shape.

curl -X POST https://www.kolvera.io/api/v2/webhooks \
  -H "Authorization: Bearer kv_your_token" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-domain.example/webhook",
       "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 reaches 10 or below, Kolvera sends a webhook to your automation endpoint; forward it to Slack 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 — 62 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 (12)

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 (2cr for a fresh result)
GET	`/contacts/:id/employment/processing`	Candidate employment processing status
POST	`/contacts/:id/employment/retry`	Retry with run_id, source_revision and history_revision
GET	`/contacts/:id/employment/runs/:run_id/review`	Preview proposed changes and evidence
POST	`/contacts/:id/employment/runs/:run_id/review`	Approve selected_role_keys with current revisions, or dismiss
POST	`/contacts/:id/employment/runs/:run_id/refresh`	Refresh a stale review without regenerating extraction

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 (2cr)
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

Desks (5)

GET	`/icp`	List all Desks
GET	`/icp/:id`	Profile + company map + prospect count
POST	`/icp`	Create `{title, target_industries, target_locations, ...}`
POST	`/icp/generate`	AI-generate Desk (3cr)
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?}`; retain your own optional 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 Event Types

Register an HTTPS endpoint through POST /api/v2/webhooks with a kv_ Bearer token. Kolvera sends JSON POST requests for supported changes. Connect through Zapier, Make, or your own server; reconcile through the REST API for complete records.

enrolment.complete reports successful enrolment (campaign_id, enrolled count). campaign.completed reports a contact finishing its sequence (campaign_id, contact_id, enrollment_id). No event fires for each email sent.

Signing is optional. Supply and keep your own secret; API responses omit it. Signed requests include X-Kolvera-Signature: sha256=<hex> over raw body bytes. See event payloads, coverage limits, retry policy, and working Python/Node verification examples.

Permanent recruitment

Use list_permanent_placements, list_candidate_placement_history and reverse_permanent_placement for placement records, visible candidate history and retained reversals. permanent_recruitment_forecast groups monthly/quarterly open, weighted and placed revenue by currency and income type. Set AUD/USD; unknown currency is excluded. Use fee_type=platform_reward for rewards, separate from client fees. Keep OTE separate from fee-basis salary.

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 (2cr for a fresh result)
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`

30 Permission Scopes

contacts:read — view contacts

contacts:write — create/edit contacts

contacts:enrich — find emails/phones

companies:read — view companies

companies:write — create and update companies and client jobs

esign:read — view your signing documents and templates

esign:write — prepare signing drafts and templates

esign:send — send reviewed invitations and reminders

conversations:read — read call & meeting transcripts

mail:read — read your native mailbox intake

mail:write — classify and link your native mailbox intake

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 Desks

icp:write — manage Desks

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	2cr for a fresh result
Find Phone (company line)	30/min	2cr fresh; 1cr cached
Deep Research	5/min	6cr per run
Expand Research	5/min	4cr per run
Generate Desk	10/min	3cr
Generate Reverse Market Profile	10/min	3cr
Company Research	10/min	2cr
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.”