People
Send people into Kenso from your own source.
Path parameters
The endpoints whose path names one of these take it as described here. An endpoint's own table lists a path parameter only when it describes it differently.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
personId | path | integer (int64) | required |
Headers
The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Ken-Version | header | string, one of: 2026-11-02, 1.1 | optional | The API version, a date in YYYY-MM-DD form. 1.1 is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and 404 where the path exists only in this version. A date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy. |
X-Ken-Workspace-Id | header | integer (int64) | optional | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers 400 workspace_required. A workspace you are not a member of answers 404 not_found. |
List people in the current workspace
/v1/peoplepeople.list- Permission
- Accounts view
- Rate limit
- 12,000 requests a minute per API key
accounts feature on your workspace. Until it is on, calls answer 404.Filters: email, linkedinUrl (any profile URL shape; normalized), q (name or email contains), ownerMemberId, leadStatus (comma list: new, working, qualified, disqualified, nurture), source (comma list on the latest source), tagIds (comma list of tag ids: people carrying any of them; GET /v1/tags?systemKey=champion gives the Champion tag), behaviorTags (repeatable: people whose behavior tags include any, for example behaviorTags=cold_responder&behaviorTags=prefers_linkedin; needs the behavior_signals feature; email_confirmed, email_dead_end and left_company cannot be filtered), relationship (comma list: to_sort, lead, customer, network, archived; matches the relationship each person reads, and includes people the LinkedIn connections import added that nobody has worked yet, who read to_sort), hasSuggestion (true: people with a suggestion from Ken; false: people without one), suggestedRelationship (comma list: lead, customer, network, archived, unsure; Ken's stored suggestion) and suggestionKind (comma list: icp_fit, customer_contact, old_teammate, classmate, personal, low_icp, unsure); both include the people the LinkedIn connections import added that nobody has worked yet. sort: -createdAt (default), name (A-Z, unnamed last), -score (highest first, unscored last), -latestSourceAt (newest first, none last). Each person carries ownerMemberId, leadStatus, relationship, relationshipSet, engagement, suggestion, score, phones, phone (the first valid one), firstSource, latestSource and tagIds. Requires Accounts view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
email | query | string | optional | |
linkedinUrl | query | string | optional | A LinkedIn profile URL in any shape. |
q | query | string | optional | Contains, case-insensitive, on the full name or email. |
ownerMemberId | query | integer (int64) | optional | People this member owns. |
leadStatus | query | string | optional | Comma-separated lead statuses, OR: new, working, qualified, disqualified, nurture. |
source | query | string | optional | Comma-separated latest sources, OR: manual, api, workflow, search, research, promoted, campaign, booking, crm, form, webhook, import, visitor, inbound_email, linkedin. |
tagIds | query | string | optional | Comma-separated tag ids, OR: people carrying any of them. |
relationship | query | string | optional | Comma-separated relationships, OR: to_sort, lead, customer, network, archived. Matches the relationship people read, derived while nobody has set it, and includes people the LinkedIn connections import added that nobody has worked yet (they read to_sort). |
hasSuggestion | query | boolean | optional | True only people with a suggestion from Ken; false only people without one. |
suggestedRelationship | query | string | optional | Comma-separated suggested relationships, OR: lead, customer, network, archived, unsure. People whose stored suggestion from Ken is one of them, people the LinkedIn connections import added included. |
suggestionKind | query | string | optional | Comma-separated suggestion kinds, OR: icp_fit, customer_contact, old_teammate, classmate, personal, low_icp, unsure. People the LinkedIn connections import added included. |
behaviorTags | query | array of string | optional | Behavior tags, repeatable (behaviorTags=a&behaviorTags=b), any-match: people whose workspace behavior tags (and network tags, with behavior_signals_network) include one. Needs behavior_signals. |
sort | query | string | optional | -createdAt (default), name, -score or -latestSourceAt. |
limit | query | integer (int32) | optional | Items per page, from 1 to 200. Default 50. |
cursor | query | string | optional | The nextCursor of the previous page. Omit it for the first page. |
curl -X GET "https://api.ken.so/v1/people?limit=50" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a list of Person. Each item has these fields. The response also carries pagination.
Show the 48 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Create one person on no account
/v1/peoplepeople.create- Permission
- Accounts edit
- Rate limit
- 4,800 requests a minute per API key
accounts feature on your workspace. Until it is on, calls answer 404.Body: fullName (required), firstName, lastName, title, email, linkedinUrl, kenPersonId, ownerMemberId, leadStatus, phones (as on people.update). The first and latest source are manual for a person and api for an API key or agent. Email is trimmed and lower-cased; the LinkedIn URL is normalized like the linkedinUrl filter. A live person with the same email or LinkedIn URL is 409 conflict with detail person_exists and their personId: use them instead of creating a twin. A name-only match is not a duplicate. A role address (a shared mailbox such as support@, info@, no-reply@) is not a person: a person who already holds it is still 409 conflict with detail person_exists. Else with a linkedinUrl, a kenPersonId or a real first and last name (both parts, from firstName and lastName or fullName, neither a role word such as support or team, the address's local part or a label of its domain, nor an initial only; intake also checks the company name it is sent) the person is created without it and the answer carries emailDropped: role_address; with none of them it is 422 role_address. No email find starts. Returns 201 with accounts: []. With account scope own it is 403 permission_denied with scope: all: add the person to one of your accounts instead. Requires Accounts edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
fullName | string | optional | |
firstName | string | optional | |
lastName | string | optional | |
title | string | optional | |
email | string | optional | |
linkedinUrl | string | optional | A profile, such as https://linkedin.com/in/jane-doe. |
kenPersonId | integer (int64) | optional | The person's Ken id: their id in Ken Search. Null clears it. |
ownerMemberId | integer (int64) | optional | A member of this workspace who owns the person, or null to clear. |
leadStatus | string | optional | new, working, qualified, disqualified or nurture. Null clears it: not a lead. |
phones | array of PersonPhoneBody | optional | Replaces the person's phones, up to 20, in order: the first is the person's phone. A number the person already has keeps when and how it was added. Null or an empty list clears them. A number marked invalid (a wrong number) stays even when left out, after the numbers sent, so it is never added back. To add or remove one number, send the whole list with that number added or left out. |
curl -X POST "https://api.ken.so/v1/people" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"fullName": "Amanda Chen",
"title": "VP of Engineering",
"email": "[email protected]",
"ownerMemberId": 1093,
"leadStatus": "new",
"phones": [
{
"number": "+15125550142",
"kind": "mobile"
}
]
}'Response 201
data is a Person.
Show the 48 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Return one person with the accounts they are a stakeholder on
/v1/people/{personId}people.get- Permission
- Accounts view
- Rate limit
- 12,000 requests a minute per API key
accounts feature on your workspace. Until it is on, calls answer 404.Each account carries the person's stakeholderId, role, priority and coverage there, highest priority first. emailFind is the newest find of their email. tagIds are the tags they carry; a champion carries the Champion tag. A merged person is 404 with detail person_merged and mergedIntoId, the person to read instead. Requires Accounts view.
curl -X GET "https://api.ken.so/v1/people/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a Person.
Show the 48 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Update person fields
/v1/people/{personId}people.update- Permission
- Accounts edit
- Rate limit
- 4,800 requests a minute per API key
accounts feature on your workspace. Until it is on, calls answer 404.Absent fields stay unchanged; null clears.
Fields: fullName, firstName, lastName, title, email, linkedinUrl, kenPersonId, ownerMemberId (a workspace member, else 400 invalid_member), leadStatus (new, working, qualified, disqualified, nurture), phones ([{ number, kind }], up to 20; replaces the list, so send every number to keep; a number the person has keeps when it was added; a number marked invalid (a wrong number) stays even when left out, after the numbers sent; a bad number is 400 invalid_phone), phoneOptOut (true: the person asked not to be called; it records now and the caller as phoneOptOutAt, keeping an earlier opt-out's time; false clears it; Kenso's dialer never calls an opted-out person), relationship (to_sort, lead, customer, network, archived; null is 400: a relationship is changed, never cleared; it clears Ken's suggestion, brings a person the LinkedIn connections import added into the main lists, and shows on the person's timeline when the relationship the person reads changes; an account the LinkedIn connections import created may follow its people to network or not_a_fit and back). score, engagement and the sources are read-only. An owner or lead status change shows on the person's timeline with before and after, and so does each new number. An email or LinkedIn URL another person holds is 409 conflict (email_taken, linkedin_url_taken) with that personId, which is left out when account scope own hides that person. A person keeps at least one of fullName, email, linkedinUrl. Pinned fields need overwritePinned: true. A merged person is 404 person_merged. Requires Accounts edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
fullName | string | optional | |
firstName | string | optional | |
lastName | string | optional | |
title | string | optional | |
email | string | optional | |
linkedinUrl | string | optional | A profile, such as https://linkedin.com/in/jane-doe. |
kenPersonId | integer (int64) | optional | The person's Ken id: their id in Ken Search. Null clears it. |
ownerMemberId | integer (int64) | optional | A member of this workspace who owns the person, or null to clear. |
leadStatus | string | optional | new, working, qualified, disqualified or nurture. Null clears it: not a lead. |
phones | array of PersonPhoneBody | optional | Replaces the person's phones, up to 20, in order: the first is the person's phone. A number the person already has keeps when and how it was added. Null or an empty list clears them. A number marked invalid (a wrong number) stays even when left out, after the numbers sent, so it is never added back. To add or remove one number, send the whole list with that number added or left out. |
customFields | map of object | optional | Custom field values by key (the fields of GET /v1/fields), merged per key: send only the keys to change, and a key as null to clear it. Each value is read as its field's type: text and url a string, number a number, boolean true or false, date a date or an ISO 8601 time, select an option's key or label, multi_select a list of them, currency {"amount": 1200.50, "currency": "USD"}, user a member id. A key no field names, an archived field or a value of the wrong type is 400 with details on customFields.<key>. A person's value pins the field as custom.<key>, like the built-in fields. Needs the custom_fields feature. |
overwritePinned | boolean | optional | |
headline | string | optional | The person's LinkedIn headline. Ken fills it, and location, seniority and department, from Ken Search and campaign contacts while blank. Set it to correct a wrong fill, or null to clear it. A member's value or clear pins the field, so Ken never fills over it. |
location | string | optional | Where the person is, such as Berlin, Germany. Null clears it. |
seniority | string | optional | Seniority, such as VP or Director. Null clears it. |
department | string | optional | Department, such as Sales or Engineering. Null clears it. |
phoneOptOut | boolean | optional | True: the person asked not to be called (phoneOptOutAt is now and you recorded it; an existing opt-out keeps its time). False clears it. Absent leaves it. Calls to an opted-out person are refused. |
relationship | string | optional | To_sort, lead, customer, network or archived. Null is refused: a relationship, once set, is changed, never unset. Clears Ken's suggestion. |
curl -X PATCH "https://api.ken.so/v1/people/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"leadStatus": "qualified",
"relationship": "lead"
}'Response 200
data is a Person.
Show the 48 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Delete a person who is on no live account
/v1/people/{personId}people.delete- Permission
- Accounts edit
- Rate limit
- 4,800 requests a minute per API key
accounts feature on your workspace. Until it is on, calls answer 404.Soft delete: the person leaves every list, search and find-or-create match, so the same email can be added again as a new person, and Kenso never re-adds them. A person still on an account is 409 conflict with detail person_on_accounts and accounts (accountId, name, stakeholderId): remove them from each first. Cancels their active email find. Returns 204. With account scope own it is 403 permission_denied with scope: all. Requires Accounts edit.
curl -X DELETE "https://api.ken.so/v1/people/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 204
HTTP/1.1 204 No ContentTake in a person from your source
/v1/people/intakepeople.intake- Permission
- Accounts edit
- Rate limit
- 600 requests an hour per workspace (Free plan: 60 an hour)
accounts feature on your workspace. Until it is on, calls answer 404. Needs the lead_intake feature on your workspace. Until it is on, calls answer 404.Sends Kenso one person from a source of your own, such as a web form, a workflow or your CRM. Kenso matches them to an existing person or creates a new one, places them on their company's account and assigns an owner. Sending the same person again updates that person and never creates a second one.
The body must identify the person with an email, a linkedinUrl, or a name with a business companyDomain. A name is fullName, or firstName and lastName.
Kenso looks for an existing person in this order: the same email, then the same LinkedIn URL, then a person with no email, the same full name and a place on the account that holds the company's domain. Deleted and merged people never match. A person with the same name who has an email is never matched by name. Instead, Kenso creates a new person and returns the other one in suggestedDuplicateOfPersonId, so a member can review the pair.
On a match, Kenso fills only the person's blank fields and never changes a value they already have. It sets the owner and the lead status only when the person has none, adds the phone to their phone numbers, and updates their latest source and their score. Kenso never changes a field a member or your CRM set, even a blank one. When the email or LinkedIn URL already belongs to another person, Kenso leaves it off this one.
A new person gets the lead status from leadStatus, else new, and a score from 0 to 100. When neither the body nor the person has a title and the body has a linkedinUrl, Kenso takes the current title from Kenso Search.
The company's domain is the email's domain. When the email is missing or on a free email provider such as gmail.com, Kenso uses companyDomain. Kenso places the person on the live account that holds that domain. When no account holds it, Kenso creates one with stage researching and source inbound, named from Kenso Search's company data, else from companyName. Creating it costs no research credits. Kenso creates no account when createAccount is false or the workspace's intake settings turn account creation off. If a member removed the person from that account before, Kenso does not add them back.
A matched person keeps their owner. Otherwise Kenso picks the first active member from this list: the account's owner, the owner of the contact with this email in your connected CRM, ownerMemberId, the workspace's default owner, then the next member in the workspace's round robin.
For a new person, Kenso adds a new lead item to Today. It also notifies the owner when the workspace's intake settings have new lead notifications on. Values in customFields fill only the person's custom fields that are blank.
A role address is a shared mailbox such as support@, info@ or no-reply@. It matches a person who already holds it, but Kenso never gives it to a new person or a matched one. With a linkedinUrl or a real first and last name, Kenso takes the person in without the address and returns emailDropped: role_address. Each part of a real name has a word of two letters or more, and neither part is a role word such as support or team, the address's local part, a label of its domain or the company name.
Each workspace can make 600 intake calls in a rolling hour.
Errors:
400 validation_failedwith detail codeidentity_required: the body has noemail, nolinkedinUrland no name with a businesscompanyDomain.400 validation_failedwith another detail code: a field is invalid. The detail'sfieldnames it, and its code isinvalid_email,invalid_linkedin_url,invalid_domain,invalid_phone,invalid_source,invalid_memberorout_of_range. A field the body does not define is also400 validation_failed.403 permission_denied: the caller works only their own accounts (account scopeown). The detail carriesscope: all, the scope this call needs.422 role_address:emailis a role address, no existing person matches, and the body has nolinkedinUrland no real first and last name. Kenso writes nothing.429 rate_limited: the workspace made 600 intake calls in the last hour. Retry after the number of seconds in theRetry-Afterheader.
Requires Accounts edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
email | string | optional | The person's email. Kenso trims it, lower-cases it and matches on it first. A shared mailbox such as support@ or info@ never becomes the person's email. |
linkedinUrl | string | optional | The person's public LinkedIn profile, such as https://linkedin.com/in/jane-doe. Kenso matches on it after the email. A member id URL (linkedin.com/in/ACwAA...) is not a public profile, so Kenso takes the person in without it. |
fullName | string | optional | The person's full name, up to 300 characters. Omitted: Kenso joins firstName and lastName. |
firstName | string | optional | The person's first name, up to 300 characters. |
lastName | string | optional | The person's last name, up to 300 characters. |
title | string | optional | The person's job title, up to 2,000 characters. Kenso sets it only on a person who has no title. |
companyName | string | optional | The company name, up to 300 characters. Kenso uses it to name a new account when Kenso Search has no name for the company's domain. |
companyDomain | string | optional | The company's domain or website, such as acme.com. Kenso uses it when the email is missing or on a free email provider such as gmail.com, and ignores a free email provider's domain sent here. |
phone | string | optional | A phone number with 8 to 15 digits and the country code, such as +15551234567. Kenso adds it to the person's phone numbers. A number without a country code is read in the country of the person or their account when Kenso knows it. |
source | string | optional | Where the person comes from: api, workflow or manual. Omitted means api. Kenso records it as the person's latest source, and as their first source when it creates them. |
sourceDetail | string | optional | Where in that source the person came from, such as a form or list name. Kenso keeps the first 300 characters. |
ownerMemberId | integer (int64) | optional | The member to own the person when the person, their account and your CRM name no owner. Must be a member of the workspace. |
leadStatus | string | optional | The lead status: new, working, qualified, disqualified or nurture. Omitted means new. Kenso sets it only on a person who has no lead status. |
customFields | map of object | optional | Values for the workspace's person custom fields, by field key. Kenso ignores keys with no person custom field and fills only fields that are blank on the person. Where custom fields are on, a value is read as its field's type (GET /v1/fields?object=person), and text is read as a CSV cell would be: yes or no for a boolean, an option's key or label for a select, options split by ; for a multi_select, 1200.50 USD for a currency. A value that is not its field's type is left out and named in the response's customFieldErrors; the person is still taken in. |
createAccount | boolean | optional | False: Kenso creates no account for a company domain that has none. True or omitted: Kenso creates one when the workspace's intake settings allow it. |
useKenEmail | boolean | optional | True with no email: Kenso takes the person's work email from its own email database when it holds a recently verified one, at no charge. Kenso looks them up by linkedinUrl, else by name with companyName or companyDomain, and only on the company's domain. With no match, or when the workspace used its daily allowance of these lookups, Kenso takes the person in without an email. Needs the extension feature on the workspace; without it the field does nothing. |
curl -X POST "https://api.ken.so/v1/people/intake" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"linkedinUrl": "https://example.com",
"fullName": "Jane Doe",
"firstName": "Jane",
"lastName": "Doe",
"title": "string",
"companyName": "Acme",
"companyDomain": "example.com",
"phone": "string",
"source": "api",
"sourceDetail": "string",
"ownerMemberId": 812,
"leadStatus": "new",
"customFields": {
"key": null
},
"createAccount": true,
"useKenEmail": true
}'Response 200
data is a PersonIntake.
Show the 8 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Search people in the current workspace with filters
/v1/people/searchpeople.search- Permission
- Accounts view
- Rate limit
- 12,000 requests a minute per API key
accounts feature on your workspace. Until it is on, calls answer 404.Body, every field optional: q (full name, email or title contains), accountIds (on any of these accounts, up to 100), onAccount (any default, none on no live account, some on at least one), roles (holds one of these roles on some live account), hasEmail, addedBy (who created the person: user, agent, api_key, system, workflow), ownerMemberId, leadStatus (list), relationship (list: to_sort, lead, customer, network, archived; matches the relationship each person reads, and includes people the LinkedIn connections import added that nobody has worked yet, who read to_sort), hasSuggestion, suggestedRelationship (list: lead, customer, network, archived, unsure) and suggestionKind (list: icp_fit, customer_contact, old_teammate, classmate, personal, low_icp, unsure), both on Ken's stored suggestion and including people the LinkedIn connections import added, source (list, on the latest source), tagIds (carries any of these tags, up to 100), sort (-createdAt default, name A-Z with unnamed people last, -score highest first with unscored last, -latestSourceAt newest first with none last, or one sortable custom field as custom.<key> or -custom.<key> with people who have no value last), filters (a list of { "field", "operator", "values" } conditions on custom fields, behind the custom_fields flag: field is custom.<key>, operator one of the field's operators on fields.list, and a field may have more than one condition), limit (1-1000, default 50), cursor, includeTotal. Lists OR within themselves; filters AND together. Each row embeds its live accounts (with stakeholderId, role, priority, coverage), emailFind and tagIds, and lastTouch (at, and channel: email, linkedin, whatsapp, facebook or instagram): the latest message with the person on any of those channels, sent or received, omitted when there is none; it does not sort. Unlike an account's lastTouchAt, it counts the person's replies but no automated reply or bounce, and a logged call does not count. Deleted and merged people never appear. With account scope own, only people on the caller's accounts, each with only those accounts. Requires Accounts view.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
q | string | optional | Contains, case-insensitive, on the full name, email or title. |
accountIds | array of integer (int64) | optional | On any of these accounts (1 to 100 ids). |
onAccount | string | optional | any (default), none (on no live account) or some (on at least one). |
roles | array of string | optional | Holds one of these roles on some live account. |
hasEmail | boolean | optional | True: people with an email. False: people without one. |
addedBy | array of string | optional | Who created the person: user, agent, api_key, system or workflow. |
ownerMemberId | integer (int64) | optional | People this member owns. |
leadStatus | array of string | optional | Has one of these lead statuses: new, working, qualified, disqualified, nurture. |
relationship | array of string | optional | The person's relationship is one of these: to_sort, lead, customer, network, archived. Matches the relationship people read, derived while nobody has set it. With this filter, people the LinkedIn connections import added that nobody has worked yet are included: they read to_sort. |
hasSuggestion | boolean | optional | True keeps only people with a suggestion from Ken; false only people without one. |
suggestedRelationship | array of string | optional | Ken's stored suggestion is one of these relationships: lead, customer, network, archived, unsure. With this filter, people the LinkedIn connections import added that nobody has worked yet are included. |
suggestionKind | array of string | optional | Ken's stored suggestion is one of these kinds: icp_fit, customer_contact, old_teammate, classmate, personal, low_icp, unsure. With this filter, people the LinkedIn connections import added are included. |
source | array of string | optional | The latest source is one of these: manual, api, workflow, search, research, promoted, campaign, booking, crm, form, webhook, import, visitor, inbound_email, linkedin. |
tagIds | array of integer (int64) | optional | Carries any of these tags (1 to 100 ids). |
connectedVia | array of integer (int64) | optional | A connection of any of these LinkedIn seats (1 to 100 linkedinAccountIds). |
includeImportOnly | boolean | optional | True includes people the LinkedIn connections import added that nobody has worked yet. Default false: they are left out unless their connection fits the ICP. |
behaviorTags | array of string | optional | Behavior tags, any-match (up to 50, such as cold_responder or best_window:weekday_morning): people whose workspace behavior tags (and network tags, with behavior_signals_network) include one. Needs behavior_signals; email_confirmed, email_dead_end and left_company cannot be filtered. |
seniority | array of string | optional | Has one of these seniorities, such as Director or VP (case-insensitive, up to 50). |
department | array of string | optional | Has one of these departments, such as Sales or Engineering (case-insensitive, up to 50). |
location | string | optional | Contains, case-insensitive, on the location. |
sort | string | optional | -createdAt (default), name, -score, -latestSourceAt, headline, location, seniority or department. people.search and people.export also take a sortable custom field as custom.<key> or -custom.<key>. |
filters | array of CustomFieldFilterBody | optional | Up to 50 conditions on custom fields, AND with each other and with the other filters. A field may have more than one (a range is two). |
limit | integer (int32) | optional | 1 to 1000. Default 50. |
cursor | string | optional | The previous page's nextCursor, with the same filters and sort. |
includeTotal | boolean | optional | True fills pagination.total: every person that passes the filters. |
curl -X POST "https://api.ken.so/v1/people/search" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"accountIds": [
6120
],
"leadStatus": [
"working",
"qualified"
],
"hasEmail": true,
"sort": "-score",
"limit": 50
}'Response 200
data is a list of Person. Each item has these fields. The response also carries pagination.
Show the 48 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Merge this person into another person
/v1/people/{personId}/mergepeople.merge- Permission
- Accounts edit
- Rate limit
- 4,800 requests a minute per API key
accounts feature on your workspace. Until it is on, calls answer 404.Body: intoPersonId, the person to keep. In one transaction the kept person keeps every value it has and takes this person's values for its blank fields; this person's account places move to it (on a shared account the two places combine, with touches, reports and seats re-pointed); removal history moves too; this person's active email find is cancelled. This person then reads as 404 person_merged with mergedIntoId. Merging into the same, a deleted or a merged person is 400 validation_failed. Returns the kept person. With account scope own it is 403 permission_denied with scope: all. Requires Accounts edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
intoPersonId | integer (int64) | optional | The person to keep. |
curl -X POST "https://api.ken.so/v1/people/812/merge" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"intoPersonId": 77310
}'Response 200
data is a Person.
Show the 48 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Upload or replace a person's photo
/v1/people/{personId}/photopeople.replace-photo- Permission
- Accounts edit
- Rate limit
- 4,800 requests a minute per API key
accounts feature on your workspace. Until it is on, calls answer 404.Multipart field file: a non-empty PNG, JPEG or WebP under 10 MB, checked by type, extension and content (else 400 validation_failed). Kenso stores it and serves it from /media; it shows as photoUrl with photoSource: upload, ahead of the person's LinkedIn photo, and replaces an earlier upload. A merged person is 404 person_merged. Returns the person. Requires Accounts edit.
Request body
multipart/form-data, optional.
| Field | Type | Required | Description |
|---|---|---|---|
file | string (binary) | optional |
curl -X PUT "https://api.ken.so/v1/people/812/photo" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-F "file=@./file"Response 200
data is a Person.
Show the 48 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Remove the photo uploaded for a person
/v1/people/{personId}/photopeople.delete-photo- Permission
- Accounts edit
- Rate limit
- 4,800 requests a minute per API key
accounts feature on your workspace. Until it is on, calls answer 404.The person shows their LinkedIn photo again (photoSource: linkedin) when Kenso has one, else no photo. Removing a photo the person does not have changes nothing. A merged person is 404 person_merged. Returns the person. Requires Accounts edit.
curl -X DELETE "https://api.ken.so/v1/people/812/photo" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a Person.
Show the 48 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
More in CRM:AccountsPerson behaviorAccount domainsStakeholdersMeeting notesAll resources