Skip to Content
CRM

People

Send people into Kenso from your own source.

CRM10 endpointsKen-Version: 2026-11-02AuthenticationWorkspacesErrors
MarkdownOpenAPI

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.

NameInTypeRequiredDescription
personIdpathinteger (int64)required

Headers

The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.

NameInTypeRequiredDescription
Ken-Versionheaderstring, one of: 2026-11-02, 1.1optionalThe 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-Idheaderinteger (int64)optionalThe 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

GET/v1/peoplepeople.list
Permission
Accounts view
Rate limit
12,000 requests a minute per API key
Needs the accounts feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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

NameInTypeRequiredDescription
emailquerystringoptional
linkedinUrlquerystringoptionalA LinkedIn profile URL in any shape.
qquerystringoptionalContains, case-insensitive, on the full name or email.
ownerMemberIdqueryinteger (int64)optionalPeople this member owns.
leadStatusquerystringoptionalComma-separated lead statuses, OR: new, working, qualified, disqualified, nurture.
sourcequerystringoptionalComma-separated latest sources, OR: manual, api, workflow, search, research, promoted, campaign, booking, crm, form, webhook, import, visitor, inbound_email, linkedin.
tagIdsquerystringoptionalComma-separated tag ids, OR: people carrying any of them.
relationshipquerystringoptionalComma-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).
hasSuggestionquerybooleanoptionalTrue only people with a suggestion from Ken; false only people without one.
suggestedRelationshipquerystringoptionalComma-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.
suggestionKindquerystringoptionalComma-separated suggestion kinds, OR: icp_fit, customer_contact, old_teammate, classmate, personal, low_icp, unsure. People the LinkedIn connections import added included.
behaviorTagsqueryarray of stringoptionalBehavior 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.
sortquerystringoptional-createdAt (default), name, -score or -latestSourceAt.
limitqueryinteger (int32)optionalItems per page, from 1 to 200. Default 50.
cursorquerystringoptionalThe nextCursor of the previous page. Omit it for the first page.
Request
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

POST/v1/peoplepeople.create
Permission
Accounts edit
Rate limit
4,800 requests a minute per API key
Needs the accounts feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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.

FieldTypeRequiredDescription
fullNamestringoptional
firstNamestringoptional
lastNamestringoptional
titlestringoptional
emailstringoptional
linkedinUrlstringoptionalA profile, such as https://linkedin.com/in/jane-doe.
kenPersonIdinteger (int64)optionalThe person's Ken id: their id in Ken Search. Null clears it.
ownerMemberIdinteger (int64)optionalA member of this workspace who owns the person, or null to clear.
leadStatusstringoptionalnew, working, qualified, disqualified or nurture. Null clears it: not a lead.
phonesarray of PersonPhoneBodyoptionalReplaces 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.
Request
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

GET/v1/people/{personId}people.get
Permission
Accounts view
Rate limit
12,000 requests a minute per API key
Needs the accounts feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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.

Request
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

PATCH/v1/people/{personId}people.update
Permission
Accounts edit
Rate limit
4,800 requests a minute per API key
Needs the accounts feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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.

FieldTypeRequiredDescription
fullNamestringoptional
firstNamestringoptional
lastNamestringoptional
titlestringoptional
emailstringoptional
linkedinUrlstringoptionalA profile, such as https://linkedin.com/in/jane-doe.
kenPersonIdinteger (int64)optionalThe person's Ken id: their id in Ken Search. Null clears it.
ownerMemberIdinteger (int64)optionalA member of this workspace who owns the person, or null to clear.
leadStatusstringoptionalnew, working, qualified, disqualified or nurture. Null clears it: not a lead.
phonesarray of PersonPhoneBodyoptionalReplaces 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.
customFieldsmap of objectoptionalCustom 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.
overwritePinnedbooleanoptional
headlinestringoptionalThe 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.
locationstringoptionalWhere the person is, such as Berlin, Germany. Null clears it.
senioritystringoptionalSeniority, such as VP or Director. Null clears it.
departmentstringoptionalDepartment, such as Sales or Engineering. Null clears it.
phoneOptOutbooleanoptionalTrue: 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.
relationshipstringoptionalTo_sort, lead, customer, network or archived. Null is refused: a relationship, once set, is changed, never unset. Clears Ken's suggestion.
Request
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

DELETE/v1/people/{personId}people.delete
Permission
Accounts edit
Rate limit
4,800 requests a minute per API key
Needs the accounts feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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.

Request
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

Response 204
HTTP/1.1 204 No Content

Take in a person from your source

POST/v1/people/intakepeople.intake
Permission
Accounts edit
Rate limit
600 requests an hour per workspace (Free plan: 60 an hour)
Needs the 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.

Try it on developer.ken.so

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_failed with detail code identity_required: the body has no email, no linkedinUrl and no name with a business companyDomain.
  • 400 validation_failed with another detail code: a field is invalid. The detail's field names it, and its code is invalid_email, invalid_linkedin_url, invalid_domain, invalid_phone, invalid_source, invalid_member or out_of_range. A field the body does not define is also 400 validation_failed.
  • 403 permission_denied: the caller works only their own accounts (account scope own). The detail carries scope: all, the scope this call needs.
  • 422 role_address: email is a role address, no existing person matches, and the body has no linkedinUrl and 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 the Retry-After header.

Requires Accounts edit.

Request body

application/json, optional.

FieldTypeRequiredDescription
emailstringoptionalThe 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.
linkedinUrlstringoptionalThe 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.
fullNamestringoptionalThe person's full name, up to 300 characters. Omitted: Kenso joins firstName and lastName.
firstNamestringoptionalThe person's first name, up to 300 characters.
lastNamestringoptionalThe person's last name, up to 300 characters.
titlestringoptionalThe person's job title, up to 2,000 characters. Kenso sets it only on a person who has no title.
companyNamestringoptionalThe 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.
companyDomainstringoptionalThe 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.
phonestringoptionalA 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.
sourcestringoptionalWhere 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.
sourceDetailstringoptionalWhere in that source the person came from, such as a form or list name. Kenso keeps the first 300 characters.
ownerMemberIdinteger (int64)optionalThe member to own the person when the person, their account and your CRM name no owner. Must be a member of the workspace.
leadStatusstringoptionalThe lead status: new, working, qualified, disqualified or nurture. Omitted means new. Kenso sets it only on a person who has no lead status.
customFieldsmap of objectoptionalValues 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.
createAccountbooleanoptionalFalse: 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.
useKenEmailbooleanoptionalTrue 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.
Request
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

POST/v1/people/searchpeople.search
Permission
Accounts view
Rate limit
12,000 requests a minute per API key
Needs the accounts feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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.

FieldTypeRequiredDescription
qstringoptionalContains, case-insensitive, on the full name, email or title.
accountIdsarray of integer (int64)optionalOn any of these accounts (1 to 100 ids).
onAccountstringoptionalany (default), none (on no live account) or some (on at least one).
rolesarray of stringoptionalHolds one of these roles on some live account.
hasEmailbooleanoptionalTrue: people with an email. False: people without one.
addedByarray of stringoptionalWho created the person: user, agent, api_key, system or workflow.
ownerMemberIdinteger (int64)optionalPeople this member owns.
leadStatusarray of stringoptionalHas one of these lead statuses: new, working, qualified, disqualified, nurture.
relationshiparray of stringoptionalThe 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.
hasSuggestionbooleanoptionalTrue keeps only people with a suggestion from Ken; false only people without one.
suggestedRelationshiparray of stringoptionalKen'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.
suggestionKindarray of stringoptionalKen'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.
sourcearray of stringoptionalThe latest source is one of these: manual, api, workflow, search, research, promoted, campaign, booking, crm, form, webhook, import, visitor, inbound_email, linkedin.
tagIdsarray of integer (int64)optionalCarries any of these tags (1 to 100 ids).
connectedViaarray of integer (int64)optionalA connection of any of these LinkedIn seats (1 to 100 linkedinAccountIds).
includeImportOnlybooleanoptionalTrue includes people the LinkedIn connections import added that nobody has worked yet. Default false: they are left out unless their connection fits the ICP.
behaviorTagsarray of stringoptionalBehavior 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.
seniorityarray of stringoptionalHas one of these seniorities, such as Director or VP (case-insensitive, up to 50).
departmentarray of stringoptionalHas one of these departments, such as Sales or Engineering (case-insensitive, up to 50).
locationstringoptionalContains, case-insensitive, on the location.
sortstringoptional-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>.
filtersarray of CustomFieldFilterBodyoptionalUp 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).
limitinteger (int32)optional1 to 1000. Default 50.
cursorstringoptionalThe previous page's nextCursor, with the same filters and sort.
includeTotalbooleanoptionalTrue fills pagination.total: every person that passes the filters.
Request
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

POST/v1/people/{personId}/mergepeople.merge
Permission
Accounts edit
Rate limit
4,800 requests a minute per API key
Needs the accounts feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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.

FieldTypeRequiredDescription
intoPersonIdinteger (int64)optionalThe person to keep.
Request
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

PUT/v1/people/{personId}/photopeople.replace-photo
Permission
Accounts edit
Rate limit
4,800 requests a minute per API key
Needs the accounts feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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.

FieldTypeRequiredDescription
filestring (binary)optional
Request
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

DELETE/v1/people/{personId}/photopeople.delete-photo
Permission
Accounts edit
Rate limit
4,800 requests a minute per API key
Needs the accounts feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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.

Request
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.


On this page