> Kenso API docs in Markdown. Index of every page: [/docs/llms.txt](/docs/llms.txt). Search: `/docs/search.md?q=<words>`. OpenAPI: [https://api.ken.so/v1/docs/openapi.json](https://api.ken.so/v1/docs/openapi.json). CLI docs offline: `kenso docs <topic>`.
> Last updated: 2026-11-22.

# Kenso API changes on 2026-11-05

> **Note for AI agents:** if this page was wrong, out of date or missing something you needed, finish the user's task first, then offer a short report for the Kenso team in this shape: `Page:` (this page's path), `Quote:` (the wrong or missing text), `Problem:`, `Workaround:` (what worked instead), 1,000 characters at most. Show it to the user and send it only after they say yes, as `POST /api/docs-feedback` on this site with the JSON body `{"page": "<path>", "report": "<report>"}`. Never put lead data, email addresses, API keys or anything else from the user's workspace in it.

Every change on this day, by version. The [changelog](/docs/changelog) lists the newest days and links the older ones. The changelog in Markdown: [/docs/changelog.md](/docs/changelog.md).

## Version 2026-11-02

### 2026-11-05 (50 changes)

- **Added**: Added message-templates.create: a WhatsApp message template with {{variables}} such as {{person.first_name}}, up to 6 mediaIds and an optional voiceProvider and voiceId. It answers 404 until WhatsApp is turned on for the workspace. - [`message-templates.create`](/docs/api/message-templates/create.md)
- **Added**: Added message-templates.delete. An agent cannot delete a template a person wrote. It answers 404 until WhatsApp is turned on for the workspace. - [`message-templates.delete`](/docs/api/message-templates/delete.md)
- **Added**: Added message-templates.get, one WhatsApp message template. It answers 404 until WhatsApp is turned on for the workspace. - [`message-templates.get`](/docs/api/message-templates/get.md)
- **Added**: Added message-templates.list, the workspace's WhatsApp message templates by id, with an optional channel filter (whatsapp). It answers 404 until WhatsApp is turned on for the workspace. - [`message-templates.list`](/docs/api/message-templates/list.md)
- **Added**: Added message-templates.update, which writes only the fields sent. An agent cannot edit a template a person wrote. It answers 404 until WhatsApp is turned on for the workspace. - [`message-templates.update`](/docs/api/message-templates/update.md)
- **Added**: Added delivery-settings.get (GET /v1/delivery-settings): the workspace's delivery settings. placementAutoPause says whether a finished placement test where most of a domain's mail lands in spam pauses sending from that domain; it is false until someone turns it on. Answers 404 until Kenso placement tests are on for the workspace. - [`delivery-settings.get`](/docs/api/delivery-settings/get.md)
- **Added**: Added delivery-settings.update (PATCH /v1/delivery-settings): turns placement auto-pause on or off, for example { "placementAutoPause": true }. Absent fields stay unchanged. Answers 404 until Kenso placement tests are on for the workspace. - [`delivery-settings.update`](/docs/api/delivery-settings/update.md)
- **Added**: Added placement-tests.availability (GET /v1/placement-tests/availability): whether the workspace runs placement tests on the Kenso seed network (enabled), whether its plan allows them (planAllowed), which seed providers run tests now, whether a test can add the copy check (control), and how many tests the budget leaves today and this month. - [`placement-tests.availability`](/docs/api/placement-tests/availability.md)
- **Changed**: Placement tests can run on the Kenso seed network. Added optional request fields subject and body (custom copy, sent together, no campaign needed) and control (also send a plain message from the same senders, to tell a copy problem from a domain problem). inboxId tests one inbox and domainId a domain's inboxes; with neither, the test uses the campaign's senders. The call can now answer 200 with the test already running for that scope. Added optional response fields scope, verdict, progress, hasControl, providersTested and control. - [`placement-tests.create`](/docs/api/placement-tests/create.md)
- **Changed**: Added optional response fields for tests on the Kenso seed network: scope, verdict (cause and summary), progress (planned, sent, read, waiting, failed, finalBy), hasControl, providersTested and control (the copy check's results). Each provider adds tested, folders, authentication (SPF, DKIM, DMARC and compauth pass counts), microsoft (median SCL and BCL) and medianArrivalSeconds. Each seed adds arm, status, tab, authentication, microsoft and arrivalSeconds. - [`placement-tests.get`](/docs/api/placement-tests/get.md)
- **Added**: Added optional query parameters inboxId and domainId to placement-tests.list. Pass exactly one of campaignId, inboxId or domainId. - [`placement-tests.list`](/docs/api/placement-tests/list.md)
- **Changed**: Added the same optional fields as placement-tests.get to each test in the placement-tests.list response: scope, verdict, progress, hasControl, providersTested, control, and the new provider and seed fields. - [`placement-tests.list`](/docs/api/placement-tests/list.md)
- **Changed**: The person model gains four optional WhatsApp fields: phones[].whatsapp (on, off or unknown: whether that number is on WhatsApp, from a check in the last 30 days), phones[].whatsappCheckedAt (when that check ran), phones[].whatsappOptOutAt (when WhatsApp to that number stopped, by the person's stop or the number's) and whatsappOptOutAt (when the person asked not to get WhatsApp messages). people.intake returns the person model but never fills them, so its response does not change. They are returned only on the people get, list and search reads, and only for a workspace with the whatsapp feature on, which is off for every workspace for now. - [`people.intake`](/docs/api/people/intake.md)
- **Added**: Added whatsapp-accounts.create-connect-session (POST /v1/whatsapp-accounts/connect-sessions), which starts a hosted session to connect a WhatsApp account and answers 201 with its url and whatsappAccountId. Omit whatsappAccountId to connect a new account (it shows as connecting until the scan completes), or pass it to reconnect one. A new account costs 1,500 credits a month and needs the first month up front: without it the call answers 400 validation_failed. Needs the whatsapp feature, which is off for every workspace for now: until it is on, the call answers 404. - [`whatsapp-accounts.create-connect-session`](/docs/api/whatsapp-accounts/create-connect-session.md)
- **Added**: Added whatsapp-accounts.delete (DELETE /v1/whatsapp-accounts/{whatsappAccountId}), which removes a WhatsApp account, ends its WhatsApp session and stops its monthly charge. It answers 204. Needs Delivery edit. Needs the whatsapp feature, which is off for every workspace for now: until it is on, the call answers 404. - [`whatsapp-accounts.delete`](/docs/api/whatsapp-accounts/delete.md)
- **Added**: Added whatsapp-accounts.get (GET /v1/whatsapp-accounts/{whatsappAccountId}), which returns one WhatsApp account of the workspace with the same fields as whatsapp-accounts.list. Needs the whatsapp feature, which is off for every workspace for now: until it is on, the call answers 404. - [`whatsapp-accounts.get`](/docs/api/whatsapp-accounts/get.md)
- **Added**: Added whatsapp-accounts.list (GET /v1/whatsapp-accounts), which lists the WhatsApp accounts connected to the workspace: each one's number, status, ramp stage, pause, working hours, daily new-chat and message caps, and today's usage. Needs the whatsapp feature, which is off for every workspace for now: until it is on, the call answers 404. - [`whatsapp-accounts.list`](/docs/api/whatsapp-accounts/list.md)
- **Added**: Added whatsapp-accounts.update (PATCH /v1/whatsapp-accounts/{whatsappAccountId}), which changes a WhatsApp account's daily caps (dailyNewChatCap, dailyMessageCap, or resetCaps for the ramp defaults), its timezone and working hours (workingHoursSchedule, resetWorkingHours), and pauses or resumes it (paused). Absent fields stay unchanged. A cap above its ceiling answers 400 validation_failed, and resuming an account WhatsApp restricted answers 409 conflict. Needs Delivery edit. Needs the whatsapp feature, which is off for every workspace for now: until it is on, the call answers 404. - [`whatsapp-accounts.update`](/docs/api/whatsapp-accounts/update.md)
- **Added**: Added whatsapp-settings.get (GET /v1/whatsapp-settings), which returns the workspace's WhatsApp setting: allowEuEeaUk (whether touches may send WhatsApp to numbers in the EU, EEA and UK; off by default) and updatedAt. Needs the whatsapp feature, which is off for every workspace for now: until it is on, the call answers 404. - [`whatsapp-settings.get`](/docs/api/whatsapp-settings/get.md)
- **Added**: Added whatsapp-settings.update (PATCH /v1/whatsapp-settings), which turns allowEuEeaUk on or off. With it on, touches send WhatsApp to numbers in the EU, EEA and UK, and the workspace answers for the legal basis. Workspace admins only. Needs the whatsapp feature, which is off for every workspace for now: until it is on, the call answers 404. - [`whatsapp-settings.update`](/docs/api/whatsapp-settings/update.md)
- **Added**: Added linkedin-accounts.reset-ramp. - [`linkedin-accounts.reset-ramp`](/docs/api/linkedin-accounts/reset-ramp.md)
- **Changed**: Documentation fix: the reference no longer lists the configurationId and byConfiguration query parameters or a configurationId field on breakdown rows. Replies are not tied to a sending configuration, so configurationId was always refused with 400 validation_failed, byConfiguration only ever returned one Unattributed row holding everyone, and the row field was never sent. Only the documentation changed: a request that still sends them gets the same response as before. - [`analytics.get-reply-classifications`](/docs/api/analytics/get-reply-classifications.md)
- **Changed**: The message in the response can carry imessage (an iMessage text's deliveredChannel imessage or sms, deliveredAt, failedAt and errorCode, reactions, mediaCount, voiceNoteId and the attachments the person sent). A new email thread never sets it. - [`threads.create`](/docs/api/threads/create.md)
- **Changed**: Added mediaIds (up to 10 uploaded images) and voiceNoteId (a voice note, sent alone with no body) to the request, for iMessage threads only: an email or LinkedIn thread answers 400 validation_failed on that field. On an iMessage thread the reply sends at once: 201 once the text is confirmed sent; 400 for a link in a first text or an unusable image or voice note; 409 invalid_state with the reason as the detail code when the line cannot send now (with nextAllowedAt and Retry-After), for images or a voice note before the person replied or on an SMS thread, and for recipient_must_reply, phone_opt_out or provider_rejected:IMESSAGE_SEND_REFUSED; 409 outcome_unknown when Kenso cannot tell whether it went; 503 when nothing was sent. delaySeconds is ignored there. The 201 message can carry imessage (an iMessage text's deliveredChannel imessage or sms, deliveredAt, failedAt and errorCode, reactions, mediaCount, voiceNoteId and the attachments the person sent). Needs the imessage feature, which is off for every workspace for now. - [`threads.create-message`](/docs/api/threads/create-message.md)
- **Changed**: An iMessage thread carries imessage: lineId (the line it is on), phone (the person's number in E.164), hasReplied and isSmsThread. Omitted on other channels. Needs the imessage feature, which is off for every workspace for now. - [`threads.get`](/docs/api/threads/get.md)
- **Changed**: channel takes imessage, and channel all lists iMessage threads too, while the workspace's imessage feature is on (off for every workspace for now); otherwise channel imessage is 400 as before. A person row's channels carries an imessage thread count while the feature is on. List rows do not carry the imessage block: read it on threads.get. - [`threads.list`](/docs/api/threads/list.md)
- **Changed**: Each message of an iMessage thread carries imessage (an iMessage text's deliveredChannel imessage or sms, deliveredAt, failedAt and errorCode, reactions, mediaCount, voiceNoteId and the attachments the person sent). Omitted on other channels. Needs the imessage feature, which is off for every workspace for now. - [`threads.list-messages`](/docs/api/threads/list-messages.md)
- **Added**: Added PUT /v1/threads/{threadId}/messages/{messageId}/reaction: set your tapback on a received iMessage text (love, like, dislike, laugh, emphasize, question or one emoji), or remove it with null. 200 with messageId, threadId, reaction and reactedAt. A text you sent is 400 imessage_reaction_unavailable; a thread on another channel is 400 on threadId; a message of another thread is 404; 503 when the line cannot react now. Kenso never reacts on its own. Needs the reply permission. Needs the imessage feature, which is off for every workspace for now. - [`threads.react-message`](/docs/api/threads/react-message.md)
- **Changed**: An iMessage thread carries imessage (lineId, phone, hasReplied, isSmsThread), as on threads.get. Needs the imessage feature, which is off for every workspace for now. - [`threads.update`](/docs/api/threads/update.md)
- **Added**: Added POST /v1/imessage-media: upload one image (jpg, png, gif or heic, under 10 MB) as the multipart field file for an iMessage text. Returns 201 with mediaId and a link that works for 1 hour; put mediaId in a touch's mediaIds. An empty, oversized or unsupported file is 400. Needs the Inbox permission. Needs the imessage feature, which is off for every workspace for now. - [`imessage-media.create`](/docs/api/imessage-media/create.md)
- **Added**: Added GET /v1/imessage-media/{mediaId}: one uploaded image with a new link that works for 1 hour. An image of another workspace is not_found. Needs the Inbox permission. Needs the imessage feature, which is off for every workspace for now. - [`imessage-media.get`](/docs/api/imessage-media/get.md)
- **Added**: Added POST /v1/voice-notes: Ken writes and speaks a voice note for a person (personId) who replied on iMessage, in the voice you pick, charged as imessage_voice_note. Send its voiceNoteId on an iMessage touch. Pass touchId for a touch's note or threadId (the thr_ id of the iMessage thread it goes on) for an inbox note, not both (400 validation_failed, error.details[0].code not_allowed on threadId); the person must have replied on that thread. A person who has not replied is 400 validation_failed with error.details[0].code recipient_must_reply. Needs the Inbox permission; a Client seat gets 403 permission_denied, since a note spends credits. Needs the imessage feature, which is off for every workspace for now. - [`voice-notes.create`](/docs/api/voice-notes/create.md)
- **Added**: Added GET /v1/voice-notes/{voiceNoteId}/imessage-audio: redirects (302) to the audio of a voice note on an iMessage text, a link that works for 1 hour. A note of another workspace is 404, a note still being made 409 voice_note_not_ready. Needs the Inbox permission. Needs the imessage feature, which is off for every workspace for now. - [`voice-notes.imessage-audio`](/docs/api/voice-notes/imessage-audio.md)
- **Added**: Added POST /v1/imessage-lines/{lineId}/cancel: an ordered line fails at no cost; an active line keeps sending until billedThroughAt, the end of its paid month, then is released; a paused line is released at once. No refunds. A down line is 409 invalid_state with error.details[0].code imessage_line_down, a line whose monthly charge is still running 409 billing_in_progress (retry in a minute), and a line changed meanwhile 409 concurrent_change. Needs the workspace_settings and billing permissions. Needs the imessage feature, which is off for every workspace for now. - [`imessage-lines.cancel`](/docs/api/imessage-lines/cancel.md)
- **Added**: Added GET /v1/imessage-lines/{lineId}: one iMessage line, in the shape imessage-lines.list returns. A line of another workspace is not_found. Needs the imessage feature, which is off for every workspace for now. - [`imessage-lines.get`](/docs/api/imessage-lines/get.md)
- **Added**: Added GET /v1/imessage-lines: the workspace's iMessage lines, Kenso's own lines at 15,000 credits a month each (paid credits, and free credits where Kenso staff allowed them for the workspace), newest order first, with status, country, number, owner, billing (unpaid, billedThroughAt) and health (ramp day, new conversations used and left today, contacts in 24 hours and 30 days, reply rate). includeEnded=true adds released and failed lines. Not paginated: pagination.hasMore is always false. Needs the imessage feature, which is off for every workspace for now. - [`imessage-lines.list`](/docs/api/imessage-lines/list.md)
- **Added**: Added POST /v1/imessage-lines: order an iMessage line in US or UK for 15,000 credits a month, paid credits only unless Kenso staff allowed the workspace's free credits for them, owned by ownerMemberId (the caller when absent). Once those credits cover it, Kenso buys it within 24 hours, and the first month is charged when it goes live. The Idempotency-Key header is required (1 to 200 characters): the same key and country returns the first order, and the same key with another country is 422 idempotency_key_reused (the owner is not compared). Refusals: 400 validation_failed or owner_not_member, 402 with error.refusal (FREE_CREDITS_NOT_ELIGIBLE when only free credits are short), 403 demo_workspace, 409 imessage_line_limit_reached (10 lines a workspace). Needs the workspace_settings and billing permissions. Needs the imessage feature, which is off for every workspace for now. - [`imessage-lines.order`](/docs/api/imessage-lines/order.md)
- **Added**: Added POST /v1/imessage-lines/{lineId}/pause: an active line stops sending until resumed. A paused line answers unchanged; any other status is 409 invalid_state. Needs the workspace_settings permission. Needs the imessage feature, which is off for every workspace for now. - [`imessage-lines.pause`](/docs/api/imessage-lines/pause.md)
- **Added**: Added POST /v1/imessage-lines/{lineId}/resume: a line a member paused sends again, or stays paused with pausedReason unpaid while its monthly credits are unpaid. A line paused for unpaid credits is 409 invalid_state. Needs the workspace_settings permission. Needs the imessage feature, which is off for every workspace for now. - [`imessage-lines.resume`](/docs/api/imessage-lines/resume.md)
- **Added**: Added PATCH /v1/imessage-lines/{lineId}: change a line's owner (ownerMemberId, an active member, else 400 owner_not_member). status is read-only: use the pause, resume and cancel actions. A released or failed line is 409 invalid_state. Needs the workspace_settings permission. Needs the imessage feature, which is off for every workspace for now. - [`imessage-lines.update`](/docs/api/imessage-lines/update.md)
- **Added**: Added optional query parameter channel to reply-templates.list. - [`reply-templates.list`](/docs/api/reply-templates/list.md)

Optional fields added on 9 operations:

- **Changed**: Added optional fields `data[].ramp`, `data[].rampPlansEnabled`, `data[].rampStartedAt`, `data[].ramp[].action`, `data[].ramp[].ceiling`, `data[].ramp[].fullVolumeOn`, `data[].ramp[].start`, `data[].ramp[].stepPerWeek`, `data[].ramp[].todayCap` and `data[].ramp[].weekIndex` to the campaigns.list-linkedin-accounts response. - [`campaigns.list-linkedin-accounts`](/docs/api/campaigns/list-linkedin-accounts.md)
- **Changed**: Added optional fields `data[].ramp`, `data[].rampPlansEnabled`, `data[].rampStartedAt`, `data[].ramp[].action`, `data[].ramp[].ceiling`, `data[].ramp[].fullVolumeOn`, `data[].ramp[].start`, `data[].ramp[].stepPerWeek`, `data[].ramp[].todayCap` and `data[].ramp[].weekIndex` to the campaigns.replace-linkedin-accounts response. - [`campaigns.replace-linkedin-accounts`](/docs/api/campaigns/replace-linkedin-accounts.md)
- **Changed**: Added optional fields `data.ramp`, `data.rampPlansEnabled`, `data.rampStartedAt`, `data.ramp[].action`, `data.ramp[].ceiling`, `data.ramp[].fullVolumeOn`, `data.ramp[].start`, `data.ramp[].stepPerWeek`, `data.ramp[].todayCap` and `data.ramp[].weekIndex` to the linkedin-accounts.get response. - [`linkedin-accounts.get`](/docs/api/linkedin-accounts/get.md)
- **Changed**: Added optional fields `data[].ramp`, `data[].rampPlansEnabled`, `data[].rampStartedAt`, `data[].ramp[].action`, `data[].ramp[].ceiling`, `data[].ramp[].fullVolumeOn`, `data[].ramp[].start`, `data[].ramp[].stepPerWeek`, `data[].ramp[].todayCap` and `data[].ramp[].weekIndex` to the linkedin-accounts.list response. - [`linkedin-accounts.list`](/docs/api/linkedin-accounts/list.md)
- **Changed**: Added optional fields `ramp`, `ramp{}.ceiling`, `ramp{}.start` and `ramp{}.stepPerWeek` to the linkedin-accounts.update request. Added optional fields `data.ramp`, `data.rampPlansEnabled`, `data.rampStartedAt`, `data.ramp[].action`, `data.ramp[].ceiling`, `data.ramp[].fullVolumeOn`, `data.ramp[].start`, `data.ramp[].stepPerWeek`, `data.ramp[].todayCap` and `data.ramp[].weekIndex` to the linkedin-accounts.update response. - [`linkedin-accounts.update`](/docs/api/linkedin-accounts/update.md)
- **Changed**: Added optional field `channel` to the reply-templates.create request. Added optional fields `data.channel` and `data.firstTextSafe` to the reply-templates.create response. - [`reply-templates.create`](/docs/api/reply-templates/create.md)
- **Changed**: Added optional fields `data.channel` and `data.firstTextSafe` to the reply-templates.get response. - [`reply-templates.get`](/docs/api/reply-templates/get.md)
- **Changed**: Added optional fields `data[].channel` and `data[].firstTextSafe` to the reply-templates.list response. - [`reply-templates.list`](/docs/api/reply-templates/list.md)
- **Changed**: Added optional fields `data.channel` and `data.firstTextSafe` to the reply-templates.update response. - [`reply-templates.update`](/docs/api/reply-templates/update.md)

- Newer day: [2026-11-06](/docs/changelog/2026-11-06.md)
- Older day: [2026-11-04](/docs/changelog/2026-11-04.md)
- Every change: [/docs/changelog.md](/docs/changelog.md)
