Integrations / AI & Automation

94 endpoints. Full platform access.

JSON REST API for contacts, companies, campaigns, enrichment, and pipeline. Bearer token auth, rate limited, CORS-ready.

Getting started

Everything you need to make your first API call.

Base URL & authentication

Rate limits

Quick test

Run this in your terminal to verify your token.

# Set your token from Settings > API Tokens
TOKEN=your_api_token_here

curl https://www.kolvera.io/api/v2/contacts?q=test \
  -H "Authorization: Bearer $TOKEN"

Endpoint reference

All 94 endpoints grouped by resource. All responses are JSON.

Download Markdown developer guide

Contacts 12 endpoints

Search, create, update, delete contacts, and trigger enrichment.

Method Endpoint Description
GET /contacts List contacts. Supports q, page, per_page.
POST /contacts Create a new contact.
GET /contacts/{id} Get a single contact by ID.
PATCH /contacts/{id} Update a contact. Partial updates supported.
DELETE /contacts/{id} Delete a contact.
POST /contacts/{id}/find-email Trigger email enrichment for this contact. 2 credits on success.
POST /contacts/{id}/find-phone Trigger phone enrichment. Credit cost varies by result type.
GET /contacts/{id}/employment/processing Read candidate employment processing status and permitted actions.
POST /contacts/{id}/employment/retry Retry with run_id, source_revision and history_revision. Requires verified email.
GET /contacts/{id}/employment/runs/{run_id}/review Preview proposed roles and evidence. run_id is the extraction run ID.
POST /contacts/{id}/employment/runs/{run_id}/review Approve explicitly selected_role_keys with current revisions, or dismiss. run_id identifies the extraction run.
POST /contacts/{id}/employment/runs/{run_id}/refresh Refresh a stale review without another model call. run_id identifies the extraction run.

Employment processing actions require the workspace pilot to be enabled. Reads require contacts:read; changes require contacts:write. Transcript changes require human approval.

Qualified people sourcing 4 endpoints

Evidence-first candidate and decision-maker sourcing. Available only when the pilot is enabled.

MethodEndpointDescription
GET/people/sourcing/quoteRead pilot availability and current prices.
POST/people/sourcing/runsStart an evidence-based search with an approved credit cap.
GET/people/sourcing/runs/{id}Read sourcing evidence, results and charges.
POST/people/sourcing/runs/{id}/resumeResume a paused run within its original cap.

Find candidates 5 endpoints

Private Zionic AU admin pilot. Contact-free discovery, explicit mobile reveal and explicit Talent Pool save. No automatic submission or outreach.

MethodEndpointDescription
POST/people/candidate-search/runsCreate a contact-free preview with reviewed criteria and an idempotency key.
GET/people/candidate-search/runs/{id}Read paginated profiles, progress, held reasons and supplier usage.
POST/people/candidate-search/runs/{id}/quoteQuote maximum supplier credits for selected profiles and reveal stage.
POST/people/candidate-search/runs/{id}/revealExecute standard or Waterfall reveal with a signed quote and idempotency key.
POST/people/candidate-search/runs/{id}/saveSave selected profiles to the Desk Talent Pool with an idempotency key.

Companies 6 endpoints

Manage company records, trigger contact discovery and deep research.

Method Endpoint Description
GET /companies List companies. Supports q, page, per_page.
GET /companies/{id} Get a single company by ID.
GET /companies/{id}/contacts List the contacts already known at this company.
PATCH /companies/{id} Update company details. Partial updates supported.
POST /companies/{id}/find-contacts Find contacts at this company. 2 credits per new contact found.
POST /companies/{id}/research Trigger AI research on this company. 2 credits.

Campaigns 7 endpoints

Query outreach campaigns, control their run state, and enrol contacts.

Method Endpoint Description
GET /campaigns List all campaigns.
GET /campaigns/{id} Get campaign details, including its steps.
GET /campaigns/{id}/stats Sends, opens, clicks and replies for this campaign.
POST /campaigns/{id}/enrol Enrol one or more contacts in this campaign.
POST /campaigns/{id}/activate Activate a draft campaign.
POST /campaigns/{id}/pause Pause a running campaign. Scheduled sends stop immediately.
POST /campaigns/{id}/resume Resume a paused campaign from where it stopped.

Desks 7 endpoints

Manage Desks and their linked company lists.

Method Endpoint Description
GET /icp List all Desks.
POST /icp Create a new Desk.
GET /icp/{id} Get Desk details and criteria. Pass include_companies=true to embed its linked companies (200 per read — page with companies_limit / companies_offset; companies_total is the true count; companies_fields is a comma-separated lean projection).
PATCH /icp/{id} Update Desk criteria.
GET /icp/{id}/prospects List prospects linked to this Desk. Supports page, per_page.
POST /icp/generate AI-generate a Desk from a brief. 3 credits.
POST /icp/{id}/build-hotlist Build a hot list from this Desk's mapped prospects.

Hot Lists 6 endpoints

Manage curated prospect lists and their members.

Method Endpoint Description
GET /hot-lists List all hot lists.
POST /hot-lists Create a new hot list.
GET /hot-lists/{id} Get hot list details and member count.
POST /hot-lists/{id}/members Add one or more contacts to this hot list.
PATCH /hot-lists/{id}/members/{member_id} Update a member's tier or notes.
DELETE /hot-lists/{id}/members/{member_id} Remove a contact from this hot list.

Pipeline 6 endpoints

Query scraped jobs, saved scrape configurations, and scrape quality.

Method Endpoint Description
GET /pipeline List pipeline jobs with status and results. Supports q, page, per_page, and fields — a comma-separated lean projection (?fields=title,company_name); id is always returned, and names matching no row come back in unknown_fields.
GET /pipeline/{id} Get a single pipeline job by ID, including job.description when available. The list endpoint omits descriptions. Stored descriptions may be excerpts; retain the source URL for the original advert.
GET /scrape-configs List saved scrape configurations.
GET /scrape-configs/{id} Get a single scrape configuration by ID.
POST /scrape-configs/{id}/excludes Add exclusion terms to a scrape configuration.
GET /scrape-quality Relevance and duplicate rates for recent scrapes.

Research 3 endpoints

Trigger deep research jobs and retrieve generated reports.

Method Endpoint Description
POST /research Trigger a new deep research job. 6 credits.
GET /research List all deep research reports.
GET /research/{id} Get the full content of a research report.

Credits 1 endpoint

Query your workspace credit balance.

Method Endpoint Description
GET /credits Current plan credit balance and add-on balance.

Meetings 6 endpoints

Log meetings, move them through their status, and pull synced call notes.

Method Endpoint Description
GET /meetings List meetings. Supports page, per_page.
POST /meetings Log a new meeting against a contact or company.
GET /meetings/{id} Get a single meeting by ID.
PATCH /meetings/{id}/status Update a meeting's status.
POST /fathom/sync Pull the latest call recordings and notes from a connected Fathom account.
GET /fathom/notes List synced call notes.

Reviewed SMS 15 endpoints

Prepare up to 100 recipients for review before explicitly approving a send. SMS access is separate from dialler access. OAuth clients need the scope listed below; template operations use settings scopes. Saving templates or confirming voicemail never sends a message.

MethodEndpointDescription
GET /sms/templates List personal and team templates, including the effective LVM default. Requires settings:read.
POST /sms/templates Save or archive a versioned template. Team edits require a workspace admin. Requires settings:write.
POST /sms/batches/preview Freeze visible recipients and final messages for review. LVM follow-ups require exact confirmed events. Requires sms:write.
GET /sms/batches/{id} Read your reviewed batch and delivery progress. Requires sms:read.
POST /sms/batches/{id}/confirm Approve the reviewed hash and revision with a stable confirmation key. Replays do not send again. Requires sms:send.
GET /sms/origins/{id} Read confirmed voicemail events and delivery state for a visible person. Requires sms:read.
POST /sms/batches/{id}/cancel Cancel remaining messages before handoff; accepted sends and history remain. Requires sms:write.
POST /sms/batches/{id}/resume Explicitly resume safe remaining messages after fresh checks. Armed or uncertain deliveries are not retried. Requires sms:send.
POST /sms/origins/{id}/call Record human-confirmed voicemail for an exact completed outbound call. Requires sms:write.
GET /sms/daily-cap Read your SMS allowance for today and the workspace default daily cap. Requires sms:read.
POST /sms/daily-cap Workspace admins set the default per-seat daily cap (1 to 500). Requires sms:write.
POST /sms/daily-overrides Workspace admins grant a dated per-member cap (at most 31 days, reason required) or revoke one with revoke and override_id. Audited. Requires sms:write.
GET /sms/queue Read your SMS allowance, open batches and inbound replies you can see, unhandled first. Optional contact_id narrows to one person. Requires sms:read.
POST /sms/messages/{id}/handled Mark an inbound reply handled by you. Idempotent; a message you cannot see returns not_found. Requires sms:write.
POST /sms/messages/{id}/stop Suppress the sender of an inbound reply you can see, through the existing opt-out record. Requires sms:write.

Terms of Business 12 endpoints

Workspace ToB template, clause policies and commercial limits. Workspace admins only.

Method Endpoint Description
GET /tob/settings Workspace admins read the Terms of Business setup: mode, supplier details, source document, field map and sign-off state. Requires settings:read.
PUT /tob/settings Workspace admins save the mode, supplier details, source document and field map. A new source document re-reads its clauses. Requires settings:write.
POST /tob/source Workspace admins upload their own Terms of Business (PDF or DOCX, up to 10 MB) as multipart file or JSON file_base64. Requires settings:write.
GET /tob/clauses Workspace admins list the template clauses with each clause's edit policy. Requires settings:read.
POST /tob/clauses Workspace admins add a clause with a heading and text, optionally after an existing clause. Requires settings:write.
PUT /tob/clauses/order Workspace admins set the clause order from a list of clause ids. Requires settings:write.
PATCH /tob/clauses/{id} Workspace admins keep or leave out a clause, or change its heading, text or policy. Requires settings:write.
DELETE /tob/clauses/{id} Workspace admins cross a clause out of the terms; it stays in the list and can be ticked back in. Requires settings:write.
PUT /tob/clauses/{id}/policy Workspace admins set one clause to editable, approval required or blocked. Requires settings:write.
PUT /tob/profiles Workspace admins set commercial limits and review thresholds for one engagement type. Requires settings:write.
POST /tob/sign-off Workspace admins sign off the ToB setup so members can send. Requires settings:write.
GET /tob/amendments Workspace admins list amendment requests. Optional state filters by status. Requires settings:read.

Webhooks 4 endpoints

Manage event subscriptions at https://www.kolvera.io/api/v2 with Authorization: Bearer kv_.... OAuth access requires webhooks:manage. Payload formats and delivery limits are documented on the webhooks page.

Method Endpoint Description
GET /webhooks List your webhook subscriptions.
POST /webhooks Create a subscription for one or more event types.
PATCH /webhooks/{id} Update a subscription's URL, events, or active state.
DELETE /webhooks/{id} Delete a subscription. 
TOKEN=your_api_token_here
curl -X POST https://www.kolvera.io/api/v2/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-domain.example/webhook","events":["enrolment.complete","campaign.completed"],"secret":"your-own-long-random-secret"}'

curl -H "Authorization: Bearer $TOKEN" https://www.kolvera.io/api/v2/webhooks
curl -X PATCH https://www.kolvera.io/api/v2/webhooks/SUBSCRIPTION_ID \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"is_active":false}'
curl -X DELETE https://www.kolvera.io/api/v2/webhooks/SUBSCRIPTION_ID \
  -H "Authorization: Bearer $TOKEN"

secret is optional. Supply and retain your own secret for signed deliveries; API responses never return it.

OAuth 2.0

For building apps that authenticate Kolvera users on their behalf.

Flow Authorisation code with PKCE support
Scopes 33 permission scopes covering all resources
Redirect URI Registration required before use
Token lifetime Access: 1 hour. Refresh: 30 days.

Authorisation endpoint

See also

Developer Portal Overview of all integration methods MCP Server 540 tools for AI assistants Webhooks 18 real-time event types

Start building today

Free trial — 50 credits, no card required. Full API access on all paid plans.

Start free trial