CRM crm
The workspace's CRM connection (HubSpot, Salesforce and more): status, sync health, field map and record lookup, plus Import now and which new CRM contacts become people. Connecting and the other sync settings stay in the Kenso app. Also an ad platform's terms attestation (ad-connections-update) and an ad audience's lift against its holdout (ad-audiences-lift); the rest of ad audiences is integrations. list-lookalike-seeds suggests seed companies for a lookalike company search: customers, CRM closed-won deals or companies that replied Interested.
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through crm_read and changes through crm_write. Each takes operation plus that operation's parameters, and your workspace role decides which operations you see.
Each operation with a route calls the Kenso API at https://api.ken.so with Authorization: Bearer <Kenso API key>, Ken-Version: 1.1 and X-Ken-Workspace-Id: <workspace id>. You can call that route directly with the same headers.
Operations: dialer-connections-cloudtalk-connect, imports-create, dialer-connections-dialpad-connect, connections-get, live-records-get, sync-get, dialer-connections-justcall-connect, ad-audiences-lift, connections-list, field-mappings-list, list-lookalike-seeds, records-lookup, live-records-search, ad-connections-update, connections-update
dialer-connections-cloudtalk-connect
Write. Early access: needs calls, calls_cloudtalk on for the workspace. POST https://api.ken.so/v1/integrations/cloudtalk/connection
Body (json): accessKeyId string, accessKeySecret string
Connect the workspace's CloudTalk account with an API access key, so its calls land in Kenso.
POST /api/v1/integrations/cloudtalk/connection. Staff, or a workspace with the calls and calls_cloudtalk flags (workspace admin). Sends Ken-Version 1.1. access_key_id and access_key_secret: an API access key a CloudTalk admin creates under Settings, API Keys. Kenso checks it with CloudTalk, creates one webhook endpoint on the account for ended calls, transcripts and AI summaries (CloudTalk's Essential plan or higher), stores the key and the endpoint's signing secret encrypted (never returned) and links each CloudTalk agent to the Kenso member with the same email. Calls land with a link to the call's CloudTalk page (its recording) and Conversation Intelligence's transcript and summary; a dial rings the rep's CloudTalk app, then calls the person. Returns 201 with the connection as calling(operation="dialer-connections-get") returns it. A key CloudTalk refuses is validation_failed on accessKeyId; CloudTalk already connected, or CloudTalk refusing Kenso's webhook (below Essential, or 50 endpoints already), is conflict; CloudTalk not answering is unavailable. Nothing is stored on any of them. Read, members and disconnect are the calling dialer-connections operations with integration_key cloudtalk.
imports-create
Write. POST https://api.ken.so/v1/crm-connections/{connectionId}/imports
Path: connectionId
Import now: read every record from the CRM again. Public, admins only. Writes nothing to the CRM.
POST /api/v1/crm-connections/{connectionId}/imports. Sends Ken-Version 1.1 and
X-Ken-Workspace-Id. Requires the integrations permission. 202 with startedAt;
follow progress with crm(operation="sync-get", ...). 409 import_running while
an import runs, 409 needs_reconnect when the CRM refused Kenso's access, 402
plan_required on the Free plan.
dialer-connections-dialpad-connect
Write. Early access: needs calls, calls_dialpad on for the workspace. POST https://api.ken.so/v1/integrations/dialpad/connection
Body (json): apiKey string
Connect the workspace's Dialpad company with a company API key, so its calls land in Kenso.
POST /api/v1/integrations/dialpad/connection. Staff, or a workspace with the calls and calls_dialpad flags (workspace admin). Sends Ken-Version 1.1. api_key: a Dialpad company API key (Dialpad Admin Settings, Authentication, API Keys) made by a company admin; add the recordings_export scope so recordings play. Kenso checks it with Dialpad, adds a webhook signed with a secret of its own, subscribes it to the company's calls, stores the key and the secret encrypted (never returned) and links each Dialpad user to the Kenso member with the same email. Returns 201 with the connection as calling(operation="dialer-connections-get") returns it (connectedAs is the Dialpad company). A key Dialpad refuses is validation_failed on apiKey; Dialpad already connected, or Dialpad refusing Kenso's webhook, is conflict; Dialpad not answering is unavailable. Nothing is stored on any of them. Read, members and disconnect are the calling dialer-connections operations with integration_key dialpad.
connections-get
Read. GET https://api.ken.so/v1/crm-connections/{connectionId}
Path: connectionId
Get one CRM connection, any status. Public. An id outside the workspace is not_found.
GET /api/v1/crm-connections/{connectionId}. Sends Ken-Version 1.1 and
X-Ken-Workspace-Id. Requires accounts view. Same fields as connections-list; a
disconnected connection keeps its history (disconnectedAt).
live-records-get
Read. Early access: needs connected_app_reads on for the workspace. GET https://api.ken.so/v1/crm-connections/{connectionId}/live-records/{objectType}/{externalId}
Path: connectionId, objectType, externalId
Read one HubSpot or Salesforce record live, with its associations and last 20 notes and activities.
GET /api/v1/crm-connections/{connectionId}/live-records/{objectType}/{externalId}.
Sends Ken-Version 1.1 and X-Ken-Workspace-Id. Needs the connected_app_reads flag,
Accounts view and Ask. object_type: contact, company or deal. external_id: the CRM's
own id (letters and digits). Returns the summary fields plus fields (the CRM's values
by its own field names), associations [{objectType, externalId}] and activities
[{kind (note, email, call, meeting, task), occurredAt, direction, subject, text}],
newest first. 404 when the CRM has no such record; 422 not_supported for another CRM.
sync-get
Read. GET https://api.ken.so/v1/crm-connections/{connectionId}/sync
Path: connectionId
Sync health of a CRM connection: switches, queues and Needs attention count. Public. No CRM call.
GET /api/v1/crm-connections/{connectionId}/sync. Sends Ken-Version 1.1 and
X-Ken-Workspace-Id. Requires accounts view. Returns connectionId, status,
pausedReason, lastError, lastImportStartedAt, lastImportCompletedAt,
importRunning, lastInboundAt, lastOutboundAt, objects (company, contact, deal,
activity, suppression, list: {enabled, enabledAt, lastInboundAt,
records: {total, linked}}), queueDepth, oldestPendingAt, needsAttentionCount,
inboundBacklog and owners {total, linked}. The list of items that need
attention is in the Kenso app.
dialer-connections-justcall-connect
Write. Early access: needs calls, calls_justcall on for the workspace. POST https://api.ken.so/v1/integrations/justcall/connection
Body (json): apiKey string, apiSecret string
Connect the workspace's JustCall account with its API key and secret, so its calls land in Kenso.
POST /api/v1/integrations/justcall/connection. Staff, or a workspace with the calls and calls_justcall flags (workspace admin). Sends Ken-Version 1.1. api_key and api_secret: the pair from JustCall's profile menu, APIs and Webhooks (JustCall's Team plan or above). Kenso checks them with JustCall, adds its webhook URL to the account's call events (completed, missed, voicemail, AI report), stores both encrypted (never returned) and links each JustCall user to the Kenso member with the same email. Calls land with their recording link and JustCall AI's transcript and summary; JustCall has no API to place a call, so a dial answers a tel link. Returns 201 with the connection as calling(operation="dialer-connections-get") returns it. A pair JustCall refuses is validation_failed on apiKey; JustCall already connected, or JustCall refusing Kenso's webhook, is conflict; JustCall not answering is unavailable. Nothing is stored on any of them. Read, members and disconnect are the calling dialer-connections operations with integration_key justcall.
ad-audiences-lift
Read. Early access: needs ad_audiences on for the workspace. GET https://api.ken.so/v1/ad-audiences/{adAudienceId}/lift
Path: adAudienceId
Compare reply rates of an ad audience's synced contacts with its random holdout, since the holdout took effect. Shows whether the ads lift replies. Read ready first: under 200 contacted per side the rates are noise.
GET /api/v1/ad-audiences/{adAudienceId}/lift.
Staff, or a workspace with the ad_audiences flag. Sends Ken-Version 1.1. Requires accounts view.
Another workspace's id, or a deleted audience, is not_found.
Returns data {adAudienceId, holdoutPercent, startedAt (when the current holdoutPercent took
effect: the audience's creation or the last change), synced, holdout, ready, message}. synced and holdout each carry contacts (the source's eligible
contacts on that side now), contacted (sent a campaign email since startedAt), replied and
positiveReplied (a reply, an Interested reply, among the contacted; out-of-office, bounces
and automated mail are not replies), replyRate and positiveReplyRate (fractions of
contacted, 4 decimals, absent while nobody is contacted). ready is true once each side has
200 contacted while the audience is active and Kenso may add to it (terms and, on Google Ads,
first party attested); until then message says why and the rates are not a result. The
holdout side is every contact the sync keeps out because of the holdout, through one of its
own addresses or an address or person it shares with a held-out contact; contacts left out for another reason (unsubscribed, bounced,
region) are on neither side. 400 lift_not_supported for a source that is not contacts, and
for a company audience. A live company audience on the same tier and ad account shows the
ads to the whole company, holdout contacts included, so this tier's lift reads lower than
the ads' real effect while one runs.
connections-list
Read. GET https://api.ken.so/v1/crm-connections
List the workspace's CRM connection (at most one is live). Public. Empty when no CRM is connected.
GET /api/v1/crm-connections. Sends Ken-Version 1.1 and X-Ken-Workspace-Id.
Requires accounts view. 404 when CRM sync is not enabled for the workspace.
Each item: id, provider (hubspot, salesforce, pipedrive, attio, close, highlevel,
twenty, dynamics, zoho), status (connected, needs_reconnect, paused, disconnected), pausedReason
(plan), externalAccountName, instanceUrl, connectedAsEmail, connectedAt,
disconnectedAt, lastImportStartedAt, lastImportCompletedAt, lastInboundAt,
lastOutboundAt, lastError, lastErrorAt, syncObjects (company, contact, deal,
activity, suppression, list: {enabled, enabledAt}), settings (createRecordsWhen,
salesforcePersonMode, emailLogging, pipelineExternalId, stageMap, importDaily,
skipOpenOpportunities, blockCustomers, pauseOnRepActivityDays,
staticListPerCampaign, listSources, inboundPeople) and capabilities. Empty fields
are omitted. inboundPeople {enabled, filters, leadStatus, defaultOwnerMemberId,
enabledAt} decides which contacts the CRM creates become people; change it with
crm(operation="connections-update", ...). Connecting, the other sync settings and
disconnecting are done in the Kenso app.
field-mappings-list
Read. GET https://api.ken.so/v1/crm-connections/{connectionId}/field-mappings
Path: connectionId
Query: objectType string
The field map: which Kenso field syncs with which CRM field, and in which direction. Public. Editing the map is done in the Kenso app.
GET /api/v1/crm-connections/{connectionId}/field-mappings. Sends Ken-Version 1.1
and X-Ken-Workspace-Id. Requires accounts view. object_type: company, contact
or deal (omit for all three). Returns mappings [{id, objectType, kenField,
kenFieldLabel, crmField, direction (ken: Kenso writes, crm: the CRM writes,
both: last human edit wins), isEnabled, isDefault, updatedAt}] and kenFields
[{key, objectType, label, dataType, fixedDirection}].
list-lookalike-seeds
Read. GET https://api.ken.so/v1/search/lookalike-seeds
Query: campaignId integer, since string, source string, stage string
Suggest seed companies for a lookalike company search: customers, CRM deals, Interested replies, any replies, a campaign's leads or website visitors. Free. Each row is a company's domain, its name and how many records point at it.
GET /api/v1/search/lookalike-seeds. Sends Ken-Version 1.1 and X-Ken-Workspace-Id. Needs the Search and
Accounts pages (view).
No credits. While the workspace's lookalikes flag is off, the call answers 404 not_found.
source is required, one of:
- customers: the workspace's customer accounts (count 1 each).
- crm: companies on deals, from the connected CRM and Kenso's own deals, at the stage asked for (count = deals).
stage: won (default), open (neither won nor lost) or any.
- crm_won: the same as crm with stage won (kept for older callers).
- interested: companies whose people replied Interested to a campaign (count = those people).
- replies: companies whose people sent any real reply to a campaign; automated replies, bounces (hard, soft,
NDR) and out-of-office do not count (count = those people).
- campaign: companies of one campaign's leads (count = the campaign's contacts at the company). Needs
campaign_id.
- website_visitors: companies behind human visits to the workspace's tracked website (count = visits).
campaign_id: required with campaign; with interested or replies, only that campaign's replies count. A positive
integer. Needs the Campaigns page (view) as well: without it the call answers 403 permission_denied. A campaign
outside the workspace, or deleted, answers 404 not_found.
since: interested, replies and website_visitors only. A day as YYYY-MM-DD (UTC); only replies or visits on or
after it count.
A parameter the source does not take answers 400 validation_failed. Free mail domains never become seeds.
Replies, campaign leads and visits are read newest first, at most 20,000, before they are grouped by company.
Returns data, up to 200 {domain, name, count}, ordered by count (highest first) then domain, and pagination
{nextCursor: null, hasMore: false}. An empty list is normal when the workspace has little CRM, reply or visit
data: take seeds from confirmed fits or the domains the user names instead.
Examples: crm(operation="list-lookalike-seeds", source="crm", stage="open");
crm(operation="list-lookalike-seeds", source="replies", campaign_id=1234, since="2026-10-01").
Use the domains as seeds of a lookalike company search, at most 100 (the first rows when there are more):
search(operation="search-companies", body={"lookalike": {"seeds": [{"domain": "acme.com"},
{"domain": "northwind.io"}], "mode": "precise", "minGrade": 3}}).
records-lookup
Read. GET https://api.ken.so/v1/crm-connections/{connectionId}/records
Path: connectionId
Query: domain string, email string, externalId string, objectType string
Look up what Kenso holds for a CRM record and the Kenso record it is linked to. Public. Send one of email, domain, or external_id with object_type.
GET /api/v1/crm-connections/{connectionId}/records. Sends Ken-Version 1.1 and
X-Ken-Workspace-Id. Requires accounts view. No CRM call: it reads Kenso's copy.
object_type: company, contact, deal, owner, activity or list (required with
external_id). A free-mail domain is refused. Each record: id, objectType,
externalId, externalSubtype, externalUrl, email, domain, displayName,
ownerExternalId, lifecycle, isOptedOut, isCustomer, hasOpenDeal,
lastRepActivityAt, crmUpdatedAt, lastSyncedAt, crmDeletedAt (a CRM delete; the
Kenso record stays), mergedIntoExternalId, snapshot (mapped CRM fields) and
linked {entityType, entityId, entityKey, entityRef}. At most 20.
live-records-search
Read. Early access: needs connected_app_reads on for the workspace. GET https://api.ken.so/v1/crm-connections/{connectionId}/live-records
Path: connectionId
Query: limit integer, objectType string, q string
Search the connected HubSpot or Salesforce live for contacts, companies or deals. Reads the CRM itself, not Kenso's synced copy (that is records-lookup).
GET /api/v1/crm-connections/{connectionId}/live-records?objectType=&q=&limit=. Sends
Ken-Version 1.1 and X-Ken-Workspace-Id. Needs the connected_app_reads flag, Accounts
view and Ask; a Client seat is refused. HubSpot CRM search or Salesforce SOSL
(contacts there include open leads). object_type: contact, company or deal. q: 2 to
200 characters. limit: 1 to 25, default 10. Each record: objectType, externalId,
subtype, name, email, domain, ownerExternalId, externalUrl, updatedAt.
pagination.hasMore says the CRM has more; narrow the query. Another CRM answers
422 not_supported. Open one record with crm(operation="live-records-get", ...).
ad-connections-update
Write. Early access: needs ad_audiences on for the workspace. PATCH https://api.ken.so/v1/ad-connections/{adConnectionId}
Path: adConnectionId
Body (json): externalAccountId string, loginAccountId string, termsAttested boolean
Record or withdraw a workspace admin's attestation of an ad platform's terms on its ad connection. Only when the user explicitly confirms the attestation sentence; never on your own.
PATCH /api/v1/ad-connections/{adConnectionId} with {"termsAttested": ...}.
Staff, or a workspace with the ad_audiences flag. Sends Ken-Version 1.1. Requires the
integrations permission (workspace admins). Another workspace's id is not_found.
The sentence, with the platform (Google Ads, Meta or LinkedIn):
"I confirm this workspace has the right to upload these contacts to {platform} under
{platform}'s terms."
Show it to the user word for word and send terms_attested=true only when they explicitly
confirm it. Never attest for them, and never infer it from another answer.
terms_attested true stores when and by whom; false withdraws it. Until it is attested the
sync creates no audience on the platform and adds nobody to one (it still removes contacts
who unsubscribe, bounce or leave the campaign). A reconnect keeps it; a disconnect clears
it. Picking the ad account stays in the Kenso app.
Returns data, the connection (see integrations(operation="ad-connections-list")).
connections-update
Write. PATCH https://api.ken.so/v1/crm-connections/{connectionId}
Path: connectionId
Body (json): settings object, syncObjects object
Choose which contacts the CRM creates become people (leads) in Kenso. Absent fields stay unchanged. Public, admins only. Only on the user's request: it decides who becomes a lead. Writes nothing to the CRM.
PATCH /api/v1/crm-connections/{connectionId} with settings.inboundPeople only; the other
sync settings stay in the Kenso app. Sends Ken-Version 1.1 and X-Ken-Workspace-Id. Requires
the integrations permission. inbound_people keys: enabled (true or false), filters (up to
10 {field, op, value}; a new list replaces the old one, [] lets every new contact
through), lead_status (new, working, qualified, disqualified or nurture; default new),
default_owner_member_id (a workspace member, or null to clear). field is the CRM's own
field name (hs_lead_status on HubSpot, LeadSource on Salesforce); op is equals, contains,
in (value a comma-separated list) or not_empty (no value). Values compare trimmed and
ignoring case, and every filter must pass. A field the record lacks is blank, so a field
only Salesforce Leads have (Status) leaves every Salesforce Contact out. Only contacts
the CRM creates after enabled turns on become people: source crm, the CRM owner (else
the default owner) and lead_status. The first import, the daily import and contacts the CRM changes create
nobody. People are created only while the workspace has the lead_intake flag. Errors
come back together in error.details (unsupported: the CRM's contacts are not synced;
invalid_member: the owner is not in the workspace). Returns the connection as
connections-get does, with settings.inboundPeople {enabled, filters, leadStatus,
defaultOwnerMemberId, enabledAt}.