LinkedIn Enrich linkedin_enrich
A LinkedIn seat's connections enrich job: Kenso sorts the seat's connections into buyers, partners and the rest, finds emails, and at the full level researches the buyers' accounts, best first, inside a hard credit cap. estimate first and get the user's yes on max_credits, then start; get and list read progress and spend, update raises the cap, cancel stops it. The connections themselves are linkedin_connections. people-suggestion-counts, people-accept-suggestions and people-undo-suggestions are Ken's suggested relationships for people in To sort: accept only on the user's request.
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through linkedin_enrich_read and changes through linkedin_enrich_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: people-accept-suggestions, cancel, estimate, get, list, start, people-suggestion-counts, people-undo-suggestions, update
people-accept-suggestions
Write. Early access: needs accounts on for the workspace. POST https://api.ken.so/v1/people/suggestions/accept
Body (json): personIds array, suggestedRelationship string, suggestionKind string
Accept Ken's suggested relationship for people in To sort: by ids, by suggestion, or all. Only on the user's request. Undo with linkedin_enrich(operation="people-undo-suggestions").
POST /api/v1/people/suggestions/accept. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Send exactly one of: person_ids (1 to 500 people, a duplicate counts once);
suggested_relationship (lead, customer, network, archived) and/or suggestion_kind (icp_fit,
customer_contact, old_teammate, classmate, personal, low_icp): every person in To sort whose
suggestion matches, at most 2,000 per call, lowest id first; or accept_all=true: every
suggestion that can be accepted, at most 2,000 per call. With none of them it refuses, so a
bare call never accepts everything. unsure cannot be accepted (400). It works in
transactions of at most 500 people; each locks its people and checks each again, so a
relationship someone sets meanwhile is never overwritten. For each person it records
person.suggestion_accepted (relationship, kind, reason, suggestedAt) and sets the suggested
relationship with source suggestion: it clears the suggestion, brings a quiet imported
connection into the main lists and records person.relationship_changed, and an account the
LinkedIn connections import created follows its people to Network or Not a fit, as with any
relationship write. Tell the user that before a bulk accept. If a later transaction fails,
the answer reports what the earlier ones accepted. Returns data.accepted, data.acceptedIds
(the people accepted: pass them to people-undo-suggestions to undo, in batches of 500),
data.skipped [{personId, reason}] (not_found, no_suggestion, unsure, not_to_sort) and
data.remaining (by suggestion or all: how many still match, so call again until 0; with
person_ids: 0). Count first with linkedin_enrich(operation="people-suggestion-counts").
cancel
Write. Early access: needs linkedin_connections_enrich on for the workspace. POST https://api.ken.so/v1/enrich-jobs/{enrichJobId}/cancel
Path: enrichJobId
Cancel an enrich job. What it found stays; runs not started never start.
POST /api/v1/enrich-jobs/{enrich_job_id}/cancel. Staff, behind the backend flag
linkedin_connections_enrich. Needs Accounts edit; only the seat's connector or a workspace
admin. Sends Ken-Version 1.1 and X-Ken-Actor: agent. Returns the job, cancelled. Cancelling
closes the job's credit cap, which also stops the later drafts of the account plans it started:
each shows the cap error when it comes due. A finished job keeps its cap open for those drafts.
Errors: 409 conflict (already finished), 403 forbidden, 404 not_found.
estimate
Read. Early access: needs linkedin_connections_enrich on for the workspace. POST https://api.ken.so/v1/linkedin-accounts/{linkedinAccountId}/enrich-estimates
Path: linkedinAccountId
Body (json): level string
Estimate enriching one LinkedIn seat's connections at a level. Charges nothing. Show the user expectedCredits and maxCredits before start.
POST /api/v1/linkedin-accounts/{linkedin_account_id}/enrich-estimates. Staff, behind the
backend flag linkedin_connections_enrich. Needs Accounts view. Sends Ken-Version 1.1 and
X-Ken-Actor: agent.
level: emails (sort everyone, find buyers' and partners' emails) or full (emails, plus
phones, research, the buying committee and an outreach plan for Tier 1 buyers' accounts and
warm-path accounts).
Returns data: connections, alreadyDone, likely {buyers, tier1, partners, accounts,
warmPathAccounts}, expectedCredits and maxCredits (also as ...Millicredits), perConnection
{expectedCredits, maxCredits}, balanceCredits, fitsBalance, phonesIncluded (true at full:
phones are found whatever the calling flags), phonesSkippedReason (always null now) and
lines[] {key, label, count, expectedCredits,
maxCredits, estimated}. Before the seat's first sync connections is 0 and only
perConnection carries figures.
Errors: 404 not_found (flag off, or a seat outside the workspace), 400 validation_failed
(level), 403 permission_denied.
get
Read. Early access: needs linkedin_connections_enrich on for the workspace. GET https://api.ken.so/v1/enrich-jobs/{enrichJobId}
Path: enrichJobId
Read one enrich job: status, spend, progress and what a stopped job did not reach.
GET /api/v1/enrich-jobs/{enrich_job_id}. Staff, behind the backend flag
linkedin_connections_enrich. Needs Accounts view. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Returns data: id, linkedInAccountId, level, status, maxCredits, expectedCredits, spentCredits
(each also as ...Millicredits), monthly {maxCredits, spentCreditsThisMonth: the spend on this
UTC month's scopes, drafts of this month's plans included whenever they land},
progress {connections, grouped, buyers, tier1, partners, others, emailsFound, phonesFound,
peopleResearched, accountsResearched, committeesMapped, plansStarted, warmPathAccounts} (the
one-time run's), left {tier1Buyers, warmPathAccounts,
tier2Emails, partners}, stoppedReason (cap, balance, cancelled, error), waitingReason
(workspace_limit while some work waits at the workspace's monthly limit for all workflows,
workflow_limit while it waits at a limit of its workflow copy; the job continues once the limit
has room, the next day or month, or once someone with Billing raises it; else null), createdAt,
startedAt, finishedAt. A stopped_cap job resumes when update raises max_credits.
Errors: 404 not_found, 403 permission_denied.
list
Read. Early access: needs linkedin_connections_enrich on for the workspace. GET https://api.ken.so/v1/linkedin-accounts/{linkedinAccountId}/enrich-jobs
Path: linkedinAccountId
List one LinkedIn seat's enrich jobs, newest first.
GET /api/v1/linkedin-accounts/{linkedin_account_id}/enrich-jobs. Staff, behind the backend
flag linkedin_connections_enrich. Needs Accounts view. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Each item as get returns it; one page, no cursor.
Errors: 404 not_found (flag off, or a seat outside the workspace), 403 permission_denied.
start
Write. Early access: needs linkedin_connections_enrich on for the workspace. POST https://api.ken.so/v1/linkedin-accounts/{linkedinAccountId}/enrich-jobs
Path: linkedinAccountId
Body (json): level string, maxCredits number, monthly object
Start enriching one LinkedIn seat's connections, best first, inside a hard credit cap. Spends credits. Run estimate first and get the user's yes on max_credits. Returns 201 with the job.
POST /api/v1/linkedin-accounts/{linkedin_account_id}/enrich-jobs. Staff, behind the backend
flag linkedin_connections_enrich. Needs Accounts edit, and only the member who connected the
seat or a workspace admin may start it. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
level: emails or full. max_credits: the hard cap in credits (above 0); the job stops before it
would spend more, or when the balance runs out. monthly_max_credits (optional): once the one-time
run is over, also enrich the seat's new connections the same way, up to this many credits each
UTC month (the work a month starts, including the later drafts of the account plans it starts).
Turns the seat's connections import on. The job is running on a seat that finished its first
sync, else pending until it does. Order: sort everyone, make buyers and their accounts live,
Tier 1 buyers and their accounts, warm-path accounts (full), Tier 2 emails, partners' emails.
Poll with get: progress counts, spentCredits, status (pending, running, stopped_cap,
stopped_balance, done, cancelled, failed) and left (what a stopped job did not reach).
Errors: 409 conflict code enrich_job_open (the seat has an open job), 400 validation_failed,
403 forbidden (not the seat's connector or an admin), 404 not_found.
people-suggestion-counts
Read. Early access: needs accounts on for the workspace. GET https://api.ken.so/v1/people/suggestion-counts
Count the people in To sort and Ken's suggestions among them.
GET /api/v1/people/suggestion-counts. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent. Returns data.total (every person in To sort, imported LinkedIn connections nobody has worked included), data.byRelationship (lead, customer, network, archived, unsure) and data.byKind (icp_fit, customer_contact, old_teammate, classmate, personal, low_icp, unsure), every key present, 0 when none. List them with people(operation="list", relationship=["to_sort"], suggested_relationship=[...]). Read from the replica, so it can lag a write by a moment.
people-undo-suggestions
Write. Early access: needs accounts on for the workspace. POST https://api.ken.so/v1/people/suggestions/undo
Body (json): personIds array
Undo accepting Ken's suggestion for up to 500 people: back to To sort with their suggestion. Only on the user's request, after people-accept-suggestions.
POST /api/v1/people/suggestions/undo. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
person_ids: 1 to 500 people (a duplicate counts once). A person goes back only when their
latest accept is newer than any other change to their relationship and they still have the
relationship they accepted: it sets to_sort (person.relationship_changed, source suggestion)
and writes the accepted suggestion back. A person who was quiet stays in the main lists. An
account the LinkedIn connections import created follows its people back, as with any
relationship write. Returns data.restored and data.skipped [{personId, reason}] (not_found, or changed_since when
someone changed their relationship after the accept or they never accepted one).
update
Write. Early access: needs linkedin_connections_enrich on for the workspace. PATCH https://api.ken.so/v1/enrich-jobs/{enrichJobId}
Path: enrichJobId
Body (json): maxCredits number, monthly object
Raise an enrich job's cap (which resumes a job stopped at its cap) or change its monthly opt-in. Spends credits. Get the user's yes on the new max_credits first.
PATCH /api/v1/enrich-jobs/{enrich_job_id}. Staff, behind the backend flag
linkedin_connections_enrich. Needs Accounts edit; only the seat's connector or a workspace
admin. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
max_credits: the new cap in credits, not below what the job spent plus what its running
steps hold (400 validation_failed, code below_spent, names that figure). Raising the cap of a
stopped_cap job resumes it in the same best-first order; nothing it did runs again.
monthly_max_credits sets the monthly opt-in (the seat's newest job only); monthly_off=true turns
it off, which stops every month's spending. Turned back on in the same month, the work resumes
inside what the month has left. Send at least one.
Errors: 409 conflict (a finished job, enrich_job_open when another job is open on the seat, or
invalid_state when turning the monthly opt-in on for a failed job or an older job),
400 validation_failed, 403 forbidden, 404 not_found.