Kenso MCP tools

Campaigns campaigns

A campaign's AI prompts: prompts(operation="list", campaign_id), alone. pause stops a campaign's sending, processing and AI workflows together: call it directly to stop any of them. resume starts a Draft (enrichment, verification and AI workflows; spends credits) or resumes a paused campaign; launch starts sending. update takes flat fields: auto_launch_when_ready=true launches it once Ready; sending_days with a weekend day needs confirm_weekend_sending=true and sending_days_requested_by (who asked, where, when). duplicate with include_contacts=true copies the leads. A read by campaign_id needs no check that the campaign exists: an unknown id comes back not found. Who clicked its links, by name: contacts search with campaign_ids=[id], sort="totalClicks", direction="desc". Its links and UTM tags: tracking_links tracking-links-list.

Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through campaigns_read and changes through campaigns_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: archive, create, create-enrichment-run, delete, duplicate, get, get-linkedin-settings, get-processing-status, get-scoring, launch, list, list-linkedin-accounts, pause, replace-linkedin-accounts, replace-linkedin-settings, replace-scoring, resume, retry-enrichment, run-scoring, update

archive

Write. POST https://api.ken.so/v1/campaigns/{campaignId}/archive

Path: campaignId

Archive a campaign: hides it from the default list and cancels its queued sends. Leads, replies and stats stay; its leads still count as duplicates for new campaigns. Idempotent. A campaign still sending returns 409 invalid_state: pause it first.

POST /api/v1/campaigns/{campaignId}/archive. Public. Sends Ken-Version 1.1.
Requires Campaigns edit and the `launch` permission. Undo with
campaign_ops(operation="unarchive", campaign_id=...).

create

Write. POST https://api.ken.so/v1/campaigns

Body (json): contactLimit integer, kind string, name string, roleId integer, source string

Create a campaign in the current workspace. Returns 201 and Location. Reserves the campaignCreate abuse quota.

POST /api/v1/campaigns. Public. Sends Ken-Version 1.1.

name is required. contact_limit, when set, must be greater than 0.
kind is sales (default) or recruiting. A sales campaign starts with stopCompanyOnReply on (a
reply also stops the rest of the lead's company); turn it off with
campaigns(operation="update", stop_company_on_reply=False). A recruiting campaign needs the
recruiting flag for the workspace, else 400 validation_failed with detail code
feature_disabled, and starts with stopCompanyOnReply, groupSameCompanySends and same-company
Cc off, so one candidate's reply never stops the others at the same employer. role_id is its
primary role, a live role of this workspace (else 404 not_found); with a sales kind it is 400
with detail code not_recruiting.
contact_limit is the contact cap, not the import cap. A contact is a
profile that is qualified and has a safe email. The campaign accepts up
to 10 times contact_limit in profiles. Import more profiles than the
contact target. An import does not spend the contact allowance.
When the campaign's contactLimitPeriod is month, contact_limit is contacts per
UTC calendar month: the count starts again on the 1st, and the profile cap is 10
times the contacts counted before this month plus contact_limit.
Requires Campaigns edit.

create-enrichment-run

Write. POST https://api.ken.so/v1/campaigns/{campaignId}/enrichment-runs

Path: campaignId

Body (json): minConfidence number

Queue enrichment for a campaign. Returns an enrichment job. min_confidence defaults to 0.5. Requires Campaigns edit.

POST /api/v1/campaigns/{campaignId}/enrichment-runs. Public. Sends Ken-Version 1.1.
The request finishes when Search accepts the batches. Poll the job with type enrichment.
A campaign outside the workspace is not_found before the run.
Each valid email Ken finds costs 1 credit ($0.02). Emails found with the
workspace's own provider key and uploaded emails are free.

delete

Write. DELETE https://api.ken.so/v1/campaigns/{campaignId}

Path: campaignId

Soft-delete a campaign. Returns 204. Requires Campaigns edit.

DELETE /api/v1/campaigns/{campaignId}. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id.

duplicate

Write. POST https://api.ken.so/v1/campaigns/{campaignId}/duplicate

Path: campaignId

Body (json): includeContacts boolean, name string

Duplicate a campaign inside the current workspace. include_contacts copies contacts. The copy stays in this workspace.

POST /api/v1/campaigns/{campaignId}/duplicate. Public. Sends Ken-Version 1.1.

Returns 201 and Location. Requires Campaigns edit. Reserves the campaign
duplicate abuse quota. Omit name to keep a generated copy name.

get

Read. GET https://api.ken.so/v1/campaigns/{campaignId}

Path: campaignId

Return one campaign in the current workspace. A missing or cross-workspace id is not_found. The payload includes the send schedule.

GET /api/v1/campaigns/{campaignId}. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id.

sendingDays is 0 (Sunday) through 6 (Saturday). sendingStartTime, sendingEndTime,
sendingTimezone, and maxEmailsPerDay are omitted when unset.
status is the collapsed lifecycle, so a sending campaign is active.
sendingStatus is the sequencer state. processingStatus is flag names, or ["none"].
sourceStatus is the stored pipeline status: to_scrape, in_progress, scraped, error, done, or draft.
sendingError is the current hard-failure error text (failure class, count in the last
60 minutes, affected inboxes) and sendingErrorAt is when it began. Both are null or
omitted when there is no error. The error clears itself and never pauses the campaign.
protectAccountPlays is true when the campaign skips people in active account plays
(accounts in stage warming, engaged, meeting_booked or in_deal). New campaigns default to true.
It acts only when account plays are on for the workspace. Counts:
campaign_ops(operation="get-account-play-protection").
approvalsWaiting is how many of the campaign's leads wait in campaign batches for a
person's approval (pending or rewriting); 0 without the campaign_batches flag. Read
them with campaign_ops(operation="campaign-batches-list").
contactCount is the contacts found with a valid email. leadCount is every non-deleted
contact in the campaign, with or without an email, so a LinkedIn-only campaign shows its
leads there while contactCount stays 0. leadCount is omitted when it cannot be counted.
readyLeadCount is the leads ready for their first email: qualified, with a valid email and
every personalization variable its sequence uses, not yet sent email 1 or accepted for sending, and not
stopped by a reply, a hard bounce or an unsubscribe (the same count as
awaitingFirstEmailCount below). It is counted live for up to 2 seconds, then the last
stored count is returned; it is omitted when there is none.
inboxCount is how many inboxes the campaign sends from (0 with none), omitted when it
cannot be read.
contactLimitPeriod is month or total. month: contactLimit is new qualified contacts with a
safe email per UTC calendar month, contactLimitUsed is this month's count,
contactLimitResetsAt is the next 1st (00:00 UTC), and fairUseContactLimit (1,000,000) caps
the lifetime count. total: contactLimit is a lifetime cap and contactLimitUsed equals
contactCount. contactLimitReached is true while processing is stopped, and
contactLimitReachedReason says why: monthly_limit (resumes on contactLimitResetsAt),
contact_limit, fair_use or lead_credits.

Campaign settings:
ownerMemberId is the owner's member id: the owner set on the campaign, else the member
who created it while they are still in the workspace. Omitted when neither.
stopOnReply (default true): a reply stops the lead's sequence. When false, neutral and
positive replies keep it going; negative replies, unsubscribes and booked meetings still stop it.
trackClicks (default true): links in an email sent as HTML go through tracking links. An
email sent as plain text (sendAsPlainText) never carries a click-tracking link and counts
no clicks: each link shows its real address without https://.
trackOpens: always false. Campaign emails never carry an open-tracking pixel. Opens are not
tracked and are never reported.
unsubscribeLink (default true): sends carry the List-Unsubscribe headers. When false they
are left out of a step whose body has the {{unsubscribe_link}} URL; a step without it keeps
them, so every send has an opt-out.
stopOnReply, trackClicks and unsubscribeLink are the stored values. They change sending only
when the workspace has the campaign_send_settings flag on; without it every campaign sends with
the defaults.
sendAsPlainText (default false): emails written as HTML go out as plain text only (text/plain,
no HTML part), with no click-tracking link: each link shows its real address without
https://, and a linked word inside a sentence keeps its words with the address in brackets. Steps with a drawn handwritten letter, a video, a Studio email, a provider-built
message or any image in the sent body (a signature logo counts) keep their HTML. Kenso can turn
plain-text sending off for
every campaign at once, so a campaign with it on may still send HTML. It needs no flag. A
duplicate in the same workspace keeps it; a copy into another workspace starts with it off.
Change it with campaigns(operation="update", send_as_plain_text=...).
replyTo is the stored campaign Reply-To override, omitted when unset (the workspace
default then applies). Change it with campaigns(operation="update", reply_to=...).
stopCompanyOnReply: a reply also stops the rest of the lead's company. New campaigns start
with it on; a duplicate keeps its source's value.
Change it with campaigns(operation="update", stop_company_on_reply=...).
newLeadsFirst (default false): first emails take the campaign's daily capacity ahead of its
follow-ups, so every lead gets email 1 before older leads get their next step. While it is
true, awaitingFirstEmailCount is the ready leads still waiting for their first email (no
email sent and none accepted for sending). Not counted: paused segments, leads the ready
checks hold back, company Cc members, bulk-paused leads (they get email 1 once resumed),
and leads the sequencer never sends email 1 to (a sequence stop such as a company reply, a
hard bounce, an unsubscribe). Still counted: leads
waiting for campaign batch approval, leads an enforced account play holds, and leads whose
email is live in another campaign. It reaches 0 once every other ready lead has had email 1;
if it stops falling above 0, the rest are those waiting leads. It is omitted while
newLeadsFirst is false, on the list, and when it cannot be counted. Every copy starts with
newLeadsFirst off: a duplicate, a template saved from the campaign, and a draft made from
that template. Change it with campaigns(operation="update", new_leads_first=...).
catchAllLaneEnabled (default false): the campaign opts in to the catch-all lane. The lane
sends to unverified CatchAll addresses whose catch-all score clears a bar, from the
workspace's own inboxes, capped per campaign and per inbox per day, and a bounce circuit
breaker pauses it. Off, the campaign never sends to a CatchAll address. It does nothing
until Kenso turns the lane on platform-wide. Every copy (a duplicate, a template, a draft
from a template) starts with it off. Change it with
campaigns(operation="update", catch_all_lane_enabled=...).
catchAllLanePausedAt: when the lane's bounce circuit breaker paused it (the hard-bounce
rate on lane sends went over the bar), UTC. The sequencer sets and clears it; no request
writes it. Omitted while the lane is not paused.
excludedCountries: ISO 3166-1 alpha-2 codes (sorted) the campaign never sends to; [] blocks
none (the default). Imports drop a lead whose country is listed (countryExcluded on the import
run, or rejected with country_excluded) and the sequencer skips one already on the campaign.
Change it with campaigns(operation="update", excluded_countries=...).
emailVerifiers (get only): the campaign's email verifiers; [] verifies no email. Change it with
campaigns(operation="update", email_verifiers=...).
kind (sales or recruiting) and roleId (the primary role of a recruiting campaign, or null).
Language settings (always present): sourceLanguage is the language the steps are written in (en
by default). languageMode is source_only (default: every lead gets the source text) or auto (a
lead gets the localization for their language when enabledLanguages lists it). enabledLanguages
and formalityOverrides (locale to formal or informal) are [] and {} when unset. languageFallback
is source (default) or hold: what an auto campaign does when a lead's language has no approved
localization.

Forecast (DEV-2541), from the sequencer's stored forecast, refreshed every 5 minutes:
forecast.plannedSendCount = sentCount + remainingSendCount. sentCount is the campaign's
sent total, rolled up from daily stats, so today's sends can show up tomorrow.
remainingSendCount is the sends still planned for the leads in the campaign.
forecast.progress is sentCount / plannedSendCount, a fraction 0-1 (not a percentage, and
not the share of leads contacted). forecast.estimatedFinishAt (UTC) is when the last planned
send should go out, from the inboxes' daily capacity (shared with the workspace's other
campaigns), maxEmailsPerDay, the sending days, window and time zone, and the step waits.
forecast.effectiveDailyCapacity is the sends a day this campaign gets while sending, 0 when
no inbox has capacity for it. forecast.calculatedAt is when it was computed.
forecast is present only while sendingStatus is sending or paused. It is omitted for drafts,
campaigns not yet sending, completed, archived and trigger campaigns, when nothing is planned,
and when the stored forecast is missing or over 24 hours old. Inside it, estimatedFinishAt is
omitted while paused or when no finish can be placed (no inbox capacity, an unusable window,
or more than two years out), and effectiveDailyCapacity is omitted while paused and until the
first forecast after a resume (up to about 5 minutes).

Pause reason (DEV-2541): pausedReason = {kind, at?, byMemberId?, detail?}, present only while
sendingStatus is paused. kind values: user (a member paused it, or an agent for a member),
bounce_guard (the campaign hard-bounce guard), sending_error (paused after repeated send
failures; Kenso does not pause for send failures today, so a campaign whose sends keep
failing stays sending and shows sendingError instead), holiday (the US-holiday pause),
client_approval (paused for the client's approval of changed copy or a lead list; approval
resumes it, or leaves it paused for a manual resume when it cannot send), billing (sending
suspended for non-payment),
workspace_locked (the workspace was deactivated or locked), other (another system pause),
unknown (nothing recorded why, such as a pause from before Kenso recorded them). Tolerate new
values. at is when sending stopped (UTC), omitted when no record names the time.
byMemberId is set only for user, when the member is known. detail is the guard's evidence
for bounce_guard and sending_error, who paused it for user (for example "Jordan Lee via
Claude Code"), or the system that did for other. No campaign is paused for having no inboxes:
a broken inbox leaves it sending and shows on the inbox.

Imported campaigns: migration = {connectionId, vendor, sourceAccountId, sourceCampaignId,
sourceStatus, syncedAt?, cutoverAt?, historyFrom, historyTo} names the tool and campaign it
was imported from; omitted for campaigns made in Kenso. historyFrom and historyTo are the
first and last day (YYYY-MM-DD) of the daily stats imported for it, and both are null when
none were imported. Daily stats cover the source campaign's whole history; imported bounces
are 0 per day where the source tool has no daily bounce count (Instantly, Salesforge).
Read an imported campaign's analytics over that range, not the recent days.

get-linkedin-settings

Read. GET https://api.ken.so/v1/campaigns/{campaignId}/linkedin-settings

Path: campaignId

Read a campaign's LinkedIn settings. A campaign outside the workspace is not_found. Requires Campaigns view.

GET /api/v1/campaigns/{campaignId}/linkedin-settings. Public. Sends Ken-Version 1.1.
channelPolicy is linkedin_only, linkedin_first_email_fallback,
email_first_linkedin_reinforce, or parallel.

get-processing-status

Read. GET https://api.ken.so/v1/campaigns/{campaignId}/processing-status

Path: campaignId

Query: limit integer

Read a campaign's processing status. Internal. limit caps events from 1 to 100. Omit it for 20.

GET /api/v1/campaigns/{campaignId}/processing-status. Internal. Sends Ken-Version 1.1.
Replaces pipeline and pipeline/events. Stage and event names are lowercase snake_case.
Only details is super_admin gated. The segmentation stage lists segments (segmentId, raw name, count)
instead of a keyed breakdown; segmentId is null when no single segment has that exact name.
A campaign outside the workspace is not_found.

get-scoring

Read. GET https://api.ken.so/v1/campaigns/{campaignId}/scoring

Path: campaignId

Read whether lead scoring is enabled for a campaign. A campaign outside the workspace is not_found. Requires Campaigns view.

GET /api/v1/campaigns/{campaignId}/scoring. Public. Sends Ken-Version 1.1.
Returns isEnabled. Scores live on the contact as qualityScore.

launch

Write. POST https://api.ken.so/v1/campaigns/{campaignId}/launch

Path: campaignId

Launch sending for a campaign. Returns the campaign after the launch command confirms.

POST /api/v1/campaigns/{campaignId}/launch. Public. Sends Ken-Version 1.1.
Requires Campaigns edit and the `launch` permission.
Paid plans include 200,000 sends per billing month; each send beyond that
costs 25 credits per 1,000 ($0.50). On Free every send costs credits.
Launch is refused with INSUFFICIENT_CREDITS when no included sends are left
and the workspace has no credits.
With the multilingual_outreach flag on, launch is refused with 409
acknowledgement_required (one details[] entry per country: code the ISO-2,
message the country and its cold email note) while the campaign has contacts
in a consent-first country nobody acknowledged. Read them with
markets(operation="compliance-get"), show the user each note, then record
their agreement with markets(operation="compliance-acknowledge") and launch
again. Each country is asked once per campaign.
Launch is refused with 400 validation_failed when a channel the campaign sends
on has no sender that can send. error.details[0].code names the channel:
no_sendable_inbox (field inboxes: no inbox can send, or every one is paused)
or no_sendable_linkedin_account (field linkedInAccounts: none connected, or
every one paused). Resume or connect a sender in Delivery, then launch again.
A campaign with a sequence with conditions is refused the same way when the
sequence cannot send: error.details[0].code open_tracking_off (field
campaignId) means it branches on an opened email, and opens are not tracked.
Remove the opened conditions with branching-sequences replace, then launch
again.
402 free_plan_sending_needs_plan: a Free workspace created after the Free
no-send rule started sends nothing. error.refusal has code
FREE_PLAN_SENDING_NEEDS_PLAN and remedy Upgrade: the user picks a paid plan,
then launch again.

list

Read. GET https://api.ken.so/v1/campaigns

Query: cursor string, includeTagIds boolean, kind string, limit integer, q string, status string

List campaigns in the current workspace. Includes archived campaigns. status is a comma-separated OR filter.

GET /api/v1/campaigns. Public. Sends Ken-Version 1.1.

client_id is the workspace, sent as X-Ken-Workspace-Id. q is a case-insensitive
substring of the campaign name, or of the owner's first name, last name, full name,
or email.
status values: active, draft, building, ready, paused, completed, error, archived.
kind filters on sales or recruiting; omit it for both. Each item carries kind and roleId (the
primary role of a recruiting campaign, or null).
Ordered by id. Response envelope: success plus data and pagination.
Each item may carry sendingError / sendingErrorAt (current hard-failure text and start
time; null or omitted when none). The error clears itself and never pauses the campaign.
Each item carries the campaign settings described on campaigns(operation="get"): ownerMemberId,
stopOnReply, stopCompanyOnReply, trackClicks, trackOpens, unsubscribeLink, sendAsPlainText, and the language
settings sourceLanguage, languageMode, enabledLanguages, formalityOverrides, languageFallback.
Sending and paused items also carry forecast, and paused items carry pausedReason, both
described on campaigns(operation="get").
contactCount counts only contacts with a valid email. Items carry leadCount (every lead,
with or without an email). The list reads it from a cached per-workspace count that
usually lags new or removed leads by under 15 minutes; on a very large workspace the
first list after a quiet period can show an older count, which the next list corrects.
For a current number use campaigns(operation="get"), which counts one campaign live.
It can be omitted on very large workspaces when the count does not finish in time; read
it per campaign with campaigns(operation="get") then.
Items carry readyLeadCount, the leads ready for their first email (described on
campaigns(operation="get")), from a stored count: launched campaigns are recounted in the
background once it is 10 minutes old, and an item with no stored count yet omits it.
Items carry contactLimitPeriod (month or total), contactLimitUsed, contactLimitResetsAt,
fairUseContactLimit, contactLimitReached and contactLimitReachedReason, described on
campaigns(operation="get").
Imported items carry migration with historyFrom / historyTo, described on
campaigns(operation="get").
include_tag_ids=true adds tagIds to each item, the ids of its tags ascending ([] when none);
tag names come from tags(operation="list"). Without it, and on campaigns(operation="get"),
items omit tagIds.

list-linkedin-accounts

Read. GET https://api.ken.so/v1/campaigns/{campaignId}/linkedin-accounts

Path: campaignId

List LinkedIn accounts assigned to a campaign. Requires Campaigns view.

GET /api/v1/campaigns/{campaignId}/linkedin-accounts. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id.
New campaigns already include every Connected seat from creation. A later replace
sticks; a seat connected afterward is not added.

pause

Write. POST https://api.ken.so/v1/campaigns/{campaignId}/pause

Path: campaignId

Pause sending, processing, and AI workflows together. Idempotent. A subsystem that is not running is left as it is.

POST /api/v1/campaigns/{campaignId}/pause. Public. Sends Ken-Version 1.1.

Requires Campaigns edit and the `launch` permission. A campaign
that is still launching returns 409 invalid_state. If any subsystem fails,
retry the same action.

replace-linkedin-accounts

Write. PUT https://api.ken.so/v1/campaigns/{campaignId}/linkedin-accounts

Path: campaignId

Body (json): assignAllConnected boolean, linkedInAccountIds array

Replace the LinkedIn accounts assigned to a campaign. Requires Campaigns edit.

PUT /api/v1/campaigns/{campaignId}/linkedin-accounts. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id.
Pass linkedin_account_ids for a full replace, including [] to clear.
Pass assign_all_connected=true to assign every Connected seat.
Ids must belong to this workspace.

replace-linkedin-settings

Write. PUT https://api.ken.so/v1/campaigns/{campaignId}/linkedin-settings

Path: campaignId

Body (json): channelPolicy string, conditionWaitDays integer, isEnabled boolean, isWithdrawEnabled boolean, notAcceptedAfterDays integer, stopAllChannelsOnReply boolean, stopEmailOnLinkedInReply boolean, stopLinkedInOnEmailReply boolean, stopSequenceForCompanyOnReply boolean

Replace a campaign's LinkedIn settings. channel_policy is snake_case. Requires Campaigns edit access (owners, admins and editors by default).

PUT /api/v1/campaigns/{campaignId}/linkedin-settings. Public. Sends Ken-Version 1.1.
not_accepted_after_days is 1 to 90. condition_wait_days is 1 to 60; omit it for 14.
stop_all_channels_on_reply true makes a LinkedIn reply stop the emails even after the
LinkedIn steps finished; with stop_linkedin_on_email_reply and stop_email_on_linkedin_reply
a reply on either channel stops every channel for that lead. Omit it to keep the stored
value (new campaigns default to true).
A campaign outside the workspace is not_found before the write.

replace-scoring

Write. PUT https://api.ken.so/v1/campaigns/{campaignId}/scoring

Path: campaignId

Body (json): isEnabled boolean

Turn lead scoring on or off for a campaign. Requires Campaigns edit. A campaign outside the workspace is not_found.

PUT /api/v1/campaigns/{campaignId}/scoring. Public. Sends Ken-Version 1.1.

resume

Write. POST https://api.ken.so/v1/campaigns/{campaignId}/resume

Path: campaignId

Resume sending, processing, and AI workflows together. Idempotent. A subsystem that was not paused is left as it is.

POST /api/v1/campaigns/{campaignId}/resume. Public. Sends Ken-Version 1.1.

Requires Campaigns edit and the `launch` permission. A campaign
that is still launching returns 409 invalid_state. If any subsystem fails,
retry the same action.
400 validation_failed with error.details[0].code no_sendable_inbox (field
inboxes): no inbox can send, or every one is paused. Do not retry: resume or
connect an inbox in Delivery, then resume again.
402 free_plan_sending_needs_plan: a Free workspace created after the Free
no-send rule started sends nothing. error.refusal has code
FREE_PLAN_SENDING_NEEDS_PLAN and remedy Upgrade: the user picks a paid plan,
then resume again.

retry-enrichment

Write. POST https://api.ken.so/v1/campaigns/{campaignId}/retry-enrichment

Path: campaignId

Re-queues failed website/metadata enrichment and email-finder attempts for contacts that still have no email. Does not restart the campaign. Does not clear qualification, personalization, segmentation, sending, or contacts that already have an email. Idempotent. A campaign outside the workspace is not_found. Requires Campaigns edit.

POST /api/v1/campaigns/{campaignId}/retry-enrichment. Public. No body.
Sends Ken-Version 1.1 and X-Ken-Workspace-Id. Requires Campaigns edit.
Success data: companyStatusesCleared, scrapeFailuresCleared, contactStatusesCleared.
Each valid email Ken finds costs 1 credit ($0.02). Emails found with the
workspace's own provider key and uploaded emails are free. On a paid plan an
email Kenso already holds for that person (recently verified, hasKenEmail in
Kenso Search) is free too.

run-scoring

Write. POST https://api.ken.so/v1/campaigns/{campaignId}/scoring/run

Path: campaignId

Body (json): contactIds array, limit integer

Score contacts in a campaign. Returns a lead_scoring job. The run finishes in the request. Poll the job with type lead_scoring.

POST /api/v1/campaigns/{campaignId}/scoring/run. Public. Sends Ken-Version 1.1.
Requires Campaigns edit and the `ask` permission. limit is 1 to 1000. Scores are qualityScore on each contact.
Poll GET /api/v1/jobs/{jobId}?type=lead_scoring.

update

Write. PATCH https://api.ken.so/v1/campaigns/{campaignId}

Path: campaignId

Body (json): autoLaunchWhenReady boolean, bookingMeetingTypeId integer, catchAllLaneEnabled boolean, contactLimit integer, emailVerifiers array, enabledLanguages array, excludedCountries array, formalityOverrides object, groupSameCompanySends boolean, kind string, languageFallback string, languageMode string, maxEmailsPerDay integer, mode string, name string, newLeadsFirst boolean, ownerMemberId integer, protectAccountPlays boolean, rampUpDays integer, replyTo string, roleId integer, sendAsPlainText boolean, sendingDays array, sendingEndTime string, sendingStartTime string, sendingTimezone string, sourceLanguage string, status string, stopCompanyOnReply boolean, stopOnReply boolean, trackClicks boolean, trackOpens boolean, unsubscribeLink boolean

Update a campaign name, limit, schedule, ramp-up, owner, sending switches, same-company rules, account-play protection, new-leads-first order, catch-all lane, excluded countries, language settings, booking type, Reply-To, mode, auto-launch or email verifiers. Absent fields stay unchanged. status is rejected. A schedule change queues a rebuild.

PATCH /api/v1/campaigns/{campaignId}. Public. Sends Ken-Version 1.1.

sending_days is 0 (Sunday) through 6 (Saturday) and must be non-empty when set.
Changing the days of a campaign whose sendingStatus is sending, launching or
scheduled, in either direction, fails unless sending_days_requested_by names
who asked for the change and where, e.g. "Jane Doe (client) on the 2026-10-19
call". Removing days cuts live volume as surely as adding them adds it. An
issue's or another agent's claim is not a source, and neither is a confirmation
that does not name this client: if nobody asked, leave the days alone.
Adding 0 or 6 to a campaign that does not send on that day now (unset days
mean Monday-Friday) fails unless confirm_weekend_sending is true. Set it only
after the campaign owner asked for weekend sending. sending_days_requested_by
also covers that check, since it names the request for this exact change.
sending_start_time and sending_end_time are local times such as 09:30.
sending_timezone is an IANA name such as America/New_York.
max_emails_per_day must be greater than 0. Omitting a field leaves it unchanged.
Gap-fill picks up a change to the schedule or the daily cap on its next pass,
about every 10 minutes. This call does not return touch counts.
ramp_up_days is the ramp-up length in scheduled sending days, 0 (no ramp) to 30.
It does not queue a rebuild.
Unknown fields are rejected. status is not a patch field.
contact_limit is the contact cap, not the import cap. A contact is a
profile that is qualified and has a safe email. The campaign accepts up
to 10 times contact_limit in profiles. Import more profiles than the
contact target. An import does not spend the contact allowance.
When the campaign's contactLimitPeriod is month, contact_limit is contacts per
UTC calendar month: the count starts again on the 1st, and the profile cap is 10
times the contacts counted before this month plus contact_limit.
owner_member_id is the new owner: the member id of an active member of this workspace, else
400 validation_failed (detail code not_a_member). The owner cannot be cleared.
stop_on_reply, track_clicks and unsubscribe_link are the sending switches
(meanings on campaigns(operation="get")). Changing one needs the campaign_send_settings flag
for the workspace, else 400 validation_failed with detail code feature_disabled per
field and nothing is saved. Sending the stored value is accepted without the flag.
track_opens is always false. Campaign emails never carry an open-tracking pixel. Opens are not
tracked and are never reported. track_opens true is refused with 400 validation_failed, detail
code open_tracking_unavailable, and nothing is saved: asked for open tracking, decline and give
that rule. track_opens false is accepted without the flag.
send_as_plain_text true sends the campaign's emails written as HTML as plain text only, from the
next send on; false sends them as written. A plain text email never carries a click-tracking
link and counts no clicks: each link shows its real address without https://. It needs no flag. Steps with a drawn handwritten letter,
a video, a Studio email, a provider-built message or any image (a Ken campaign image, or an img in
the sent body such as a lead variable's picture or a signature logo) keep their HTML.
Only those steps keep their HTML, per send (one step can keep HTML from an inbox whose signature has a
logo and go plain from one without); the others still go out as plain text. Turning it on while the
campaign's sequence with conditions branches on email_opened is 400 validation_failed (detail code
open_tracking_off on sendAsPlainText) and nothing is saved.
On a draft, remove the opened conditions first; once the campaign has launched, leave it off.
email_verifiers replaces the campaign's email verifiers (at least one of kenso, leadmagic,
findymail, zerobounce, neverbounce; kenso is Kenso's own mailbox check). Kenso's run first. The default is the first three.
zerobounce and neverbounce run only when selected, on the workspace's own key: they spend that
key's credits, never Kenso's. Adding one with no working key is 400 validation_failed, detail
code provider_key_missing, and nothing is saved. A list of only zerobounce or neverbounce leaves
emails unverified while that key cannot be used (cooling down or refused), so keep one of
Kenso's beside it.
stop_company_on_reply true makes a reply also stop every other contact at the lead's
company. It is the same stored value as stop_sequence_for_company_on_reply in
campaigns(operation="replace-linkedin-settings") and needs no LinkedIn setup.
group_same_company_sends true makes coworkers at one company share a send day.
new_leads_first true gives first emails the campaign's daily capacity ahead of its follow-ups
(follow-ups wait until every ready lead has had email 1); false, the default, sends due
follow-ups first. Gap-fill uses it on its next pass. Watch awaitingFirstEmailCount on
campaigns(operation="get") to see when every lead has had email 1. On a campaign that keeps
getting new leads (top-ups, imports), follow-ups can wait as long as it stays on, so turn it
off once awaitingFirstEmailCount reaches 0.
catch_all_lane_enabled true opts the campaign in to the catch-all lane: it may also send to
unverified CatchAll addresses whose catch-all score clears a bar, from the workspace's own
inboxes, capped per campaign and per inbox per day, with a bounce circuit breaker that pauses
the lane (catchAllLanePausedAt on campaigns(operation="get")). false turns it off. It is off by
default and does nothing until Kenso turns the lane on platform-wide. The paused stamp is
system-owned and cannot be sent.
protect_account_plays true skips people in active account plays (accounts in stage
warming, engaged, meeting_booked or in_deal); false sends to them. People already stopped
for an account play stay stopped either way.
booking_meeting_type_id names a live, enabled round robin meeting type of this workspace that takes the
campaign's bookings when the account owner and sender can't; clear_booking_meeting_type true removes it.
reply_to is this campaign's Reply-To on its Kenso Sequencer cold emails. It overrides the workspace
default (workspace(operation="update", reply_to=...)); clear_reply_to true removes the override so
the workspace default applies again (a send from a sending provider identity on a reply_to_inbox connection
takes the connection's Reply-To inbox before the workspace default). Send one of the two, not both. Replies go
to that address instead of the sending inbox, so it survives send-inbox and domain rotation. The address must
be a live mailbox connected to this same workspace that Kenso reads replies from, or a sending provider identity
whose provider receives its replies, not a member's own mailbox (so stop-on-reply
and the Master Inbox keep working), else 400 validation_failed on field replyTo with detail code
not_connected or not_ingested. Kenso brand domains (ken.so,
getken.ai, ...) are refused. When it equals the sending inbox no header is written.
role_id sets the primary role of a recruiting campaign, a live role of this workspace (needs
the recruiting flag); clear_role true removes it. Send one of the two, not both. On a sales
campaign it is 400 validation_failed with detail code not_recruiting. A campaign's kind is set
at create and cannot be changed.
excluded_countries replaces the countries the campaign never sends to: ISO 3166-1 alpha-2 codes
or country names (["DE", "Austria"]), stored as upper-case codes; [] clears the list. Imports
drop a lead whose country is listed and the sequencer skips one already on the campaign, from
its next pass; a lead whose country Kenso cannot read is kept. An entry that names no country is
400 validation_failed on field excludedCountries with detail code invalid_country, and nothing
is written.
Language settings (meanings on campaigns(operation="get")): source_language is a market pack
locale (fr-FR) or a language (en). language_mode is source_only or auto, language_fallback
source or hold. enabled_languages and formality_overrides ({"fr-FR": "informal"}) replace the
stored list and map; clear_enabled_languages or clear_formality_overrides (or [] / {}) empties
one. Each needs the workspace's multilingual_outreach flag, else 400 validation_failed with
detail code feature_disabled per field sent. An unknown or draft locale is unknown_language or
draft_language.
mode is batch or trigger. Batch to trigger converts the campaign to always-on (it then takes
contacts from trigger firings, see the triggers tool); trigger to batch is 400 validation_failed
with detail code mode_one_way and nothing is written. Switching a batch campaign that is already
set to auto-launch to trigger is 400 validation_failed on autoLaunchWhenReady unless the same
request sends auto_launch_when_ready false, and mode trigger with auto_launch_when_ready true on
a batch campaign is 400 too: a trigger campaign never auto-launches.
auto_launch_when_ready true launches the campaign once it is ready, with no further confirmation
(it starts sending and spending sending credits); false keeps the manual launch. Changing it needs
the launch permission (403 forbidden), is 400 once the campaign launched or for a trigger or
approval-test campaign, and 409 conflict once auto-launch has made its one attempt. Auto-launch
is one-shot: if it cannot proceed at ready (billing, credits, schedule, no sendable inbox) the
campaign stays ready and you launch it with campaigns(operation="launch") after the fix. Both
replace the retired campaign_ops mode and campaign_flow set_auto_launch.
Requires Campaigns edit. Use launch, pause, resume, or archive to change status.