{"openapi":"3.0.4","info":{"title":"Kenso API: People","version":"1.1","description":"The People endpoints of the Kenso API, with every component they use. The full spec is https://api.ken.so/v1/docs/openapi.json. Every request sends `Authorization: Bearer <your API key>` and `Ken-Version: 2026-11-02`."},"servers":[{"url":"https://api.ken.so"}],"security":[{"Bearer":[]}],"tags":[{"name":"people","description":"A person is one real human in your workspace, the same record across your campaigns and your accounts. A person\ncarries their owner, lead status, score, phone numbers and a record of where they came from.\nList people, look one up by email or LinkedIn URL, or search them by account, role, lead status and tags. Create,\nupdate, merge and delete people, and upload or remove a person's photo. Put a person on an account through the\naccount's stakeholders. Use intake to send Kenso people from your own sources, such as a web form, a workflow or\nyour CRM: Kenso matches each one to an existing person or creates them, places them on their company's account and\nassigns an owner.","x-displayName":"People"}],"paths":{"/v1/people":{"get":{"tags":["people"],"summary":"List people in the current workspace.","description":"Filters: `email`, `linkedinUrl` (any profile URL shape; normalized), `q` (name or\nemail contains), `ownerMemberId`, `leadStatus` (comma list: new, working, qualified,\ndisqualified, nurture), `source` (comma list on the latest source), `tagIds` (comma list of tag\nids: people carrying any of them; `GET /v1/tags?systemKey=champion` gives the Champion tag),\n`behaviorTags` (repeatable: people whose behavior tags include any, for example\n`behaviorTags=cold_responder&behaviorTags=prefers_linkedin`; needs the `behavior_signals` feature;\n`email_confirmed`, `email_dead_end` and `left_company` cannot be filtered),\n`relationship` (comma list: to_sort, lead, customer, network, archived; matches the relationship each person\nreads, and includes people the LinkedIn connections import added that nobody has worked yet, who read to_sort),\n`hasSuggestion` (true: people with a suggestion from Ken; false: people without one),\n`suggestedRelationship` (comma list: lead, customer, network, archived, unsure; Ken's stored suggestion) and\n`suggestionKind` (comma list: icp_fit, customer_contact, old_teammate, classmate, personal, low_icp, unsure);\nboth include the people the LinkedIn connections import added that nobody has worked yet.\n`sort`: `-createdAt` (default), `name` (A-Z, unnamed last), `-score` (highest first,\nunscored last), `-latestSourceAt` (newest first, none last). Each person carries `ownerMemberId`,\n`leadStatus`, `relationship`, `relationshipSet`, `engagement`, `suggestion`,\n`score`, `phones`, `phone` (the first valid one), `firstSource`, `latestSource` and\n`tagIds`. Requires Accounts view.\n\nRate limit: 12,000 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `accounts` feature on your workspace. Until it is on, calls answer 404.","operationId":"people.list","parameters":[{"name":"email","in":"query","schema":{"type":"string"}},{"name":"linkedinUrl","in":"query","description":"A LinkedIn profile URL in any shape.","schema":{"type":"string"}},{"name":"q","in":"query","description":"Contains, case-insensitive, on the full name or email.","schema":{"type":"string"}},{"name":"ownerMemberId","in":"query","description":"People this member owns.","schema":{"type":"integer","format":"int64"}},{"name":"leadStatus","in":"query","description":"Comma-separated lead statuses, OR: new, working, qualified, disqualified, nurture.","schema":{"type":"string"}},{"name":"source","in":"query","description":"Comma-separated latest sources, OR: manual, api, workflow, search, research, promoted, campaign, booking, crm,\nform, webhook, import, visitor, inbound_email, linkedin.","schema":{"type":"string"}},{"name":"tagIds","in":"query","description":"Comma-separated tag ids, OR: people carrying any of them.","schema":{"type":"string"}},{"name":"relationship","in":"query","description":"Comma-separated relationships, OR: to_sort, lead, customer, network, archived. Matches the relationship\npeople read, derived while nobody has set it, and includes people the LinkedIn connections import added that nobody\nhas worked yet (they read to_sort).","schema":{"type":"string"}},{"name":"hasSuggestion","in":"query","description":"True only people with a suggestion from Ken; false only people without one.","schema":{"type":"boolean"}},{"name":"suggestedRelationship","in":"query","description":"Comma-separated suggested relationships, OR: lead, customer, network, archived, unsure. People whose\nstored suggestion from Ken is one of them, people the LinkedIn connections import added included.","schema":{"type":"string"}},{"name":"suggestionKind","in":"query","description":"Comma-separated suggestion kinds, OR: icp_fit, customer_contact, old_teammate, classmate, personal,\nlow_icp, unsure. People the LinkedIn connections import added included.","schema":{"type":"string"}},{"name":"behaviorTags","in":"query","description":"Behavior tags, repeatable (`behaviorTags=a&behaviorTags=b`), any-match: people whose workspace\nbehavior tags (and network tags, with `behavior_signals_network`) include one. Needs `behavior_signals`.","schema":{"type":"array","items":{"type":"string"}}},{"name":"sort","in":"query","description":"-createdAt (default), name, -score or -latestSourceAt.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Items per page, from 1 to 200. Default 50.","schema":{"maximum":200,"minimum":1,"type":"integer","format":"int32","default":50}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page. Omit it for the first page.","schema":{"type":"string"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonListResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-features":["accounts"],"x-ken-permission":{"kind":"page","page":"accounts","access":"view","summary":"Accounts view"},"x-ken-rate-limit":{"limit":12000,"windowSeconds":60,"per":"api_key"}},"post":{"tags":["people"],"summary":"Create one person on no account.","description":"Body: `fullName` (required), `firstName`, `lastName`, `title`, `email`,\n`linkedinUrl`, `kenPersonId`, `ownerMemberId`, `leadStatus`, `phones` (as on\n`people.update`). The first and latest source are `manual` for a person and `api` for an API\nkey or agent. Email is trimmed and lower-cased; the LinkedIn URL is\nnormalized like the `linkedinUrl` filter. A live person with the same email or LinkedIn URL is\n`409 conflict` with detail `person_exists` and their `personId`: use them instead of\ncreating a twin. A name-only match is not a duplicate. A role address (a shared mailbox such as support@, info@,\nno-reply@) is not a person: a person who already holds it is still `409 conflict` with detail\n`person_exists`. Else with a\n`linkedinUrl`, a `kenPersonId` or a real first and last name (both parts, from `firstName` and\n`lastName` or `fullName`, neither a role word such as support or team, the address's local part or a\nlabel of its domain, nor an initial only; intake also checks the company name it is sent) the person is created\nwithout it and the answer carries\n`emailDropped: role_address`; with none of them it is `422 role_address`. No email find starts.\nReturns `201` with `accounts: []`.\nWith account scope `own` it is `403` `permission_denied` with `scope: all`: add the person to one of your accounts instead. Requires Accounts edit.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `accounts` feature on your workspace. Until it is on, calls answer 404.","operationId":"people.create","parameters":[{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePersonBody"}}}},"responses":{"201":{"description":"Created","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"409":{"description":"Conflict","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["conflict"]},"422":{"description":"Unprocessable Content","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["role_address"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-features":["accounts"],"x-ken-permission":{"kind":"page","page":"accounts","access":"edit","summary":"Accounts edit"},"x-ken-rate-limit":{"limit":4800,"windowSeconds":60,"per":"api_key"}}},"/v1/people/{personId}":{"get":{"tags":["people"],"summary":"Return one person with the accounts they are a stakeholder on.","description":"Each account carries the person's `stakeholderId`, `role`, `priority` and\n`coverage` there, highest priority first. `emailFind` is the newest find of their email.\n`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\nread instead. Requires Accounts view.\n\nRate limit: 12,000 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `accounts` feature on your workspace. Until it is on, calls answer 404.","operationId":"people.get","parameters":[{"name":"personId","in":"path","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-features":["accounts"],"x-ken-permission":{"kind":"page","page":"accounts","access":"view","summary":"Accounts view"},"x-ken-rate-limit":{"limit":12000,"windowSeconds":60,"per":"api_key"}},"patch":{"tags":["people"],"summary":"Update person fields. Absent fields stay unchanged; null clears.","description":"Fields: fullName, firstName, lastName, title, email, linkedinUrl, kenPersonId, `ownerMemberId`\n(a workspace member, else `400` `invalid_member`), `leadStatus` (new, working, qualified,\ndisqualified, nurture), `phones` (`[{ number, kind }]`, up to 20; replaces the list, so send every\nnumber to keep; a number the person has keeps when it was added; a number marked invalid (a wrong number) stays\neven when left out, after the numbers sent; a bad number is `400` `invalid_phone`), `phoneOptOut` (true: the person asked not to be\ncalled; it records now and the caller as `phoneOptOutAt`, keeping an earlier opt-out's time; false clears it;\nKenso's dialer never calls an opted-out person; with the imessage feature on, Kenso texts them nothing either: a\ntext not yet written is skipped and a written one fails. A STOP reply sets it. false clears it, but a number that\ntexted STOP still gets no text),\n`relationship` (to_sort, lead, customer, network, archived;\nnull is `400`: a relationship is changed, never cleared; it clears Ken's `suggestion`, brings a person the\nLinkedIn connections import added into the main lists, and shows on the person's timeline when the relationship\nthe person reads changes; an account the LinkedIn connections import created may follow its people to network or\nnot_a_fit and back).\n`score`, `engagement` and the sources are read-only. An owner or lead status change shows on the\nperson's timeline with before and after, and so does each new number. An email or\nLinkedIn URL another person holds is `409 conflict` (`email_taken`,\n`linkedin_url_taken`) with that `personId`, which is left out when account scope `own`\nhides that person. A person keeps at least one of fullName, email, linkedinUrl. Pinned fields need\n`overwritePinned: true`. A merged person is `404` `person_merged`. Requires Accounts edit.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `accounts` feature on your workspace. Until it is on, calls answer 404.","operationId":"people.update","parameters":[{"name":"personId","in":"path","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePersonBody"}}}},"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"409":{"description":"Conflict","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["conflict"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-features":["accounts"],"x-ken-permission":{"kind":"page","page":"accounts","access":"edit","summary":"Accounts edit"},"x-ken-rate-limit":{"limit":4800,"windowSeconds":60,"per":"api_key"}},"delete":{"tags":["people"],"summary":"Delete a person who is on no live account.","description":"Soft delete: the person leaves every list, search and find-or-create match, so the same email can be\nadded again as a new person, and Kenso never re-adds them. A person still on an account is\n`409 conflict` with detail `person_on_accounts` and `accounts`\n(`accountId`, `name`, `stakeholderId`): remove them from each first. Cancels their\nactive email find. Returns `204`. With account scope `own` it is `403` `permission_denied` with `scope: all`. Requires Accounts edit.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `accounts` feature on your workspace. Until it is on, calls answer 404.","operationId":"people.delete","parameters":[{"name":"personId","in":"path","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"responses":{"204":{"description":"No Content","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"409":{"description":"Conflict","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["conflict"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-features":["accounts"],"x-ken-permission":{"kind":"page","page":"accounts","access":"edit","summary":"Accounts edit"},"x-ken-rate-limit":{"limit":4800,"windowSeconds":60,"per":"api_key"}}},"/v1/people/intake":{"post":{"tags":["people"],"summary":"Take in a person from your source","description":"Sends Kenso one person from a source of your own, such as a web form, a workflow or your CRM. Kenso matches\nthem to an existing person or creates a new one, places them on their company's account and assigns an owner.\nSending the same person again updates that person and never creates a second one.\n            \nThe body must identify the person with an `email`, a `linkedinUrl`, or a name with a business\n`companyDomain`. A name is `fullName`, or `firstName` and `lastName`.\n            \nKenso looks for an existing person in this order: the same email, then the same LinkedIn URL, then a person\nwith no email, the same full name and a place on the account that holds the company's domain. Deleted and\nmerged people never match. A person with the same name who has an email is never matched by name. Instead,\nKenso creates a new person and returns the other one in `suggestedDuplicateOfPersonId`, so a member can\nreview the pair.\n            \nOn a match, Kenso fills only the person's blank fields and never changes a value they already have. It sets\nthe owner and the lead status only when the person has none, adds the phone to their phone numbers, and updates\ntheir latest source and their score. Kenso never changes a field a member or your CRM set, even a blank one.\nWhen the email or LinkedIn URL already belongs to another person, Kenso leaves it off this one.\n            \nA new person gets the lead status from `leadStatus`, else `new`, and a score from 0 to 100. When\nneither the body nor the person has a title and the body has a `linkedinUrl`, Kenso takes the current\ntitle from Kenso Search.\n            \nThe company's domain is the email's domain. When the email is missing or on a free email provider such as\ngmail.com, Kenso uses `companyDomain`. Kenso places the person on the live account that holds that\ndomain. When no account holds it, Kenso creates one with stage `researching` and source `inbound`,\nnamed from Kenso Search's company data, else from `companyName`. Creating it costs no research credits.\nKenso creates no account when `createAccount` is false or the workspace's intake settings turn account\ncreation off. If a member removed the person from that account before, Kenso does not add them back.\n            \nA matched person keeps their owner. Otherwise Kenso picks the first active member from this list: the\naccount's owner, the owner of the contact with this email in your connected CRM, `ownerMemberId`, the\nworkspace's default owner, then the next member in the workspace's round robin.\n            \nFor a new person, Kenso adds a new lead item to Today. It also notifies the owner when the workspace's intake\nsettings have new lead notifications on. Values in `customFields` fill only the person's custom fields\nthat are blank.\n            \nA role address is a shared mailbox such as support@, info@ or no-reply@. It matches a person who already\nholds it, but Kenso never gives it to a new person or a matched one. With a `linkedinUrl` or a real\nfirst and last name, Kenso takes the person in without the address and returns\n`emailDropped: role_address`. Each part of a real name has a word of two letters or more, and neither\npart is a role word such as support or team, the address's local part, a label of its domain or the company\nname.\n            \nEach workspace can make 600 intake calls in a rolling hour.\n            \nErrors:\n            \n- `400 validation_failed` with detail code `identity_required`: the body has no `email`, no\n  `linkedinUrl` and no name with a business `companyDomain`.\n- `400 validation_failed` with another detail code: a field is invalid. The detail's `field` names\n  it, and its code is `invalid_email`, `invalid_linkedin_url`, `invalid_domain`,\n  `invalid_phone`, `invalid_source`, `invalid_member` or `out_of_range`. A field\n  the body does not define is also `400 validation_failed`.\n- `403 permission_denied`: the caller works only their own accounts (account scope `own`). The\n  detail carries `scope: all`, the scope this call needs.\n- `422 role_address`: `email` is a role address, no existing person matches, and the body has no\n  `linkedinUrl` and no real first and last name. Kenso writes nothing.\n- `429 rate_limited`: the workspace made 600 intake calls in the last hour. Retry after the number of\n  seconds in the `Retry-After` header.\n            \nRequires Accounts edit.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.\n\nNeeds 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.","operationId":"people.intake","parameters":[{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntakePersonBody"}}}},"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonIntakeResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","validation_failed","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"403":{"description":"Forbidden","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["permission_denied"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"422":{"description":"Unprocessable Content","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["role_address"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-features":["accounts","lead_intake"],"x-ken-permission":{"kind":"page","page":"accounts","access":"edit","summary":"Accounts edit"},"x-ken-rate-limit":{"limit":4800,"windowSeconds":60,"per":"api_key","summary":"600 requests an hour per workspace (Free plan: 60 an hour)","quotas":[{"policy":"peopleIntake","per":"workspace","limits":[{"limit":600,"windowSeconds":3600}],"plans":[{"plan":"Free","limits":[{"limit":60,"windowSeconds":3600}]}]}]}}},"/v1/people/search":{"post":{"tags":["people"],"summary":"Search people in the current workspace with filters.","description":"Body, every field optional: `q` (full name, email or title contains), `accountIds` (on any\nof these accounts, up to 100), `onAccount` (`any` default, `none` on no live account,\n`some` on at least one), `roles` (holds one of these roles on some live account),\n`hasEmail`, `addedBy` (who created the person: user, agent, api_key, system, workflow),\n`ownerMemberId`, `leadStatus` (list), `relationship` (list: to_sort, lead, customer, network,\narchived; matches the relationship each person reads, and includes people the LinkedIn connections import added\nthat nobody has worked yet, who read to_sort), `hasSuggestion`, `suggestedRelationship` (list: lead,\ncustomer, network, archived, unsure) and `suggestionKind` (list: icp_fit, customer_contact, old_teammate,\nclassmate, personal, low_icp, unsure), both on Ken's stored suggestion and including people the LinkedIn connections\nimport added, `source` (list, on the latest source), `tagIds`\n(carries any of these tags, up to 100), `sort` (`-createdAt` default, `name` A-Z with unnamed people last, `-score` highest\nfirst with unscored last, `-latestSourceAt` newest first with none last, or one sortable custom field as\n`custom.<key>` or `-custom.<key>` with people who have no value last), `filters` (a list\nof `{ \"field\", \"operator\", \"values\" }` conditions on custom fields, behind the `custom_fields` flag:\n`field` is `custom.<key>`, `operator` one of those the field's type takes (as on `CustomFieldFilterBody`), and a\nfield may have more than one condition), `limit`\n(1-1000, default 50), `cursor`, `includeTotal`. Lists OR within themselves; filters AND\ntogether. Each row embeds its live accounts (with `stakeholderId`, `role`,\n`priority`, `coverage`), `emailFind` and `tagIds`, and `lastTouch`\n(`at`, and `channel`: `email`, `linkedin`, `whatsapp`, `facebook`, `instagram` or `imessage`):\nthe latest message with the person on any of those channels, sent or received, omitted when there is none; it does\nnot sort. Unlike an account's `lastTouchAt`, it counts\nthe person's replies but no automated reply or bounce, and a logged call does not count. Deleted and merged people\nnever appear. With\naccount scope `own`, only people on the caller's accounts, each with only those accounts.\nRequires Accounts view.\n\nRate limit: 12,000 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `accounts` feature on your workspace. Until it is on, calls answer 404.","operationId":"people.search","parameters":[{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchPeopleBody"}}}},"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonListResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-features":["accounts"],"x-ken-permission":{"kind":"page","page":"accounts","access":"view","summary":"Accounts view"},"x-ken-rate-limit":{"limit":12000,"windowSeconds":60,"per":"api_key"}}},"/v1/people/{personId}/merge":{"post":{"tags":["people"],"summary":"Merge this person into another person.","description":"Body: `intoPersonId`, the person to keep. In one transaction the kept person keeps every value\nit has and takes this person's values for its blank fields; this person's account places move to it\n(on a shared account the two places combine, with touches, reports and seats re-pointed); removal\nhistory moves too; this person's active email find is cancelled. This person then reads as\n`404` `person_merged` with `mergedIntoId`. Merging into the same, a deleted or a\nmerged person is `400 validation_failed`. Returns the kept person. With `dryRun: true` nothing is\nwritten: the answer is the kept person as they are, with `mergeSummary` (`isDryRun`,\n`fieldChanges` the merge would fill, and `moved`: `accountCount`, `combinedAccountCount`,\n`opportunityCount`, `meetingCount`, `taskCount`, `noteCount`, `timelineEventCount`);\nit refuses what the merge would refuse, and where the workspace has no dry run yet it is\n`400 validation_failed` with `not_available`. A dry run never waits for a person or account another\nwrite holds: it answers `409 conflict` with `busy`, and the same call can be sent again. With account scope `own` it is `403` `permission_denied` with `scope: all`.\nRequires Accounts edit.\nA workspace key gets `403 forbidden`: the merge records the member who made it, and a workspace key is not\na person.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `accounts` feature on your workspace. Until it is on, calls answer 404.","operationId":"people.merge","parameters":[{"name":"personId","in":"path","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MergePeopleBody"}}}},"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","validation_failed","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"403":{"description":"Forbidden","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["forbidden"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"409":{"description":"Conflict","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["conflict"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-features":["accounts"],"x-ken-permission":{"kind":"page","page":"accounts","access":"edit","summary":"Accounts edit"},"x-ken-rate-limit":{"limit":4800,"windowSeconds":60,"per":"api_key"}}},"/v1/people/{personId}/photo":{"put":{"tags":["people"],"summary":"Upload or replace a person's photo.","description":"Multipart field `file`: a non-empty PNG, JPEG or WebP under 10 MB, checked by type, extension and content\n(else `400` `validation_failed`). Kenso stores it and serves it from `/media`; it shows as\n`photoUrl` with `photoSource: upload`, ahead of the person's LinkedIn photo, and replaces an earlier\nupload. A merged person is `404` `person_merged`. Returns the person. Requires Accounts edit.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `accounts` feature on your workspace. Until it is on, calls answer 404.","operationId":"people.replace-photo","parameters":[{"name":"personId","in":"path","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}}},"encoding":{"file":{"style":"form"}}}}},"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-features":["accounts"],"x-ken-permission":{"kind":"page","page":"accounts","access":"edit","summary":"Accounts edit"},"x-ken-rate-limit":{"limit":4800,"windowSeconds":60,"per":"api_key"}},"delete":{"tags":["people"],"summary":"Remove the photo uploaded for a person.","description":"The person shows their LinkedIn photo again (`photoSource: linkedin`) when Kenso has one, else no photo.\nRemoving a photo the person does not have changes nothing. A merged person is `404` `person_merged`.\nReturns the person. Requires Accounts edit.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `accounts` feature on your workspace. Until it is on, calls answer 404.","operationId":"people.delete-photo","parameters":[{"name":"personId","in":"path","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-features":["accounts"],"x-ken-permission":{"kind":"page","page":"accounts","access":"edit","summary":"Accounts edit"},"x-ken-rate-limit":{"limit":4800,"windowSeconds":60,"per":"api_key"}}}},"components":{"securitySchemes":{"Bearer":{"type":"http","description":"Enter: Bearer {your Kenso API key}. Create one in the Kenso app under Settings > Integrations > API Keys.","scheme":"bearer","bearerFormat":"Opaque API key"}},"headers":{"RateLimit-Limit":{"description":"The request limit of the rate limit this request is closest to reaching: your plan's limit for this kind of call, your API key's own limit, or the operation's own limit, whichever has the fewest requests left.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"The requests left under that limit. `0` on a `429`.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"The seconds until that limit resets.","schema":{"type":"integer"}}},"schemas":{"AccountMergeFieldChange":{"required":["field"],"type":"object","properties":{"field":{"type":"string","description":"The field's API name, such as `ownerMemberId` or `industry`."},"from":{"description":"The kept account's value before the merge. Absent when it was empty."},"to":{"description":"The value the merge sets: the merged-away account's."}},"additionalProperties":false},"Actor":{"required":["kind"],"type":"object","properties":{"kind":{"type":"string","description":"Who made the change: `user` (a member in the app), `agent` (Ken or another AI agent), `api_key`,\n`workflow` or `system` (Kenso itself)."},"memberId":{"type":"integer","description":"The id of the member behind the change. Omitted when no member is.","format":"int64","nullable":true}},"additionalProperties":false,"description":"Who created or last changed a record."},"ApiKeyError":{"required":["error"],"type":"object","properties":{"error":{"type":"string","description":"A sentence for people that says what went wrong. It can change, so do not parse it."}},"additionalProperties":false,"description":"The body the API key check in front of the operations answered until November 2026, instead of the error body (`Failure`): `{ \"error\": \"Invalid or revoked API key\" }` on a `401`, `{ \"error\": \"Rate limit exceeded\" }` on a `429` and `{ \"error\": \"Authentication is temporarily unavailable\" }` on a `503`. It has no `code`, so branch on the HTTP status."},"ConnectedVia":{"type":"object","properties":{"linkedinAccountId":{"type":"integer","description":"The id of the connected LinkedIn account in Kenso.","format":"int64"},"displayName":{"type":"string","description":"The name on that LinkedIn account. Omitted when unknown.","nullable":true},"memberId":{"type":"integer","description":"The id of the member who connected that LinkedIn account to Kenso. Omitted when Kenso did not record it.","format":"int64","nullable":true}},"additionalProperties":false,"description":"A teammate's LinkedIn account that has a person as a connection."},"CreatePersonBody":{"type":"object","properties":{"fullName":{"type":"string","nullable":true},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"linkedinUrl":{"type":"string","description":"A profile, such as https://linkedin.com/in/jane-doe.","nullable":true},"kenPersonId":{"type":"integer","description":"The person's Ken id: their id in Ken Search. Null clears it.","format":"int64","nullable":true},"ownerMemberId":{"type":"integer","description":"A member of this workspace who owns the person, or null to clear.","format":"int64","nullable":true},"leadStatus":{"type":"string","description":"new, working, qualified, disqualified or nurture. Null clears it: not a lead.","nullable":true},"phones":{"type":"array","items":{"$ref":"#/components/schemas/PersonPhoneBody"},"description":"Replaces the person's phones, up to 20, in order: the first is the person's phone. A number the person already\nhas keeps when and how it was added. Null or an empty list clears them. A number marked invalid (a wrong number)\nstays even when left out, after the numbers sent, so it is never added back. To add or remove one number, send\nthe whole list with that number added or left out.","nullable":true}},"additionalProperties":false,"description":"people.create: a person on no account. fullName is required.","example":{"fullName":"Amanda Chen","title":"VP of Engineering","email":"amanda.chen@northwind.example.com","ownerMemberId":1093,"leadStatus":"new","phones":[{"number":"+15125550142","kind":"mobile"}]}},"CustomFieldFilterBody":{"type":"object","properties":{"field":{"type":"string","description":"The field, as custom.<key>, with the key a record's customFields uses.","nullable":true},"operator":{"type":"string","description":"An operator the field's type takes, by type: text is, is_not, contains; number is, is_not, lt, gte; boolean is;\ndate lt, gte, within_days, older_than_days; select, multi_select and user is, is_not; currency lt, gte; url\ncontains. Every type but boolean also takes is_empty and is_not_empty, the only two a json field takes.","nullable":true},"values":{"type":"array","items":{"type":"string"},"description":"1 to 50 values of the field's type, OR. Required, except for is_empty and is_not_empty, which take none.","nullable":true}},"additionalProperties":false,"description":"One condition on a custom field: the field, an operator and values."},"CustomFieldMeta":{"required":["source"],"type":"object","properties":{"source":{"type":"string","description":"`user` (a member, in the app), `crm` (your CRM), `agent` (Ken or another agent), `api_key`,\n`workflow` or `system`. A `user` or `crm` value is pinned: the field is listed in\n`pinnedFields` as `custom.<key>`."},"at":{"type":"string","description":"When the value was set.","format":"date-time"},"memberId":{"type":"integer","description":"The member who set it, or who the agent or key acted for. Absent when no member did.","format":"int64","nullable":true}},"additionalProperties":false,"description":"Who or what last set a custom field's value on a record, and when."},"ErrorAccount":{"type":"object","properties":{"accountId":{"type":"integer","description":"The account's id.","format":"int64"},"name":{"type":"string","description":"The account's name."},"stakeholderId":{"type":"integer","description":"The person's stakeholder id on this account.","format":"int64"}},"additionalProperties":false,"description":"An account named in an error detail."},"ErrorBody":{"type":"object","properties":{"code":{"type":"string","description":"Stable error code, such as `validation_failed` or `not_found`. Branch on this value."},"message":{"type":"string","description":"A sentence for people that explains the error. It can change, so do not parse it."},"details":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"},"description":"One entry per problem, naming the field or limit it is about. Omitted when there are none.","nullable":true},"requestId":{"type":"string","description":"The id of this request: the same value as the `X-Correlation-Id` response header. Quote it when you write\nto contact@ken.so."},"docUrl":{"type":"string","description":"The page on this code in the developer docs, which says what it means and how to fix it. The errors guide for a\ncode that has no page of its own.","readOnly":true},"refusal":{"allOf":[{"$ref":"#/components/schemas/Refusal"}],"description":"On a `402`, the plan rule or usage limit that refused the request and how to lift it. Omitted otherwise."},"impact":{"allOf":[{"$ref":"#/components/schemas/InvalidationImpact"}],"description":"On a `409` that refuses a change because it would clear stored AI output (a prompt edit, a restore or a\nreset), how much the change would clear. Omitted otherwise."},"surface":{"type":"string","description":"Set only by the voice ticket's `409` (code `voice_conversation_active`): the chat the person's other\nvoice conversation runs in, `support`, `ken` or `onboarding`. Omitted on every other error.","nullable":true}},"additionalProperties":false,"description":"What went wrong in a request."},"ErrorDetail":{"type":"object","properties":{"field":{"type":"string","description":"The request field, header or limit the problem is about, such as `name` or `Ken-Version`."},"code":{"type":"string","description":"Stable code for this problem, such as `required` or `invalid`."},"message":{"type":"string","description":"A sentence for people that explains this problem."},"count":{"type":"integer","description":"On `export_limit_exceeded`, how many rows match the export. Omitted otherwise.","format":"int32","nullable":true},"index":{"type":"integer","description":"The position of the refused item in the request's list. Omitted otherwise.","format":"int32","nullable":true},"limit":{"type":"integer","description":"On `export_limit_exceeded`, the row limit the export ran with. On a `quota_exceeded` detail whose\n`field` names a quota, that quota's limit. On a `rate_limited` detail from your workspace's rate\nlimits, the limit that was hit. Omitted otherwise.","format":"int32","nullable":true},"resetAt":{"type":"string","description":"On some `quota_exceeded` details, when the quota frees up, in UTC. It is the same instant as the top-level\n`quotaResetAt`. On a `rate_limited` detail from your workspace's rate limits, when that limit resets.\nOmitted otherwise.","format":"date-time","nullable":true},"retryAfterSeconds":{"type":"integer","description":"On those `quota_exceeded` details and on most `rate_limited` details, the seconds to wait. It is the\nsame value as the `Retry-After` header. Omitted otherwise.","format":"int32","nullable":true},"inboxId":{"type":"integer","description":"The inbox the problem is about. Omitted otherwise.","format":"int64","nullable":true},"domainId":{"type":"integer","description":"The domain the problem is about. Omitted otherwise.","format":"int64","nullable":true},"domainName":{"type":"string","description":"The name of that domain, or the domain name the request gave. Omitted otherwise.","nullable":true},"accountId":{"type":"integer","description":"On `domain_taken`, `already_stakeholder` and `previously_removed`, the existing account to use\ninstead. Omitted otherwise.","format":"int64","nullable":true},"personId":{"type":"integer","description":"On `email_taken` and `linkedin_url_taken`, the existing person to use instead. Omitted otherwise.","format":"int64","nullable":true},"stakeholderId":{"type":"integer","description":"The account stakeholder the problem is about. Omitted otherwise.","format":"int64","nullable":true},"championId":{"type":"integer","description":"Not used. Always omitted.","format":"int64","nullable":true},"callTaskId":{"type":"integer","description":"On `call_task_exists`, the open call task that already holds the person's slot. Omitted otherwise.","format":"int64","nullable":true},"status":{"type":"string","description":"On `invalid_transition`, the current status. Omitted otherwise.","nullable":true},"allowed":{"type":"array","items":{"type":"string"},"description":"On `out_of_range`, the allowed values. On `invalid_transition`, the statuses the change is allowed\nfrom. Omitted otherwise.","nullable":true},"scope":{"type":"string","description":"On a `permission_denied` for an account owner change, the account scope the call needs (`all`). On\n`sending_paused`, what the pause covers: `inbox`, `domain` or `workspace`. Omitted otherwise.","nullable":true},"removedAt":{"type":"string","description":"On `previously_removed`, when a person removed the stakeholder, in UTC. Omitted otherwise.","format":"date-time","nullable":true},"page":{"type":"string","description":"On `permission_denied`, the page the call needs, such as `campaigns`. Omitted otherwise.","nullable":true},"required":{"type":"string","description":"On `permission_denied`, the access `page` needs: `view` or `edit`. Omitted otherwise.","nullable":true},"feature":{"type":"string","description":"On `permission_denied`, the permission the call needs, such as `launch`. Omitted otherwise.","nullable":true},"runId":{"type":"integer","description":"On `committee_run_active` and `run_not_finding`, the committee run the problem is about. Omitted\notherwise.","format":"int64","nullable":true},"mergedIntoId":{"type":"integer","description":"On `person_merged`, the person the merged person now lives on. On `account_merged`, the account the\nmerged account now lives on. Omitted otherwise.","format":"int64","nullable":true},"accounts":{"type":"array","items":{"$ref":"#/components/schemas/ErrorAccount"},"description":"On `person_on_accounts`, the accounts that block the change. Omitted otherwise.","nullable":true},"stage":{"type":"string","description":"On `stage_in_use` and `system_stage`, the opportunity stage key the problem is about. Omitted otherwise.","nullable":true},"opportunityCount":{"type":"integer","description":"On `stage_in_use`, how many opportunities are in that stage. Omitted otherwise.","format":"int32","nullable":true},"rule":{"type":"string","description":"On `guardrail_violation`, the contact limit rule the change breaks. Omitted otherwise.","nullable":true},"nextAllowedAt":{"type":"string","description":"On `guardrail_violation`, the first `dueAt` that passes every contact limit, in UTC. On a refused\nsend, when to retry. Omitted otherwise, and when waiting does not clear it.","format":"date-time","nullable":true},"fix":{"type":"string","description":"On a refused send, what to do next, in plain words. Omitted otherwise.","nullable":true},"opensAt":{"type":"string","description":"On `outside_calling_hours`, when the person's calling window opens, in UTC. Omitted otherwise.","format":"date-time","nullable":true},"currentVersion":{"type":"integer","description":"On a knowledge file's `version_conflict`, the file's current version. Omitted otherwise.","format":"int32","nullable":true},"provider":{"type":"string","description":"On a CRM connection error (`provider_error`, `exchange_failed`, `already_connected`,\n`account_mismatch` or `provider_unavailable`), the CRM it is about. Omitted otherwise.","nullable":true},"sharedWithMaster":{"type":"boolean","description":"True on a `quota_exceeded` detail when the shared limit of the white-label master workspace was hit, so\n`limit` is the limit of the whole white-label account. Omitted otherwise. The master's id is never sent.","nullable":true},"stepId":{"type":"integer","description":"On `link_reputation_blocked`, the saved sequence step that holds the blocked link. Omitted otherwise, and\nfor a step the save would have created.","format":"int64","nullable":true},"stepOrder":{"type":"integer","description":"On `link_reputation_blocked`, the `stepOrder` of that step. Omitted otherwise.","format":"int32","nullable":true},"url":{"type":"string","description":"On `link_reputation_blocked`, the blocked link as the step's copy writes it. Omitted otherwise.","nullable":true},"key":{"type":"string","description":"On `unfilled_template_key`, the template key the text still holds, such as `first_name` for\n`{first_name}`. Omitted otherwise.","nullable":true},"marker":{"type":"string","description":"On `unfilled_template_key`, that key as the text writes it, such as `{first_name}` or `[company]`.\nOmitted otherwise.","nullable":true},"retryAt":{"type":"string","description":"On a warm path Start's `guardrail_connector_monthly`, `guardrail_account_monthly`,\n`guardrail_connector_cooldown` and `guardrail_handoff_weekly`, when the limit frees up, in UTC. Omitted\notherwise.","format":"date-time","nullable":true},"workspaceId":{"type":"integer","description":"On `last_admin`, a workspace that needs a new admin before the account can be deleted. On\n`new_admin_not_found`, the workspace of the refused choice. Omitted otherwise.","format":"int64","nullable":true},"workspaceName":{"type":"string","description":"On `last_admin`, the name of that workspace. Omitted otherwise.","nullable":true},"class":{"type":"string","description":"On a `rate_limited` detail from your workspace's rate limits, the class of call that hit its limit:\n`read`, `write`, `bulk`, `heavy` or `sensitive`. Omitted otherwise.","nullable":true},"window":{"type":"string","description":"On that detail, the window whose limit was hit: `minute`, `day` or `bulkItemsDay`. Omitted\notherwise.","nullable":true}},"additionalProperties":false,"description":"One problem in an error: the field or limit it is about, a stable `code` and a `message`. The other fields\nappear only with the codes their descriptions name."},"Failure":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false on an error."},"error":{"allOf":[{"$ref":"#/components/schemas/ErrorBody"}],"description":"What went wrong."},"quotaResetAt":{"type":"string","description":"When the quota that refused the request frees up, in UTC. Set on some quota refusals. Omitted otherwise.","format":"date-time","nullable":true},"currentVersion":{"type":"integer","description":"The current revision of a workflow draft, on a draft save's `409 version_conflict`. Read the workflow\nagain, then send this value as `baseVersion`. Omitted otherwise.","format":"int32","nullable":true},"current":{"allOf":[{"$ref":"#/components/schemas/MeetingRepNotesCurrent"}],"description":"Your meeting notes and their version as stored now, on a meeting notes save's `409 version_conflict`.\nMerge your change, then save again with `baseVersion` set to `current.repNotesVersion`. Omitted\notherwise."},"refusal":{"allOf":[{"$ref":"#/components/schemas/Refusal"}],"description":"A copy of `error.refusal`, set on some billing refusals. Omitted otherwise."},"message":{"type":"string","description":"A copy of `error.message`, set together with `refusal`. Omitted otherwise.","nullable":true},"lookalikeSeeds":{"description":"How Kenso read each seed of a lookalike search, on its `422 no_usable_seeds`:\n`{resolved: [{input, companyId, personId, name, domain}], unresolved: [{input, reason}]}`. Use it to show\nwhy no seed was usable. Omitted otherwise."}},"additionalProperties":false,"description":"The body of every error, with a 4xx or 5xx status. Branch on `error.code`."},"IntakePersonBody":{"type":"object","properties":{"email":{"type":"string","description":"The person's email. Kenso trims it, lower-cases it and matches on it first. A shared mailbox such as support@ or\ninfo@ never becomes the person's email.","nullable":true},"linkedinUrl":{"type":"string","description":"The person's public LinkedIn profile, such as https://linkedin.com/in/jane-doe. Kenso matches on it after the\nemail. A member id URL (linkedin.com/in/ACwAA...) is not a public profile, so Kenso takes the person in without it.","nullable":true},"fullName":{"type":"string","description":"The person's full name, up to 300 characters. Omitted: Kenso joins `firstName` and `lastName`.","nullable":true},"firstName":{"type":"string","description":"The person's first name, up to 300 characters.","nullable":true},"lastName":{"type":"string","description":"The person's last name, up to 300 characters.","nullable":true},"title":{"type":"string","description":"The person's job title, up to 2,000 characters. Kenso sets it only on a person who has no title.","nullable":true},"companyName":{"type":"string","description":"The company name, up to 300 characters. Kenso uses it to name a new account when Kenso Search has no name for the\ncompany's domain.","nullable":true},"companyDomain":{"type":"string","description":"The company's domain or website, such as acme.com. Kenso uses it when the email is missing or on a free email\nprovider such as gmail.com, and ignores a free email provider's domain sent here.","nullable":true},"phone":{"type":"string","description":"A phone number with 8 to 15 digits and the country code, such as +15551234567. Kenso adds it to the person's\nphone numbers. A number without a country code is read in the country of the person or their account when Kenso\nknows it.","nullable":true},"source":{"type":"string","description":"Where the person comes from: `api`, `workflow` or `manual`. Omitted means `api`. Kenso records\nit as the person's latest source, and as their first source when it creates them.","nullable":true},"sourceDetail":{"type":"string","description":"Where in that source the person came from, such as a form or list name. Kenso keeps the first 300 characters.","nullable":true},"ownerMemberId":{"type":"integer","description":"The member to own the person when the person, their account and your CRM name no owner. Must be a member of the\nworkspace.","format":"int64","nullable":true},"leadStatus":{"type":"string","description":"The lead status: `new`, `working`, `qualified`, `disqualified` or `nurture`. Omitted means\n`new`. Kenso sets it only on a person who has no lead status.","nullable":true},"customFields":{"type":"object","additionalProperties":{},"description":"Values for the workspace's person custom fields, by field key. Kenso ignores keys with no person custom field and\nfills only fields that are blank on the person. Where custom fields are on, a value is read as its field's type,\nand text is read as a CSV cell would be: `yes` or `no` for a\nboolean, an option's key or label for a select, options split by `;` for a multi_select, `1200.50 USD`\nfor a currency. A value that is not its field's type is left out and named in the response's\n`customFieldErrors`; the person is still taken in.","nullable":true},"createAccount":{"type":"boolean","description":"False: Kenso creates no account for a company domain that has none. True or omitted: Kenso creates one when the\nworkspace's intake settings allow it.","nullable":true},"useKenEmail":{"type":"boolean","description":"True with no `email`: Kenso takes the person's work email from its own email database when it holds a recently\nverified one, at no charge. Kenso looks them up by `linkedinUrl`, else by name with `companyName` or\n`companyDomain`, and only on the company's domain. With no match, or when the workspace used its daily\nallowance of these lookups, Kenso takes the person in without an email. Needs the `extension` feature on the\nworkspace; without it the field does nothing.","nullable":true}},"additionalProperties":false,"description":"One person to take in from your own source."},"InvalidationImpact":{"type":"object","properties":{"qualificationResponses":{"type":"integer","description":"Stored qualification answers the change would clear.","format":"int32"},"qualifiedFlags":{"type":"integer","description":"Contacts whose qualified result the change would clear.","format":"int32"},"segmentationReasoning":{"type":"integer","description":"Stored segmentation explanations the change would clear.","format":"int32"},"segmentationAssignmentsKept":{"type":"integer","description":"Contacts that keep their segment.","format":"int32"},"segmentationAssignmentsReset":{"type":"integer","description":"Contacts that go back to the default segment.","format":"int32"},"personalizationLines":{"type":"integer","description":"Personalized lines the change would clear.","format":"int32"},"personalizationLeads":{"type":"integer","description":"Contacts that would lose their personalized lines.","format":"int32"},"rewritingLines":{"type":"integer","description":"Rewritten lines the change would clear.","format":"int32"},"rewritingLeads":{"type":"integer","description":"Contacts that would lose their rewritten lines.","format":"int32"}},"additionalProperties":false,"description":"How much stored AI output a change would clear in each AI step of a campaign, and how many segment assignments it\nkeeps or resets."},"MeetingRepNotesCurrent":{"type":"object","properties":{"repNotes":{"type":"string","description":"Your notes as stored now. Empty before your first save."},"repNotesVersion":{"type":"integer","description":"The stored notes' version. Send it as `baseVersion` when you save again.","format":"int32"}},"additionalProperties":false,"description":"Your meeting notes as Kenso stores them now, sent with a `409 version_conflict` on a notes save."},"MergePeopleBody":{"type":"object","properties":{"intoPersonId":{"type":"integer","description":"The person to keep.","format":"int64","nullable":true},"dryRun":{"type":"boolean","description":"True to write nothing and answer with what the merge would fill and move (`mergeSummary`). The person in\nthe answer is the kept person as they are before the merge.","nullable":true}},"additionalProperties":false,"example":{"intoPersonId":77310}},"Pagination":{"type":"object","properties":{"nextCursor":{"type":"string","description":"Send this value as `cursor` to get the next page. Omitted on the last page.","nullable":true},"hasMore":{"type":"boolean","description":"True when more items follow this page. Stop paging when it is false."},"total":{"type":"integer","description":"Deprecated: the same number as `totalCount`. Read `totalCount`.","format":"int32","nullable":true,"deprecated":true},"totalCount":{"type":"integer","description":"The number of items that match the list's filters, across all pages. Omitted when the list does not count them.","format":"int32","nullable":true},"isTotalCapped":{"type":"boolean","description":"True when `totalCount` stopped counting at its cap, so more items match than it says. Keep paging with\n`hasMore`. Omitted when `totalCount` is exact. Only `GET /v1/threads` with `q` caps its total.","nullable":true}},"additionalProperties":false,"description":"Where a list page ends and how to get the next page."},"Person":{"required":["createdBy","pinnedFields","relationship","updatedBy"],"type":"object","properties":{"id":{"type":"integer","description":"The person's id.","format":"int64"},"mergeSummary":{"allOf":[{"$ref":"#/components/schemas/PersonMergeSummary"}],"description":"Only on the answer of a people.merge sent with `dryRun`: what the merge would fill and move."},"fullName":{"type":"string","description":"The person's full name. Omitted when unknown.","nullable":true},"firstName":{"type":"string","description":"The person's first name. Omitted when unknown.","nullable":true},"lastName":{"type":"string","description":"The person's last name. Omitted when unknown.","nullable":true},"title":{"type":"string","description":"The person's job title. Omitted when unknown.","nullable":true},"email":{"type":"string","description":"The person's email, in lower case. Omitted when Kenso has none.","nullable":true},"linkedinUrl":{"type":"string","description":"The person's LinkedIn profile, as https://linkedin.com/in/{slug}. Omitted when Kenso has none.","nullable":true},"kenPersonId":{"type":"integer","description":"The person's id in Kenso Search. Omitted when Kenso has not matched them there.","format":"int64","nullable":true},"ownerMemberId":{"type":"integer","description":"The id of the member who owns the person. Omitted when nobody owns them.","format":"int64","nullable":true},"leadStatus":{"type":"string","description":"The person's lead status: `new`, `working`, `qualified`, `disqualified` or `nurture`.\nOmitted when the person is not a lead.","nullable":true},"leadStatusAt":{"type":"string","description":"When the lead status last changed, in UTC. Omitted when the person has no lead status.","format":"date-time","nullable":true},"relationship":{"type":"string","description":"Who the person is to you: `to_sort`, `lead`, `customer`, `network` or `archived`. Until\nsomeone sets it, Kenso derives it: `to_sort` for a person the LinkedIn connections import added that nobody has\nworked yet, `customer` for a person on an account in onboarding, client or churned (or marked a customer), else\n`lead`. Set it with `people.update`."},"relationshipSet":{"type":"boolean","description":"True when someone set the relationship; false while Kenso derives it."},"engagement":{"type":"string","description":"How far outreach to the person has gone, derived by Kenso and read-only: `not_contacted`, `contacted`,\n`replied`, `meeting`, `bounced` or `unsubscribed`, the first that holds in the order\nunsubscribed, meeting, replied, bounced, contacted. On `people.get`, `people.list`, `people.search`\nand the `people.update` answer; omitted elsewhere.","nullable":true},"lastTouch":{"allOf":[{"$ref":"#/components/schemas/PersonLastTouch"}],"description":"The latest email, LinkedIn, WhatsApp, Facebook, Instagram or iMessage message with the person, sent or received (an automated\nreply or a bounce is not one). Unlike an account's `lastTouchAt`, it counts the person's replies, and a logged call does not count.\nRead-only. Only on `people.search` rows, and omitted there when there is none."},"suggestion":{"allOf":[{"$ref":"#/components/schemas/PersonSuggestion"}],"description":"Ken's suggestion for the person's relationship, until someone sets the relationship. Omitted when there is none."},"score":{"type":"integer","description":"How well the person fits, from 0 to 100. Kenso adds points for the seniority of their title, a business email\ndomain, their account's tier and the source they came from. Read-only. Omitted until Kenso scores the person.","format":"int32","nullable":true},"phones":{"type":"array","items":{"$ref":"#/components/schemas/PersonPhone"},"description":"Every phone number the person has, in stored order. An entry with `invalidAt` is a known wrong number."},"phone":{"type":"string","description":"The first number in `phones` without `invalidAt`. Omitted when there is none.","nullable":true},"phoneOptOutAt":{"type":"string","description":"When the person asked not to be called, in UTC. Kenso does not call a person who opted out. Omitted when they have\nnot asked.","format":"date-time","nullable":true},"whatsappOptOutAt":{"type":"string","description":"When the person asked not to get WhatsApp messages; Kenso never sends them one. Only on the people get, list and\nsearch reads with the whatsapp feature on; omitted otherwise and when they have not.","format":"date-time","nullable":true},"firstSource":{"allOf":[{"$ref":"#/components/schemas/PersonSource"}],"description":"Where the person first came from. Read-only. Omitted when Kenso has no record of it."},"latestSource":{"allOf":[{"$ref":"#/components/schemas/PersonSource"}],"description":"Where the person most recently came from, such as the latest intake that matched them. Read-only. Omitted when\nKenso has no record of it."},"headline":{"type":"string","description":"The person's LinkedIn headline. Omitted when unknown.","nullable":true},"location":{"type":"string","description":"Where the person is based, such as a city and country. Omitted when unknown.","nullable":true},"seniority":{"type":"string","description":"The person's seniority from Kenso's LinkedIn data, such as Director or VP. Omitted when unknown.","nullable":true},"department":{"type":"string","description":"The person's function from Kenso's LinkedIn data, such as Sales or Engineering. Omitted when unknown.","nullable":true},"photoUrl":{"type":"string","description":"The URL of the person's photo: an uploaded photo, else their LinkedIn photo. Kenso stores and serves the file\nitself, so this is never a LinkedIn URL. Omitted when there is no photo.","nullable":true},"photoSource":{"type":"string","description":"Where the photo came from: `upload` for an uploaded photo, `linkedin` for their LinkedIn photo. Omitted\nwhen there is no photo.","nullable":true},"profileSource":{"type":"string","description":"Where Kenso's LinkedIn data for the person came from: `ken_search` (Kenso Search) or `contact` (a campaign\ncontact linked to the person). Omitted until Kenso has filled some of it.","nullable":true},"profileEnrichedAt":{"type":"string","description":"When Kenso last checked its LinkedIn data for the person, in UTC. Omitted until Kenso has filled some of it.","format":"date-time","nullable":true},"profile":{"allOf":[{"$ref":"#/components/schemas/PersonProfile"}],"description":"The rest of the person's LinkedIn profile that Kenso holds. Only a read of one person includes it, so lists and the\nintake response leave it out. Omitted until Kenso fills it."},"customFields":{"type":"object","additionalProperties":{},"description":"The record's custom field values by key (the fields the workspace defined): a string, number or boolean, a list of\noption keys for a multi_select field, `{amount, currency}` for a currency field. A select field holds its\noption's key. Empty when none is set."},"customFieldMeta":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/CustomFieldMeta"},"description":"Who or what last set each custom field, by key. Absent when no value has a record of it.","nullable":true},"pinnedFields":{"type":"array","items":{"type":"string"},"description":"The fields a member or your CRM set, by their names in this object, such as `title` or `email`. Kenso's\nautomatic updates, intake included, leave these fields as they are. Empty when there are none."},"createdBy":{"allOf":[{"$ref":"#/components/schemas/Actor"}],"description":"Who created the person."},"updatedBy":{"allOf":[{"$ref":"#/components/schemas/Actor"}],"description":"Who last changed the person."},"createdAt":{"type":"string","description":"When the person was created, in UTC.","format":"date-time"},"updatedAt":{"type":"string","description":"When the person last changed, in UTC.","format":"date-time"},"emailFind":{"allOf":[{"$ref":"#/components/schemas/PersonEmailFindSummary"}],"description":"The newest search for the person's email. Omitted when nobody asked Kenso to find it. The intake response leaves\nit out."},"phoneFind":{"allOf":[{"$ref":"#/components/schemas/PersonPhoneFindSummary"}],"description":"The newest search for the person's phone number. Omitted when nobody asked Kenso to find it. The intake response\nleaves it out."},"accounts":{"type":"array","items":{"$ref":"#/components/schemas/PersonAccount"},"description":"The live accounts the person is on, highest priority first. Empty when they are on none. A caller who works only\ntheir own accounts sees only those. Some list responses leave it out.","nullable":true},"tagIds":{"type":"array","items":{"type":"integer","format":"int64"},"description":"The ids of the tags the person carries, in ascending order. A champion carries the workspace's Champion tag. The\nintake response leaves it out.","nullable":true},"connectedVia":{"type":"array","items":{"$ref":"#/components/schemas/ConnectedVia"},"description":"The teammates' LinkedIn accounts that have the person as a connection. Omitted when none does. The intake\nresponse leaves it out.","nullable":true},"connectionIcpScore":{"type":"integer","description":"How well the person fits your ideal customer profile, from 0 to 100, as Kenso scored them as a teammate's\nLinkedIn connection. 70 or more is a fit. When several teammates know them, this is the highest score. Omitted\nwhen no connection is scored. The intake response leaves it out.","format":"int32","nullable":true},"importOnlyAt":{"type":"string","description":"When Kenso added the person from a teammate's LinkedIn connections, in UTC. Until someone works the person, they\nstay out of the main people list and Ken runs nothing on them. Omitted once someone works them, and for people\nfrom any other source.","format":"date-time","nullable":true},"emailDropped":{"type":"string","description":"Set only on the person a create call returns: `role_address` when the email sent was a shared mailbox, such as\nsupport@ or info@, so Kenso created the person without it. Omitted otherwise.","nullable":true},"facebook":{"allOf":[{"$ref":"#/components/schemas/PersonFacebook"}],"description":"The person's Facebook profile, on people.get with the facebook_outreach feature: the confirmed one, else a\nweak match waiting on \"Is this them?\". Omitted otherwise."}},"additionalProperties":false,"description":"A person in the workspace: one real human, the same record across campaigns and accounts.","example":{"id":77310,"fullName":"Amanda Chen","firstName":"Amanda","lastName":"Chen","title":"VP of Engineering","email":"amanda.chen@northwind.example.com","kenPersonId":51800231,"ownerMemberId":1093,"leadStatus":"working","leadStatusAt":"2026-10-13T16:22:05Z","relationship":"lead","relationshipSet":true,"engagement":"replied","score":78,"phones":[{"number":"+15125550142","kind":"mobile","source":"api","addedAt":"2026-09-23T15:02:11Z"}],"phone":"+15125550142","firstSource":{"source":"api","at":"2026-09-23T15:02:11Z"},"latestSource":{"source":"form","detail":"Demo request","at":"2026-10-13T16:22:05Z"},"headline":"VP of Engineering at Northwind Labs","location":"Austin, Texas, United States","seniority":"VP","department":"Engineering","pinnedFields":["title"],"customFields":{"buying_role":"evaluator"},"createdBy":{"kind":"user","memberId":1093},"updatedBy":{"kind":"user","memberId":1093},"createdAt":"2026-09-23T15:02:11Z","updatedAt":"2026-10-14T09:41:27Z","accounts":[{"accountId":6120,"stakeholderId":2410,"name":"Northwind Labs","primaryDomain":"northwind.example.com","role":"champion","priority":1,"coverage":"engaged"}],"tagIds":[341]}},"PersonAccount":{"required":["name","role"],"type":"object","properties":{"accountId":{"type":"integer","description":"The account's id.","format":"int64"},"stakeholderId":{"type":"integer","description":"The id of the person's stakeholder record on this account.","format":"int64"},"name":{"type":"string","description":"The account's name."},"primaryDomain":{"type":"string","description":"The account's primary domain, such as acme.com. Omitted when it has none.","nullable":true},"logoUrl":{"type":"string","description":"The URL of the account's logo. Omitted when Kenso has none.","nullable":true},"role":{"type":"string","description":"The person's role in the account's buying committee: `champion`, `economic_buyer`, `approver`,\n`evaluator`, `user`, `executive_sponsor`, `blocker` or `unknown`."},"priority":{"type":"integer","description":"The person's priority on this account, from 1 (highest) to 3. Omitted when not set.","format":"int32","nullable":true},"coverage":{"type":"string","description":"How outreach covers the person on this account: `engaged`, `planned`, `gap` or\n`not_targeted`.","nullable":true}},"additionalProperties":false,"description":"An account a person is on, with the person's place there."},"PersonEmailFindSummary":{"required":["status"],"type":"object","properties":{"id":{"type":"integer","description":"The email find's id.","format":"int64"},"status":{"type":"string","description":"Where the find stands: `queued`, `running`, `paused` (waiting for credits), `found`,\n`not_found` or `failed`."},"completedAt":{"type":"string","description":"When the find finished, in UTC. Omitted while it is not finished.","format":"date-time","nullable":true},"fromKenPool":{"type":"boolean","description":"True when Kenso's own email database found the email at no charge. Omitted otherwise.","nullable":true}},"additionalProperties":false,"description":"The newest search for a person's email."},"PersonFacebook":{"required":["source","status","url"],"type":"object","properties":{"url":{"type":"string"},"source":{"type":"string"},"confidence":{"type":"string","nullable":true},"status":{"type":"string"}},"additionalProperties":false,"description":"The person's Facebook profile on people.get. Status confirmed: the profile Kenso uses. Status candidate: a\nweak match waiting on \"Is this them?\". source is found_by_kenso for a profile Kenso found, else user, known or import."},"PersonIntake":{"required":["matchedBy","person"],"type":"object","properties":{"person":{"allOf":[{"$ref":"#/components/schemas/Person"}],"description":"The person after the intake, with the accounts they are on."},"created":{"type":"boolean","description":"True when this call created the person. False when it matched an existing person."},"matchedBy":{"type":"string","description":"How Kenso found the existing person: `email`, `linkedin_url` or `name_domain` (the same name on the\ncompany's account). `none` when this call created the person."},"accountId":{"type":"integer","description":"The account that holds the person's company domain. Omitted when there is no business domain, or when no account\nholds it and Kenso created none.","format":"int64","nullable":true},"accountCreated":{"type":"boolean","description":"True when this call created that account."},"suggestedDuplicateOfPersonId":{"type":"integer","description":"Set when this call created a person while another person with the same name and an email on the same domain\nexists. The two may be the same human. Omitted otherwise.","format":"int64","nullable":true},"emailDropped":{"type":"string","description":"Set to `role_address` when `email` was a shared mailbox, such as support@ or info@, that the person does\nnot hold, so Kenso took them in without it. Omitted otherwise.","nullable":true},"customFieldErrors":{"type":"array","items":{"$ref":"#/components/schemas/PersonIntakeFieldError"},"description":"The `customFields` values Kenso left out because they are not their field's type. Omitted when every value\nwas taken, and where custom fields are off in the workspace. One entry with code `not_saved` means none was written: send them again.","nullable":true}},"additionalProperties":false,"description":"The result of a person intake."},"PersonIntakeFieldError":{"required":["code","field","message"],"type":"object","properties":{"field":{"type":"string","description":"The value's place in the request: `customFields.tier`."},"code":{"type":"string","description":"`invalid`: not the field's type. `invalid_member`: a user field's id is not a workspace member."},"message":{"type":"string","description":"What the field takes, in plain words."}},"additionalProperties":false,"description":"A custom field value a person intake left out."},"PersonIntakeResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/PersonIntake"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"PersonLastTouch":{"required":["channel"],"type":"object","properties":{"at":{"type":"string","description":"When the message was sent or received, in UTC.","format":"date-time"},"channel":{"type":"string","description":"Where it happened: `email`, `linkedin`, `whatsapp`, `facebook`, `instagram` or\n`imessage`. Read an unknown value as a channel added later."}},"additionalProperties":false,"description":"A person's latest email, LinkedIn, WhatsApp, Facebook, Instagram or iMessage message, sent or received."},"PersonListResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"type":"array","items":{"$ref":"#/components/schemas/Person"},"description":"The items on this page."},"pagination":{"allOf":[{"$ref":"#/components/schemas/Pagination"}],"description":"Where this page ends and how to get the next one."}},"additionalProperties":false,"description":"The body of a successful list operation: one page of results in `data`, and `pagination` to get the next\npage."},"PersonMergeMoved":{"type":"object","properties":{"accountCount":{"type":"integer","description":"Accounts the kept person joins.","format":"int32"},"combinedAccountCount":{"type":"integer","description":"Accounts both people are on, where the two places become one.","format":"int32"},"opportunityCount":{"type":"integer","description":"Deals the merged person is on.","format":"int32"},"meetingCount":{"type":"integer","format":"int32"},"taskCount":{"type":"integer","format":"int32"},"noteCount":{"type":"integer","format":"int32"},"timelineEventCount":{"type":"integer","description":"Captured email threads and meetings on the merged person's timeline.","format":"int32"}},"additionalProperties":false,"description":"How many of the merged person's records of each kind move to the kept person."},"PersonMergeSummary":{"required":["fieldChanges","moved"],"type":"object","properties":{"isDryRun":{"type":"boolean","description":"True: the call was a dry run, and nothing was written."},"fieldChanges":{"type":"array","items":{"$ref":"#/components/schemas/AccountMergeFieldChange"},"description":"The kept person's blank fields the merge fills, each with the value before and the value after."},"moved":{"allOf":[{"$ref":"#/components/schemas/PersonMergeMoved"}],"description":"How many of the merged person's records of each kind move to the kept person."}},"additionalProperties":false,"description":"What a people.merge dry run would do: nothing was written. Only on the answer of a merge sent with\n`dryRun`."},"PersonPhone":{"required":["kind","number","source"],"type":"object","properties":{"number":{"type":"string","description":"The number as a plus sign and 8 to 15 digits, starting with the country code, such as +15551234567."},"kind":{"type":"string","description":"The kind of number: `mobile`, `work` or `other`."},"source":{"type":"string","description":"Who added the number: a person source such as `manual`, `api`, `crm` or `form`, or the name\nof the service that found it."},"addedAt":{"type":"string","description":"When the number was added, in UTC.","format":"date-time"},"invalidAt":{"type":"string","description":"When the number was marked as a wrong number, in UTC. Omitted for a number not known to be wrong.","format":"date-time","nullable":true},"whatsapp":{"type":"string","description":"on, off or unknown: whether this number is on WhatsApp, from a check in the last 30 days. Only on the people get,\nlist and search reads with the whatsapp feature on; omitted otherwise.","nullable":true},"whatsappCheckedAt":{"type":"string","description":"When that check ran. Omitted when whatsapp is unknown or omitted.","format":"date-time","nullable":true},"whatsappOptOutAt":{"type":"string","description":"When WhatsApp to this number stopped: the person's stop or the number's, whichever came first. Kenso never sends\nWhatsApp to it. Omitted when neither is set or whatsapp is omitted. phoneOptOutAt blocks WhatsApp too.","format":"date-time","nullable":true}},"additionalProperties":false,"description":"One of a person's phone numbers."},"PersonPhoneBody":{"required":["number"],"type":"object","properties":{"number":{"type":"string","description":"8 to 15 digits with the country code, such as +15551234567 (a leading 00 reads as +). A number without one is\nread in the person's country when Ken knows it. Spaces, dashes, brackets and an extension are dropped.\nRequired."},"kind":{"type":"string","description":"mobile, work or other. Absent keeps the kind of a number the person already has, else other.","nullable":true}},"additionalProperties":false,"description":"One phone of a person write."},"PersonPhoneFindSummary":{"required":["status"],"type":"object","properties":{"status":{"type":"string","description":"Where the find stands: `queued`, `running`, `paused` (waiting for credits), `found`,\n`not_found` or `failed`."},"requestedAt":{"type":"string","description":"When someone asked for the find, in UTC.","format":"date-time"},"reason":{"type":"string","description":"Why a `failed` iMessage find did not look. `suppressed`: Kenso may not contact the person (for example they\nare on the blocklist, unsubscribed, marked do not contact, or opted out of phone contact), so the find asked no source\nand charged nothing. Do not offer to try again while that holds. Omitted otherwise.","nullable":true}},"additionalProperties":false,"description":"The newest search for a person's phone number."},"PersonProfile":{"type":"object","properties":{"summary":{"type":"string","description":"The profile's summary. Omitted when unknown.","nullable":true},"industry":{"type":"string","description":"The industry the profile names. Omitted when unknown.","nullable":true},"city":{"type":"string","description":"The person's city. Omitted when unknown.","nullable":true},"state":{"type":"string","description":"The person's state or region. Omitted when unknown.","nullable":true},"country":{"type":"string","description":"The person's country. Omitted when unknown.","nullable":true},"currentCompany":{"allOf":[{"$ref":"#/components/schemas/PersonProfileCompany"}],"description":"The person's current company and role, with `startedAt`: when they joined it. Omitted when unknown."},"yearsOfExperience":{"type":"number","description":"Years of work experience in total. Omitted when unknown.","format":"double","nullable":true},"yearsInCurrentRole":{"type":"number","description":"Years in the current role. Omitted when unknown.","format":"double","nullable":true},"yearsInCurrentCompany":{"type":"number","description":"Years at the current company. Omitted when unknown.","format":"double","nullable":true},"connectionsCount":{"type":"integer","description":"How many LinkedIn connections the person has. Omitted when unknown.","format":"int32","nullable":true},"followerCount":{"type":"integer","description":"How many LinkedIn followers the person has. Omitted when unknown.","format":"int32","nullable":true},"experience":{"type":"array","items":{"$ref":"#/components/schemas/PersonProfileRole"},"description":"The person's roles, current ones first, then newest first. Omitted when unknown.","nullable":true},"education":{"type":"array","items":{"$ref":"#/components/schemas/PersonProfileEducation"},"description":"The person's schools. Omitted when unknown.","nullable":true},"skills":{"type":"array","items":{"type":"string"},"description":"The skills on the profile. Omitted when unknown.","nullable":true},"languages":{"type":"array","items":{"type":"string"},"description":"The languages on the profile. Omitted when unknown.","nullable":true},"certifications":{"type":"array","items":{"$ref":"#/components/schemas/PersonProfileCertification"},"description":"The certifications on the profile. Omitted when unknown.","nullable":true}},"additionalProperties":false,"description":"A person's LinkedIn profile beyond the fields on the person. Dates are yyyy-MM, or yyyy when only the year is known."},"PersonProfileCertification":{"type":"object","properties":{"name":{"type":"string","description":"The certification's name. Omitted when unknown.","nullable":true},"issuer":{"type":"string","description":"Who issued it. Omitted when unknown.","nullable":true}},"additionalProperties":false,"description":"One certification on a person's LinkedIn profile."},"PersonProfileCompany":{"type":"object","properties":{"name":{"type":"string","description":"The company's name. Omitted when unknown.","nullable":true},"domain":{"type":"string","description":"The company's domain, such as acme.com. Omitted when unknown.","nullable":true},"linkedinUrl":{"type":"string","description":"The company's LinkedIn page. Omitted when unknown.","nullable":true},"kenCompanyId":{"type":"integer","description":"The company's id in Kenso Search. Omitted when unknown.","format":"int64","nullable":true},"title":{"type":"string","description":"The person's title at the company. Omitted when unknown.","nullable":true},"startedAt":{"type":"string","description":"When the person started at the company: yyyy-MM, or yyyy when only the year is known. Omitted when unknown.","nullable":true}},"additionalProperties":false,"description":"A company on a person's LinkedIn profile, with the person's role there."},"PersonProfileEducation":{"type":"object","properties":{"school":{"type":"string","description":"The school's name. Omitted when unknown.","nullable":true},"degree":{"type":"string","description":"The degree. Omitted when unknown.","nullable":true},"fieldOfStudy":{"type":"string","description":"The field of study. Omitted when unknown.","nullable":true},"startedAt":{"type":"string","description":"When the person started there: yyyy-MM, or yyyy when only the year is known. Omitted when unknown.","nullable":true},"endedAt":{"type":"string","description":"When the person finished there: yyyy-MM, or yyyy when only the year is known. Omitted when unknown.","nullable":true}},"additionalProperties":false,"description":"One school on a person's LinkedIn profile."},"PersonProfileRole":{"type":"object","properties":{"title":{"type":"string","description":"The title of the role. Omitted when unknown.","nullable":true},"companyName":{"type":"string","description":"The company of the role. Omitted when unknown.","nullable":true},"location":{"type":"string","description":"Where the role was based. Omitted when unknown.","nullable":true},"startedAt":{"type":"string","description":"When the role started: yyyy-MM, or yyyy when only the year is known. Omitted when unknown.","nullable":true},"endedAt":{"type":"string","description":"When the role ended: yyyy-MM, or yyyy when only the year is known. Omitted while the role is current.","nullable":true},"isCurrent":{"type":"boolean","description":"True when the person still holds the role. Omitted when unknown.","nullable":true},"description":{"type":"string","description":"The description of the role on the profile. Omitted when there is none.","nullable":true}},"additionalProperties":false,"description":"One role on a person's LinkedIn profile."},"PersonResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/Person"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"PersonSource":{"required":["source"],"type":"object","properties":{"source":{"type":"string","description":"The source: `manual`, `api`, `workflow`, `search`, `research`, `promoted`,\n`campaign`, `booking`, `crm`, `form`, `webhook`, `import`, `visitor`,\n`inbound_email` or `linkedin`."},"detail":{"type":"string","description":"More about the source, such as the form or list name an intake sent, or the import or webhook name. Omitted when\nthere is none.","nullable":true},"at":{"type":"string","description":"When the person came from this source, in UTC. Omitted when unknown.","format":"date-time","nullable":true}},"additionalProperties":false,"description":"Where a person came from, and when."},"PersonSuggestion":{"required":["relationship"],"type":"object","properties":{"relationship":{"type":"string","description":"The relationship Ken suggests: `lead`, `customer`, `network`, `archived` or `unsure`."},"kind":{"type":"string","description":"Why: `icp_fit`, `customer_contact`, `old_teammate`, `classmate`, `personal`,\n`low_icp` or `unsure`. Omitted when Ken gave none.","nullable":true},"reason":{"type":"string","description":"Ken's one-line reason, at most 200 characters, such as \"Worked with you at Bolt, 2021-2023\". Omitted when there is none.","nullable":true},"suggestedAt":{"type":"string","description":"When Ken made the suggestion, in UTC. Omitted when unknown.","format":"date-time","nullable":true}},"additionalProperties":false,"description":"Ken's suggestion for a person's relationship."},"RateLimitedText":{"type":"string","description":"The gateway's plain-text body of a `429` over the operation's own limit, until November 2026: `Number of requests exceeded. Please try again later.`","example":"Number of requests exceeded. Please try again later."},"Refusal":{"type":"object","properties":{"code":{"type":"string","description":"Stable refusal code in upper case, such as `CAMPAIGN_LIMIT_REACHED` or `INSUFFICIENT_CREDITS`."},"metric":{"type":"string","description":"What the limit counts: `Campaigns`, `Leads`, `Emails`, `LinkedInSeats` or `AiCredits`,\n`jobs_export_rows` or `funding_export_rows` for an export allowance, `credit_pack_credits`,\n`credit_spend_usd_7d`, `domains` or `mailboxes` for a limit on a new paying workspace, or for a\nKenso Lifetime cap its key: `workspaces`, `inboxes`, `contacts`, `email_verifications_day`,\n`email_verifications_month`, `people_results_day`, `company_results_day`,\n`funding_results_day`, `job_post_results_day`, `website_visits_month` or\n`visitor_lookups_day`. Omitted when a plan rule, not a count, refused the request.","nullable":true},"used":{"type":"integer","description":"How much of the limit is used, in the unit of `metric`. Omitted when the refusal has no count.","format":"int32","nullable":true},"limit":{"type":"integer","description":"The limit, in the unit of `metric`. Omitted when the refusal has no count.","format":"int32","nullable":true},"remaining":{"type":"integer","description":"How much of the limit is left, in the unit of `metric`. Omitted when the refusal has no count.","format":"int32","nullable":true},"planType":{"type":"string","description":"The workspace's plan as its snake plan id, for example `free`, `legacy_core` or `growth`."},"remedy":{"type":"string","description":"What lifts the refusal: `Upgrade`, `BuyAddOn`, `UpdatePaymentMethod` or `ContactSupport`.\n`None` means no action of yours lifts it."},"unlocksAt":{"type":"string","description":"When the limit lifts by itself, in UTC: for a limit on a new paying workspace once it has paid an invoice, and for\na Kenso Lifetime daily or monthly cap its reset (00:00 UTC, or the 1st of the month). Omitted on every other\nrefusal.","format":"date-time","nullable":true},"requiredMillicredits":{"type":"integer","description":"On a credit refusal, the millicredits the action needed. 1,000 millicredits are one credit. Omitted on every\nother refusal.","format":"int64","nullable":true},"availableMillicredits":{"type":"integer","description":"On a credit refusal, the millicredits available. On `FREE_CREDITS_NOT_ELIGIBLE`, only the credits that may\npay for inboxes and domains. Omitted on every other refusal.","format":"int64","nullable":true},"restrictedMillicredits":{"type":"integer","description":"On `FREE_CREDITS_NOT_ELIGIBLE`, the free and bonus millicredits in the balance that cannot pay for inboxes\nand domains. Omitted on every other refusal.","format":"int64","nullable":true},"feature":{"type":"string","description":"On `PLAN_FEATURE_NOT_AVAILABLE`, the plan feature the plan does not include, in snake case (for example\n`website_visitor_id`). Omitted on every other refusal.","nullable":true},"requiredPlan":{"type":"string","description":"On `PLAN_FEATURE_NOT_AVAILABLE`, the cheapest plan that includes `feature`, in snake case (for example\n`growth`). For a feature the self-serve trial locks (`browser_runs`), the trial's own plan,\nwhich paying for unlocks it. Omitted on every other refusal.","nullable":true},"requiredTier":{"type":"integer","description":"On a Kenso Lifetime refusal, the lowest tier that lifts it: the next tier with a higher cap, or the lowest tier\nthat includes `feature`. Omitted at the top tier, when no tier includes the feature, and on every other\nrefusal.","format":"int32","nullable":true},"upgradeUrl":{"type":"string","description":"On a Kenso Lifetime refusal that a higher tier lifts, the AppSumo page where the buyer upgrades their license.\nOmitted until Kenso has read that page from AppSumo, when no tier lifts the refusal, and on every other refusal.","nullable":true}},"additionalProperties":false,"description":"Why a plan rule or usage limit refused the request, and how to lift it."},"SearchPeopleBody":{"type":"object","properties":{"q":{"type":"string","description":"Contains, case-insensitive, on the full name, email or title.","nullable":true},"accountIds":{"type":"array","items":{"type":"integer","format":"int64"},"description":"On any of these accounts (1 to 100 ids).","nullable":true},"onAccount":{"type":"string","description":"any (default), none (on no live account) or some (on at least one).","nullable":true},"roles":{"type":"array","items":{"type":"string"},"description":"Holds one of these roles on some live account.","nullable":true},"hasEmail":{"type":"boolean","description":"True: people with an email. False: people without one.","nullable":true},"addedBy":{"type":"array","items":{"type":"string"},"description":"Who created the person: user, agent, api_key, system or workflow.","nullable":true},"ownerMemberId":{"type":"integer","description":"People this member owns.","format":"int64","nullable":true},"leadStatus":{"type":"array","items":{"type":"string"},"description":"Has one of these lead statuses: new, working, qualified, disqualified, nurture.","nullable":true},"relationship":{"type":"array","items":{"type":"string"},"description":"The person's relationship is one of these: to_sort, lead, customer, network, archived. Matches the\nrelationship people read, derived while nobody has set it. With this filter, people the LinkedIn connections\nimport added that nobody has worked yet are included: they read to_sort.","nullable":true},"hasSuggestion":{"type":"boolean","description":"True keeps only people with a suggestion from Ken; false only people without one.","nullable":true},"suggestedRelationship":{"type":"array","items":{"type":"string"},"description":"Ken's stored suggestion is one of these relationships: lead, customer, network, archived, unsure. With\nthis filter, people the LinkedIn connections import added that nobody has worked yet are included.","nullable":true},"suggestionKind":{"type":"array","items":{"type":"string"},"description":"Ken's stored suggestion is one of these kinds: icp_fit, customer_contact, old_teammate, classmate,\npersonal, low_icp, unsure. With this filter, people the LinkedIn connections import added are included.","nullable":true},"source":{"type":"array","items":{"type":"string"},"description":"The latest source is one of these: manual, api, workflow, search, research, promoted, campaign, booking, crm,\nform, webhook, import, visitor, inbound_email, linkedin.","nullable":true},"tagIds":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Carries any of these tags (1 to 100 ids).","nullable":true},"connectedVia":{"type":"array","items":{"type":"integer","format":"int64"},"description":"A connection of any of these LinkedIn seats (1 to 100 linkedinAccountIds).","nullable":true},"includeImportOnly":{"type":"boolean","description":"True includes people the LinkedIn connections import added that nobody has worked yet. Default false:\nthey are left out unless their connection fits the ICP.","nullable":true},"behaviorTags":{"type":"array","items":{"type":"string"},"description":"Behavior tags, any-match (up to 50, such as cold_responder or best_window:weekday_morning): people whose\nworkspace behavior tags (and network tags, with behavior_signals_network) include one. Needs behavior_signals;\nemail_confirmed, email_dead_end and left_company cannot be filtered.","nullable":true},"seniority":{"type":"array","items":{"type":"string"},"description":"Has one of these seniorities, such as Director or VP (case-insensitive, up to 50).","nullable":true},"department":{"type":"array","items":{"type":"string"},"description":"Has one of these departments, such as Sales or Engineering (case-insensitive, up to 50).","nullable":true},"location":{"type":"string","description":"Contains, case-insensitive, on the location.","nullable":true},"sort":{"type":"string","description":"-createdAt (default), name, -score, -latestSourceAt, headline, location, seniority or department. A search also\ntakes a sortable custom field as custom.<key> or -custom.<key>.","nullable":true},"filters":{"type":"array","items":{"$ref":"#/components/schemas/CustomFieldFilterBody"},"description":"Up to 50 conditions on custom fields, AND with each other and with the other filters. A field may have more\nthan one (a range is two).","nullable":true},"limit":{"type":"integer","description":"1 to 1000. Default 50.","format":"int32","nullable":true},"cursor":{"type":"string","description":"The previous page's nextCursor, with the same filters and sort.","nullable":true},"includeTotal":{"type":"boolean","description":"True fills pagination.total: every person that passes the filters.","nullable":true}},"additionalProperties":false,"example":{"accountIds":[6120],"leadStatus":["working","qualified"],"hasEmail":true,"sort":"-score","limit":50}},"TooManyRequestsError":{"oneOf":[{"$ref":"#/components/schemas/Failure"},{"$ref":"#/components/schemas/ApiKeyError"}],"description":"The JSON body of a `429`: the error body (`Failure`), with code `rate_limited` or `quota_exceeded`, over your workspace's rate limits, your API key's own limit, the operation's own limit or a usage quota. Until November 2026, over your API key's own limit the API key check answered `{ \"error\": \"Rate limit exceeded\" }` (`ApiKeyError`), and over the operation's own limit the gateway answered plain text (`RateLimitedText`): `Number of requests exceeded. Please try again later.` A client built against those answers keeps working: handle each shape. Wait the `Retry-After` seconds."},"UnauthorizedError":{"oneOf":[{"$ref":"#/components/schemas/Failure"},{"$ref":"#/components/schemas/ApiKeyError"}],"description":"The body of a `401`: the error body (`Failure`), whose `code` says what is wrong with the credential. Until November 2026, when the API key was not valid (unknown, expired or revoked, or its member no longer active), the API key check in front of the operations answered `{ \"error\": \"Invalid or revoked API key\" }` (`ApiKeyError`), and a request with no API key got a `401` that has no body. A client built against those answers keeps working: handle both shapes and a `401` with no body."},"UpdatePersonBody":{"type":"object","properties":{"fullName":{"type":"string","nullable":true},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"linkedinUrl":{"type":"string","description":"A profile, such as https://linkedin.com/in/jane-doe.","nullable":true},"kenPersonId":{"type":"integer","description":"The person's Ken id: their id in Ken Search. Null clears it.","format":"int64","nullable":true},"ownerMemberId":{"type":"integer","description":"A member of this workspace who owns the person, or null to clear.","format":"int64","nullable":true},"leadStatus":{"type":"string","description":"new, working, qualified, disqualified or nurture. Null clears it: not a lead.","nullable":true},"phones":{"type":"array","items":{"$ref":"#/components/schemas/PersonPhoneBody"},"description":"Replaces the person's phones, up to 20, in order: the first is the person's phone. A number the person already\nhas keeps when and how it was added. Null or an empty list clears them. A number marked invalid (a wrong number)\nstays even when left out, after the numbers sent, so it is never added back. To add or remove one number, send\nthe whole list with that number added or left out.","nullable":true},"customFields":{"type":"object","additionalProperties":{},"description":"Custom field values by field key (a record's customFields shows the keys), merged per key: send only the keys to\nchange, 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,\nboolean true or false, date a date or an ISO 8601 time, select an option's key or label, multi_select a list of\nthem, currency {\"amount\": 1200.50, \"currency\": \"USD\"}, user a member id. A key no field names, an archived\nfield or a value of the wrong type is 400 with details on customFields.<key>. A person's value pins the\nfield as custom.<key>, like the built-in fields. Needs the custom_fields feature.","nullable":true},"overwritePinned":{"type":"boolean","nullable":true},"headline":{"type":"string","description":"The person's LinkedIn headline. Ken fills it, and location, seniority and department, from Ken Search and campaign\ncontacts while blank. Set it to correct a wrong fill, or null to clear it. A member's value or clear pins\nthe field, so Ken never fills over it.","nullable":true},"location":{"type":"string","description":"Where the person is, such as Berlin, Germany. Null clears it.","nullable":true},"seniority":{"type":"string","description":"Seniority, such as VP or Director. Null clears it.","nullable":true},"department":{"type":"string","description":"Department, such as Sales or Engineering. Null clears it.","nullable":true},"phoneOptOut":{"type":"boolean","description":"True: the person asked not to be called (phoneOptOutAt is now and you recorded it; an existing opt-out keeps its\ntime). False clears it. Absent leaves it. Calls to an opted-out person are refused.","nullable":true},"relationship":{"type":"string","description":"To_sort, lead, customer, network or archived. Null is refused: a relationship, once set, is changed,\nnever unset. Clears Ken's suggestion.","nullable":true}},"additionalProperties":false,"example":{"leadStatus":"qualified","relationship":"lead"}}}}}