Kenso MCP tools

LinkedIn Connections linkedin_connections

Manage your LinkedIn connections. Requests your seats receive: Kenso's spam and ICP triage, each seat's off, manual or autonomous accept setting, and accepting or skipping one request or many. Invitations your seats sent that are still pending: list them, and withdraw picked ones or all older than N days (queued and paced). The workspace's network: each seat's 1st-degree connections matched to Kenso Search and scored against the ICP, job changes, account suggestions, and promoting connections to accounts. Accept, skip or change a seat as its owner only when they ask: the change counts as the owner's own. The seats themselves (connect, reconnect, edit, remove) are the linkedin tool.

Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through linkedin_connections_read and changes through linkedin_connections_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: network-account-suggestions, invitation-withdrawals-create, requests-decide, requests-decide-bulk, inbound-get, network-get, warm-paths-hop-outcome, connections-list, invitation-withdrawals-list, invitations-list, requests-list, connections-promote, warm-paths-run-cancel, warm-paths-run-create, warm-paths-run-get, network-sync, connections-update, inbound-update, connections-warm-paths, warm-paths-warmth

network-account-suggestions

Read. Early access: needs linkedin_network on for the workspace. GET https://api.ken.so/v1/linkedin-network/account-suggestions

Query: cursor string, limit integer

List companies where ICP-fit connections work that are not accounts yet, best first. Each suggestion names up to 5 fit connections. Add one with operation connections-promote.

GET /api/v1/linkedin-network/account-suggestions. Staff, behind the backend flag
linkedin_network. Needs Accounts view. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Companies (by company domain) with at least one icpStatus fit connection and no live
account for that domain, sorted by fitConnectionCount, then topScore, then domain.
Items: companyDomain, companyName, kenCompanyId, industry, employeeCount,
fitConnectionCount and connectionCount (people, each counted once), topScore,
connections[] (up to 5 fit people, best score first: id, fullName, title, icpScore, linkedinUrl,
linkedinAccountId, isJobChanged).
limit 1 to 200 (default 50). Pass pagination.nextCursor back unchanged; hasMore says
whether there is another page.
To add a suggestion as an account with its people as stakeholders, pass the
connection ids: linkedin_connections(operation="connections-promote", connection_ids=[101, 102]).
Errors: 404 not_found (flag off), 400 validation_failed (limit out_of_range, cursor
invalid), 403 permission_denied.

invitation-withdrawals-create

Write. Early access: needs linkedin_inbound on for the workspace. POST https://api.ken.so/v1/linkedin-invitations/withdrawals

Body (json): invitationIds array, linkedinAccountId integer, olderThanDays integer

Withdraw pending LinkedIn invitations on one of your seats: picked ids, or every one older than N days. Queued and paced at 25 a day per seat. LinkedIn blocks re-inviting a withdrawn person for about 3 weeks.

POST /api/v1/linkedin-invitations/withdrawals. Staff, behind the backend flag
linkedin_inbound. Needs Accounts edit and the approve permission. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Only the seat owner, the member who connected the seat, may list or
withdraw its invitations: any other seat answers 404 not_found. Kenso records who asked and
the client it came through (withdrawal.requestedVia).
Tell the user before you withdraw: LinkedIn blocks re-inviting a withdrawn person for about
3 weeks.
- linkedin_account_id: the seat (required).
- invitation_ids: 1 to 100 invitationId values from operation invitations-list on this seat.
  Only ids already seen by the list can be withdrawn; any other id comes back in notFound.
  Repeats are sent once.
- older_than_days: 1 to 365, every pending invitation on the seat sent more than that many
  days ago. The sweep skips invites a campaign still owns (a campaign contact on this seat
  still waiting on its invite): those follow their campaign's own withdraw rule.
Send exactly one of invitation_ids and older_than_days.
Nothing reaches LinkedIn in this call. Withdraws are queued, and Kenso's background withdraw
sends them paced: at most 25 per seat per day, inside the seat's working hours, sharing the
seat's spacing with its campaign actions and inbound accepts, and waiting while LinkedIn
holds or cools the seat. A large sweep trickles out over days or weeks. Withdrawing an
invite a campaign sent marks that campaign contact withdrawn, and the campaign does not
invite them again.
Answers 202. With invitation_ids: data.queued (how many this call queued; a failed withdraw
is queued again), data.alreadyQueued (ids already queued, withdrawn or gone, left as they
were) and data.notFound. With older_than_days: data.sweepId, data.olderThanDays and
data.status (running). The sweep first reads the seat's whole sent list, and the seat's
withdraws wait while it runs; a seat's running sweep is answered as it is, with its own
olderThanDays. Follow it with operation invitation-withdrawals-list.
Errors: 400 validation_failed (exactly_one, out_of_range, invalid), 403 permission_denied,
404 not_found, 409 invalid_state code seat_unavailable.

requests-decide

Write. Early access: needs linkedin_inbound on for the workspace. POST https://api.ken.so/v1/linkedin-requests/{linkedinRequestId}/decisions

Path: linkedinRequestId

Body (json): action string, updatedAt date-time

Accept or skip one LinkedIn connection request on your own seat, or accept a hidden spam request to rescue it. Only when the person asked you to decide this request: it counts as the seat owner's, in their name on LinkedIn.

POST /api/v1/linkedin-requests/{linkedinRequestId}/decisions. Staff, behind the backend
flag linkedin_inbound. Needs Accounts edit and the approve permission. Sends Ken-Version 1.1
and X-Ken-Actor: agent.
Decides as the caller's Kenso user (DEV-5878): the seat owner's agent or API key decides
exactly as the owner would in the Kenso app, and Kenso records the client it came through
(decidedVia). Call it only after the person saw the request (operation requests-list) and
told you to accept or skip it; never decide requests on your own. After an accept as lead on
an autonomous seat with send_first_message on, the AI first message goes out with no one
approving; on a manual seat it waits for a person on Today. A request that came with an
invitation note always waits for a person (or their agent, when asked) to approve the reply.
- linkedin_request_id: the request (id from operation requests-list).
- action: accept_as_lead (accept, then hand the person to Accounts or the seat's campaign),
  accept_only (accept and add to the network, nothing else) or skip (hide it; it stays
  pending on LinkedIn).
- updated_at: the request's updatedAt from the version you showed the user (optional; a newer
  version is 409 conflict, code concurrent_change).
An accept queues the request: the paced background accept sends it to LinkedIn later. It works
from awaiting_decision or ignored (a rescued spam item), a skip only from awaiting_decision;
anything else is 409 invalid_state, code invalid_transition. A seat that is not connected is
409 invalid_state, code seat_unavailable, and a seat whose inbound mode is off is 409
invalid_state, code seat_off. Only a request on a seat the caller connected can
be decided; any other id is 404 not_found, and so is every id for a key with no Kenso user.
An unknown action is 400 validation_failed, code unknown_action.
To decide many at once: linkedin_connections(operation="requests-decide-bulk").
Returns the request in its new state, as operation requests-list lists it.
Errors: 403 permission_denied, 404 not_found, 409 as above.

requests-decide-bulk

Write. Early access: needs accounts, linkedin_inbound on for the workspace.

Accept or skip many LinkedIn connection requests at once: by id, or every request waiting in a lane. Only when the person asked for it. lane="strong" with accept_as_lead accepts every strong fit on your seats. Each counts as the seat owner's decision.

POST /api/v1/approvals/decisions, the approvals bulk route. Staff, behind the backend flags
linkedin_inbound and accounts: the route opens when one of
accounts, linkedin_ai_notes, agent_templates or linkedin_engagement is on for the workspace, and connection
requests need linkedin_inbound. Needs Accounts edit and the approve permission, or
approve_own_sends. Sends Ken-Version 1.1 and X-Ken-Actor: agent. Decides as the caller's Kenso
user (DEV-5878): the seat owner's agent or API key decides as the owner, only when the person
asked for these decisions. A key with no Kenso user connected no seat, so each id is not_found.
- action: accept_as_lead, accept_only or skip, one action for every request in the call.
- linkedin_request_ids: 1 to 500 request ids (id from operation requests-list), sent as
  linreq_<id>; repeats are sent once. Accepting an ignored request (hidden spam) rescues it.
- lane: strong, unclear or spam, instead of ids: every request awaiting a decision in that
  lane on the seats you connected, newest first, up to 500 per call. lane="strong" with
  action="accept_as_lead" accepts every strong fit.
- linkedin_account_id: with lane, one of your seats; without it, every seat you connected.
Send linkedin_request_ids or lane, not both.
Each request is decided on its own, exactly as operation requests-decide decides one, and
counts as the seat owner's decision: after an accept as lead on an autonomous seat with
send_first_message on, the AI first message goes out with no one approving; on a manual
seat it waits for a person on Today; a request that came with an invitation note always
waits for a person (or their agent, when asked) to approve the reply. One failing request
never stops the rest.
Returns data.results[] (id as linreq_<id>, status decided or failed, and error with code and
message when it failed), data.decided, data.failed and data.hasMore. With lane, hasMore true
means more requests are waiting: call again with the same arguments. It turns false once a
call decides nothing. Codes on a failed request: not_found (not a request on a seat you
connected), invalid_transition (an accept works from awaiting_decision or ignored, a skip
only from awaiting_decision), seat_unavailable, seat_off, internal_error (retry that one).
Errors: 400 validation_failed (unknown_action on action, ids_or_filter, too_many, invalid on
filter.lane or filter.linkedinAccountId), 403 permission_denied, 404 not_found (a flag off).

inbound-get

Read. Early access: needs linkedin_inbound on for the workspace. GET https://api.ken.so/v1/linkedin-inbound

Read each LinkedIn seat's inbound connection request settings, scan state and request counts. Shows the caller's own seats, and for a workspace admin the colleagues' seats that are not off.

GET /api/v1/linkedin-inbound. Staff, behind the backend flag linkedin_inbound. Needs
Accounts view. Sends Ken-Version 1.1 and X-Ken-Actor: agent. Reading never starts a scan
and calls no LinkedIn API; nulls are omitted.

data.seats[], oldest first: the live LinkedIn accounts (seats) the caller connected, any
mode; for a workspace admin also the colleagues' seats that are not off (isOwnSeat false).
- linkedinAccountId, displayName, connectedByMemberId, isOwnSeat.
- seatStatus (the LinkedIn account): connecting, connected, credentials_error, restricted,
  disconnected, deleted, connect_failed.
- Settings: mode (off, manual, autonomous; a seat never configured shows off),
  acceptThreshold (0-100, default 80: the score at or above which autonomous mode accepts by
  itself), lane (accounts or campaign: where accepted leads go), campaignId, sendFirstMessage
  (the delayed AI first message after an accept, accounts lane only),
  autonomousEnabledByMemberId, autonomousEnabledAt, autonomousEnabledVia (app when the owner
  saved it in the Kenso app, else the client that did, such as Claude Code, or api), updatedAt.
- Scan: scanStatus (pending, scanning, idle, paused, blocked), nextScanAt,
  firstScanCompletedAt, lastSuccessAt, backoffUntil, lastError (such as rate_limited,
  timeout, http_403). paused backs off until backoffUntil; blocked stays blocked until the
  seat reconnects.
- counts[]: one entry per lane (spam, strong, unclear; omitted before triage) and status
  (pending_triage, awaiting_decision, accept_queued, accepted, ignored, gone, failed),
  with a nonzero count.

To change a seat: linkedin_connections(operation="inbound-update"). To read the requests:
linkedin_connections(operation="requests-list"). To connect, reconnect, edit or remove a seat:
the linkedin tool (linkedin(operation="list") lists them).
Errors: 404 not_found (the flag is off for the workspace), 403 permission_denied.

network-get

Read. Early access: needs linkedin_network or linkedin_connections_import on for the workspace. GET https://api.ken.so/v1/linkedin-network

Read the workspace's LinkedIn network: each seat's connection sync and the workspace counts. Counts cover matched, ICP-fit and job-changed connections. Reading never starts a sync.

GET /api/v1/linkedin-network. Staff, behind the backend flag linkedin_network or
linkedin_connections_import (either one). Needs Accounts view. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Any member with Accounts view sees every seat of the workspace; nulls
are omitted.

data.seats[], one per LinkedIn account (seat): linkedinAccountId, displayName,
connectedByMemberId, seatStatus, pausedAt, status, connectionCount (connections Kenso
has read), totalCount (the total LinkedIn reports, when it sends one),
initialSyncCompletedAt, lastSuccessAt, nextRunAt, backoffUntil, lastError.
- seatStatus (the LinkedIn account): connecting, connected, credentials_error,
  restricted, disconnected, deleted, connect_failed.
- status (the seat's connection sync): not_started (no sync row yet), pending,
  syncing (first sync in progress), synced, paused (backing off after a 429, a
  timeout or a 5xx until backoffUntil), blocked (Unipile answered 401, 403, 404 or
  422; stays blocked until the seat reconnects).
The connections import (DEV-5778), per seat: importConnections (the seat imports its
connections into Accounts), importConnectionsChangedAt, importedPeopleCount and
importedAccountsCount (records the import created), surfacedPeopleCount and
surfacedAccountsCount (of those, the ones someone has worked since). Switch a seat's
import with linkedin(operation="update", changes={"import_connections": true}).
Workspace counts, of people (someone two seats both know counts once):
connectionCount, matchedCount, pendingCount (match or score still
pending), icpFitCount, jobChangedCount (job change within the window),
jobChangedIcpFitCount, seniorJobChangedIcpFitCount (job changed, ICP fit, and
seniority vp, c_level, owner or partner), hasIcp (the workspace has ICP text; without
it connections score unknown) and jobChangeWindowDays (180).

To read or sync sooner, call linkedin_connections(operation="network-sync").
Errors: 404 not_found (the flag is off for the workspace), 403 permission_denied.

warm-paths-hop-outcome

Write. Early access: needs accounts, linkedin_network, warm_paths_v2 on for the workspace. POST https://api.ken.so/v1/warm-paths/{warmPathId}/hops/{hop}/outcome

Path: warmPathId, hop

Body (json): outcome string, personId integer

Confirm or correct how a sent warm path hop ended, and move the path on.

POST /api/v1/warm-paths/{warmPathId}/hops/{hop}/outcome. Staff; needs the
accounts, linkedin_network and warm_paths_v2 features. Sends Ken-Version 1.1
and X-Ken-Actor: agent. When a sent hop gets a reply, the hop's
pendingOutcome holds Ken's reading (outcome, confidence, reason, person,
isInterested); confirm it or correct it here. hop is the hop's index (its hop field). outcome: agreed,
declined, redirected, unknown_person, pointed or no_reply. person_id: only
with pointed or redirected, the person the reply points to. Returns data: the
path (status, hops) and move: next_hop (agreed: Ken drafts the next hop as a
touch waiting for the requester's approval; nextHopRefusal says why when it
could not: no_channel, never_ask, no_credits, draft_failed), succeeded (the
target answered; other active paths to them are cancelled), failed (declined
or unknown_person: that connector is never offered for this person again;
no_reply: the connector rests 90 days), expired (no_reply on the reply to an
intro) or replan (the named person is added as a stakeholder and
the next warm paths read ranks a path to them; nothing starts by itself).
Conflicts (the code says why): outcome_set (the hop already ended with
another outcome), not_yours (only the requester or an Accounts editor),
not_active, not_awaiting_outcome (not sent yet). Charges writer credits for
the next hop's draft.

connections-list

Read. Early access: needs linkedin_network or linkedin_connections_import on for the workspace. GET https://api.ken.so/v1/linkedin-connections

Query: companyDomain string, cursor string, group string, icpStatus string, importStatus string, jobChanged boolean, limit integer, linkedinAccountId integer, matchStatus string, q string, seniority string, sort string, tier string, warmPath boolean

List the workspace's LinkedIn connections with their Kenso Search match, ICP score and job change. Filter by seat, ICP status, job change, seniority, match status, group, tier, warm path, company domain or name text.

GET /api/v1/linkedin-connections. Staff, behind the backend flag linkedin_network or
linkedin_connections_import (either one). Needs Accounts view. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Every argument is optional. icp_status, seniority, match_status,
import_status, group and tier take one value or comma-separated values (comma = OR); an
unknown value is 400 validation_failed.
- linkedin_account_id: one seat's connections.
- icp_status: pending, fit (score 70 or more), not_fit, unknown (not scored: no Kenso
  Search match, or the workspace has no ICP text).
- job_changed: true keeps connections whose job changed within the window (180 days),
  false keeps the rest.
- seniority: Kenso Search levels in snake_case: unknown, training, entry, individual,
  senior, manager, director, vp, c_level, owner, partner (Search may add a level).
- match_status: pending, matched, not_found, failed.
- import_status: the connections import into Accounts (DEV-5778): pending, imported (a
  person was created or tagged), skipped (importSkipCode says why), dismissed (a member
  removed the imported person; the import never re-creates them).
- group: the connections enrich grouping (DEV-8511): buyer, partner, other. Honored only
  while the backend flag linkedin_connections_enrich is on; ignored otherwise.
- tier: 1 or 2, buyers only (tier 1 can sign or decide). Same flag as group.
- warm_path: true keeps connections who hold a current advisor, board or investor seat
  at an ICP-fit company. Same flag as group; false is no filter.
- company_domain: any domain, website URL or email (normalized).
- q: matches name, title or company (up to 300 characters).
- sort: -createdAt (default), -icpScore (highest first, unscored last), -connectedAt
  (newest first).
limit 1 to 200 (default 50). Pass pagination.nextCursor back unchanged with the same
filters and sort.
Items: id, linkedinAccountId, fullName, firstName, lastName, headline, linkedinUrl,
pictureUrl, connectedAt, matchStatus, title, seniority, companyName, companyDomain,
companyLinkedinUrl, industry, employeeCount, kenPersonId, kenCompanyId,
jobChangedAt, isJobChanged, previousCompanyName, previousTitle, icpStatus, icpScore,
icpReasons[], accountId (the live account owning companyDomain, when there is one),
createdAt, updatedAt, and the import's importStatus, personId (the person it created or
tagged), importedAt, importSkipCode and importAccountId. doNotAsk (the never-ask mark)
is on the connections of the caller's own seats only, while the backend flag
warm_paths_v2 is on. Nulls are omitted.
roles[]: the person's current roles, the current company first, each with companyName,
title, positionKind (employee, founder, executive, advisor, board, investor, member,
mentor; read from the title), accountId (the account the import linked for that role;
other companies are linked only where the backend flag linkedin_connections_all_roles
is on) and isPrimary (true for the current company's role).
While linkedin_connections_enrich is on (DEV-8511), each item also carries enrich (omitted
until sorted: group, reasonKind, reason, tier, groupedAt, emailFound, phoneFound, state),
warmPaths[] (accountId, companyName, positionKind: ICP-fit companies where the person holds
a current advisor, board or investor seat) and introTargets[] (a partner's ICP-fit
companies: companyName, title, positionKind, isCurrent, accountId, fitReason).
One seat's imported connections: linkedin_connections(operation="connections-list",
linkedin_account_id=5, import_status="imported").
The tier 1 buyers with a warm path: linkedin_connections(operation="connections-list",
group="buyer", tier="1", warm_path=True).
The senior ICP-fit job changers: linkedin_connections(operation="connections-list",
icp_status="fit", job_changed=True, seniority="vp,c_level").
To put connections into a campaign: contacts(operation="contact-imports-create",
campaign_id=42, source="linkedin_connections", connection_ids=[101, 102]).
Errors: 404 not_found (flag off), 400 validation_failed (details carry field and code,
for example limit out_of_range, cursor invalid, icpStatus with an unknown value), 403
permission_denied.

invitation-withdrawals-list

Read. Early access: needs linkedin_inbound on for the workspace. GET https://api.ken.so/v1/linkedin-invitations/withdrawals

Query: cursor string, limit integer, linkedinAccountId integer, status string

List the withdraws asked for on one of your LinkedIn seats, latest first, with the seat's recent sweeps. Filter by status: queued, withdrawn, gone (no longer pending, most likely accepted) or failed.

GET /api/v1/linkedin-invitations/withdrawals. Staff, behind the backend flag
linkedin_inbound. Needs Accounts view. Sends Ken-Version 1.1 and X-Ken-Actor: agent. Only
the member who connected the seat reads its withdraws: any other seat is 404 not_found.
Read from Kenso, not LinkedIn, so a disconnected seat still shows its history.
- linkedin_account_id: the seat (required).
- status: one or several comma-separated (comma = OR): queued (waiting for the paced
  withdraw), withdrawn, gone (no longer pending on LinkedIn: accepted, expired or withdrawn
  elsewhere; Kenso did not withdraw it), failed (withdrawing it again queues it again).
- limit: 1 to 200 (default 50). cursor: pagination.nextCursor, unchanged, with the same
  filters.
Returns data.items (invitations as operation invitations-list lists them, each with its
withdrawal: status, requestedAt, requestedVia, requestedByMemberId, sweepId, withdrawnAt,
error), data.sweeps (the seat's latest 10 older_than_days sweeps: sweepId,
linkedinAccountId, olderThanDays, status running, done or failed, queued, scannedPages,
startedAt, finishedAt, error) and data.pagination. A sweep's error is read_failed or
unexpected_shape on a failed sweep, or page_cap_reached on a done sweep that stopped at its
page cap (5,000 invites by default) before the end of the sent list: its oldest invites were not read
or queued.
Errors: 400 validation_failed (status, limit or cursor), 404 not_found.

invitations-list

Read. Early access: needs linkedin_inbound on for the workspace. GET https://api.ken.so/v1/linkedin-invitations

Query: cursor string, limit integer, linkedinAccountId integer

List the pending LinkedIn invitations one of your seats sent, newest first, read from LinkedIn. Each shows the person, when it was sent, the campaign that sent it (or none) and any withdraw.

GET /api/v1/linkedin-invitations. Staff, behind the backend flag linkedin_inbound. Needs
Accounts view. Sends Ken-Version 1.1 and X-Ken-Actor: agent. Only the member who connected
the seat lists its invitations: any other seat is 404 not_found.
- linkedin_account_id: the seat (required; linkedinAccountId from operation inbound-get).
- limit: 1 to 100 (default 50).
- cursor: pagination.nextCursor from the previous page, unchanged.
Each call reads one page from LinkedIn through Kenso's LinkedIn rate limiter, so page only as
far as you need. pagination.hasMore stays true until a page comes back empty.
Items (data[]): invitationId (what operation invitation-withdrawals-create takes),
linkedinAccountId, providerId (the person's LinkedIn member id), name, publicIdentifier and
profileUrl (LinkedIn rarely sends them), sentAt, campaignId and contactId (the campaign on
this seat that invited the person; omitted for an invitation sent outside Kenso), and
withdrawal (status queued, withdrawn, gone or failed, requestedAt, requestedVia,
requestedByMemberId, sweepId, withdrawnAt, error) once someone asked to withdraw it.
Nulls are omitted. Only ids a list returned can be withdrawn.
Errors: 400 validation_failed (limit out_of_range, cursor invalid), 404 not_found (not your
seat, or the flag is off), 409 invalid_state code seat_unavailable (the seat is not
connected), 429 rate_limited (LinkedIn is limiting reads on this seat: wait the Retry-After
seconds, then list again with the same cursor), 503 (LinkedIn could not be read; retry in a
minute).

requests-list

Read. Early access: needs linkedin_inbound on for the workspace. GET https://api.ken.so/v1/linkedin-requests

Query: cursor string, lane string, limit integer, linkedinAccountId integer, status string

List the LinkedIn connection requests on the caller's seats with Ken's spam and ICP triage, newest first. Filter by seat, lane or status. lane=spam with status=ignored lists what Ken hid.

GET /api/v1/linkedin-requests. Staff, behind the backend flag linkedin_inbound. Needs
Accounts view. Sends Ken-Version 1.1 and X-Ken-Actor: agent. Only the seats the caller
connected: a colleague's seat lists nothing. Every argument is optional.
- linkedin_account_id: one seat.
- lane: spam, strong (at or above the seat's accept_threshold) or unclear (everything else,
  including no ICP, no match or a failed triage). Requests triage has not reached have no lane.
- status: pending_triage, awaiting_decision, accept_queued (decided, waiting for the paced
  accept), accepted, ignored (hidden as spam, or skipped), gone (withdrawn, or accepted
  by hand on LinkedIn), failed.
lane=spam with status=ignored lists the requests Ken hid as spam, which a person can still
accept with operation requests-decide.
limit 1 to 200 (default 50). Pass pagination.nextCursor back unchanged with the same filters.
Items: id, linkedinAccountId, fullName, firstName, lastName, headline, note (the invitation
note), linkedinUrl, pictureUrl, receivedAt, status, lane, spamCategory (sellers,
recruiters_job_seekers, empty_profile, none), icpScore (0-100), icpReasons[] (up to 3),
matchStatus (Kenso Search: pending, matched, not_found, failed), title, seniority, companyName,
companyDomain, companyLinkedinUrl, industry, employeeCount, decision (accept_as_lead,
accept_only, skip), decidedBy (person or autonomous), decidedByMemberId, decidedVia (app,
else the client that decided, such as Claude Code, or api), decidedAt,
acceptedAt, handoffStatus (none, pending, done, failed), accountId, personId, contactId,
campaignId, createdAt, updatedAt (the decision version). Nulls are omitted.
Errors: 404 not_found (flag off), 400 validation_failed (limit out_of_range, cursor invalid,
an unknown lane or status), 403 permission_denied.

connections-promote

Write. Early access: needs accounts, linkedin_network on for the workspace. POST https://api.ken.so/v1/linkedin-connections/promote

Body (json): connectionIds array, stage string

Add LinkedIn connections to target accounts as stakeholders, creating accounts for new companies. A new account starts research, charged like accounts create. Up to 100 connections per call.

POST /api/v1/linkedin-connections/promote. Staff, behind the backend flags
linkedin_network and accounts. Needs Accounts edit. Sends Ken-Version 1.1 and
X-Ken-Actor: agent.
connection_ids: 1 to 100 connection ids (operation connections-list, or the connections[]
of operation network-account-suggestions); repeats are sent once.
stage: researching (default), warming or engaged. It applies to accounts this call
creates; an existing account keeps its stage.
Connections are grouped by company domain. A domain a live account owns joins that
account; an unknown one becomes a new account (source search, research queued as for
any new account, charged like accounts create). Each connection becomes a stakeholder
(role unknown, source search).
Returns data.stage, data.accounts[] (accountId, name, domain, created, research
(queued or waiting_credits, when the account was created and research is on),
people[] with connectionId, personId, stakeholderId, result: added or
already_stakeholder) and data.skipped[] (connectionId, code, message). skipped codes:
- not_found: not a connection of this workspace.
- not_matched: no Kenso Search match yet.
- no_company_domain, generic_email_domain: no company domain an account can own.
- domain_taken: another member's account owns the domain and the caller works only
  its own accounts.
- previously_removed: a person removed them from that account; agents and API keys
  do not re-add them.
- failed: retry.
Errors: 400 validation_failed when nothing is promotable (one detail per connection,
with the codes above), or for connectionIds required or out_of_range; 404 not_found
(a flag off); 403 permission_denied.

warm-paths-run-cancel

Write. Early access: needs accounts, linkedin_network, warm_paths_v2 on for the workspace. POST https://api.ken.so/v1/warm-path-runs/{runId}/cancel

Path: runId

Cancel a queued, running or waiting warm path run. The people it already ranked keep their paths.

POST /api/v1/warm-path-runs/{runId}/cancel. Staff; needs the accounts,
linkedin_network and warm_paths_v2 features. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Returns the run. A cancelled run answers again; a done or
failed run is 409 invalid_state.

warm-paths-run-create

Write. Early access: needs accounts, linkedin_network, warm_paths_v2 on for the workspace. POST https://api.ken.so/v1/warm-path-runs

Body (json): controlShare number, filters object, personIds array

Queue a warm path run: rank the ways in to up to 1,000 people in the background. Returns 202 with the run.

POST /api/v1/warm-path-runs. Staff; needs the accounts, linkedin_network and
warm_paths_v2 features. Sends Ken-Version 1.1 and X-Ken-Actor: agent. Send
person_ids (1 to 1,000) or filters, not both. filters is the people.search
filters in wire form (camelCase), for example {"accountIds": [812], "roles":
["champion"]}: every person they match, at most 1,000 (more is 400
too_many_targets). People not in the workspace are left out; none left is
400. control_share (0 to 0.5, default 0) holds that share of the people out at
random as the cold control: they get no warm ranking, so Experiments can
measure the lift. Ken ranks each person for the calling user, grouped by
account. A workspace holds at most 5 queued or running runs (409); they run
one at a time. Follow it with warm-paths-run-get, then read the results with
warm-paths-warmth.

warm-paths-run-get

Read. Early access: needs accounts, linkedin_network, warm_paths_v2 on for the workspace. GET https://api.ken.so/v1/warm-path-runs/{runId}

Path: runId

Read a warm path run: status, progress and coverage ("23 warm, 31 possible, 46 cold").

GET /api/v1/warm-path-runs/{runId}. Staff; needs the accounts,
linkedin_network and warm_paths_v2 features. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. status: queued, running, waiting_for_budget, done,
failed, cancelled. waiting_for_budget: the workspace's list runs spent
today's share of Kenso Search lookups (70 of the 100 a day; account pages
keep the rest), so the run picks up at resumesAt (the next UTC midnight)
and ranks the rest; it can still be cancelled. resumesAt is null in every
other status. targetCount, processedCount, controlShare, coverage
{warmCount (best path recommended), possibleCount (check_first), coldCount
(no warm path beats cold), controlCount (held out), failedCount,
skippedCount (gone from the workspace)}, controlPersonIds,
requesterMemberId, createdAt, startedAt, finishedAt.

network-sync

Write. Early access: needs linkedin_network on for the workspace. POST https://api.ken.so/v1/linkedin-network/sync

Body (json): linkedinAccountId integer

Queue a LinkedIn connections sync for one seat, or for every connected seat. Returns 202. Never reads LinkedIn inline: the background sync picks the seat up within minutes.

POST /api/v1/linkedin-network/sync. Staff, behind the backend flag linkedin_network.
Needs Accounts edit. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
linkedin_account_id (optional) is one seat; a seat that is not a live seat of the
workspace is 404 not_found. Without it, every connected, bound, unpaused seat.
For each seat: creates a missing sync row due now, or makes the existing row due now,
never sooner than its back-off; a blocked row is left alone. Connections whose Kenso
Search match failed go back to pending and get matched again; when the workspace has
ICP text, matched connections scored unknown go back to pending and get scored.
The sync reads one page per seat per run, a few minutes apart during the first sync
(about 4 hours for 4,000 connections), then the first page every 4 to 10 hours.
Answers 202 with the same data as linkedin_connections(operation="network-get"): seats[] with
status (not_started, pending, syncing, synced, paused, blocked) and the workspace counts.
Errors: 404 not_found (flag off, or a seat that is not a live seat of the workspace),
403 permission_denied.

connections-update

Write. Early access: needs warm_paths_v2 on for the workspace. PATCH https://api.ken.so/v1/linkedin-connections/{connectionId}

Path: connectionId

Body (json): doNotAsk boolean

Mark one of your own LinkedIn connections never ask, or clear the mark. A never-ask person is never used as a connector in a warm path. Only the seat's owner sees or sets it.

PATCH /api/v1/linkedin-connections/{connectionId}. Staff, behind the backend flag
warm_paths_v2. Needs Accounts view or Network view.
connection_id: a connection id from operation connections-list.
do_not_ask: true keeps the person out of every warm path as a connector; false clears it.
Only the member who connected the connection's seat (the person whose credential the
call uses) sets or clears it. For anyone else, another workspace's connection or a
removed one the answer is 404 not_found, so nobody learns another member's marks.
Setting it again keeps the time it was first set. The mark is per seat, its effect per
person: once any seat owner marks someone, warm paths leave that person out as a
connector everywhere in the workspace, also through other seats, whose rows still show
doNotAsk false.
Returns data: the connection as connections-list shows it to its owner, with doNotAsk.
Mark someone never ask: linkedin_connections(operation="connections-update",
connection_id=101, do_not_ask=True).
Errors: 404 not_found (flag off, or not a connection of one of your own seats), 400
validation_failed (doNotAsk required), 403 permission_denied.

inbound-update

Write. Early access: needs linkedin_inbound on for the workspace. PATCH https://api.ken.so/v1/linkedin-inbound/seats/{linkedinAccountId}

Path: linkedinAccountId

Body (json): acceptThreshold integer, campaignId integer, lane string, mode string, sendFirstMessage boolean

Change one LinkedIn seat's inbound settings, autonomous mode included, as the member who connected it. Turn autonomous on, or change an autonomous seat, only when the person asked you to: Ken then accepts in their name.

PATCH /api/v1/linkedin-inbound/seats/{linkedinAccountId}. Staff, behind the backend flag
linkedin_inbound. Needs Accounts edit, and the approve permission to turn autonomous on or to
change an autonomous seat. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Send at least one setting; an absent one stays as it is. Kenso calls no LinkedIn API here:
the background scan reads a seat once it is on.
- linkedin_account_id: the seat (linkedinAccountId from operation inbound-get).
- mode: off (nothing is scanned or accepted), manual (Ken scans and triages; a person
  accepts in Approvals) or autonomous (Ken also accepts requests at or above
  accept_threshold by itself, paced and in working hours).
- accept_threshold: 0 to 100, the score line for autonomous accepts (default 80).
- lane: accounts or campaign, where accepted leads go.
- campaign_id: with lane campaign, a scheduled or sending campaign of this workspace that
  sends from this seat (a campaign with no seat list sends from every seat); otherwise
  400 validation_failed with seat_not_in_campaign on campaignId.
  clear_campaign=true sends null and clears it; not both.
- send_first_message: the delayed AI first message after an accept (accounts lane only).

Autonomous: switching to autonomous, and changing accept_threshold, lane, campaign_id or
send_first_message on a seat that is autonomous (before or after the change), let Ken accept
connections in the owner's name, so they also need the approve permission (403
permission_denied without it). The owner's agent or API key (an MCP session or a Kenso API key
of that member) may do them as the owner (DEV-5878); an agent does so only when the person
asked for that change. Switching to off or manual needs no approve permission.
The change counts as the seat owner's approval, exactly as if the owner saved the seat in
the Kenso app. On an autonomous seat Ken then accepts every request scoring at or above
accept_threshold by itself, paced and in working hours. With send_first_message on, the AI
first message after an accept then goes out with no one approving. A request that came with
an invitation note still waits for a person (or their agent, when asked) to approve the reply.
Kenso records who changed the seat and through which client (autonomousEnabledVia). Switching
to manual and back restarts the autonomous window (autonomousEnabledAt), so change only what
the owner asked for.
Only the member who connected the seat changes it. A workspace admin may send exactly
mode="off" for a colleague's seat; anything else on a colleague's seat is 404 not_found, and
a Kenso API key with no member behind it owns no seat.
Returns the seat as operation inbound-get lists it.
Errors: 400 validation_failed (accept_threshold out of range, seat_not_in_campaign), 403
permission_denied, 404 not_found (flag off, or not your seat; every seat for a key with no Kenso
user).

connections-warm-paths

Read. Early access: needs linkedin_connections_enrich on for the workspace. GET https://api.ken.so/v1/linkedin-connections/warm-paths

Query: cursor string, limit integer, linkedinAccountId integer

List the ICP-fit companies where a LinkedIn connection holds an advisor, board or investor seat. One row per company with the connections who hold the seat; filter by seat.

GET /api/v1/linkedin-connections/warm-paths. Staff, behind the backend flag
linkedin_connections_enrich (DEV-8511). Needs Accounts view or Network view. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Every argument is optional.
- linkedin_account_id: only the seat's connections; left out, every seat's.
limit 1 to 200 (default 50). Pass pagination.nextCursor back unchanged with the same
seat. Rows are in company name order.
Items: accountId (the workspace account the fit links, omitted when there is none),
companyName, domain, people[] (connectionId, personId, name, title, positionKind:
advisor, board or investor). A warm path is a role fit the connections enrich wrote
with is_current and icp_fit; the companies come from the people's role companies, not
from a new account.
Every warm path of one seat: linkedin_connections(operation="connections-warm-paths",
linkedin_account_id=5).
Errors: 404 not_found with code feature_off (flag off), 400 validation_failed (limit out_of_range, cursor
invalid, linkedinAccountId out_of_range), 403 permission_denied.

warm-paths-warmth

Read. Early access: needs accounts, linkedin_network, warm_paths_v2 on for the workspace. GET https://api.ken.so/v1/warm-paths/warmth

Query: accountIds string, personIds string

Read the warmth of up to 200 people or accounts: each one's best stored warm path in one line.

GET /api/v1/warm-paths/warmth. Staff; needs the accounts, linkedin_network and
warm_paths_v2 features. Sends Ken-Version 1.1 and X-Ken-Actor: agent. Send
person_ids or account_ids (1 to 200), not both. Returns data: for each one
with a stored path, personId, accountId, warmPathId, band (high, medium, low),
verdict (recommended, check_first, cold_best), shape, line ("via Danny to
Priya", "direct to Priya" or "cold"), isControl and computedAt. For an
account, the best path among its people. Reads stored paths only, never
ranks: people with none are left out. Rank them with warm-paths-run-create, or
one person with the committee tool's warm-paths-person.