External Approvals client_approvals
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through client_approvals_read and changes through client_approvals_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: campaign-batches-approve, touches-approve, approvals-bulk-decide, approvals-decide, get-item, get-settings, approvals-list, list-events, list-items, resend, restore-lead, touches-retry, rotate-link, update-settings
campaign-batches-approve
Write. POST https://api.ken.so/v1/campaign-batches/{campaignBatchId}/approve
Path: campaignBatchId
Body (json): count integer, updatedAt date-time
Approve a campaign batch as the caller's Kenso user: every email in it is released to send. Only when the person asked you to approve this batch, after seeing its samples.
POST /api/v1/campaign-batches/{campaignBatchId}/approve. Internal, behind the campaign_batches
flag. Sends Ken-Version 1.1, X-Ken-Workspace-Id and X-Ken-Actor: agent. Needs campaigns edit and
the approve permission. Approves as the caller's Kenso user (DEV-5878), recorded on the batch as
"<name> (agent)". Call it only when the person told you to approve this batch, after you showed
them its samples (campaign-batches-get).
- count: the batch's count from the version the person reviewed. When leads joined since,
nothing is approved: 409 conflict with batch_changed.
- updated_at: the batch's updatedAt from the campaign-batches-get the person reviewed. Send it:
a lead skipped, restored or edited since is then batch_changed too, even when the count
still matches. Omitted, only the count is checked.
Approving closes the batch and approves every lead in it; the next lead opens the next batch. The
workflow runs waiting on it send within about a minute. A batch that is not pending, waits on the
client, or that Ken did not finish rewriting (rewrite_incomplete) is 409 invalid_state. An API key
with no Kenso user gets 403 approval_requires_human. Returns the batch, status approved.
touches-approve
Write. Early access: needs accounts on for the workspace. POST https://api.ken.so/v1/touches/{touchId}/approve
Path: touchId
Body (json): recipientVersion string, updatedAt date-time
Approve a touch as the caller's Kenso user: an email or LinkedIn touch then sends, a call or task is done. Only when the person asked you to approve this touch; never approve touches you planned unasked.
POST /api/v1/touches/{touchId}/approve. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Approves as the caller's Kenso user (DEV-5878), as if they clicked approve in Today. Call it only
after the person saw this version of the touch and told you to approve it.
- updated_at: the touch's updatedAt from the version the person reviewed. A newer version is 409
conflict with concurrent_change and nothing is approved: read it again and ask again.
- recipient_version: the touch's recipientVersion from that version (optional): when the
person's email or LinkedIn URL changed since, approve is 409 concurrent_change.
An email or LinkedIn touch becomes approved and is queued to send 40 to 180 seconds from now
(never before its due time, and within the sender's sending window) from the account's Sends
from inbox or LinkedIn account; a call or task becomes done. An Instagram touch (instagram_dm,
instagram_follow, instagram_like, instagram_comment; instagram flag) becomes approved and waits
there until Kenso's Instagram sender takes it, from the account's Sends from Instagram account.
A Facebook touch (facebook_message, facebook_friend_request, facebook_follow, facebook_like,
facebook_comment; facebook_outreach flag) becomes approved and waits there until Kenso's
Facebook sender takes it, from the account's Sends from Facebook account; its approver is the
account owner.
Refusals: 403 approval_not_allowed (only the member whose inbox, LinkedIn or Instagram account
sends the touch, else the account owner, approves; the message names them), account_has_no_owner or
approval_requires_owner with the permissions rules on, 403 permission_denied without Accounts
edit and approve, 403 approval_requires_human for an API key with no Kenso user, 409
invalid_transition from a status that cannot be approved, 409 invalid_state with
voice_note_not_ready on voiceId for a whatsapp_message touch with a voice whose note is
not generated yet for its current text and voice (try again in a minute), 400 validation_failed
(instagramHandle required) for an Instagram touch whose person has no accepted Instagram handle
(verified or manual): accept the handle first. Same rule as
client_approvals(operation="approvals-decide") on touch_<id>.
approvals-bulk-decide
Write. Early access: needs accounts or linkedin_ai_notes or agent_templates or linkedin_engagement on for the workspace. POST https://api.ken.so/v1/approvals/decisions
Body (json): action string, filter object, ids array, items array
Decide many LinkedIn note, connection request or engagement approvals at once, as the caller's Kenso user. Only when the person asked for this bulk decision; never to clear your own items unasked.
POST /api/v1/approvals/decisions. Staff. Sends Ken-Version 1.1, X-Ken-Workspace-Id and
X-Ken-Actor: agent. Each item is decided as the caller's Kenso user, as the person's own "approve
all" would (DEV-5878). Call it only when the person told you to decide these items.
- action: notes take approve or send_without_note; connection requests take accept_as_lead,
accept_only or skip; LinkedIn engagement (likes, endorsements, comments) takes approve or skip.
- Exactly one of: ids (up to 500 ids of one type, lnote_123, linreq_123 or leng_123); items (up to 500,
each {"id": "lnote_123", "updatedAt": "..."} with the version the person reviewed: a note that
changed since fails with concurrent_change); or type with its filter, every pending item up to
500 per call: type campaign.linkedin_note or campaign.linkedin_engagement with campaign_id, or type
linkedin.connection_request with optional lane (strong, unclear or spam) and
linkedin_account_id (one of the caller's own seats).
Answers 200 with results, decided, failed and hasMore (a filter call left more: call again while
it is true). One failing item does not stop the rest. Item error codes: not_found,
unsupported_type, approval_requires_human (an API key with no Kenso user), invalid_transition,
approval_expired, seat_unavailable (use send_without_note), concurrent_change, too_long,
required, internal_error. Needs Campaigns edit plus approve, or approve_own_sends for notes from
seats the caller connected. A malformed call is 400 validation_failed.
approvals-decide
Write. Early access: needs accounts or linkedin_ai_notes or agent_templates or linkedin_engagement on for the workspace. POST https://api.ken.so/v1/approvals/{approvalId}/decisions
Path: approvalId
Body (json): action string, input object, params object, recipientVersion string, updatedAt date-time
Approve, edit, snooze or skip one approval as the caller's Kenso user. Approving a send sends it. Decide only when the person asked you to take this decision on this item; never clear your own proposals unasked.
POST /api/v1/approvals/{approvalId}/decisions. Staff. Sends Ken-Version 1.1, X-Ken-Workspace-Id
and X-Ken-Actor: agent. The decision is applied as the caller's Kenso user, as if they clicked it in
Today (DEV-5878): an approved touch or reply sends, an approved calendar change goes out, an
approved agent team proposal is applied. Call it only when the person told you to take this
decision on this item, after showing them the version they are deciding. Never use it to approve
proposals, drafts or touches you made yourself unless the person asked for exactly that.
- approval_id: the item's id from approvals-list (touch_9001, reply_4, calendar_write_12,
lnote_5, linreq_7, leng_8, request_501).
- action: one of the item's own action ids (approve, edit, snooze, skip, send_without_note,
accept_as_lead, accept_only).
- updated_at: the item's updatedAt from the version the person reviewed. Required to approve
(optional for a LinkedIn note); a newer version is 409 conflict with concurrent_change and
nothing is decided.
- recipient_version: a touch item's recipientVersion from that version (optional); when the
person's email or LinkedIn URL changed since, approve is 409 concurrent_change.
- action_params: the chosen action's params, echoed back unchanged.
- action_input: the chosen action's input by name, for example {"body": "..."} for a reply's
edit or a note's edited text, or {"clientYes": "Ana at Acme, call, 24 Oct"} for a proposal on
a client workspace.
Every other rule still applies: Accounts edit plus approve (Campaigns edit plus approve for a
LinkedIn note or a proposal), the approver rule (only the member whose inbox or LinkedIn sends the
touch, else the account owner: 403 approval_not_allowed; with the permissions rules on and no
owner, account_has_no_owner or approval_requires_owner), and the account scope (404 not_found).
An API key with no Kenso user gets 403 approval_requires_human. Only a pending item can be decided:
anything else is 409 invalid_state with invalid_transition. Returns the item in its new state.
get-item
Read. GET https://api.ken.so/v1/client-approvals/items/{itemId}
Path: itemId
Get one external approval item with what the client sees, their comments and its events.
GET /api/v1/client-approvals/items/{item_id}. Public. Sends Ken-Version 1.1
and X-Ken-Workspace-Id. Any member role. 404 when the item is not in the
workspace, or the member's pages do not cover its kind (replies need
Inbox, copy and lead lists Campaigns, orders Delivery, share items
Share). A reply item needs the inbox scope on an OAuth connection.
The item fields from list-items, plus snapshot (the copy, lead list, reply
or order exactly as the client reviews it; a lead list carries
removedContactIds), comments [{id, anchor, body, authorName, createdAt}]
and events (newest first, at most 200). In a copy snapshot, each of renders
is one message for one sample lead; a lead routed to another language renders
the approved localization, and that render also carries language (fr-FR),
mirrorSubject and mirrorBody (the English mirror, filled with the same
variables; a LinkedIn mirror has no subject), qaScore (0-100) and editedByHuman
(true when a person edited the localization after Ken wrote it, so the mirror
may not match it).
get-settings
Read. GET https://api.ken.so/v1/client-approvals/settings
Get the workspace's external approval settings: which kinds need the client's approval, reminder emails, the External approvals link and the pending count.
GET /api/v1/client-approvals/settings. Public. Sends Ken-Version 1.1 and
X-Ken-Workspace-Id. Requires the workspace_settings permission. 404 when the
client_approvals flag is off.
The External approvals link (portalUrl) needs no login for the partner's
client: whoever holds it can approve, so only workspace_settings reads it.
Rotate it when it leaks (rotate-link). The first read creates the settings
and the link.
Fields:
- rules {copy, leadList, reply, order}: require (the client approves first)
or auto (Ken goes ahead).
- reminderEmails: the client's addresses for the "items to approve" email
and the reminders.
- timeZone: IANA zone of the 9 AM daily reminder.
- portalUrl, portalTokenRotatedAt (null until the first rotation).
- approvalLinksEnabled: the white-label master's "External approval links"
switch. While false every rule acts as auto.
- pendingCount: items waiting on the client.
approvals-list
Read. Early access: needs accounts or linkedin_ai_notes or agent_templates or linkedin_engagement on for the workspace. GET https://api.ken.so/v1/approvals
Query: accountId integer, ids string, limit integer, type string
List what waits for a person's approval, soonest due first. Read only: approvals-decide decides one.
GET /api/v1/approvals. Staff. Sends Ken-Version 1.1 and X-Ken-Workspace-Id. Needs one of the accounts, linkedin_ai_notes, agent_templates or linkedin_engagement flags on for the workspace. A workspace with none of them gets an empty data list and a message, not an error. Without ids it lists the pending items in the workspace, soonest dueAt first. ids (up to 50, for example touch_9001) returns those items in any status, in that order; unknown ids are left out. type matches an item type or its prefix: touch, touch.email, reply, reply.email, calendar_write, campaign, campaign.linkedin_note, campaign.linkedin_engagement. account_id narrows to one account's touches and leaves replies, calendar changes and LinkedIn notes and engagement out. A campaign.linkedin_engagement item is a like, endorsement or comment a campaign LinkedIn step holds for approval (DEV-8448): its blocks show the post or skill and, for a comment, the exact text. limit 1-50 (default 10); pagination.hasMore says more pending items wait than the page shows. The caller sees only the items it may approve: touches, replies and calendar changes need the Accounts page, LinkedIn notes, LinkedIn engagement and agent team proposals need Campaigns edit plus approve, and a client seat sees only the items it approves. A calendar change is listed only to the member whose calendar it changes. Each item: id, type, title, dueAt, status, updatedAt and its actions. Show the items to the person; they decide in Today in Kenso, on the approval card, or by asking you to decide one with client_approvals(operation="approvals-decide").
list-events
Read. GET https://api.ken.so/v1/client-approvals/events
Query: before date-time, cursor string, itemId integer, limit integer
List the external approval event log, newest first: decisions, comments, lead removals, reminders, link rotations and rule changes.
GET /api/v1/client-approvals/events. Public. Sends Ken-Version 1.1 and X-Ken-Workspace-Id. Any member role. Leaves out the events of items the member's pages do not cover, as list-items does. Unlike list-items it does not check the inbox consent scope: reply item events keep their kind, subject key and decision comments (never the reply itself). item_id filters to one item. before is an ISO-8601 instant (exclusive upper bound); a cursor wins over it. limit 1-200 (default 50) and cursor from pagination.nextCursor. Each event: id, itemId, eventType (item_created, approved, changes_requested, commented, lead_removed, lead_restored, superseded, cancelled, reminder_sent, link_rotated, rules_changed, campaign_paused, campaign_resumed, classic_review_submitted; share links add share_created, share_viewed, share_reminder_sent, share_submitted, share_revoked, report_sent, decision_undone, and snapshot_refreshed when a new link gave a pending copy item frozen as raw templates its rendered copy), actorKind (reviewer, user, system), actorName (the client's typed name for a reviewer), actorUserId, data (event details) and createdAt.
list-items
Read. GET https://api.ken.so/v1/client-approvals/items
Query: campaignId integer, cursor string, kind string, limit integer, status string
List external approval items, newest first. Filter by status, kind or campaign.
GET /api/v1/client-approvals/items. Public. Sends Ken-Version 1.1 and X-Ken-Workspace-Id. Any member role, and the list holds only the kinds the member's pages cover at view: replies need Inbox, copy and lead lists Campaigns, orders Delivery. A connection without the inbox scope gets no reply items, and kind=reply is refused for it. Filters: status (pending, approved, changes_requested, superseded, cancelled), kind (copy, lead_list, reply, order), campaign_id. limit 1-200 (default 50) and cursor from pagination.nextCursor. A page can hold fewer items than limit; keep paging while pagination.hasMore is true. Each item: id, kind, status, title, campaignId, campaignName, subjectId, subjectKey, fingerprint, pausedCampaign (the item paused a running campaign; approval resumes it if approvals still hold the pause), createdByUserId, createdAt, decidedAt, decidedByName, decisionComment. superseded means a newer version replaced the item before a decision.
resend
Write. POST https://api.ken.so/v1/client-approvals/recipients/resend
Body (json): recipientEmail string
Email one reminder address a fresh External approvals link with what waits for approval.
POST /api/v1/client-approvals/recipients/resend. Internal. Sends Ken-Version 1.1 and X-Ken-Workspace-Id. Requires the workspace_settings permission. recipient_email must be one of the workspace's reminder emails (see client_approvals(operation="get-settings")). That address, and no other, gets the pending-approvals email with its own External approvals link, valid for 14 days. Use it when the client lost the email or the link expired. Answers 404 not_found while the workspace does not have onboarding_v5 on. Answers 202 with no body once the email went out. Errors: 400 validation_failed (not an email address), 404 not_found (not a reminder email), 409 conflict with detail code nothing_pending (no item waits), 429 quota_exceeded with detail code resend_cooldown (a link went to this address less than 10 minutes ago; Retry-After gives the seconds), 503 when the email could not be sent.
restore-lead
Write. POST https://api.ken.so/v1/client-approvals/items/{itemId}/leads/{contactId}/restore
Path: itemId, contactId
Put back a lead the client removed from a lead-list item.
POST /api/v1/client-approvals/items/{item_id}/leads/{contact_id}/restore.
Internal. Sends Ken-Version 1.1 and X-Ken-Workspace-Id. Requires the
workspace_settings permission.
The contact rejoins the campaign and leaves the item's removedContactIds.
A contact that was not removed is a no-op success. 400 when the item is
not a lead list or the contact is not on it. Returns {itemId, contactId,
restored}.
touches-retry
Write. Early access: needs accounts on for the workspace. POST https://api.ken.so/v1/touches/{touchId}/retry
Path: touchId
Body (json): recipientVersion string, updatedAt date-time
Send a failed email, LinkedIn, Instagram or WhatsApp touch again, as the caller's Kenso user. Only when the person asked you to retry this touch.
POST /api/v1/touches/{touchId}/retry. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
A retry approves the send again, so it follows touches-approve's rules (DEV-5878): call it only
when the person told you to send this failed touch again. Works only from failed on a send
channel (email, the LinkedIn channels, the Instagram channels, whatsapp_message); anything else is
409 invalid_transition. An Instagram touch that failed with outcome_unknown is refused with 409
invalid_transition ("Kenso cannot tell whether this Instagram action went out; check the
Instagram thread first"), because a resend could DM or comment twice: it stays failed, and
touches-update refuses to edit it the same way, until a person checks the Instagram thread and
skips it or plans a new touch.
- updated_at: the touch's updatedAt from the version the person reviewed (required).
- recipient_version: the touch's recipientVersion from that version (optional).
The touch goes back to approved, its attempts reset, and it sends 40 to 180 seconds from now under
the approval it already has. A touch with no approval is 409 approval_required: approve it with
touches-approve. Refusals are touches-approve's.
rotate-link
Write. POST https://api.ken.so/v1/client-approvals/settings/rotate-link
Issue a new External approvals link. The old link stops working at once.
POST /api/v1/client-approvals/settings/rotate-link. Internal. Sends Ken-Version 1.1 and X-Ken-Workspace-Id. Requires the workspace_settings permission. The External approvals link needs no login for the partner's client; rotate it when it leaks. Send the new portalUrl to the client. Returns the same settings as get-settings.
update-settings
Write. PATCH https://api.ken.so/v1/client-approvals/settings
Body (json): preset string, reminderEmails array, rules object, timeZone string
Change which kinds need the client's approval, the reminder emails or the reminder time zone. Omitted fields stay as they are.
PATCH /api/v1/client-approvals/settings {rules, reminderEmails, timeZone,
preset}. Internal. Sends Ken-Version 1.1 and X-Ken-Workspace-Id. Requires
the workspace_settings permission. Provide at least one field.
- rules: any of copy, lead_list, reply, order, each require or auto,
e.g. {"lead_list": "require", "reply": "auto"}. Kinds left out keep
their rule.
- reminder_emails: replaces the whole list, at most 20 addresses; [] clears it.
- time_zone: IANA zone, e.g. Europe/London.
- preset: recommended sets copy, lead list and order to require and reply
to auto; rules in the same call override it.
Returns the same settings as get-settings. A require rule holds new work
until the client approves it: launch and resume answer 409
approval_required, and a held reply answers 202 held_for_client_approval.