Today today
A member's queue for the day: touches waiting on them, tasks due today and setup rows, plus what they cleared today. Act on touch rows with account_touches. Also call tasks and the member's Call queue (call-tasks-*, call-queue-list), the member's logged calls and dialing (calls-*), and the call steps of a campaign or segment sequence (call-sequences-*, segment-call-sequences-*).
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through today_read and changes through today_write. Each takes operation plus that operation's parameters, and your workspace role decides which operations you see.
Each operation with a route calls the Kenso API at https://api.ken.so with Authorization: Bearer <Kenso API key>, Ken-Version: 1.1 and X-Ken-Workspace-Id: <workspace id>. You can call that route directly with the same headers.
Operations: call-tasks-create, calls-create, call-tasks-delete, calls-dial, call-sequences-get, call-tasks-get, calls-get, segment-call-sequences-get, get, call-queue-list, call-tasks-list, calls-list, calls-recording, call-sequences-replace, segment-call-sequences-replace, call-tasks-skip, call-tasks-snooze, call-tasks-update, calls-update, update
call-tasks-create
Write. Early access: needs calls on for the workspace. POST https://api.ken.so/v1/call-tasks
Body (json): assigneeMemberId integer, contactId integer, dueAt date-time, instructions string, personId integer, phone string, title string
Create a call task on a person or a contact, or get back the one already open. Create one only when the user asks for a call. The member places the call in the Kenso app.
POST /api/v1/call-tasks. Staff, or a workspace with the calls flag. Sends Ken-Version 1.1 and X-Ken-Actor: agent. Exactly one of person_id and contact_id (a contact's task is also on its person when it has one). due_at: ISO-8601 instant, default now, at most 90 days out. title: 1-200 characters. instructions: what to cover, up to 2000. assignee_member_id: a member of this workspace, default the caller (an API key with no member must send it). phone: any format, stored E.164 (a bad number is invalid_phone); without it the call uses the person's primary phone. The reason is manual, accountId the person's first account, expiresAt a week after due_at (after now for a past due_at); call.task_created goes on the person's timeline. When the person (else contact) already has an open call task, that task comes back with existing: true instead of a new one (one past its expiresAt is expired and a new task created). A member who works only their own accounts gets conflict call_task_exists with no task id when that task is assigned to someone else, and not_found for a contact whose person is not on their accounts.
calls-create
Write. Early access: needs calls on for the workspace. POST https://api.ken.so/v1/calls
Body (json): askedNotToBeCalled boolean, callTaskId integer, contactId integer, direction string, disposition string, durationSeconds integer, endedAt date-time, externalId string, followUpAt date-time, nextStep string, notes string, personId integer, phone string, recordingUrl string, startedAt date-time, touchId integer
Log a call a member made or took, with its outcome. The outcome moves the lead.
POST /api/v1/calls. Staff, or a workspace with the calls flag (accounts edit). Sends Ken-Version 1.1. Send person_id, contact_id, phone, call_task_id or touch_id (a call task or touch names its person; a phone no person or contact holds is person_not_found unless a call task or touch names the person). disposition (required): connected, voicemail, no_answer, busy, wrong_number, meeting_booked, not_interested. direction: outbound (default) or inbound. started_at (default now), ended_at, follow_up_at: ISO-8601 instants with an offset. duration_seconds gives ended_at when that is not sent. notes up to 20,000 characters, next_step up to 1,000. call_task_id (the call task this call worked) or touch_id (the call touch it is), not both. recording_url: an https link. external_id (up to 200): your own id; the same id from the same caller updates that call instead of adding one (200, not 201). Effects: the call task closes or retries, the touch completes, and the lead moves (connected: working; meeting_booked: qualified, the account to meeting_booked and its campaign stopped; not_interested: disqualified and its campaign stopped; wrong_number: the number marked invalid and a phone find queued). follow_up_at queues a follow-up call task, or moves the person's open one to then. The caller is the call's member. Returns the call. asked_not_to_be_called=true: the person asked on the call not to be called again. It opts the person out of calls (people-update phone_opt_out) before the call is logged; a call with no person fails, and if the opt-out fails nothing is logged. Send it only when the person said so: wrong_number alone never opts out.
call-tasks-delete
Write. Early access: needs calls on for the workspace. DELETE https://api.ken.so/v1/call-tasks/{callTaskId}
Path: callTaskId
Delete a call task. It leaves every list and the Call queue. Delete only when the user asks; skip a call that should not happen instead.
DELETE /api/v1/call-tasks/{callTaskId}. Staff, or a workspace with the calls flag. Sends
Ken-Version 1.1 and X-Ken-Actor: agent. Soft delete. Returns 204 (an empty result).
calls-dial
Write. Early access: needs calls on for the workspace. POST https://api.ken.so/v1/calls/dial
Body (json): callTaskId integer, force boolean, personId integer, phone string, touchId integer
Start a call in the member's own dialer, or get a tel: link. Only when the member asked to call now.
POST /api/v1/calls/dial. Staff, or a workspace with the calls flag (accounts edit). Sends Ken-Version 1.1. Send exactly one of call_task_id, touch_id (an account touch on the call channel; the call is to its stakeholder's person), person_id or phone (any format). The number is the task's, else the person's phone, else the task contact's. A connected dialer the member is linked on places the call on the member's device (status dialing, externalCallId) and Kenso logs the call: callId, with the task or touch it works and no disposition yet. Save the outcome with calls-update on that callId (it closes the task or completes the touch); the dialer's own events fill in its duration and recording. Without callId (status dialing for a number no person or contact holds) the dialer's event, or calls-create, logs it. Otherwise status tel with telHref, and nothing is logged: log the call with calls-create. no_number: the member's dialer user has no number to call from. agent_unavailable, no_number and failed keep telHref. Refusals: 409 opted_out (the person asked not to be called), 409 do_not_contact, 409 blocklisted or 409 unsubscribed (the person is marked do not contact, is on the workspace blocklist by their email or an account's domain, or unsubscribed; the built-in dialer refuses them the same way), 409 do_not_call (a provider the workspace's own key asked marked the person do not call; their stored numbers are not dialed), 409 no_phone (Kenso has no number for the person; find one on their account first), 409 outside_calling_hours (the person's calling hours; the error detail carries opensAt) and 409 limit_reached (the workspace's calls per person per day). force=true dials past limit_reached, never past calling hours, an opt-out, a suppression or do_not_call; send it only when the member says so. A touch_id of another channel is 400.
call-sequences-get
Read. Early access: needs sequence_call_steps on for the workspace. GET https://api.ken.so/v1/campaigns/{campaignId}/call-sequence
Path: campaignId
Return the campaign call lane: the call steps after its email steps. Needs the sequence_call_steps flag and Campaigns view.
GET /api/v1/campaigns/{campaignId}/call-sequence. Sends Ken-Version 1.1; client_id is
sent as X-Ken-Workspace-Id. The campaign's root lane by step_order: the steps a contact
gets while its segment has no call lane of its own. A campaign of another workspace,
or a workspace without the sequence_call_steps flag, is 404.
call-tasks-get
Read. Early access: needs calls on for the workspace. GET https://api.ken.so/v1/call-tasks/{callTaskId}
Path: callTaskId
Return one call task.
GET /api/v1/call-tasks/{callTaskId}. Staff, or a workspace with the calls flag. Sends
Ken-Version 1.1. Not found for another workspace's task, a deleted one, or another member's
when the member works only their own accounts. The task as call-tasks-list returns it.
calls-get
Read. Early access: needs calls on for the workspace. GET https://api.ken.so/v1/calls/{callId}
Path: callId
Return one call with its transcript.
GET /api/v1/calls/{callId}. Staff, or a workspace with the calls flag (accounts view). Sends
Ken-Version 1.1. Not found for another workspace's call or a deleted one. The call as calls-list
returns it, plus transcript when the dialer sent one. hasRecording true means calls-recording has a link.
segment-call-sequences-get
Read. Early access: needs sequence_call_steps on for the workspace. GET https://api.ken.so/v1/segments/{segmentId}/call-sequence
Path: segmentId
Return a segment's own call lane (empty while its contacts get the campaign's). Needs the sequence_call_steps flag and Campaigns view.
GET /api/v1/segments/{segmentId}/call-sequence. Sends Ken-Version 1.1; client_id is
sent as X-Ken-Workspace-Id. Empty while the segment has no call lane of its own, and
then its contacts get the campaign's lane (today(operation="call-sequences-get")).
A segment of another workspace is 404.
get
Read. Early access: needs accounts, today on for the workspace. GET https://api.ken.so/v1/today
Query: scope string, timezone string
Return the member's Today: open rows (touches, tasks, setup, touch plans, opportunities, meetings, replies, signals) and what they cleared today. Touch rows carry their approval id and the approval rule; act on them with the touches tools.
GET /api/v1/today. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
scope: mine (default; the member's accounts plus accounts with no owner) or everyone.
timezone: IANA zone that sets the day for a member with no app time zone, default UTC
(for example Europe/Bucharest); the member's app time zone (account get timeZone) wins.
data.items: hosting_setup first when an email row is open and no hosting hostname is
Ready, then Knowledge rows (knowledge_review_all, knowledge_daily) for a member with
Knowledge edit, and (meeting_call_types flag on, for a member who may approve and has
Meetings view) up to 10 kind meeting_follow_up rows, id meeting_follow_up_<meetingId>,
newest first, in both scopes: "Approve the follow-up to <recipient>", detail "After
<meeting title>", a no-account follow-up draft waiting for the member, who owns it.
followUpDraft is the draft as notetaker(operation="get-follow-up-draft") returns it; the
owner approves it in Kenso, and approving or skipping it clears the row. Then
(accounts_plan flag on) up to 50 paused and ended touch plan rows,
then opportunity rows oldest first, then send touches awaiting approval or failed (any
due date, except one snoozed past the end of the local day), approved send touches held because their Sends from inbox or LinkedIn
account needs reconnecting, and manual tasks (call, event, intro, task) due before the
end of the local day, by dueAt, then the remaining paused and ended rows and thin touch
plan rows. Each touch row has id (touch_<id>), kind (touch, task), title, dueAt, touch,
approval (canDecide, note) and notice, which never blocks approval: reconnect_inbox or
reconnect_linkedin when the account's Sends from inbox or LinkedIn account needs its
owner to reconnect it (label "<name> needs to reconnect their inbox", or "Reconnect
your inbox" for the member's own), else connect_inbox on an email row with no Sends
from inbox whose account owner has no connected inbox. A reschedule touch row (touch.reason
reschedule) also has atRisk true when its meeting has moved two or more times (needs the
meeting_rebook_chase flag; omitted otherwise). A meeting email touch row (touch.reason
meeting_email), open or in data.done, also has meetingChange: cancelled, no_show or rescheduled,
the meeting change the email answers (needs the meeting_rebook_chase flag; omitted otherwise
and on every other row). Touch plan rows are kind system with title, detail, account (id, name) and
plan (the account plan): plan_paused_<accountId> when a reply paused the plan (dueAt
is the pause; repliedBy is the sender when mapped; resume or end it with the account
plan tools), plan_ended_<accountId> for 7 days after a plan completed, and
plan_thin_<accountId> for an active plan with plan.thin (fewer live steps than the
plan minimum, 8 by default; map more people). Opportunity rows show only while the
workspace has the opportunities flag, for the last 30 days:
- kind opportunity_suggestion, id opportunity_suggestion_<id>: an interested reply or
a booked meeting from a personal email address (gmail.com and the like), so Ken made
no opportunity. suggestion has signal (interested, meeting_booked), email, name,
ownerMemberId, campaignId, threadId, meetingId, occurredAt. Create the opportunity
on an account with that person and the row goes.
- kind opportunity_no_show, id opportunity_no_show_<id>: a meeting on an open deal
was a no-show. opportunity is the deal; noShow has meetingId, meetingAt and
recordedAt. It goes once the deal changes stage, closes or is deleted.
- kind opportunity_quiet, id opportunity_quiet_<id> (also needs the deal_quiet flag):
"<deal> went quiet", an open deal whose account had no reply, held meeting or
connected call for the workspace's quietAfterDays and has no meeting booked ahead
(not cancelled, starting later). opportunity is the deal (its
quietSince is when the silence began); quiet has lastActivityAt, lastActivityKind
(reply, meeting, call, or created when there was none since the deal opened),
daysQuiet, thresholdDays and recordedAt. It goes once a reply, held meeting or
connected call lands, a meeting is booked, or the deal closes or is deleted (it
comes back if that meeting is cancelled or starts without being held), and like
the other opportunity rows 30 days after recordedAt even while the deal stays quiet (the
opportunity's quietSince still shows it). Dismiss it with
today(operation="update") state done, or draft a check-in with action draft_nudge.
Then, with the lead_intake flag on, people lead intake created in the last 7 days, oldest
first:
- kind new_lead, id new_lead_<capturedEventId>: "New lead: <name> at <account>", detail
the title and where the lead came from ("via form · Pricing page"). lead has personId,
accountId, name, title, accountName, source, sourceDetail, ownerMemberId and capturedAt.
In mine, leads the member owns or nobody owns. It goes when the person is deleted or
merged.
- kind merge_suggestion, id merge_suggestion_<id>: "Are <name> and <name> the same
person?", detail why ("Same phone number · Same name and email domain"), oldest first
after the touches and new leads. duplicate has duplicateId, personId, otherPersonId,
reasons (email_local_part, phone, name_account, name_domain), foundBy (intake, sweep),
personA, personB (person summaries) and suggestedAt. In mine, pairs where the member
owns either person or neither has an owner; under account scope own, only pairs whose
two people are both on the member's accounts. Merge with people(operation="merge")
and the row goes; it also goes when either person is deleted.
At most 200 of those. After them, outside the 200, with the calls flag on, the calls
group, the member's own calls in both scopes:
- kind call, id call_task_<callTaskId> or a call touch's touch_<touchId>: "Call <name>",
detail the title and company. The first 2 rows of the member's Call queue due by the
end of the local day, in queue order (callable first); call carries the queue item as
today(operation="call-queue-list") returns it. While calls is on, call touches show
here and not as task rows, so in everyone teammates' call touches are not on Today
(they are on each member's Call queue).
- kind call_disposition, id call_<callId>: "How did your call with <name> go?", a call
a dialer logged (or an answered browser call that ended, source ken) for the
member in the last 3 days with no outcome, newest first, up to 50. loggedCall has
callId, personId, contactId, accountId, name, number, source, direction, startedAt
and durationSeconds.
data.calls (null while calls is off): open and callableNow as
today(operation="call-queue-list") counts the member's queue ("All calls · N"), and
dueToday, the calls due by the end of the local day the member has not cleared from
Today. Then up to 50 rows each of these, the
meeting kinds only with the meetings flag on and Meetings view, reply only with Inbox
view, signal only with the accounts_signals flag on:
- kind meeting_notes, id meeting_notes_<meetingId>: "Add notes for <title>", an
account meeting that ended 24 hours to 7 days ago, was not cancelled, and has no
notes: none ready, no rep note, no transcript of any source, no attached notes
source and no notes search still running; oldest first. meeting.candidates is the
number of calls the search left for "Which call is this?" on the Notes tab (0 when
it found none); the detail says so.
- kind reply, id reply_email_<n> or reply_linkedin_<n>: a thread on the inbox To Reply
tab, newest first. title is the sender, detail the lead's reply text as a
140-character preview, else the subject when the reply has no text, dueAt the
thread's reminder. reply has threadId (thr_), channel (email, linkedin), fromName,
fromEmail, company (the lead's company, when known), subject, preview, interest,
receivedAt, reminderAt and campaignId; no account. In mine, threads whose owner (the inbox owner, else the
campaign creator, each only while an active member) is the member, or that have no
such owner.
- kind meeting, id meeting_<meetingId>: a meeting that starts today and has not ended
or been cancelled, by start; detail is the account name, dueAt the start.
Both meeting kinds carry meeting (id mtg_<id>, title, startsAt, endsAt, accountId,
ownerMemberId, meetingUrl; candidates on meeting_notes only) and account when the
meeting has one.
- kind signal, id signal_<signalId>: an account signal detected in the last 7 days
(reply and meeting signals left out), newest first, with signal and account.
In mine these are the member's own meetings, and signals on their accounts or accounts
with no owner. data.hasMore says more rows exist than data.items holds. data.groups
names the later groups whose gate passed (calls, meeting_notes, reply, meeting,
signal), rows or not. data.done: rows the member acted on today, newest first, each with
doneAs: approved (a touch they approved), done (marked done), snoozed (snoozed on Today)
or skipped (a touch they skipped or snoozed on the touch routes and did not undo). With the
campaign_batches flag on, done also lists kind campaign_batch, id campaign_batch_<batchId>: a
campaign batch the member approved (doneAs approved) or sent back (doneAs done) today and
that is not pending again, with campaignBatch as
campaign_ops(operation="campaign-batches-list") returns it.
data.brief: Ken's read of the day, from the daily brief's counts and the rows above,
with no model call. greeting is a short line for the member's local time ("Up late?",
"Good morning.", "Happy weekend.") with their first name when known: late night
22:00-04:59, weekend (the rest of Saturday and Sunday), early morning 05:00-07:59,
morning 08:00-11:29, lunch 11:30-13:29, afternoon 13:30-17:29, evening 17:30-21:59;
within a band the member keeps one line all local day. text is at most two sentences: the
replies waiting ("<sender> is waiting on your reply." or "<n> replies are waiting on
you.") and the next meeting today ("Your next meeting is <title> at 2:30 PM."); with
neither, the daily brief's counts ("3 to approve, 2 tasks due."), or "Your Today is
clear."; with calls on the counts add calls.dueToday ("1 task due, 4 calls due."). In
scope everyone the text drops "you" and "your" (the rows are the team's).
needsYou counts touches to approve, failed or waiting on a sender, tasks due, and
meeting_notes, call and call_disposition rows. chips (at most 3, each with label, prompt and
focus): prep the next meeting, who at the first plan_thin account is untouched, what changed
at the newest signal's account. label names the meeting or account and is for display only;
prompt is fixed text that names no record ("Prep me for this meeting", "Who at this account
have we not touched yet? Suggest who to add to the plan.", "What changed at this account?
Start with the newest signal."); focus is the record it asks about, {meetingId (mtg_...),
accountId} on the prep chip (accountId omitted when the meeting has none) and {accountId} on
the others. Send prompt with focus, never the label, to Ken.
data.batches (campaign_batches flag on and Campaigns view, else empty): every campaign batch waiting for
approval, oldest first, whatever the scope, each as
campaign_ops(operation="campaign-batches-list") returns it. The
credential must carry a person.
call-queue-list
Read. Early access: needs calls on for the workspace. GET https://api.ken.so/v1/call-queue
Query: assignee string, due string, limit integer, timezone string
Return a member's Call queue: who to call, callable first, with phone, local zone and when each can be called.
GET /api/v1/call-queue. Staff, or a workspace with the calls flag. Sends Ken-Version 1.1. Open call tasks that have not expired, assigned to the member, and open call touches (planned, drafted, awaiting approval, failed) on the member's accounts or accounts with no owner. assignee: "me" (default) or, for a workspace admin, a member id (else 403). due: now, today (before the end of the local day in the caller's app time zone, else timezone, IANA, default UTC) or all (default). limit 1-200 (default 50); pagination.hasMore says more exist (no cursor). Each item: id (task_<id> or touch_<id>), callTaskId or touchId, personId, contactId, accountId, name, title, company, phone (the task's, else the person's primary phone, else the contact's), dueAt, callableNow (due, in the calling window, under the limit and with a phone), opensAt (when the window or the limit lets it be called: the window start; with limitReached, the next day's window, or local midnight while any time is callable; never before dueAt), notCallableReason (opted_out: the person asked not to be called, and opensAt is omitted; do_not_contact, blocklisted or unsubscribed: the person is marked do not contact, is on the workspace blocklist by their email or an account's domain, or unsubscribed, so they are not dialed and opensAt is omitted; do_not_call: a provider the workspace's own key asked marked the person do not call, so their stored number is not dialed and opensAt is omitted; no_phone: no number, so not callable until one is added), timeZoneId, zoneSource (account, phone, owner, default), limitReached (the calls per person per day limit), reason, callTitle and note (what the call is for: a task's title and instructions, a touch's title and rationale; null when blank), campaignId, attempts, briefReady (a model brief is ready: committee(operation="call-tasks-get-brief") reads a task's, meeting_notes(operation="touches-get-call-brief") a touch's). Order: callable first, then dueAt, then id. counts: open and callableNow over the queue read (at most 500).
call-tasks-list
Read. Early access: needs calls on for the workspace. GET https://api.ken.so/v1/call-tasks
Query: accountId integer, assignee string, campaignId integer, cursor string, due string, limit integer, personId integer, status string, timezone string
List call tasks: calls members should make to people and contacts, by due time. Work a member's calls in order with today(operation="call-queue-list") instead.
GET /api/v1/call-tasks. Staff, or a workspace with the calls flag. Sends Ken-Version 1.1. assignee: "me" or a member id; omitted lists every member's tasks (a member who works only their own accounts always gets only their own, and naming another member is 403). status: open, done, skipped, expired; comma = OR. due: now (due before now), today (before the end of the local day, overdue included) or overdue (before the local day started), in the caller's app time zone (account get timeZone), else timezone (IANA, default UTC). person_id, account_id, campaign_id narrow the list. limit 1-200 (default 50); cursor from pagination.nextCursor. Each task: id, kind (call), status (open, done, skipped, expired), reason (sequence, plan, signal, manual, reply, follow_up), personId, contactId, accountId, campaignId, assigneeMemberId, dueAt, expiresAt, phone, title, instructions, briefWrittenAt, attempts, snoozeCount, callId, doneAt, skipReason, createdAt, updatedAt.
calls-list
Read. Early access: needs calls on for the workspace. GET https://api.ken.so/v1/calls
Query: accountId integer, campaignId integer, cursor string, disposition string, from date-time, limit integer, memberId integer, personId integer, to date-time
List logged calls, newest first, with their outcome, notes and next step.
GET /api/v1/calls. Staff, or a workspace with the calls flag (accounts view). Sends Ken-Version 1.1. person_id, account_id, member_id (the member who made or took the call) and campaign_id narrow the list. from_time (started at or after) and to_time (started before) are ISO-8601 instants with an offset; either may be sent alone. disposition: connected, voicemail, no_answer, busy, wrong_number, meeting_booked, not_interested; comma = OR. limit 1-200 (default 50); cursor from pagination.nextCursor. Each call: id, personId, contactId, accountId, campaignId, callTaskId, touchId, memberId, direction (outbound, inbound), source (manual, api, webhook, aircall, ringover), disposition (omitted while a dialer's call has none), startedAt, answeredAt, endedAt, durationSeconds, talkSeconds, notes, nextStep, followUpAt, fromNumber, toNumber, hasRecording, externalId, externalUrl, summary, createdAt, updatedAt. The list leaves out transcripts: calls-get returns one.
calls-recording
Read. Early access: needs calls on for the workspace. GET https://api.ken.so/v1/calls/{callId}/recording
Path: callId
Return a link to a call's recording.
GET /api/v1/calls/{callId}/recording. Staff, or a workspace with the calls flag (accounts view).
Sends Ken-Version 1.1. The route redirects to the recording: a fresh link from the dialer that logged
the call while it is still connected, else the https link the call was logged with. Returns
{"url": ...}; the recording itself is never downloaded here. Dialer links expire, so fetch a new
one rather than keeping it. No recording is not found.
call-sequences-replace
Write. Early access: needs sequence_call_steps on for the workspace. PUT https://api.ken.so/v1/campaigns/{campaignId}/call-sequence
Path: campaignId
Body (json): steps array
Replace the campaign call lane with steps (the whole lane; [] clears it). Needs the sequence_call_steps flag and Campaigns edit.
PUT /api/v1/campaigns/{campaignId}/call-sequence. Sends Ken-Version 1.1; client_id is
sent as X-Ken-Workspace-Id. anchor_email_step_order is a step of the campaign's email
sequence. A campaign of another workspace is 404.
steps is the whole lane: a stored step left out is deleted, and [] clears the lane.
Each step:
- id: a stored step to update; omitted or 0 adds one.
- step_order (required, 1 or more): the step's place in the lane. Two active steps
cannot share one.
- anchor_email_step_order (required): the step_order of the email the call comes after,
in the email sequence this lane's contacts get. A lane with no email sequence takes
no call step.
- position_in_gap (0 or more, default 0): orders calls anchored to the same email.
- wait_days (0 to 365, default 0): days after that email.
- name (up to 100 characters), instructions (up to 2000 characters, the call task's
instructions), is_active (default true).
- find_phone (default true): queue a phone find for a contact without a number.
- skip_without_phone (default true): skip the step when no number is known by then.
- assignee_mode: campaign_owner (default), account_owner or member.
assignee_member_id: a workspace member, with member only.
camelCase keys (stepOrder, anchorEmailStepOrder, ...) work too.
Every invalid field comes back in one 400 validation_failed (details[].field) and
nothing is written. Returns the lane as stored: {campaignId, segmentId, steps}.
segment-call-sequences-replace
Write. Early access: needs sequence_call_steps on for the workspace. PUT https://api.ken.so/v1/segments/{segmentId}/call-sequence
Path: segmentId
Body (json): steps array
Replace a segment's own call lane with steps (the whole lane; [] clears it). Needs the sequence_call_steps flag and Campaigns edit.
PUT /api/v1/segments/{segmentId}/call-sequence. Sends Ken-Version 1.1; client_id is
sent as X-Ken-Workspace-Id. anchor_email_step_order is a step of the email sequence
the segment's contacts get: the segment's own when it has steps, else the campaign's.
A segment of another workspace is 404. Step fields match the campaign call lane
(today(operation="call-sequences-replace")).
call-tasks-skip
Write. Early access: needs calls on for the workspace. POST https://api.ken.so/v1/call-tasks/{callTaskId}/skip
Path: callTaskId
Body (json): reason string
Skip an open call task, with why: no_phone, not_relevant or other.
POST /api/v1/call-tasks/{callTaskId}/skip. Staff, or a workspace with the calls flag. Sends
Ken-Version 1.1 and X-Ken-Actor: agent. reason: no_phone, not_relevant or other. The task
becomes skipped with skipReason and doneAt and leaves the Call queue; call.task_skipped goes
on the person's timeline. Reopen it with today(operation="call-tasks-update") and status
open. A task that is not open is invalid_state. A task another writer changed
meanwhile is conflict call_task_changed: read it again and retry. Returns the
task.
call-tasks-snooze
Write. Early access: needs calls on for the workspace. POST https://api.ken.so/v1/call-tasks/{callTaskId}/snooze
Path: callTaskId
Body (json): until date-time
Move an open call task to later, by default the next day's calling window.
POST /api/v1/call-tasks/{callTaskId}/snooze. Staff, or a workspace with the calls flag.
Sends Ken-Version 1.1 and X-Ken-Actor: agent. until: ISO-8601 instant in the future, at
most 90 days out. Without it the task moves to 08:00 the next weekday in its zone while the
workspace keeps calls to business hours, else to a day from now. expiresAt moves with it and
snoozeCount goes up by one. A task that is not open is invalid_state. A task another writer changed
meanwhile is conflict call_task_changed: read it again and retry. Returns the
task.
call-tasks-update
Write. Early access: needs calls on for the workspace. PATCH https://api.ken.so/v1/call-tasks/{callTaskId}
Path: callTaskId
Body (json): assigneeMemberId integer, dueAt date-time, instructions string, phone string, status string, title string
Change an open call task's due time, title, instructions, assignee or phone, or reopen a skipped or expired one.
PATCH /api/v1/call-tasks/{callTaskId}. Staff, or a workspace with the calls flag. Sends
Ken-Version 1.1 and X-Ken-Actor: agent. Absent fields stay unchanged. changes keys
(snake_case or wire camelCase): due_at (ISO-8601 instant, at most 90 days out;
moves expiresAt with it),
title (null clears), instructions (null clears), assignee_member_id (a member of this
workspace, not null), phone (null clears; a bad number is invalid_phone), status (only "open": reopens
a skipped or expired task, clears its skip reason and keeps it in the queue another week).
A done task stays done (invalid_state). When the person already has another open task the
reopen is conflict call_task_exists with that task's callTaskId (one past its expiresAt is
expired instead). A task another writer changed
meanwhile is conflict call_task_changed: read it again and retry. Skip a task
with today(operation="call-tasks-skip"). Returns the task.
calls-update
Write. Early access: needs calls on for the workspace. PATCH https://api.ken.so/v1/calls/{callId}
Path: callId
Body (json): askedNotToBeCalled boolean, disposition string, followUpAt date-time, nextStep string, notes string
Change a call's outcome, notes, next step or follow-up.
PATCH /api/v1/calls/{callId}. Staff, or a workspace with the calls flag (accounts edit). Sends
Ken-Version 1.1. changes: disposition (cannot be null), notes (up to 20,000, null clears), next_step
(up to 1,000, null clears), follow_up_at (ISO-8601 instant with an offset, null clears),
asked_not_to_be_called (true opts the call's person out of calls, as on calls-create; a call with no
person fails; false changes nothing, and people-update phone_opt_out=false clears an opt-out). Absent
keys stay. The first disposition a call gets runs its effects as on calls-create; changing it later
only records the change. A new follow_up_at queues a follow-up call task. Returns the call.
Example: changes={"disposition": "meeting_booked", "next_step": "Send the deck"}.
update
Write. Early access: needs accounts, today on for the workspace. PATCH https://api.ken.so/v1/today/items/{todayItemId}
Path: todayItemId
Body (json): action string, snoozedUntil date-time, state string, timezone string
Mark a Today row done, snooze it, or show it again, for the member only; or draft a nudge on a quiet deal row. The touch itself does not change; a reply row's thread and a merge suggestion's pair do. Snooze a touch's due date with api_touches_snooze.
PATCH /api/v1/today/items/{todayItemId}. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. today_item_id: touch_<id> (a touch in this workspace, else
not found), hosting_setup, knowledge_review_all, knowledge_daily,
plan_paused_<accountId>, plan_ended_<accountId> or plan_thin_<accountId> (an account
in this workspace, else not found; the row comes back when the plan pauses, ends or
starts again), opportunity_suggestion_<id>, opportunity_no_show_<id> or
opportunity_quiet_<id> (not found when the workspace lacks the opportunities flag, or
for a quiet row the deal_quiet flag), new_lead_<id> (not found without the
lead_intake flag or outside the member's account scope), merge_suggestion_<id> (not
found without the lead_intake flag, once merged, or under account scope own unless both
people are on the member's accounts), meeting_<meetingId> or
meeting_notes_<meetingId> (a meeting the member can see, else not found; not found
without the meetings flag), signal_<signalId> (a signal on an account in the
member's scope, else not found; not found without the accounts_signals flag), and
reply_email_<n> or reply_linkedin_<n> (a thread in this workspace, else not found;
403 without Inbox edit), and call_task_<callTaskId> (a call task assigned to the member)
or call_<callId> (a call the member logged), not found without the calls flag. done on
a call row hides the row only: the task stays open and in the Call queue. A reply row writes to its thread the way threads(operation="update")
does: done archives it, marks it read and clears a due reminder (it leaves To Reply),
snoozed sets its reminder to snoozed_until, open puts back what done or snoozed
changed (archived, read, saved, the reminder) while nobody changed it since. A failed
thread read or write stores nothing. done on a merge_suggestion row is "Not a
duplicate" for the whole workspace: Ken never suggests that pair again and it leaves
every member's Today, so it needs accounts edit (403 without it, nothing written);
open undoes the member's own dismiss; snoozed only hides it for the member.
state: done (hidden until the next local midnight in the member's app time zone, else
timezone, IANA, then required with done; done on an opportunity, new_lead, merge_suggestion, meeting_notes or signal row dismisses it for good), snoozed (hidden until
snoozed_until, an ISO-8601
instant in the future and at most 90 days out; required for snoozed and refused
otherwise) or open (shown again; succeeds when nothing was hidden). Returns id, state
and until (omitted for open).
action (instead of state, never with it): draft_nudge, on an opportunity_quiet_<id> row
only. Only on the user's explicit request. It creates one planned email touch (reason
signal, due now, no body, title "Nudge: <deal>") to the deal's primary person, else the
account's stakeholder with the most recent reply or connected call. Ken's writer drafts
the body for approval; nothing is sent. A second call returns the same touch, or drafts a
new one when that touch was deleted. The row is
then done for 30 days. Returns id, state done, until and touchId (approve or edit it
with the touches tools). Needs accounts edit (403 without it) and the accounts_writer
flag (400 writer_off without it); 422 no_recipient when nobody on the account can get
it (set the deal's primary person to a stakeholder with an email).