People people
The real people in your workspace, on target accounts or on none (the Accounts lane): find, add, merge, export and find emails. Kenso Search's 280M people are the search tool.
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through people_read and changes through people_write. Each takes operation plus that operation's parameters, and your workspace role decides which operations you see.
Each operation with a route calls the Kenso API at https://api.ken.so with Authorization: Bearer <Kenso API key>, Ken-Version: 1.1 and X-Ken-Workspace-Id: <workspace id>. You can call that route directly with the same headers.
Operations: activity, batch, create, create-people-source, delete, delete-photo, duplicates, export, find-emails, find-phones, intake-settings-get, get, intake, list, list-people-sources, merge, search, intake-settings-update, update, update-phones
activity
Read. Early access: needs accounts on for the workspace. GET https://api.ken.so/v1/people/{personId}/activity
Path: personId
Query: category string, limit integer
Return one person's timeline: what was sent to them, what they replied, and what is planned next. category filters (comma = OR): email, linkedin, instagram, whatsapp, facebook, calls_meetings, assets, signals, website, crm, ken.
GET /api/v1/people/{personId}/activity. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. The same rows and shape as accounts(operation="activity"), for one
person: their touches on the accounts the caller can see, the events naming them, and
every email and LinkedIn message to or from them (message_sent and message_received
rows with message). An account's timeline is the union of its people's. category is
comma-separated (absent = all); limit caps the earlier rows, 1 to 500 (default 100).
A merged person is not_found with person_merged and mergedIntoId, the person to read
instead.
batch
Write. Early access: needs accounts on for the workspace. POST https://api.ken.so/v1/people/batch
Body (json): findEmails boolean, rows array
Create or match up to 200 people in one call, each optionally onto an account. Each row reports created, matched or invalid; sending the same rows again creates nothing.
POST /api/v1/people/batch. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
rows: 1 to 200 objects with keys person or person_id, then optionally account_id or
account_domain, role and priority (1 to 3). person keys: full_name (required; a
person without it comes back invalid), first_name, last_name, title, email,
linkedin_url, ken_person_id. Roles: champion,
economic_buyer, approver, evaluator, user, executive_sponsor, blocker, unknown.
Each row runs on its own: an invalid row writes nothing and comes back invalid with an
error, and the rest go on. A person with the same email, else LinkedIn URL, else
ken_person_id, is matched and only their blank fields fill; a row with none of
them matches the same full name on the same account; else the person is created. A row
with only a name needs an account that exists, else it is invalid. account_domain
resolves to the live account with that domain (account_not_found when none; a person
with an email, LinkedIn URL or ken_person_id is still written). A role address (support@,
info@, no-reply@) is not the person's own email: it matches whoever holds it and never fills
onto a person. A new person with a LinkedIn URL or ken_person_id is created without it; one
with a real first and last name (as on create) matches the same full name on the row's
account, else is created there without it, and with no account is invalid. Those rows carry
emailDropped role_address. A row with only the address is invalid; both invalid cases carry
reason role_address.
A batch never creates accounts. Places are written like a CSV import, as the user's, so
role and priority pin. A place a person removed comes back previously_removed and is
never forced. find_emails=true queues an email find for each created or matched person
without an email (1 credit per email found); if queueing fails the rows still come back
with emailFind not_requested, so queue them with people(operation="find-emails").
Returns data.results, one per row: {index, person (created, matched, invalid),
personId, account (added, already_on_account, previously_removed, account_not_found,
or not_requested when the row named no account or is invalid), stakeholderId,
emailFind (queued, has_email, active, not_requested), error, reason (role_address or
null), emailDropped (role_address or omitted)}, data.counts {created,
matched, invalid, addedToAccounts}, and data.paused (true when the queued finds wait
for credits).
create
Write. Early access: needs accounts on for the workspace. POST https://api.ken.so/v1/people
Body (json): email string, firstName string, fullName string, kenPersonId integer, lastName string, leadStatus string, linkedinUrl string, ownerMemberId integer, phones array, title string
Create one person on no account. Returns 201 with the person. Someone with the same email or LinkedIn URL fails with person_exists and their personId: use them. A role address (support@, info@) is dropped when a real name or LinkedIn URL names them, else 422 role_address.
POST /api/v1/people. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent. person keys: full_name (required), first_name, last_name, title, email, linkedin_url, ken_person_id, owner_member_id, lead_status, phones (as in update). snake_case or camelCase keys. A name-only match is not a duplicate. A role address (a shared mailbox: support@, info@, sales@, no-reply@ and the like) that no one holds is refused with 422 role_address and nothing is written (someone who holds it is still person_exists), unless linkedin_url, ken_person_id or a real first and last name names the person: then they are created without that email and the answer carries emailDropped: role_address. A real name has both parts (first_name and last_name, else full_name), neither a role word (support, team, info, sales...), the address's local part or a label of its domain (intake also checks the company name it is sent), nor an initial only: Joe Pitingolo at info@ventari.app passes, Support Team does not. No email find starts; queue one with people(operation="find-emails"). Do not add a company's shared inbox as a person. The new person's source is api. To add someone to an account, use the accounts tool's stakeholders-create instead; it matches or creates the person in the same call.
create-people-source
Write. Early access: needs accounts, lead_intake on for the workspace. POST https://api.ken.so/v1/inbound-webhooks
Body (json): app string, createAccounts boolean, defaultOwnerMemberId integer, kind string, mapping array, name string, preset string, samplePayloadJson string
Create a people webhook: each delivery to its URL creates or updates a person. Needs accounts and lead_intake. Requires the integrations permission (admins by default). Returns the ingest url.
POST /api/v1/inbound-webhooks. Sends Ken-Version 1.1. Requires the integrations permission (admins by default) and the accounts and lead_intake features in the workspace (X-Ken-Workspace-Id). The API returns 201 with kind people. name is required and at most 120 characters. Give a preset or a mapping. preset: hubspot_forms, typeform, webflow or tally bring people in with source form; rb2b or vector with source visitor; generic (flat keys email, first_name, last_name, full_name, company, company_domain, title, phone, linkedin_url) with source webhook. zapier, make and n8n are generic that also set app. app (zapier, make or n8n) without a preset uses generic; a preset app that differs from app is rejected. A mapping wins over the preset and must map email, profile_url, or a name with company_domain. default_owner_member_id must be a workspace member (invalid_member); omitted, the intake settings decide the owner. create_accounts false never creates the person's account; true or omitted follows the intake settings. kind is optional and only people. A delivery whose body intake cannot take (no email, LinkedIn URL, or name with a company domain) is logged rejected with the reason; others are logged created, updated or duplicate_suggested (webhooks(operation="deliveries")).
delete
Write. Early access: needs accounts on for the workspace. DELETE https://api.ken.so/v1/people/{personId}
Path: personId
Delete a person who is on no account. Only on the user's explicit request. A person still on an account fails with person_on_accounts, listing each stakeholderId.
DELETE /api/v1/people/{personId}. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Returns 204. The person leaves every list, search and match, so the same email can be
added again as a new person, and Ken never re-adds them. Cancels their active email find.
To fold a duplicate into another person, use merge instead.
delete-photo
Write. Early access: needs accounts on for the workspace. DELETE https://api.ken.so/v1/people/{personId}/photo
Path: personId
Remove the photo a member uploaded for a person. Only on the user's explicit request. The person shows the profile photo Kenso saved again, or no photo. Returns the person.
DELETE /api/v1/people/{personId}/photo. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Deletes the uploaded file. Afterwards photoUrl is the LinkedIn profile photo Kenso stored
(photoSource linkedin), or both are absent. A person with no upload returns unchanged.
Uploading a photo is a file upload from the People screen in the Kenso app.
duplicates
Read. Early access: needs accounts, lead_intake on for the workspace. GET https://api.ken.so/v1/people/{personId}/duplicates
Path: personId
List the people Ken thinks may be the same as this person, and why. Check both before merging.
GET /api/v1/people/{personId}/duplicates. Staff (opens with the lead_intake flag). Sends
Ken-Version 1.1 and X-Ken-Actor: agent. Returns data, the person's open merge suggestions,
newest first, at most 100, in one page: id, todayItemId (merge_suggestion_<id>, the Today
row), personId, otherPersonId, reasons (email_local_part: the same email apart from dots and
a plus tag; phone; name_account: the same name on one account; name_domain: the same name
on one business email domain), foundBy (intake or the nightly sweep), createdAt and
otherPerson (a person summary). Lead intake suggests one when it creates a person with the
same name on the domain as a person with another email; the sweep finds the rest. To merge,
call people(operation="merge") with the duplicate as person_id: the suggestion resolves.
To say they are different people, mark the Today row done with
today(operation="update"): Ken never suggests that pair again. A merged person
fails with person_merged.
export
Write. Early access: needs accounts on for the workspace. POST https://api.ken.so/v1/people/export
Body (json): accountIds array, addedBy array, behaviorTags array, connectedVia array, department array, hasEmail boolean, hasSuggestion boolean, includeImportOnly boolean, leadStatus array, location string, onAccount string, ownerMemberId integer, q string, relationship array, roles array, seniority array, sort string, source array, suggestedRelationship array, suggestionKind array, tagIds array
Export the people the search filters match as CSV text, up to 5,000 rows. More than 5,000 matches is refused before anything is exported: narrow the filters.
POST /api/v1/people/export. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Requires export access (admin or member). The filters and sort are the search
operation's (no paging); behavior_tags, relationship, has_suggestion, suggested_relationship and
suggestion_kind filter the same way.
The tool counts the matches first with search and include_total;
over 5,000 it stops and exports nothing. Larger exports (up to 50,000) run from the
People screen in the Kenso app. Returns {format: csv, rowCount, csv}, plus truncated: true
when people added after the count pushed it past 5,000 and the extra rows were cut. The header is
full_name,first_name,last_name,title,email,linkedin_url,accounts,added_by,added_at.
accounts reads "Acme (evaluator, P2); Globex (user)"; added_by is Ken, User, API key or
Workflow; added_at is the UTC date. Each export writes an audit-log entry.
People made from contacts of a Kenso library list are never exported:
excludedLibraryPeople says how many the filters matched (the count above includes
them, so rowCount can be lower). It is absent until the backend sends it.
find-emails
Write. Early access: needs accounts on for the workspace. POST https://api.ken.so/v1/people/email-finds
Body (json): accountId integer, personIds array
Queue an email find for each person without an email. Returns 202. 1 credit per email found; nothing is charged when none is found. An email Kenso already holds for the person is free on paid plans.
POST /api/v1/people/email-finds. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
person_ids: 1 to 500 people. account_id (optional) is the account whose domain the find
searches. Returns data.queued [{personId, findId}], data.skipped [{personId, reason:
not_found, has_email or active_find}], data.estimate.maxCredits (the most this can
cost) and data.paused (true when the workspace is out of credits: the finds wait and
run when credits arrive). Follow progress on each person's emailFind (get or search).
Each find checks the emails Kenso already holds first (recently verified, the
same pool behind hasKenEmail in Kenso Search): on a paid plan such a hit costs
no credit.
find-phones
Write. Early access: needs accounts, calls on for the workspace. POST https://api.ken.so/v1/people/phone-finds
Body (json): personIds array
Queue a phone find for each person without a usable phone. Returns 202. Charged per number found; nothing is charged when none is found.
POST /api/v1/people/phone-finds. Staff, behind the calls flag. Sends Ken-Version 1.1 and X-Ken-Actor: agent. person_ids: 1 to 500 people. Returns data.queued, data.alreadyHavePhone, data.alreadyQueued and data.skipped (counts), and data.personIds with the ids in each of those four lists. skipped covers people that are not found, deleted, merged or outside the caller's account scope. A find for a workspace out of credits waits, paused, and runs when credits arrive. Follow progress on each person's phoneFind (people get, list or search); a found number goes on the person's phones.
intake-settings-get
Read. Early access: needs accounts, lead_intake on for the workspace. GET https://api.ken.so/v1/intake-settings
Read how the workspace takes in new leads: default owner, round robin, notifications, account creation.
GET /api/v1/intake-settings. Staff (opens with the lead_intake flag). Sends Ken-Version 1.1 and X-Ken-Actor: agent. Returns data.defaultOwnerMemberId, data.roundRobinMemberIds, data.notifyNewLeads, data.createAccounts, data.updatedByMemberId and data.updatedAt. A workspace that never saved settings reads the defaults (no owner, no rotation, notify and create accounts on).
get
Read. Early access: needs accounts on for the workspace. GET https://api.ken.so/v1/people/{personId}
Path: personId
Return one person with the accounts they are a stakeholder on.
GET /api/v1/people/{personId}. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
accounts lists each place, highest priority first. emailFind is the newest email find.
tagIds lists the ids of the tags on the person (the Champion tag marks a champion).
relationship: to_sort, lead, customer, network or archived (labels To sort, Lead, ...). While
relationshipSet is false it is derived: to_sort for a quiet person (LinkedIn connections import),
else customer on a live onboarding, client or churned (or customer) account, else lead.
engagement (read-only): the first of unsubscribed, meeting, replied, bounced, contacted,
not_contacted that holds. suggestion: Ken's {relationship, kind, reason, suggestedAt}, else absent.
Profile fields (DEV-5072), which Ken fills from Kenso Search and campaign contacts into blanks
only: headline, location, seniority, department; photoUrl (stored by Kenso, never a LinkedIn
link) with photoSource upload or linkedin; profileSource (ken_search or contact) and
profileEnrichedAt. profile: summary, industry, city, state, country, currentCompany
(startedAt is their tenure), years counters, experience (current first), education,
skills, languages, certifications; dates yyyy-MM or yyyy. Absent means not found.
With the whatsapp feature on, each phone carries whatsapp (on, off or unknown: from a check in the
last 30 days), whatsappCheckedAt and whatsappOptOutAt (Kenso never sends WhatsApp to that number),
and the person carries whatsappOptOutAt; phoneOptOutAt blocks WhatsApp too.
people(operation="delete-photo") removes an uploaded photo.
A merged person fails with person_merged and mergedIntoId: read that person instead.
intake
Write. Early access: needs accounts, lead_intake on for the workspace. POST https://api.ken.so/v1/people/intake
Body (json): companyDomain string, companyName string, createAccount boolean, customFields object, email string, firstName string, fullName string, lastName string, leadStatus string, linkedinUrl string, ownerMemberId integer, phone string, source string, sourceDetail string, title string, useKenEmail boolean
Take in one lead: match or create the person, place them on their company's account, assign an owner. Matches by email, then LinkedIn URL; only blank fields fill on a match. A new lead lands on its owner's Today.
POST /api/v1/people/intake. Staff (opens with the lead_intake flag). Sends Ken-Version 1.1 and X-Ken-Actor: agent. person keys: email, linkedin_url, or a name (full_name, or first_name and last_name) with a business company_domain (one is required, else identity_required); title, company_name, phone (8 to 15 digits with the country code, else invalid_phone), source (api default, workflow or manual; anything else is invalid_source), source_detail (the form or list name), owner_member_id (a workspace member, else invalid_member), lead_status (new default, working, qualified, disqualified, nurture), custom_fields (person custom field keys; unknown keys are ignored), create_account (false keeps a new business domain from becoming an account) and use_ken_email (true with no email: take the address from Kenso's email pool when it holds a recently verified one for the person, free; matched by the LinkedIn profile, else the name with the company name or domain; no match takes the person in without an email). A match fills only blank fields, never a field a person set, adds the phone and updates the latest source. A new person gets lead status new and a score. A business domain with no account gets one at stage researching (no research credits) unless the workspace's intake settings or create_account say no. Owner: the person's, else the account's, the CRM contact's, owner_member_id, the workspace default, then the round robin. Returns data.person, data.created, data.matchedBy (email, linkedin_url, name_domain, none), data.accountId, data.accountCreated and data.suggestedDuplicateOfPersonId (same name on the domain with another email: check before merging). A role address (support@, info@, no-reply@) matches the person who holds it but never fills onto one. With a linkedin_url or a real first and last name (as on create) the person comes in without it and data.emailDropped is role_address; with neither and no match it is 422 role_address and nothing is written. 600 calls an hour per workspace.
list
Read. Early access: needs accounts on for the workspace. GET https://api.ken.so/v1/people
Query: behaviorTags array, cursor string, email string, hasSuggestion boolean, leadStatus string, limit integer, linkedinUrl string, ownerMemberId integer, q string, relationship string, sort string, source string, suggestedRelationship string, suggestionKind string, tagIds string
List people in the workspace (not Kenso Search records). Look a person up by email or LinkedIn URL before adding them to an account.
GET /api/v1/people. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent. linkedin_url takes any profile URL shape. q matches the name or email. owner_member_id: people this member owns. lead_status: any of new, working, qualified, disqualified, nurture. source: the latest source is any of manual, api, workflow, search, research, promoted, campaign, booking, crm, form, webhook, import, visitor, inbound_email, linkedin. tag_ids: carries any of these tags (1 to 100 tag ids); a champion is a person with the workspace's Champion tag (tags operation list with system_key champion returns its id). behavior_tags: people whose behavior tags include any of these (1 to 50, e.g. cold_responder, prefers_linkedin, best_window:weekday_morning); needs the behavior_signals feature, else 400; email_confirmed, email_dead_end and left_company cannot be filtered. relationship, has_suggestion, suggested_relationship and suggestion_kind filter as in search. sort: -createdAt (default, newest first), name, -score (highest first), -latestSourceAt (most recently sourced first), or headline, location, seniority or department (A to Z); people without the value sort last. Each person carries tagIds (the ids of their tags) and get's relationship and profile fields (headline, location, seniority, department, photoUrl, photoSource, profileSource, profileEnrichedAt), not profile. With the whatsapp feature on, each phone carries whatsapp (on, off or unknown: from a check in the last 30 days), whatsappCheckedAt and whatsappOptOutAt (Kenso never sends WhatsApp to that number), and the person carries whatsappOptOutAt; phoneOptOutAt blocks WhatsApp too. For filters (accounts, roles, email, who added them) use the search operation. For the 280M-person database use the search tool instead.
list-people-sources
Read. Early access: needs accounts, lead_intake on for the workspace. GET https://api.ken.so/v1/inbound-webhooks
Query: cursor string, limit integer
List the workspace's people webhooks, ordered by id. Each delivery to a people webhook creates or updates a person. Needs accounts and lead_intake.
GET /api/v1/inbound-webhooks. Sends Ken-Version 1.1. Requires the `integrations` permission and the accounts and lead_intake features in the workspace (X-Ken-Workspace-Id). Pages use limit (1 to 200) and cursor, ordered by id. There is no totalCount. Each webhook has kind people, url (the ingest URL), preset, app (zapier, make or n8n), defaultOwnerMemberId, createAccounts, peopleCreated, peopleUpdated, and status active or paused; campaignId is omitted. A campaign's webhooks are listed with webhooks(operation="inbound-webhooks-list"). Get, update, delete, rotate-token, test-mapping and deliveries work on a people webhook through the same webhooks operations.
merge
Write. Early access: needs accounts on for the workspace. POST https://api.ken.so/v1/people/{personId}/merge
Path: personId
Body (json): intoPersonId integer
Merge a duplicate person into the one to keep. Returns the kept person. Cannot be undone. Only on the user's explicit request.
POST /api/v1/people/{personId}/merge. Staff. Sends Ken-Version 1.1 and X-Ken-Actor:
agent. person_id is the duplicate; into_person_id is the person to keep. In one step
the kept person keeps every value it has and takes the duplicate's values for its blank
fields, the duplicate's account places move to it (on a shared account the two places
combine), and the duplicate's active email find is cancelled. The duplicate then reads
as person_merged. Merging into themselves (same_person), a deleted person
(person_deleted) or a merged one (person_merged) fails.
search
Read. Early access: needs accounts on for the workspace. POST https://api.ken.so/v1/people/search
Body (json): accountIds array, addedBy array, behaviorTags array, connectedVia array, cursor string, department array, hasEmail boolean, hasSuggestion boolean, includeImportOnly boolean, includeTotal boolean, leadStatus array, limit integer, location string, onAccount string, ownerMemberId integer, q string, relationship array, roles array, seniority array, sort string, source array, suggestedRelationship array, suggestionKind array, tagIds array
Search people in the workspace by account, role, email, owner, lead status, source, tag and profile. Each person embeds their accounts (stakeholderId, role, priority, coverage) and emailFind.
POST /api/v1/people/search. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Every argument is optional; none lists everyone. Filters AND together; the values of
one list OR together.
q: contains, on the full name, email or title (up to 300 characters).
account_ids: on any of these accounts (1 to 100 ids).
on_account: any (default), none (on no live account) or some (on at least one).
roles: holds one of these roles on some live account: champion, economic_buyer,
approver, evaluator, user, executive_sponsor, blocker, unknown.
has_email: true for people with an email, false for people without one.
added_by: who created the person: user, agent (Ken), api_key, system, workflow.
owner_member_id: people this workspace member owns.
lead_status: has one of new, working, qualified, disqualified, nurture.
source: the latest source is one of manual, api, workflow, search, research, promoted,
campaign, booking, crm, form, webhook, import, visitor, inbound_email, linkedin.
tag_ids: carries any of these tags (1 to 100 tag ids). A champion is a person with the
workspace's Champion tag: pass its id (tags operation list with system_key champion).
seniority, department: has one of these values (case-insensitive, up to 50 each), e.g.
["VP", "Director"], ["Sales"]. location: contains, on the location.
connected_via: a LinkedIn connection of any of these teammates' seats (1 to 100
linkedinAccountIds from linkedin(operation="list")).
include_import_only: true also returns people the LinkedIn connections import added that
nobody has worked yet. Default false: they are left out unless their connection fits the ICP.
behavior_tags: people whose behavior tags include any of these (1 to 50, e.g. cold_responder,
prefers_linkedin, best_window:weekday_morning); needs the behavior_signals feature, else 400;
email_confirmed, email_dead_end and left_company cannot be filtered.
relationship: any of to_sort, lead, customer, network, archived, as get reads it (quiet people
read to_sort and are included). has_suggestion: true only people with Ken's suggestion, false without.
suggested_relationship: Ken's stored suggestion is any of lead, customer, network, archived,
unsure; suggestion_kind: any of icp_fit, customer_contact, old_teammate, classmate, personal,
low_icp, unsure. Both include quiet people. Accept them with
linkedin_enrich(operation="people-accept-suggestions").
sort: -createdAt (default), name (A to Z, unnamed people last), -score (highest first),
-latestSourceAt (most recently sourced first), or headline, location, seniority or
department (A to Z); people without the value sort last. limit 1
to 200 (default 50). Pass pagination.nextCursor back unchanged with the same filters and
sort. include_total=true fills pagination.total. Deleted and merged people never appear.
Each person carries accounts [{accountId, name, stakeholderId, role, priority,
coverage}] and emailFind {id, status, completedAt, fromKenPool} (the newest find, or absent;
fromKenPool is true when Kenso's own email database found the email for free, whether or not the
person kept it, else absent), plus
ownerMemberId, leadStatus, score, phones, phone, firstSource, latestSource and tagIds
(the ids of the tags on the person), plus get's relationship and profile fields (headline, location,
seniority, department, photoUrl, photoSource, profileSource, profileEnrichedAt), not profile.
lastTouch {at, channel} (search only): the latest email, LinkedIn, WhatsApp, Facebook or Instagram
message with the person, sent or received (not an auto-reply or bounce), channel email, linkedin,
whatsapp, facebook or instagram; absent when there is none.
Unlike an account's lastTouchAt it counts replies and not logged calls. No sort reads it.
With the whatsapp feature on, each phone carries whatsapp (on, off or unknown: from a check in the
last 30 days), whatsappCheckedAt and whatsappOptOutAt (Kenso never sends WhatsApp to that number),
and the person carries whatsappOptOutAt; phoneOptOutAt blocks WhatsApp too.
A person who is a teammate's LinkedIn connection carries connectedVia [{linkedinAccountId,
displayName, memberId}] and connectionIcpScore (0 to 100, fit at 70, omitted when not
scored); one the import added that nobody has worked carries importOnlyAt.
intake-settings-update
Write. Early access: needs accounts, lead_intake on for the workspace. PATCH https://api.ken.so/v1/intake-settings
Body (json): createAccounts boolean, defaultOwnerMemberId integer, notifyNewLeads boolean, roundRobinMemberIds array
Change who owns new leads and whether intake notifies and creates accounts. Absent fields stay unchanged. Only on the user's request: it changes who gets every new lead.
PATCH /api/v1/intake-settings. Staff (opens with the lead_intake flag). Sends Ken-Version 1.1 and X-Ken-Actor: agent. changes keys: default_owner_member_id (a workspace member, or null to clear), round_robin_member_ids (up to 50 members in rotation order; a new list restarts the rotation; null or [] clears it), notify_new_leads (true or false), create_accounts (true or false). A non-member is invalid_member. Returns the settings as intake-settings-get does.
update
Write. Early access: needs accounts on for the workspace. PATCH https://api.ken.so/v1/people/{personId}
Path: personId
Body (json): department string, email string, firstName string, fullName string, headline string, kenPersonId integer, lastName string, leadStatus string, linkedinUrl string, location string, overwritePinned boolean, ownerMemberId integer, phoneOptOut boolean, phones array, relationship string, seniority string, title string
Update a person. Absent fields stay unchanged; null clears one. An email or LinkedIn URL another person holds fails with that personId.
PATCH /api/v1/people/{personId}. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
changes keys: full_name, first_name, last_name, title, email, linkedin_url,
ken_person_id, owner_member_id, lead_status, phones, phone_opt_out, headline, location,
seniority, department. A person keeps at least one of full_name, email, linkedin_url.
headline, location, seniority, department: Ken fills them from Kenso Search and campaign
contacts while blank. Send a value to correct a wrong fill, or null to clear one; a
member's value or clear is pinned, so Ken never fills over it.
A new linkedin_url or ken_person_id clears what Ken filled from the old identity (those
fields, title and the Kenso id unless a person set them, the profile and the LinkedIn
photo), and Ken fills the person again from the new one.
owner_member_id: a workspace member's user id (else invalid_member), or null to clear.
lead_status: new, working, qualified, disqualified, nurture, or null to clear.
phones: the whole list, which replaces the stored one (up to 20), e.g.
[{"number": "+15551234567", "kind": "mobile"}]. kind is mobile, work or other (default
other). A number needs 8 to 15 digits with the country code (else invalid_phone). A
number already stored keeps when and how it was added; one left out is removed, except a
number marked invalid (a wrong number), which stays. To add or remove one number, use
people(operation="update-phones") instead: it does not resend the list.
relationship: to_sort, lead, customer, network or archived (null is refused); clears Ken's suggestion
and surfaces a quiet person. Many people: committee(operation="people-set-relationship").
phone_opt_out: true when the person asked not to be called. It records now and the caller
as phoneOptOutAt (an earlier opt-out keeps its time); Kenso's dialer never calls them. false
clears it: send false only when the person asked to be called again.
score and the sources are read-only.
A field a person set needs overwrite_pinned=true, only when the user asked.
update-phones
Write. Early access: needs accounts on for the workspace. PATCH https://api.ken.so/v1/people/{personId}/phones
Path: personId
Body (json): add array, overwritePinned boolean, primary string, remove array
Add, remove or reorder a person's phones without resending the list. Use it instead of update's phones, which replaces the whole list.
PATCH /api/v1/people/{personId}/phones. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Send at least one of add, remove, primary. Kenso applies remove, then add, then primary to the
phones stored when the call runs, so two edits at once both land.
add: up to 20 phones, e.g. [{"number": "+15551234567", "kind": "mobile"}]. kind is mobile,
work or other (default other). A new number goes after the person's phones with source api
and writes person.phone_added. A number the person has keeps its entry and takes the kind
sent; a number marked invalid (a wrong number) stays marked, so adding it does not make it
callable. The person keeps at most 20 phones, wrong numbers included (else out_of_range).
remove: up to 20 numbers. A valid number is removed. A number marked invalid (a wrong
number) stays, so it is never added back. A number the person does not have is ignored.
primary: a valid number the person has after add and remove. It moves first and becomes
the person's phone (else unknown_phone, also for a number marked invalid).
A number needs 8 to 15 digits with the country code (else invalid_phone).
Phones a person set need overwrite_pinned=true, only when the user asked.
Returns the person, as update does.