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.