Kenso MCP tools

Accounts accounts

Target companies you work one to one (the Accounts lane): accounts, their domains and stakeholders. People are the people tool; your own Kenso user is the account tool. For a brief on an account or to prep a call or meeting with it, call knowledge with operation="context" first (its account_id), not get. Counts and filtered lists: search (include_total=true for a total). Not the workspace's company records: a company by name or domain is contacts companies-list.

Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through accounts_read and changes through accounts_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: activity, add-to-campaign, bulk-create, bulk-update, domain-create, create, stakeholders-create, create-sales-navigator-account-import, domain-delete, delete, stakeholders-delete, facets, get, list, stakeholders-list, merge, contacts-promote, search, update, stakeholders-update

activity

Read. Early access: needs accounts on for the workspace. GET https://api.ken.so/v1/accounts/{accountId}/activity

Path: accountId

Query: category string, limit integer

Return one account's timeline: upcoming touches and earlier activity, newest first. category filters (comma = OR): email, linkedin, instagram, whatsapp, facebook, calls_meetings, assets, signals, website, crm, ken.

GET /api/v1/accounts/{accountId}/activity. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. category is comma-separated (absent = all). limit caps the
earlier rows, 1 to 500 (default 100).
Returns data.upcoming (open touches by dueAt; needsApproval when a person must
approve), data.earlier (sent and done touches, account events, finished research
and every email and LinkedIn message to or from the account's people, newest first;
repeated text in one category keeps only the newest), data.hasMoreEarlier, and
data.categoryCounts (every category, counted over every earlier row before
category and limit). Items carry kind, category, text, occurredAt or dueAt, the ids
they relate to (touchId, stakeholderId, personId, researchId) and link.target:
conversation, touch, research, person or sequence. Meeting booked, rescheduled,
cancelled and no-show rows carry bookingTool (ken, cal_com, calendly, hubspot or
chili_piper) when a scheduler booked the meeting; absent for calendar-synced ones.
Messages: kind message_sent (campaign steps, Inbox sends, LinkedIn invites and
messages) or message_received (a person's reply, text "{name} replied"). A sent touch
whose message is found keeps kind touch. Either carries message: id (msg_), direction
(outbound, inbound), source (campaign, inbox, touch, import), campaignId, campaignName,
step, fromName, fromAddress, toAddress, subject, body (plain text, up to 4000 characters;
bodyTruncated when cut), opened, clicked, bounced, and on a reply inReplyTo (subject,
step, campaignName, occurredAt, body up to 1000) for the latest message sent to that
contact before it. A reply's signal and reply-received event rows are folded into it.
body, bodyTruncated and inReplyTo.body need Inbox view: without it the rows come without text.
A LinkedIn voice note's message also carries voiceNote (voiceNoteId, status, durationMs,
language, provider, voiceId, scriptText, failureReason, audioAvailable, audioUrl); a
lead's own voice note has voiceNoteId 0, status received and only durationMs, and one the
seat owner sent from LinkedIn itself is the same with status sent.
voiceNote.scriptText, like body, needs Inbox view.

add-to-campaign

Write. Early access: needs accounts, nurture_air_cover on for the workspace. POST https://api.ken.so/v1/accounts/{accountId}/add-to-campaign

Path: accountId

Body (json): campaignId integer, who string

Add the account's people with no 1:1 touch planned to a campaign. Returns added, alreadyIn and skipped. The campaign's own sequence then emails them, so confirm the campaign with the user first.

POST /api/v1/accounts/{accountId}/add-to-campaign. Staff, behind the backend flag
nurture_air_cover. Sends Ken-Version 1.1 and X-Ken-Actor: agent. Requires accounts edit
and campaigns edit. campaign_id (required) is a campaign of the workspace that is not
archived or completed. who: not_yet_contacted (default: people nobody ever sent a 1:1
touch, a member mailbox email or a campaign email) or everyone_mapped.
A person joins when they are a stakeholder of the account with an email, targeted and
not a blocker. The economic buyer, anyone with a 1:1 touch planned and anyone touched
in the last 30 days stay out, and so does anyone another open campaign already holds,
so an account's people join one campaign (the first add wins). People are imported like
a lead upload (dedup, blocklist, lead credits); the step never emails by itself. Running
it again adds nobody twice. Returns data: accountId, campaignId, campaignName, added,
alreadyIn (already in the campaign) and skipped (held back by the rules or another
campaign, or left out by the import: a duplicate elsewhere in the workspace, a rejected
row). When it added
anyone, the account timeline shows "N people with no 1:1 touch added to {campaign}".
Errors: validation_failed (400, a missing campaignId or a bad who); not_found (404, the
account or campaign is not in the workspace, or, with account scope own, the account is
not the caller's); invalid_state (409, campaign_closed: pick a draft, active or paused
campaign); plan_limit_reached (402, the workspace's lead credits refused the import and
nobody joined: tell the user to buy leads or upgrade).

bulk-create

Write. Early access: needs accounts on for the workspace. POST https://api.ken.so/v1/accounts/bulk-create

Body (json): items array

Add up to 100 target accounts in one call. Ken names each from Kenso Search and starts research. Each result is created, domain_taken (use that accountId), invalid or failed. Each created account starts research, charged per run (its AI work plus web pages).

POST /api/v1/accounts/bulk-create. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
items: 1 to 100, each {domains: [...], source?: manual|csv|search|promoted|workflow|api, fields?: {...}}
with the same domains and fields as accounts-create. Returns 200 with {created, skipped, failed, results[]}
in request order, even when some items fail. A created result carries the account and research: queued, or
waiting_credits when the workspace is short (it resumes when credits return); research is omitted when
account research is off. domain_taken counts as skipped and carries the owning accountId and domain. The same
domain twice in one call creates once and the repeat is domain_taken. invalid carries field and code.

bulk-update

Write. Early access: needs accounts on for the workspace. POST https://api.ken.so/v1/accounts/bulk-update

Body (json): accountIds array, accountType string

Set one account type on up to 500 accounts in one call. Each result is updated, unchanged, not_found, forbidden, conflict or failed.

POST /api/v1/accounts/bulk-update. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
account_ids: 1 to 500 account ids (a repeat counts once). account_type: prospect,
client, lost, churned, partner, competitor, investor or do_not_contact, with the same
rules as account_type on accounts-update. client from a caller who is not a workspace
admin fails whole with 403 customer_not_allowed; another type on an account that is a
client is a forbidden result for that account only. Returns 200 with {updated,
unchanged, failed, results[]}, one result per distinct id in request order:
{accountId, status, accountType (updated and unchanged), code and error (the rest),
mergedIntoId (conflict account_merged: use that account)}. An id outside the workspace
is not_found. Each account saves on its own, so a failed one never undoes the others;
retry only the failed ones. unchanged means the account already had the type. Only
client changes sending by itself: another type blocks the accounts' domains only while an
enabled blocklist rule names it (account_types on lists(operation="blocklist-rules-list")),
and a client moved to lost, churned, competitor or do_not_contact keeps its domains blocked;
to stop contacting accounts, use the blocklist. Set it only when the user asked for that type.

domain-create

Write. Early access: needs accounts on for the workspace. POST https://api.ken.so/v1/accounts/{accountId}/domains

Path: accountId

Body (json): domain string, isPrimary boolean

Add a domain to an account. Returns the account with every domain. A domain the account already has is a no-op. One another account owns is domain_taken.

POST /api/v1/accounts/{accountId}/domains. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. domain: a domain, website URL or work email (normalized).
is_primary=true makes it the primary domain.

create

Write. Early access: needs accounts on for the workspace. POST https://api.ken.so/v1/accounts

Query: skipResearch boolean

Body (json): angle string, cadenceDays integer, domains array, employeeCount integer, fitScore integer, fundingRound string, hqLocation string, industry string, kenCompanyId integer, linkedinUrl string, name string, networkLabel string, ownerMemberId integer, sendsFromFacebookAccountId integer, sendsFromInboxId integer, sendsFromLinkedInAccountId integer, sendsFromWhatsAppAccountId integer, source string, stage string, whyNow string

Create a target account from its domains. Returns 201 with the account. A domain another account owns fails with domain_taken and that account's id: use it.

POST /api/v1/accounts. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Ken names the account from Kenso Search and, when research is on, starts research, charged per run
(its AI work plus web pages).
skip_research (optional): true creates the account without research or the committee run, so the create
is free; start research later with committee(operation="research", account_id=...). Absent or false: as above.
domains: 1 to 20 domains, website URLs or work emails; the first is primary.
fields (optional): name (defaults to the Kenso Search name, else from the primary domain:
acme.com becomes Acme), stage (default researching; onboarding or client needs a workspace
admin and makes a customer), network_label (partner, investor or personal; stage network
only), owner_member_id,
fit_score (0-100), why_now, angle, cadence_days (1-365), industry, funding_round
(1-100 characters, such as Seed or Series B), employee_count, hq_location,
linkedin_url, ken_company_id (the company's Kenso id), sends_from_inbox_id, sends_from_linkedin_account_id,
sends_from_whatsapp_account_id, sends_from_facebook_account_id. snake_case or camelCase keys.
sends_from_inbox_id is the member's primary inbox email touches send from (or a shared
campaign inbox on one of the workspace's cold sending domains; the account owner approves its
touches), sends_from_linkedin_account_id the member-connected LinkedIn account LinkedIn
touches send from, and sends_from_whatsapp_account_id the WhatsApp account a member
connected that the account's WhatsApp touches send from.
sends_from_facebook_account_id is the member-connected Facebook account Facebook touches send from (needs Facebook
outreach on; otherwise not_enabled). Omit them to use the owner's. An agent may set them; a bad id fails with not_found,
not_owned or email_domain_mismatch (the inbox is off the workspace's email domain; the
message says what fixes it).
An agent's values are not pinned, so a person can change them later.

stakeholders-create

Write. Early access: needs accounts on for the workspace. POST https://api.ken.so/v1/accounts/{accountId}/stakeholders

Path: accountId

Body (json): coverage string, fillsSeatId integer, force boolean, kenNote string, note string, person object, personId integer, priority integer, reportsToStakeholderId integer, role string, source string

Add a person to an account as a stakeholder. Returns 201. Send person_id, or person {email, linkedin_url, full_name, title} (a match is reused).

POST /api/v1/accounts/{accountId}/stakeholders. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Send exactly one of person_id and person; a new person is
created when nothing matches. fields keys: role, priority, coverage, note,
ken_note, reports_to_stakeholder_id. person keys: full_name, first_name, last_name,
title, email, linkedin_url, ken_person_id; matched by email, then LinkedIn
URL, then Kenso person id, and a match only gains its blank fields. A role address
(support@, info@, no-reply@) is not a person: a new person with only that is 422
role_address; one with a linkedin_url, ken_person_id or a real first and last name is
added without it (a real name matches the same full name on the account first). role: champion,
economic_buyer, approver, evaluator, user, executive_sponsor, blocker, unknown.
priority 1 to 3. coverage: engaged, planned, gap, not_targeted. note is the short
line on the chart node; ken_note is the longer note for the person rail (up to 1,000 characters).
reports_to_stakeholder_id is a stakeholder on the same account (no loops).
fills_seat_id is an open seat from the committee tool's get on this account; the seat closes
in the same write. already_stakeholder returns the existing stakeholderId.
previously_removed means a person removed them: ask the user, and resend with
force=true only if they say so.

create-sales-navigator-account-import

Write. Early access: needs accounts, sales_navigator on for the workspace. POST https://api.ken.so/v1/linkedin-accounts/{linkedinAccountId}/sales-navigator/account-imports

Path: linkedinAccountId

Body (json): url string

Import the companies of a Sales Navigator account search or list as accounts. Reads the first 8 pages (about 200 to 400 companies) through your own seat; creates those with a website domain.

POST /api/v1/linkedin-accounts/{linkedinAccountId}/sales-navigator/account-imports.
Sends Ken-Version 1.1. Listed to members only in a workspace with the accounts
and sales_navigator features (the route is 404 when either is off). Needs
Accounts edit and the import permission.

linkedin_account_id is a seat you connected yourself: another member's seat
is not_found. url is a Sales Navigator account search or account list; a lead
search or list is validation_failed (import people with
contacts(operation="contact-imports-create", source="sales_navigator", ...)).
Companies are created in batches of 100 like accounts(operation="bulk-create")
(source api; research starts per created account). Returns counts: read,
created, domainTaken (already an account), invalid, failed (retry by importing
the same url again), skippedNoDomain (no website in Sales Navigator) and
truncated (the list was longer than what was read).
A seat without Sales Navigator is 409 sales_navigator_required.

domain-delete

Write. Early access: needs accounts on for the workspace. DELETE https://api.ken.so/v1/account-domains/{accountDomainId}

Path: accountDomainId

Remove a domain from its account. Returns the account. The last domain cannot go (last_domain). Removing the primary promotes the oldest.

DELETE /api/v1/account-domains/{accountDomainId}. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. account_domain_id is domains[].id on the account.

delete

Write. Early access: needs accounts on for the workspace. DELETE https://api.ken.so/v1/accounts/{accountId}

Path: accountId

Delete an account. Frees its domains, removes its stakeholders, skips open touches. People stay. Only on the user's explicit request. Requires Accounts edit access.

DELETE /api/v1/accounts/{accountId}. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Returns 204. Use stage not_a_fit or paused to set an account aside instead.

stakeholders-delete

Write. Early access: needs accounts on for the workspace. DELETE https://api.ken.so/v1/stakeholders/{stakeholderId}

Path: stakeholderId

Remove a stakeholder from its account. Skips their open touches; the person stays.

DELETE /api/v1/stakeholders/{stakeholderId}. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Returns 204. Prefer coverage not_targeted to keep the history visible.

facets

Read. Early access: needs accounts on for the workspace. POST https://api.ken.so/v1/accounts/facets

Body (json): filters array, timeZone string

Count accounts per filter value, under the other filter conditions. Lists the industry and fundingRound values in use. No q.

POST /api/v1/accounts/facets. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
filters: the same conditions as the search operation (optional).
Returns data.totalCount (accounts that pass every condition) and data.facets, one
{field, values: [{value, count}]} per field in this order: stage, committee,
lastTouch, industry, fundingRound, headcount, signal, latestSignal, then
hasOpenOpportunity while Opportunities is on, then tier, then accountType. A value's
count applies every other condition but not its own field's, so it is how many
accounts the list would show with that value added (an account with several signal
kinds counts under each). stage, committee, lastTouch, headcount, signal,
latestSignal and accountType list every value, zero counts included. tier lists "1"
to the ladder's tierCount. industry and fundingRound list the 100 values most used in
the workspace. time_zone: an IANA zone for the lastTouch and latestSignal buckets, as
on the search operation.

get

Read. Early access: needs accounts on for the workspace. GET https://api.ken.so/v1/accounts/{accountId}

Path: accountId

Query: expand string

Return one account with its domains, owner, stage and pinned fields. expand='stakeholders' embeds up to 200 stakeholders with their person. expand='research' embeds the research dossier (see committee(operation='research')).

GET /api/v1/accounts/{accountId}. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
pinnedFields lists the fields a person set; change those only when the user asks.
expand is comma-separated (stakeholders,research). researchStatus and researchedAt are on
every account; expand=research adds the research block that committee(operation='research') returns.
Reading it never starts a run.
A lost account carries reengageAfter (YYYY-MM-DD), the day Ken drafts its one re-engagement
touch (the lost deal's day plus 180 days); omitted otherwise.

list

Read. Early access: needs accounts on for the workspace. GET https://api.ken.so/v1/accounts

Query: accountType string, cursor string, domain string, expand string, fitsIcp boolean, hasOpenOpportunity boolean, ids string, isCustomer boolean, latestSignalAfter date-time, limit integer, nextTouchBefore date-time, ownerMemberId integer, q string, sort string, stage string, stageGroup string, tagIds string

List target accounts in the workspace, with domains, tagIds, signal score and open opportunities. Filter by stage, stage group, owner, domain (any URL or email works), name text, next touch, latest signal, tags, open opportunity, customer, account type or ICP fit. sort=-score with latest_signal_after and fits_icp=true lists the accounts heating up. account_ids=[...] reads up to 100 accounts as get does, in one call.

GET /api/v1/accounts. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
stage: comma-separated, any of the 16 stages: new, researching, warming, engaged,
meeting_booked, in_deal, onboarding, client, churned, nurture, paused, lost, network,
not_a_fit, competitor, do_not_contact.
stage_group: comma-separated, any of to_sort (new), pipeline (researching to
in_deal), customers (onboarding, client, churned), later (nurture, paused, lost), network
and archive (not_a_fit, competitor, do_not_contact). Every account carries stageGroup.
Onboarding and client hold isCustomer true (domains blocked).
domain is normalized (https://www.acme.com/x -> acme.com).
q matches the name or a domain. next_touch_before and latest_signal_after are
ISO-8601 instants; a time without an offset is UTC. latest_signal_after keeps
accounts whose latest signal's event time is at or after it. tag_ids: up to 100
tag ids; an account carrying any of them matches (OR). Every account has tagIds,
the ids of its tags ([] when none); tag names come from tags(operation="list").
has_open_opportunity true keeps accounts with a live opportunity in an open stage,
false keeps accounts without one. is_customer true keeps customer accounts, false the
rest. Every account carries isCustomer, customerSince (when it became one) and
customerSource (manual, opportunity_won or crm; both omitted when not a customer).
account_type: comma-separated, any of prospect, client, lost, churned, partner,
competitor, investor, do_not_contact (client,lost keeps either). Every account carries
accountType, which follows the stage: client at onboarding and client; churned, competitor,
do_not_contact and lost by name; partner or investor at network by networkLabel (partner,
investor or personal; omitted off network); else prospect or the type set before stages.
fits_icp true keeps the accounts that fit the ICP, the ones Today surfaces for their
signals: none of the account's domains is one of the workspace's own domains, its
stage is in pipeline or later, and research has not scored its fit below 20 (an account not
researched yet fits); false keeps the rest. sort: -createdAt (default), name, nextTouchAt,
-score (highest first, never scored last), -latestSignalAt (newest first, no signal
last). Today's Heating up is latest_signal_after=<now - 7 days>, fits_icp=true,
sort=-score, limit=4.
limit 1 to 200 (default 50). Pass pagination.nextCursor back unchanged with the
same filters and sort. Each account has score (0-99), scoredAt, signalCount,
engagedPeopleCount and latestSignal {id, kind, title, occurredAt, detectedAt}
once it has been scored. recentSignalKinds lists the distinct kinds of its signals
whose event time is in the last 90 days, read live (stored kinds, so a job_change
filter match can show leadership_hire); omitted when there are none. Search, get,
update and account-domain responses carry recentSignalKinds too.
Every account carries tier and autoTier (1 to the ladder's tierCount, see
account_signals(operation="account-tiers-get")). autoTier is where the ladder puts
it: the tier it was placed at, else the tier its score falls in (not scored yet
reads score 0, the last tier). tier is the tier it is worked at: tierOverride when
a person set one, else autoTier. tierOverride is omitted for Auto.
While Opportunities is on for the workspace, each account carries openOpportunityCount
(0 when none), openPipelineAmount (the sum of its open opportunities' amounts in the
workspace currency, omitted when none has an amount) and openOpportunityStage (stage
key of the newest open opportunity, omitted when none is open). With Opportunities
off, and on create and update responses, the three fields are left out: a missing
openOpportunityCount does not mean zero.
An account at stage lost with a lost opportunity carries reengageAfter (YYYY-MM-DD):
the day Ken drafts one re-engagement touch for it, the lost deal's day plus 180 days
(AccountsPlan:ReengageAfterDays). Omitted on every other account; get carries it too.
expand='committee' adds each account's committee summary in the same call: stakeholderCount,
openSeatCount, coverage {covered, total} (as committee(operation='get') reports it), roles
[{role, stakeholderCount, openSeatCount}] and run (the latest mapping run, omitted when Ken
never mapped the account). Without expand there is no committee.
expand='connections' adds each account's teammates' LinkedIn connections: connections {count
(distinct people at the account), people [{personId, fullName}] (the first few), connectedVia
[{linkedinAccountId, displayName, memberId}]}, omitted when there are none. expand='committee,connections'
adds both. Accounts the LinkedIn connections import added that nobody has worked yet carry
importOnlyAt; they are left out unless one of their connections fits the ICP, or domain looks
one up.
account_ids: up to 100 account ids (sent as ids=). Returns those accounts in one call, each exactly as
accounts(operation='get') returns it, in the order given; expand='stakeholders' embeds up to
200 stakeholders each (research is one account's read: use get). Ids that are missing,
deleted or outside the caller's scope are left out; a merged id answers with the account it
was merged into. With account_ids, send no other argument but expand (the API answers 400 otherwise).

stakeholders-list

Read. Early access: needs accounts on for the workspace. GET https://api.ken.so/v1/accounts/{accountId}/stakeholders

Path: accountId

Query: cursor string, limit integer

List an account's stakeholders, each with its person, role and coverage.

GET /api/v1/accounts/{accountId}/stakeholders. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Oldest first. accounts get with expand='stakeholders' returns
up to 200 in one call.

merge

Write. Early access: needs accounts on for the workspace. POST https://api.ken.so/v1/accounts/{accountId}/merge

Path: accountId

Body (json): intoAccountId integer

Merge a duplicate account into the one to keep (same company). Returns the kept account. Cannot be undone. Only on the user's explicit request. Requires accounts edit, like delete.

POST /api/v1/accounts/{accountId}/merge. Staff. Sends Ken-Version 1.1 and X-Ken-Actor:
agent. account_id is the duplicate, merged away; into_account_id is the account to keep.
In one step:
- Fields: the kept account keeps every field a person set. Otherwise a field a person
  set on the duplicate wins, and a blank field takes the duplicate's value.
- Domains move as secondary domains; the kept account keeps its primary.
- Stakeholders move. A person on both accounts becomes one stakeholder. A person a
  human removed from the kept account stays removed.
- Touches move. Unsent ones are skipped (account_merged) when the kept account already
  has an open touch.
- Research, committee runs and seats, email finds, Studio pages, opportunities, bookings,
  Scheduler links, meetings, calendar guests, tags, meeting notes and the timeline move (a tag both accounts
  carry stays once). A second open research or committee run is closed
  (paid research is refunded). Every opportunity moves, open ones stay open.
The duplicate's id then reads as the kept account, and a write to it fails with
account_merged naming the kept account.

Errors: same_account (400, the two ids are equal); account_merged (409, either account
was merged already: error.details[].mergedIntoId is the account to use); 404 when
either account is not in the workspace or was deleted, or, with account scope own, is
not the caller's.

contacts-promote

Write. Early access: needs accounts, promote_to_accounts on for the workspace. POST https://api.ken.so/v1/contacts/promote

Body (json): contactIds array, stage string

Promote 1 to 100 campaign contacts to Accounts, one target account per company. Reuses the account that already owns a company domain. Never stamps do-not-contact.

POST /api/v1/contacts/promote. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Requires campaigns edit and accounts edit. stage is researching, warming (default) or engaged.

Contacts are grouped by company: the company domain, else the email domain. A new
account starts at stage with source promoted and Ken researches it. An existing
account only moves forward (researching, warming, engaged, meeting_booked, in_deal); one at
new moves to stage, and one in customers, later, network or archive keeps its stage. Each contact with an email or a LinkedIn
URL joins as an engaged stakeholder (priority 1). Every campaign sequence at the
account's domains stops. One account.promoted activity event per account.

Returns data.stage, data.accounts (accountId, name, domain, created, stage,
previousStage when an existing account moved, research, people with result added,
already_member, no_identity, previously_removed or failed, sequenceStop done or failed
(failed: promote again to retry the stop) and sequencesStopped) and data.skipped
(contactId, code not_found, no_company_domain,
generic_email_domain, domain_taken (another member's account owns it and the caller
works only its own accounts), recruiting_campaign (a recruiting campaign's candidate
never becomes an account) or failed, message). When nothing could be promoted the call is
400 validation_failed with one contactIds detail per skipped contact.

Read. Early access: needs accounts on for the workspace. POST https://api.ken.so/v1/accounts/search

Body (json): cursor string, expand array, filters array, includeImportOnly boolean, includeTotal boolean, limit integer, q string, sort string, timeZone string, where object

Search accounts with filter conditions and AND / OR groups, as the Accounts list does. filters: [{field, operator: is|is_not, values}]. where: {match: all|any, conditions: [condition | group]}. include_total=true fills pagination.total.

POST /api/v1/accounts/search. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Every argument is optional; none lists every account.
filters: a list of {"field", "operator", "values"} conditions, for example
[{"field": "stage", "operator": "is", "values": ["engaged", "warming"]}].
Conditions AND together; the values of one condition OR together. operator is is
or is_not; is_not also matches an account with no value for the field. One
condition per field (a second fails with duplicate_field). At most 50 values per
condition; a condition with no values is ignored.
Fields and values:
- stage: the 16 stages, new to do_not_contact, as on accounts_list.
- stageGroup: to_sort, pipeline, customers, later, network, archive (as on accounts_list).
  Not a facet field.
- committee: none_engaged (no stakeholder with coverage engaged or planned, also
  when there are no stakeholders), under_half (under half of them), half_or_more.
- lastTouch: past_7_days, one_to_four_weeks (7 to 28 days ago), over_a_month,
  never (no touch sent or done). A touch is a sent or done account touch, an
  outbound email, or a campaign LinkedIn invite, message or InMail to the
  account's people; a LinkedIn message sent from the Inbox does not count.
- headcount: under_250, from_250_to_999, from_1000 (employeeCount; an account
  with no employeeCount is in no bucket).
- industry, fundingRound: any text, exact match. Read the values in use from the
  facets operation.
- signal: job_change, funding, hiring, public_post, event, asset_view, tech_change.
  Accounts with a signal of that kind whose event time (when it happened, else
  when Ken found it) is in the last 90 days; job_change also matches
  leadership_hire. is_not matches accounts with none of them.
- latestSignal: the latest signal's event time in the lastTouch buckets:
  past_7_days, one_to_four_weeks, over_a_month, never (no signal or not scored).
- hasOpenOpportunity: true (the account has a live opportunity in an open stage) or
  false. Items carry openOpportunityCount, openPipelineAmount and openOpportunityStage.
- isCustomer: true (the account is a customer) or false.
- tier: "1" to "10" (strings), the tier the account is worked at, the tier field of
  each item: the hand-set tier, else the tier the ladder placed it at, else the
  tier its score falls in on the workspace's ladder. A tier past the ladder's
  tierCount matches no account.
- accountType: prospect, client, lost, churned, partner, competitor, investor,
  do_not_contact (follows the stage).
last_touch, funding_round, latest_signal, has_open_opportunity, is_customer,
account_type and stage_group are accepted for lastTouch, fundingRound, latestSignal,
hasOpenOpportunity, isCustomer, accountType and stageGroup.
An unknown field or value fails with the allowed list.
where: a group {"match": "all" or "any", "conditions": [...]}, each entry a condition
or a group (2 levels at most, 50 conditions in all), ANDed with filters. A field may
repeat; a condition with no values is ignored. Every filters field takes is / is_not
with the values above, plus:
- headcount lt / gte N employees; committee lt / gte N (0-100, the engaged-or-planned
  share; none is 0).
- lastTouch, latestSignal within_days / older_than_days N (1-365; never matches neither).
- owner: is / is_not member ids (is_not also matches no owner), or is_empty.
- tags: tag ids; is = has any of them, is_not = has none.
- domain: is (normalized like a domain write), contains, ends_with (e.g. ".io").
- pipelineStage: open opportunity stage keys (is, is_not = none of them, is_empty).
- nextTouch: is_planned, is_not_planned, within_days N (overdue counts).
- connectedVia: is / is_not "any" (some teammate's LinkedIn seat lists one of the
  account's people) or seat ids (linkedinAccountIds from linkedin(operation="list")).
Example: {"match": "any", "conditions": [{"field": "tier", "operator": "is",
"values": ["1"]}, {"match": "all", "conditions": [{"field": "accountType",
"operator": "is", "values": ["prospect"]}, {"field": "lastTouch", "operator":
"older_than_days", "values": [30]}]}]}. Errors name the path, e.g.
where.conditions[1].conditions[0].values[0].
q matches the name or a domain (up to 300 characters). sort: -createdAt (default),
name, nextTouchAt, -score, -latestSignalAt. limit 1 to 200 (default 50). Pass pagination.nextCursor back
unchanged with the same filters, where, q and sort. include_total=true fills
pagination.total with every account that passes the filters, where and q. Each item
embeds its domains.
time_zone: an IANA zone such as Europe/Bucharest. With a zone, lastTouch, latestSignal
and nextTouch count calendar days in it, as the app does: past_7_days is today and the
7 days before it, within_days N starts at the zone's midnight N days ago. The member's
app time zone (Settings) wins over it. With neither, the windows roll back from now.
include_import_only: true also returns accounts the LinkedIn connections import added that
nobody has worked yet (they carry importOnlyAt). Default false: they are left out unless one
of their connections fits the ICP.
expand: ["connections"] adds each account's connections {count, people [{personId,
fullName}], connectedVia [{linkedinAccountId, displayName, memberId}]}, omitted when none.

update

Write. Early access: needs accounts on for the workspace. PATCH https://api.ken.so/v1/accounts/{accountId}

Path: accountId

Body (json): accountType string, angle string, cadenceDays integer, employeeCount integer, fitScore integer, fundingRound string, hqLocation string, industry string, isCustomer boolean, kenCompanyId integer, linkedinUrl string, name string, networkLabel string, overwritePinned boolean, ownerMemberId integer, sendsFromFacebookAccountId integer, sendsFromInboxId integer, sendsFromInstagramAccountId integer, sendsFromLinkedInAccountId integer, sendsFromWhatsAppAccountId integer, stage string, tierOverride integer, whyNow string

Update account fields. Absent fields stay unchanged; null clears one. A field a person set fails with pinned_by_user unless overwrite_pinned=true.

PATCH /api/v1/accounts/{accountId}. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
changes keys: name, stage, network_label, owner_member_id, fit_score, why_now, angle,
cadence_days, industry, funding_round, employee_count, hq_location, linkedin_url,
ken_company_id, sends_from_inbox_id, sends_from_linkedin_account_id,
sends_from_instagram_account_id, sends_from_whatsapp_account_id, sends_from_facebook_account_id,
tier_override, is_customer, account_type.
stage: one of the 16 stages on accounts_list. The Customer flag and accountType follow it:
onboarding and client make the account a customer (domains blocked); moving a customer off
them clears the flag, keeping its domains blocked at churned, lost, competitor or
do_not_contact. A stage that sets or clears the flag needs a workspace admin (403
customer_not_allowed); a stage and is_customer that disagree fail with conflict.
network_label (partner, investor or personal; null clears it) needs stage network, sent or
stored; leaving network clears it.
sends_from_inbox_id is the member's primary inbox (isPrimary in inboxes list) email touches
send from, or a shared campaign inbox on one of the workspace's cold sending domains (the
account owner approves its touches); sends_from_linkedin_account_id is the member-connected LinkedIn account LinkedIn
touches send from; sends_from_instagram_account_id is the member-connected Instagram account
Instagram touches send from (update only, not create); sends_from_whatsapp_account_id is the
WhatsApp account a member connected that the account's WhatsApp touches send from;
sends_from_facebook_account_id is the member-connected Facebook account Facebook touches send from
(needs Facebook outreach on; otherwise not_enabled). null clears
any of them, so the account owner's own sends. An agent may set them and they are never pinned;
a bad id fails with not_found, not_owned, not_member (the member who connected it left) or
email_domain_mismatch (the inbox is off the workspace's email domain; the message says
what fixes it).
tier_override (1 to the ladder's tier_count) sets the account's tier by hand and routes it
to that tier's destination (account-tiers) after the other fields save; null is Auto: the
account goes back to its autoTier (the tier the ladder placed it at, else its score's
tier) without routing, unless the hand-set tier moved the account to a lane its autoTier
does not work (a campaign or Watch): Auto then keeps the hand-set tier, so the tier
matches where the account is. Either way the change shows in the account's activity. A
tier that adds the account's people to a campaign or stops them in one also needs campaigns
edit. Set it only when the user asked for that tier. A field that fails validation saves
nothing. A tier the campaign refuses (the plan's lead limit) or a 409 from another tier
change leaves the tier unset and keeps the other fields saved, so send tier_override in its
own call when the other fields must not apply without it.
is_customer (true or false; null fails) marks the account a customer or clears it, after
the other fields save. Only a workspace admin may change it: anyone else gets 403 forbidden
with code customer_not_allowed and nothing saves (sending the stored value back is ignored).
true blocklists every domain of the
account with reason customer, so its people are never emailed, and moves the stage to
client (onboarding stays); false at onboarding or client moves it to churned and keeps those rows. Set it only when the user asked for that change.
account_type: prospect, client, lost, churned, partner, competitor, investor or
do_not_contact (null fails), saved after is_customer. It moves the stage (client, churned,
competitor, do_not_contact and lost to that stage; partner and investor to network with that
label; prospect to researching); stage in the same call wins. client is the customer flag: setting
client sets is_customer true and moving a client to another type clears it, so either
change needs a workspace admin (403 customer_not_allowed, nothing saves). Any other change
is open to anyone who can edit accounts. account_type and is_customer that disagree in one
call fail with conflict. Each change writes account.type_changed to the timeline. Only
client changes sending by itself: another type blocks the account's domains only while an
enabled blocklist rule names it (account_types on lists(operation="blocklist-rules-list")),
and a client moved to lost, churned, competitor or do_not_contact keeps its domains blocked.
To stop contacting an account, use the blocklist, not account_type.
Set overwrite_pinned only when the user asked for that exact change.

stakeholders-update

Write. Early access: needs accounts on for the workspace. PATCH https://api.ken.so/v1/stakeholders/{stakeholderId}

Path: stakeholderId

Body (json): coverage string, kenNote string, note string, overwritePinned boolean, priority integer, reportsToStakeholderId integer, role string

Update a stakeholder's role, priority, coverage, notes or manager. Null clears one.

PATCH /api/v1/stakeholders/{stakeholderId}. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. changes keys: role, priority, coverage, note, ken_note,
reports_to_stakeholder_id. Values as in stakeholders-create. A field a person set
needs overwrite_pinned=true, only when the user asked.