Campaigns
Create and update campaigns, launch, pause, resume, archive and duplicate them, assign their inboxes and LinkedIn accounts, and run scoring and enrichment.
Path parameters
The endpoints whose path names one of these take it as described here. An endpoint's own table lists a path parameter only when it describes it differently.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
campaignId | path | integer (int64) | required | Id of the campaign. |
Headers
The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Ken-Version | header | string, one of: 2026-11-02, 1.1 | optional | The API version, a date in YYYY-MM-DD form. 1.1 is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and 404 where the path exists only in this version. A date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy. |
X-Ken-Workspace-Id | header | integer (int64) | optional | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers 400 workspace_required. A workspace you are not a member of answers 404 not_found. |
List campaigns
/v1/campaignscampaigns.list- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
Returns the workspace's campaigns, oldest first, archived ones included.
status filters by one or more statuses, comma-separated: active, draft, building, ready, paused, completed, error or archived. kind filters by sales or recruiting. q matches part of the campaign name or of the owner's name or email, ignoring case. createdAfter (inclusive) and createdBefore (exclusive) keep the campaigns created in that range. sort=-createdAt lists newest first and sort=createdAt oldest first; send the same sort on every page.
Each item's leadCount comes from a cached count that usually trails new or removed contacts by under 15 minutes; GET /v1/campaigns/{campaignId} counts live. On a very large workspace leadCount can be omitted when the count does not finish in time. linkedInOnly appears only on this list. Each item's readyLeadCount is the last stored count: a list recounts launched campaigns whose count is over 10 minutes old in the background, and a campaign with no stored count omits it. With includeTagIds=true each item's tagIds lists the tags on the campaign; without it tagIds is omitted.
Errors:
400 validation_failed:status,kind,sort,limit(1 to 200) orcursoris invalid, a cursor comes from a page with anothersort, orcreatedBeforeis not later thancreatedAfter.
Requires Campaigns view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
status | query | string | optional | Only the campaigns in these statuses, as a comma-separated list of active, draft, building, ready, paused, completed, error and archived. Omit it for every status. |
q | query | string | optional | Only the campaigns whose name contains this text, or whose owner's first name, last name, full name or email contains it, ignoring case. |
limit | query | integer (int32) | optional | Number of campaigns per page, from 1 to 200, default 50. |
cursor | query | string | optional | The nextCursor from the previous page. Omit it for the first page. |
kind | query | string | optional | Only the campaigns of this kind: sales or recruiting. Omit it for both. |
includeTagIds | query | boolean | optional | true adds each item's tagIds. Omit it to leave tagIds out. |
sort | query | string | optional | The order: createdAt lists oldest first and -createdAt newest first. Omit it to list by id, oldest first. Send the same sort on every page. |
createdAfter | query | string (date-time) | optional | Only campaigns created at or after this time, in UTC. |
createdBefore | query | string (date-time) | optional | Only campaigns created before this time, in UTC. Must be later than createdAfter. |
curl -X GET "https://api.ken.so/v1/campaigns?limit=50" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a list of Campaign. Each item has these fields. The response also carries pagination.
Show the 62 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Create a campaign
/v1/campaignscampaigns.create- Permission
- Campaigns edit
- Rate limit
- 60 requests a minute and 500 a day per workspace (Free plan: 6 a minute and 50 a day)
Creates a campaign and returns it, with its URL in the Location header. Without a schedule it sends Monday to Friday, 10:00 to 18:00 New York time; change that with PATCH /v1/campaigns/{campaignId}.
kind is sales (the default) or recruiting. A sales campaign starts with stopCompanyOnReply and groupSameCompanySends on. A recruiting campaign needs the recruiting feature, starts with both off and with same-company Cc off, and can name the role it hires for in roleId.
source says where in the app the campaign was started, for Kenso's product analytics: builder (the default) or search. It does not change the campaign, and a call with an API key or from an agent is counted as such whatever it sends.
Errors:
400 validation_failed:nameis missing,contactLimitis not greater than 0, orkindorsourceis unknown. Detail codefeature_disabledmeans the workspace does not have the recruiting feature, andnot_recruitingmeansroleIdwas sent for a sales campaign.404 not_found:roleIdis not a role in this workspace.429 rate_limited: the workspace created too many campaigns in a short time. Try again later.
Requires Campaigns edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | required | Display name of the campaign. Required. |
contactLimit | integer (int32) | optional | Most contacts the campaign may hold, greater than 0. Omit to set it later; workflows and launch need one. |
kind | string | optional | Campaign type: sales (the default) or recruiting. A recruiting campaign needs the recruiting feature. |
roleId | integer (int64) | optional | Id of the main role a recruiting campaign hires for, a role in this workspace. Only for a recruiting campaign. |
source | string | optional | Where in the app the campaign was started, for Kenso's product analytics: builder (the default) or search. It does not change the campaign. A call with an API key or from an agent is counted as such, whatever it sends. |
curl -X POST "https://api.ken.so/v1/campaigns" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"name": "Q4 SaaS founders",
"contactLimit": 2500,
"kind": "sales"
}'Response 201
data is a Campaign.
Show the 62 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get a campaign
/v1/campaigns/{campaignId}campaigns.get- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
Returns one campaign with its settings, sending progress and, while it is paused, why. leadCount is counted live. readyLeadCount is counted live too, for up to 2 seconds, then the last stored count.
Errors:
404 not_found: the campaign does not exist in this workspace.
Requires Campaigns view.
curl -X GET "https://api.ken.so/v1/campaigns/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a Campaign.
Show the 62 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Update a campaign
/v1/campaigns/{campaignId}campaigns.update- Permission
- Campaigns edit
- Rate limit
- 4,800 requests a minute per API key
Changes the fields you send and returns the campaign. Omitted fields stay as they are. A field the request body does not list, including status and catchAllLanePausedAt, is rejected; change the status with the launch, pause, resume, restart and archive actions.
Kenso checks replyTo, excludedCountries, bookingMeetingTypeId, roleId and mode before it writes anything, so a refused value leaves the campaign unchanged. Schedule and daily limit changes take effect from the next scheduling pass, within about 10 minutes. excludedCountries applies to imports right away and to contacts already in the campaign from the next sending pass.
Some fields need a workspace feature. Changing stopOnReply, trackClicks or unsubscribeLink needs the campaign send settings feature; sending the current value is always accepted. trackOpens is always false: campaign emails never carry an open-tracking pixel, so opens are not tracked and are never reported. trackOpens true is refused; false is accepted without the feature. The language fields (sourceLanguage, languageMode, enabledLanguages, formalityOverrides, languageFallback) need the multilingual outreach feature, even to send the current value. roleId needs the recruiting feature.
sendAsPlainText true sends the campaign's emails written as HTML as plain text only, from the next send on, and needs no feature. 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, decided per send. Turning sendAsPlainText on is refused while the campaign's sequence with conditions branches on an opened email.
mode trigger turns a batch campaign into a trigger campaign; the reverse is rejected. To make that switch on a campaign set to launch by itself, send autoLaunchWhenReady false in the same request. autoLaunchWhenReady true launches the campaign once it is ready, with no further confirmation, so changing it needs the launch permission.
emailVerifiers replaces the verifiers that check the campaign's emails. zerobounce and neverbounce run on the workspace's own key and spend its credits, never Kenso's; no campaign gets them unless it lists them.
Errors:
400 validation_failed: a field is invalid, or a field the body does not list was sent. Detail codes includefeature_disabled(the workspace lacks the feature the field needs),not_a_member(ownerMemberIdis not an active member),provider_key_missing(emailVerifiersaddszerobounceorneverbounceand the workspace has no working key for it),kind_immutable(kindwas sent),not_recruiting(roleIdon a sales campaign),invalid_country,unknown_language,draft_language,invalid_value,mode_one_way(trigger back to batch),open_tracking_off(sendAsPlainTextturned on while the sequence with conditions branches on an opened email),open_tracking_unavailable(trackOpenstrue: opens are not tracked), andinvalid,not_connectedornot_ingestedfor areplyTothat is not a connected mailbox Kenso reads.autoLaunchWhenReadyis also rejected once the campaign has launched, and on a trigger or approval test campaign.402 plan_limit_reached: the newcontactLimitis more than the workspace's remaining lead credits.403 forbidden:autoLaunchWhenReadywas changed without thelaunchpermission.404 not_found: the campaign does not exist in this workspace.409 conflict:autoLaunchWhenReadywas changed after auto-launch already ran.
Requires Campaigns edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | optional | New display name. It cannot be blank. |
contactLimit | integer (int32) | optional | New contact limit, greater than 0. |
status | string | optional | Always rejected: change the status with the launch, pause, resume, restart and archive actions instead. |
sendingDays | array of integer (int32) | optional | Days to send on, from 0 (Sunday) to 6 (Saturday). Cannot be empty. |
sendingStartTime | string | optional | Start of the daily sending window, as a time such as 09:30. |
sendingEndTime | string | optional | End of the daily sending window, as a time such as 18:00. |
sendingTimezone | string | optional | Time zone of the sending window: a supported IANA name such as America/New_York, or prospect to send in each contact's own time zone. |
maxEmailsPerDay | integer (int32) | optional | Most emails the campaign sends per day, greater than 0. |
ownerMemberId | integer (int64) | optional | Member id of the new campaign owner, who must be an active member of the workspace. Null or omitted keeps the current owner; the owner cannot be cleared. |
stopOnReply | boolean | optional | True stops a contact's sequence on any reply; false lets neutral and positive replies continue it. Changing this or the other sending switches needs the campaign send settings feature; sending the current value is always accepted. |
trackClicks | boolean | optional | True sends links through tracking links. Same feature rule as stopOnReply. |
trackOpens | boolean | optional | Always false: campaign emails never carry an open-tracking pixel. Opens are not tracked and are never reported. true is refused with 400 validation_failed, detail code open_tracking_unavailable; false is accepted and needs no feature. |
unsubscribeLink | boolean | optional | True adds the List-Unsubscribe headers to every email; false drops them from steps that carry the {{unsubscribe_link}} link. Same feature rule as stopOnReply. |
sendAsPlainText | boolean | optional | True sends emails written as HTML as plain text only, with no HTML part. 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, decided per send. Omit (or send null) to leave it unchanged. Unlike stopOnReply, changing it needs no feature. Turning it on is refused (open_tracking_off) while the campaign's sequence with conditions branches on an opened email. |
protectAccountPlays | boolean | optional | True skips people in active account plays. Turning it off does not restart people already stopped. |
rampUpDays | integer (int32) | optional | Ramp-up length in scheduled sending days, from 0 (no ramp) to 30. |
stopCompanyOnReply | boolean | optional | True stops every contact at the same company when one replies. Same setting as stopSequenceForCompanyOnReply in the LinkedIn settings. |
groupSameCompanySends | boolean | optional | True sends to contacts at the same company on the same day. |
newLeadsFirst | boolean | optional | True gives first emails the campaign's daily capacity ahead of follow-ups, from the next scheduling pass. While it is on, the response carries awaitingFirstEmailCount. |
catchAllLaneEnabled | boolean | optional | True opts the campaign in to the catch-all lane, false opts it out. It has no effect until Kenso turns the lane on for all workspaces. catchAllLanePausedAt is set by Kenso and cannot be sent. |
emailVerifiers | array of string | optional | The verifiers that check the campaign's emails, replacing the saved list: any of kenso (Kenso's own mailbox check), leadmagic (LeadMagic catch-all), findymail, zerobounce and neverbounce, at least one. Kenso's verifiers run first, in the order Kenso picks, then zerobounce, then neverbounce, each only for the emails the ones before it left undecided, whatever order you send. zerobounce and neverbounce run on the workspace's own ZeroBounce or NeverBounce key and spend its credits, never Kenso's; adding one the workspace has no working key for is refused (provider_key_missing). A list of only zerobounce or neverbounce leaves an email unverified while that key cannot be used (cooling down after a rate limit, or refused): list one of Kenso's verifiers too to keep checking emails then. No campaign gets them unless it lists them. Omit to keep the saved list. |
bookingMeetingTypeId | integer (int64) | optional | Id of an enabled round robin meeting type in this workspace that takes the campaign's bookings when the account owner and the sender cannot. Null clears it. |
replyTo | string | optional | Reply-To address for this campaign, used instead of the workspace's. It must be a mailbox connected to this workspace that Kenso reads replies from, not a member's own mailbox. Null clears it, so the campaign uses the workspace's setting. |
excludedCountries | array of string | optional | Countries this campaign never sends to, as ISO 3166-1 alpha-2 codes or country names, such as DE or Germany. Replaces the saved list; [] clears it and null keeps it. |
kind | string | optional | Always rejected with detail code kind_immutable: the kind is set when the campaign is created. |
roleId | integer (int64) | optional | Id of the main role a recruiting campaign hires for, a role in this workspace. Null clears it. Needs the recruiting feature, and is rejected on a sales campaign. |
sourceLanguage | string | optional | Language the steps are written in: a market locale such as fr-FR, or a language such as en. This and the other language settings need the multilingual outreach feature. |
languageMode | string | optional | How each email's language is picked: source_only or auto. |
enabledLanguages | array of string | optional | Market locales to translate into. Replaces the saved list; null or [] clears it. |
formalityOverrides | map of string | optional | Tone per locale, formal or informal. Replaces the saved map; null or {} clears it. |
languageFallback | string | optional | What auto does when a contact's language has no approved translation: source or hold. |
mode | string | optional | How contacts enter the campaign: batch or trigger. trigger turns a batch campaign into a trigger campaign; the reverse is rejected. |
autoLaunchWhenReady | boolean | optional | True launches the campaign by itself once it is ready. Needs the launch permission, and is rejected once the campaign has launched or auto-launch has already run. |
curl -X PATCH "https://api.ken.so/v1/campaigns/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"sendingDays": [
1,
2,
3,
4
],
"sendingStartTime": "08:30",
"sendingEndTime": "16:30",
"sendingTimezone": "America/Chicago",
"maxEmailsPerDay": 400,
"rampUpDays": 7
}'Response 200
data is a Campaign.
Show the 62 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Delete a campaign
/v1/campaigns/{campaignId}campaigns.delete- Permission
- Campaigns edit
- Rate limit
- 4,800 requests a minute per API key
Deletes the campaign and its segments. A campaign that is sending is paused first, so nothing more is sent. The campaign no longer appears in any list.
Errors:
404 not_found: the campaign does not exist in this workspace.
Requires Campaigns edit.
curl -X DELETE "https://api.ken.so/v1/campaigns/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 204
HTTP/1.1 204 No ContentGet the campaign's agent work overrides
/v1/campaigns/{campaignId}/agent-workcampaigns.get-agent-work- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
agent_work feature on your workspace. Until it is on, calls answer 404.Returns each kind a campaign can override (personalization) with the campaign's override (executor, null when it follows the workspace) and the workspace's setting (workspaceExecutor).
Errors:
404 not_found: the campaign is not in the workspace or is deleted, or the workspace does not have theagent_workfeature.
Requires Campaigns view. Not open to a Client seat.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
campaignId | path | integer (int64) | required |
curl -X GET "https://api.ken.so/v1/campaigns/812/agent-work" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a CampaignAgentWork.
Show the 2 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Update the campaign's agent work overrides
/v1/campaigns/{campaignId}/agent-workcampaigns.update-agent-work- Permission
- Campaigns edit and the
workspace_settingspermission - Rate limit
- 4,800 requests a minute per API key
agent_work feature on your workspace. Until it is on, calls answer 404.Sets or clears the campaign's override of each kind you name. Body: { "settings": [ { "kind": "personalization", "executor": "my_agent" } ] }. executor is kenso_ai, my_agent, or null to clear the override so the campaign follows its workspace. Returns the campaign's overrides after the change, in the same shape as the GET. With my_agent, the campaign's personalization waits for the workspace's agent (kenso work run) even when the workspace is on kenso_ai: Kenso's AI does not write it, and the full prompt and the lead's facts go to that agent. With kenso_ai, Kenso's AI writes it even when the workspace is on my_agent.
Errors:
400 validation_failed:settingsis missing or empty, akindis not one a campaign can override, anexecutoris not a known value, or a kind is named twice. Each problem is onedetails[]entry, such assettings[0].kind. Nothing is saved.404 not_found: the campaign is not in the workspace or is deleted, or the workspace does not have theagent_workfeature.
Requires Campaigns edit and the workspace_settings permission. Not open to a Client seat or an agent's run key.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
campaignId | path | integer (int64) | required |
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
settings | array of UpdateCampaignAgentWorkEntry | optional | One entry per kind to change, each kind at most once. At least one entry. |
curl -X PATCH "https://api.ken.so/v1/campaigns/812/agent-work" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"settings": [
{
"kind": "personalization",
"executor": "my_agent"
}
]
}'Response 200
data is a CampaignAgentWork.
Show the 2 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Archive a campaign
/v1/campaigns/{campaignId}/archivecampaigns.archive- Permission
- Campaigns edit and the
launchpermission - Rate limit
- 4,800 requests a minute per API key
Sets the campaign's status to archived and returns it. Its queued emails are cancelled, so nothing sends while it is archived; its leads, replies and stats stay, Analytics keeps counting them, and its leads still count as duplicates for new campaigns. Archiving does not stop a sending campaign itself, so it is allowed only from draft, paused or completed: pause a sending campaign first. Undo with POST /v1/campaigns/{campaignId}/unarchive. Archiving an archived campaign changes nothing.
Errors:
400 validation_failed: the campaign is not draft, paused or completed.404 not_found: the campaign does not exist in this workspace.409 invalid_state: the campaign is sending or launching. Pause it first.
Requires Campaigns edit and the launch permission.
curl -X POST "https://api.ken.so/v1/campaigns/812/archive" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a Campaign.
Show the 62 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Unarchive a campaign
/v1/campaigns/{campaignId}/unarchivecampaigns.unarchive- Permission
- Campaigns edit and the
launchpermission - Rate limit
- 4,800 requests a minute per API key
Brings an archived campaign back and returns it. It never starts sending: a campaign archived after it finished comes back completed, one that launched comes back paused, so call POST /v1/campaigns/{campaignId}/resume to send again, and one that never launched comes back a draft. Resume plans the sends that archiving cancelled. Unarchiving a campaign that is not archived changes nothing.
Errors:
404 not_found: the campaign does not exist in this workspace.409 conflict: the campaign changed while it was being unarchived. Try again.
Requires Campaigns edit and the launch permission.
curl -X POST "https://api.ken.so/v1/campaigns/812/unarchive" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a Campaign.
Show the 62 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
List a campaign's inboxes
/v1/campaigns/{campaignId}/inboxescampaigns.list-inboxes- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
Returns the inboxes the campaign sends from.
Errors:
404 not_found: the campaign does not exist in this workspace.
Requires Campaigns view.
curl -X GET "https://api.ken.so/v1/campaigns/812/inboxes" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a list of Inbox. Each item has these fields. The response also carries pagination.
Show the 41 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Replace a campaign's inboxes
/v1/campaigns/{campaignId}/inboxescampaigns.replace-inboxes- Permission
- Campaigns edit
- Rate limit
- 4,800 requests a minute per API key
Sets the inboxes the campaign sends from and returns them. The new set replaces the old one.
Send inboxIds for a saved list, or assignAllActive to save every inbox that can send through Kenso, optionally only those of one provider. Send allInboxes true to use all inboxes instead: every inbox a launch would assign joins now, and inboxes connected later join too. Paused inboxes the campaign does not already have are left out. allInboxes ignores the other fields and needs the sender routing feature.
Errors:
400 validation_failed:inboxIdsis missing, names an inbox that is not in this workspace or cannot send, no inbox matchedassignAllActiveorallInboxes, orprovideris unknown. Detail codefeature_disabledmeans the workspace does not have the sender routing feature.404 not_found: the campaign does not exist in this workspace.
Requires Campaigns edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
inboxIds | array of integer (int64) | optional | Ids of the workspace inboxes the campaign should use. Required unless assignAllActive or allInboxes is true. |
assignAllActive | boolean | optional | True assigns every inbox in the workspace that can send through Kenso, as a saved list. inboxIds is then ignored. |
provider | string | optional | With assignAllActive, assigns only inboxes of this kind: google, microsoft, azure or custom_smtp. |
allInboxes | boolean | optional | True makes the campaign use all inboxes: every inbox a launch would assign joins now, and inboxes connected later join too. inboxIds, assignAllActive and provider are then ignored. Needs the sender routing feature. Omitted or false keeps a saved list of the inboxes you send. |
curl -X PUT "https://api.ken.so/v1/campaigns/812/inboxes" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"inboxIds": [
5530,
5531,
5532
],
"assignAllActive": false
}'Response 200
data is a list of Inbox. Each item has these fields. The response also carries pagination.
Show the 41 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
List a campaign's LinkedIn accounts
/v1/campaigns/{campaignId}/linkedin-accountscampaigns.list-linkedin-accounts- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
Returns the LinkedIn accounts the campaign runs its LinkedIn steps from.
Errors:
404 not_found: the campaign does not exist in this workspace.
Requires Campaigns view.
curl -X GET "https://api.ken.so/v1/campaigns/812/linkedin-accounts" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a list of LinkedInAccount. Each item has these fields. The response also carries pagination.
Show the 48 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Replace a campaign's LinkedIn accounts
/v1/campaigns/{campaignId}/linkedin-accountscampaigns.replace-linkedin-accounts- Permission
- Campaigns edit
- Rate limit
- 4,800 requests a minute per API key
Sets the LinkedIn accounts the campaign uses and returns them. The new set replaces the old one. Send linkedInAccountIds, or assignAllConnected true to assign every connected LinkedIn account in the workspace.
Errors:
400 validation_failed:linkedInAccountIdsis missing or names an account that is not in this workspace, orassignAllConnectedfound no connected account.404 not_found: the campaign does not exist in this workspace.
Requires Campaigns edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
linkedInAccountIds | array of integer (int64) | optional | Ids of the workspace's LinkedIn accounts to assign. Required unless assignAllConnected is true. |
assignAllConnected | boolean | optional | True assigns every connected LinkedIn account in the workspace. linkedInAccountIds is then ignored. |
curl -X PUT "https://api.ken.so/v1/campaigns/812/linkedin-accounts" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"linkedInAccountIds": [
2207
],
"assignAllConnected": false
}'Response 200
data is a list of LinkedInAccount. Each item has these fields. The response also carries pagination.
Show the 48 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get a campaign's LinkedIn settings
/v1/campaigns/{campaignId}/linkedin-settingscampaigns.get-linkedin-settings- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
Returns how the campaign uses LinkedIn alongside email: whether LinkedIn steps run, how the two channels combine, how long to wait on connection requests, and which replies stop which channel.
Errors:
404 not_found: the campaign does not exist in this workspace.
Requires Campaigns view.
curl -X GET "https://api.ken.so/v1/campaigns/812/linkedin-settings" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a LinkedInSettings.
Show the 9 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Replace a campaign's LinkedIn settings
/v1/campaigns/{campaignId}/linkedin-settingscampaigns.replace-linkedin-settings- Permission
- Campaigns edit
- Rate limit
- 4,800 requests a minute per API key
Saves all of the campaign's LinkedIn settings at once and returns them. Send every field: an omitted boolean is saved as false, and an omitted conditionWaitDays as 14. Only stopSequenceForCompanyOnReply keeps its current value when omitted.
channelPolicy is linkedin_only, linkedin_first_email_fallback, email_first_linkedin_reinforce or parallel. Set linkedin_only before launch: a launched campaign cannot switch to it, because contacts already in its email sequence would keep getting emails.
Errors:
400 validation_failed:channelPolicyis missing or unknown,notAcceptedAfterDaysis not 1 to 90,conditionWaitDaysis not 1 to 60, or a launched campaign would switch tolinkedin_only.404 not_found: the campaign does not exist in this workspace.
Requires Campaigns edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
isEnabled | boolean | optional | True runs the campaign's LinkedIn steps. |
channelPolicy | string | optional | Required: linkedin_only, linkedin_first_email_fallback, email_first_linkedin_reinforce or parallel. A launched campaign cannot switch to linkedin_only. |
notAcceptedAfterDays | integer (int32) | optional | Days to wait for a connection request to be accepted, from 1 to 90. |
conditionWaitDays | integer (int32) | optional | Days a step waits for its condition before it is skipped, from 1 to 60. Omitted or 0 means 14. |
isWithdrawEnabled | boolean | optional | True withdraws a connection request that was not accepted within notAcceptedAfterDays. |
stopLinkedInOnEmailReply | boolean | optional | True stops a contact's LinkedIn steps when they reply by email. |
stopEmailOnLinkedInReply | boolean | optional | True stops a contact's emails when they reply on LinkedIn. |
stopSequenceForCompanyOnReply | boolean | optional | True stops the sequence for every contact at the same company when one of them replies. Same setting as the campaign's stopCompanyOnReply. Omitted keeps the current value. |
stopAllChannelsOnReply | boolean | optional | True stops every channel when the contact replies on any channel, also after their LinkedIn steps finished. Omitted keeps the current value (true for a campaign with no LinkedIn settings yet). |
curl -X PUT "https://api.ken.so/v1/campaigns/812/linkedin-settings" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"isEnabled": true,
"channelPolicy": "email_first_linkedin_reinforce",
"notAcceptedAfterDays": 21,
"conditionWaitDays": 14,
"isWithdrawEnabled": true,
"stopLinkedInOnEmailReply": true,
"stopEmailOnLinkedInReply": true,
"stopSequenceForCompanyOnReply": true,
"stopAllChannelsOnReply": true
}'Response 200
data is a LinkedInSettings.
Show the 9 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Launch a campaign
/v1/campaigns/{campaignId}/launchcampaigns.launch- Permission
- Campaigns edit and the
launchpermission - Rate limit
- 10 requests a minute per API key
Starts sending the campaign and returns it once the launch is confirmed. Calling it again while the campaign is launching or sending changes nothing. Check GET /v1/campaigns/{campaignId}/launch-readiness first to see what would stop the launch.
On a Draft whose leads were never prepared, such as a duplicate, launch starts preparing them and turns auto-launch on, so the campaign launches on its own once its first leads are ready. The answer is the campaign with status building and autoLaunchWhenReady true. An import that has not finished, a sequence with conditions that cannot launch, a billing hold, an invalid schedule, a LinkedIn setup that cannot send, or no inbox that can send refuses it first, as below.
When your client must approve the copy, a contact list or other items first, the launch asks them and is refused until they approve.
Errors:
400 validation_failed: the campaign is not ready to launch, for example its schedule is invalid, no inbox can send, or its LinkedIn setup is incomplete. When no channel the campaign sends on can send,error.detailshas one entry whosecodenames the channel:no_sendable_inbox(fieldinboxes) when the campaign has no inbox that can send or every one is paused, andno_sendable_linkedin_account(fieldlinkedInAccounts) when no LinkedIn account it sends from is connected or every one is paused. Branch on the code, not the message. A campaign with a sequence with conditions that cannot send is refused the same way:error.detailshas one entry on the fieldcampaignIdwhosecodeisopen_tracking_offwhen the sequence branches on an opened email: opens are not tracked, so remove the opened conditions, then launch again.402 plan_limit_reached: sending is suspended for non-payment.402 dispute_hold: sending is held during a payment dispute.402 free_plan_sending_needs_plan: the workspace is on the Free plan, which sends nothing for a workspace created after the Free no-send rule started.error.refusalhascodeFREE_PLAN_SENDING_NEEDS_PLANandremedyUpgrade: pick a paid plan, then call again.404 not_found: the campaign does not exist in this workspace.409 approval_required: your client has to approve first; thekindsdetail lists what waits, such ascopyorlead_list.409 acknowledgement_required: the campaign has contacts in a country with consent-first cold email rules, and nobody has acknowledged those rules for this campaign yet.409 conflict: another launch in the workspace is in progress. Try again shortly.409 invalid_state: the workspace's data is scheduled for deletion or being deleted.503 service_unavailable: Kenso could not start sending right now. Try again shortly.
Requires Campaigns edit and the launch permission.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | optional | A unique value, such as a UUID, that makes a retry safe. Send the same key when you retry. For 24 hours, a repeat of the same request with the same key gets the first response again, with the Idempotent-Replayed: true header, and Kenso does not run the action twice. The same key with a different request answers 422 idempotency_key_reused. Keys are per workspace and at most 200 characters long. A repeat sent while the first request is still running can get 503 service_unavailable with Retry-After. Retry it with the same key. Kenso does not store a 4xx or 5xx response, so a retry after one runs the action again. |
curl -X POST "https://api.ken.so/v1/campaigns/812/launch" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a Campaign.
Show the 62 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Duplicate a campaign
/v1/campaigns/{campaignId}/duplicatecampaigns.duplicate- Permission
- Campaigns edit
- Rate limit
- 20 requests a minute per API key
Creates a draft copy of the campaign's setup in the same workspace and returns it, with its URL in the Location header. The copy is named name, or "Copy of" plus the original name.
With includeContacts true, Kenso also copies the contacts and their AI and enrichment data in the background. An email keeps its verification result only when it was verified in the last 30 days; the others go back to unknown. Send history is never copied.
Errors:
400 validation_failed: the copied contacts would pass the campaign's import limit, the workspace is inactive, or the campaign is a recruiting campaign and the workspace does not have the recruiting feature.404 not_found: the campaign does not exist in this workspace.429 rate_limited: the workspace made too many copies in a short time, or too many copies with contacts are still running. Try again later.
Requires Campaigns edit.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
campaignId | path | integer (int64) | required | Id of the campaign to copy. |
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | optional | Name of the copy. Omitted or blank names it "Copy of" plus the original name. |
includeContacts | boolean | optional | True also copies the contacts and their AI and enrichment data, in the background. False (the default) copies only the setup. |
curl -X POST "https://api.ken.so/v1/campaigns/812/duplicate" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"name": "Q1 SaaS founders",
"includeContacts": false
}'Response 201
data is a Campaign.
Show the 62 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Pause a campaign
/v1/campaigns/{campaignId}/pausecampaigns.pause- Permission
- Campaigns edit and the
launchpermission - Rate limit
- 4,800 requests a minute per API key
Pauses the campaign's sending, processing and AI workflows together, and returns the campaign. Parts that are not running are left as they are. Pausing a paused campaign changes nothing. If one part fails to pause, the call returns that error and you can call it again.
Errors:
404 not_found: the campaign does not exist in this workspace.409 invalid_state: the campaign is still launching. Try again once the launch finishes.
Requires Campaigns edit and the launch permission.
curl -X POST "https://api.ken.so/v1/campaigns/812/pause" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a Campaign.
Show the 62 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Resume a campaign
/v1/campaigns/{campaignId}/resumecampaigns.resume- Permission
- Campaigns edit and the
launchpermission - Rate limit
- 240 requests a minute per API key
Resumes the campaign's sending, processing and AI workflows together, and returns the campaign. Parts that were not paused are left as they are. Resuming a running campaign changes nothing. If one part fails to resume, the call returns that error and you can call it again.
Errors:
400 validation_failed: sending cannot resume, for example because no inbox can send.402 free_plan_sending_needs_plan: the workspace is on the Free plan, which sends nothing for a workspace created after the Free no-send rule started.error.refusalhascodeFREE_PLAN_SENDING_NEEDS_PLANandremedyUpgrade: pick a paid plan, then call again.404 not_found: the campaign does not exist in this workspace.409 approval_required: your client has to approve changes first; thekindsdetail lists what waits.409 invalid_state: the campaign is still launching, or the workspace's data is scheduled for deletion or being deleted.
Requires Campaigns edit and the launch permission.
curl -X POST "https://api.ken.so/v1/campaigns/812/resume" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a Campaign.
Show the 62 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Check whether a campaign can launch
/v1/campaigns/{campaignId}/launch-readinesscampaigns.get-launch-readiness- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
Returns whether the campaign can launch, each condition that stands in the way, and an estimate of how long sending will take. Read it before POST /v1/campaigns/{campaignId}/launch.
reasons lists what blocks the launch, plus advisory notices that do not. warnings never change canLaunch. approval_required means your client was asked and the launch is refused until they approve; approval_will_be_requested means nobody was asked yet, and the launch will ask them and then wait. Both list what waits in kinds. On a campaign that translates its steps, a localization_incomplete warning per language names the steps with no approved translation and whether those contacts get the source text or are held. When the estimate cannot be calculated, its counts are omitted and a sending_estimate_unavailable warning says why.
Errors:
404 not_found: the campaign does not exist in this workspace.
Requires Campaigns view.
curl -X GET "https://api.ken.so/v1/campaigns/812/launch-readiness" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a LaunchReadiness.
Show the 10 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Check whether a campaign's workflows can start
/v1/campaigns/{campaignId}/workflow-readinesscampaigns.get-workflow-readiness- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
Runs the checks that must pass before the campaign's enrichment, email verification and AI workflows can start, and returns each one with isPassed. The checks cover imported contacts or an active signal, the contact limit, the name, the schedule, the email sequence and its AI variables. Whether the campaign can start sending is GET /v1/campaigns/{campaignId}/launch-readiness.
Errors:
404 not_found: the campaign does not exist in this workspace.
Requires Campaigns view.
curl -X GET "https://api.ken.so/v1/campaigns/812/workflow-readiness" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a WorkflowReadiness.
Show the 2 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Count contacts by gateway and mailbox host
/v1/campaigns/{campaignId}/mail-providerscampaigns.get-mail-providers- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
security_gateways feature on your workspace. Until it is on, calls answer 404.Counts the campaign's contacts by the email security gateway in front of their address and by the host of their mailbox. Each contact is judged by its first Safe or Verified email, the one the contact list shows.
gateways lists every security gateway and mailboxProviders every mailbox host and forwarding service Kenso tracks, including those with 0 contacts, most contacts first. pendingCount counts contacts whose domain is not checked for a gateway yet. At most 100,000 contacts are counted; past that, isPartial is true.
Errors:
404 not_found: the campaign does not exist in this workspace.
Requires Campaigns view.
curl -X GET "https://api.ken.so/v1/campaigns/812/mail-providers" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a CampaignMailProviders.
Show the 4 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get a campaign's weekly report
/v1/campaigns/{campaignId}/weekly-reportcampaigns.get-weekly-report- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
Returns one week of the campaign's email numbers, its numbers to date and per segment, what changed during the week, and what happens next. The sentences in changed and next are written from the data, not by AI.
weekOf is any date in the Monday-to-Sunday week you want, as YYYY-MM-DD from 2000-01-01 to one year from today. Without it, the report covers the latest week that has ended both in the report's time zone and in UTC. timeZone is an IANA name such as Europe/Berlin; without it the campaign's sending time zone is used, else UTC. The week's dates are picked in that time zone, and its numbers are counted on those days in UTC, as on the Analytics tab. toDate and segments run from the day the campaign was created (at most 366 days back) to the end of the week. next describes now, in the campaign's sending time zone, and is empty for a week older than the default week.
Errors:
400 validation_failed:weekOfis not aYYYY-MM-DDdate in range, ortimeZoneis not an IANA time zone name.404 not_found: the campaign does not exist in this workspace.
Requires Campaigns view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
weekOf | query | string | optional | Any date in the week to report, as YYYY-MM-DD. Defaults to the latest finished week. |
timeZone | query | string | optional | IANA time zone the week's dates are picked in. Defaults to the campaign's sending time zone, else UTC. |
curl -X GET "https://api.ken.so/v1/campaigns/812/weekly-report" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a CampaignWeeklyReport.
Show the 8 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get a campaign's lead scoring setting
/v1/campaigns/{campaignId}/scoringcampaigns.get-scoring- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
Returns whether lead scoring is on for the campaign.
Errors:
404 not_found: the campaign does not exist in this workspace.
Requires Campaigns view.
curl -X GET "https://api.ken.so/v1/campaigns/812/scoring" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a ScoringSettings.
Show the 1 response field and an example
The fields and an example are also on this endpoint's Markdown page.
Turn lead scoring on or off
/v1/campaigns/{campaignId}/scoringcampaigns.replace-scoring- Permission
- Campaigns edit
- Rate limit
- 4,800 requests a minute per API key
Turns lead scoring on or off for the campaign and returns the new setting. Score contacts with POST /v1/campaigns/{campaignId}/scoring/run.
Errors:
404 not_found: the campaign does not exist in this workspace.
Requires Campaigns edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
isEnabled | boolean | optional | True turns lead scoring on; false or omitted turns it off. |
curl -X PUT "https://api.ken.so/v1/campaigns/812/scoring" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"isEnabled": true
}'Response 200
data is a ScoringSettings.
Show the 1 response field and an example
The fields and an example are also on this endpoint's Markdown page.
List a campaign's AI workflows
/v1/campaigns/{campaignId}/ai-workflowscampaigns.list-ai-workflows- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
Returns the AI workflows attached to the campaign. Ids: 1 qualification, 2 personalization, 3 rewriting, 4 segmentation, 6 scoring, 8 line check.
Errors:
404 not_found: the campaign does not exist in this workspace.
Requires Campaigns view.
curl -X GET "https://api.ken.so/v1/campaigns/812/ai-workflows" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a list of CampaignAiWorkflow. Each item has these fields. The response also carries pagination.
Show the 2 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Replace a campaign's AI workflows
/v1/campaigns/{campaignId}/ai-workflowscampaigns.replace-ai-workflows- Permission
- Campaigns edit
- Rate limit
- 4,800 requests a minute per API key
Sets the AI workflows the campaign runs and returns them. Send every workflow id the campaign should run in aiWorkflowIds: ids you leave out are detached, and [] detaches all of them. To add one workflow, read the current set first. No other campaign field changes.
Ids: 1 qualification, 2 personalization, 3 rewriting, 4 segmentation, 6 scoring, 8 line check. Rewriting runs only when the campaign has rewriting prompts. Line check grades personalization lines before they are saved and holds a contact whose lines fail. A campaign gets it with personalization by default, and this call does not add it: keep 8 in the list to keep it on.
While the campaign is scheduled, launching or sending, 1, 2 and 4 must stay as they are and 3 can only be added, because they decide which contacts may send. Pause the campaign first to change them. 6 and 8 can change at any time.
Errors:
400 validation_failed:aiWorkflowIdsis missing or holds an unknown id.404 not_found: the campaign does not exist in this workspace.409 invalid_state: the change touches 1, 2, 3 or 4 in a way that is not allowed while the campaign is scheduled, launching or sending.
Requires Campaigns edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
aiWorkflowIds | array of integer (int64) | required | Every workflow id to attach: 1 qualification, 2 personalization, 3 rewriting, 4 segmentation, 6 scoring or 8 line check. Required. [] detaches every workflow. |
curl -X PUT "https://api.ken.so/v1/campaigns/812/ai-workflows" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"aiWorkflowIds": [
1,
2,
6
]
}'Response 200
data is a list of CampaignAiWorkflow. Each item has these fields. The response also carries pagination.
Show the 2 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Score a campaign's contacts
/v1/campaigns/{campaignId}/scoring/runcampaigns.run-scoring- Permission
- Campaigns edit and the
askpermission - Rate limit
- 60 requests a minute per API key
Scores the campaign's qualified contacts and returns a finished lead_scoring job with the counts. The run completes within the request; read the job again with GET /v1/jobs/{jobId}?type=lead_scoring. Each score is the contact's qualityScore.
Send contactIds to score those contacts, or omit it to let Kenso pick. limit caps the run at 1 to 1000 contacts, 100 by default. Lead scoring must be on for the campaign.
Errors:
400 validation_failed:limitis not 1 to 1000.404 not_found: the campaign does not exist in this workspace.409 conflict: lead scoring is off for the campaign, or none of the contacts are qualified, so nothing was scored.
Requires Campaigns edit and the ask permission.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
contactIds | array of integer (int64) | optional | Ids of the contacts to score; only qualified contacts among them are scored. Omit to let Kenso pick up to limit of the campaign's qualified contacts. |
limit | integer (int32) | optional | Most contacts to score in this run, from 1 to 1000. Defaults to 100. |
curl -X POST "https://api.ken.so/v1/campaigns/812/scoring/run" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"contactIds": [
90125,
90126
]
}'Response 200
data is a Job.
Show the 14 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Start an enrichment run
/v1/campaigns/{campaignId}/enrichment-runscampaigns.create-enrichment-run- Permission
- Campaigns edit
- Rate limit
- 10 requests a minute per API key; 20 requests a minute and 500 a day per workspace (Free plan: 2 a minute and 50 a day)
Matches the campaign's contacts and their companies against Kenso's people and company data to fill in missing details. The call returns an enrichment job once every batch is queued; the matching runs in the background. minConfidence is the lowest match confidence to accept, from 0 to 1, 0.5 by default.
Errors:
400 validation_failed:minConfidenceis not between 0 and 1.400 validation_failed: the workspace is a developer sandbox. A sandbox holds seeded and test data only, so enrichment runs are not available in it.404 not_found: the campaign does not exist in this workspace.429 rate_limited: the workspace started too many enrichment runs in a short time. Try again later.503 service_unavailable: a batch could not be queued. Try again shortly.
Requires Campaigns edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
minConfidence | number (float) | optional | Lowest match confidence to accept, from 0 to 1. Defaults to 0.5. |
curl -X POST "https://api.ken.so/v1/campaigns/812/enrichment-runs" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"minConfidence": 0.7
}'Response 200
data is a Job.
Show the 14 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Retry failed enrichment
/v1/campaigns/{campaignId}/retry-enrichmentcampaigns.retry-enrichment- Permission
- Campaigns edit
- Rate limit
- 10 requests a minute per API key
Clears the campaign's failed website reads and failed email searches so Kenso tries those contacts and companies again, and returns how many were cleared. It does not restart processing and does not change qualification, personalization or what was sent. If enrichment is paused, the failures are still cleared and the retries wait until it resumes. Calling it when nothing failed returns zero counts.
Errors:
400 validation_failed: the campaign is archived.404 not_found: the campaign does not exist in this workspace.
Requires Campaigns edit.
curl -X POST "https://api.ken.so/v1/campaigns/812/retry-enrichment" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a RetryEnrichment.
Show the 3 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Schedule a campaign's launch
/v1/campaigns/{campaignId}/launch-schedulecampaigns.set-launch-schedule- Permission
- Campaigns edit and the
launchpermission - Rate limit
- 4,800 requests a minute per API key
launch_schedule feature on your workspace. Until it is on, calls answer 404.Sets when the campaign launches and returns it, with launchAt set and autoLaunchWhenReady on. At that time Kenso launches it as you would, with the same checks (billing, credits, inboxes, client approval). If the campaign is not ready yet by then, it launches as soon as it is. Where the client approves campaigns, Kenso asks the client as soon as the campaign is ready, so the approval can be in by then; a launch still waiting on it goes out once the client approves. Sends then follow its sending days, window and time zone, so a launch on a Sunday for a weekday campaign sends its first emails on Monday. Launching it yourself before then launches it now. Call it again to move the time, and DELETE /v1/campaigns/{campaignId}/launch-schedule to clear it.
If the launch is refused at that time, for example because sending credits ran out, the campaign stays ready for you to launch by hand, and Kenso does not try again.
Errors:
400 validation_failed:launchAtis missing, under 5 minutes or over 90 days from now, or the campaign cannot be scheduled: a trigger campaign, an approval test campaign, or one that already launched.404 not_found: the campaign does not exist in this workspace.409 conflict: auto-launch already ran for this campaign.
Requires Campaigns edit and the launch permission.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
launchAt | string (date-time) | optional | When to launch, as an ISO 8601 date and time with its offset, such as 2026-11-16T09:00:00+01:00 or 2026-11-16T08:00:00Z. At least 5 minutes and at most 90 days from now. |
curl -X PUT "https://api.ken.so/v1/campaigns/812/launch-schedule" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"launchAt": "2026-10-19T13:00:00Z"
}'Response 200
data is a Campaign.
Show the 62 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Clear a campaign's launch schedule
/v1/campaigns/{campaignId}/launch-schedulecampaigns.clear-launch-schedule- Permission
- Campaigns edit and the
launchpermission - Rate limit
- 4,800 requests a minute per API key
launch_schedule feature on your workspace. Until it is on, calls answer 404.Removes the scheduled launch time and returns the campaign. With autoLaunchWhenReady false (the default) the campaign waits for you to launch it; with true it launches as soon as it is ready, which can be right away. Clearing a campaign with no schedule, or one that already launched, changes nothing.
Errors:
400 validation_failed: the schedule can no longer change, for example on a campaign that is launching.404 not_found: the campaign does not exist in this workspace.409 conflict: the scheduled launch already ran.
Requires Campaigns edit and the launch permission.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
autoLaunchWhenReady | query | boolean | optional | True keeps auto-launch on once the schedule is gone. Defaults to false. |
curl -X DELETE "https://api.ken.so/v1/campaigns/812/launch-schedule" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a Campaign.
Show the 62 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Restart a campaign's processing
/v1/campaigns/{campaignId}/restartcampaigns.restart- Permission
- Campaigns edit and the
launchpermission - Rate limit
- 200 requests a minute per API key
Runs the campaign's processing again from the start. Use it to recover a campaign that stalled or failed, or to reprocess after you change its setup. Returns the campaign.
On a draft campaign it starts processing behind the same readiness checks as resume. A campaign with autoLaunchWhenReady on launches by itself once processing reaches ready.
Errors:
400 validation_failed: the campaign is archived, is a draft trigger campaign (start it withPOST /v1/campaigns/{campaignId}/resume), or fails the readiness checks.404 not_found: the campaign does not exist in this workspace.409 invalid_state: the workspace's data is scheduled for deletion or being deleted.
Requires Campaigns edit and the launch permission.
curl -X POST "https://api.ken.so/v1/campaigns/812/restart" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a Campaign.
Show the 62 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get a campaign's sender routing
/v1/campaigns/{campaignId}/sender-routingcampaigns.get-sender-routing- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
Returns the campaign's sender routing rules with what each one covers now. Each rule sends the first email to contacts on one mailbox provider or security gateway only from the rule's domains and inboxes. A security gateway rule wins over a mailbox provider rule. Contacts no rule matches get their first email from the inboxes no rule claims (everyoneElse).
For each rule and for everyoneElse you get the campaign's inboxes that can send now, their combined daily limit, and the contacts that can still get an email and match now. At most 100,000 contacts are read, and a contact whose provider is still being detected is in no group. warnings lists rules with no inbox that can send (rule_no_inbox), contacts left with no inbox (everyone_else_no_inbox), and rules that need more than 5 days to reach their contacts (rule_slow). allInboxes shows whether the campaign uses all inboxes or a saved list.
Errors:
400 validation_failed: the workspace does not have the sender routing feature (detail codefeature_disabled).404 not_found: the campaign does not exist in this workspace.
Requires Campaigns view.
curl -X GET "https://api.ken.so/v1/campaigns/812/sender-routing" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a SenderRouting.
Show the 4 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Replace a campaign's sender routing rules
/v1/campaigns/{campaignId}/sender-routingcampaigns.replace-sender-routing- Permission
- Campaigns edit
- Rate limit
- 4,800 requests a minute per API key
Replaces every sender routing rule of the campaign and returns the routing as GET /v1/campaigns/{campaignId}/sender-routing does. Send [] in rules to clear them.
Each rule names one mailbox provider or security gateway in provider (one rule per provider) and at least one whole sending domain in domains or single inbox in inboxIds. Inboxes added later on a listed domain join the rule. The rules apply to first emails planned from now on and to queued first emails when they send. Follow-ups always come from the inbox that sent the first email.
Errors:
400 validation_failed: a rule is invalid. Detail codes:unknown_provider,unsupported_provider,duplicate_provider,empty_rule(no domain and no inbox),unknown_domain(no workspace inbox on that domain),unknown_inbox, orfeature_disabledwhen the workspace does not have the sender routing feature.404 not_found: the campaign does not exist in this workspace.
Requires Campaigns edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
rules | array of ReplaceCampaignSenderRouteRule | required | The rules, at most one per provider. Required. |
curl -X PUT "https://api.ken.so/v1/campaigns/812/sender-routing" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"rules": [
{
"provider": "microsoft_365",
"domains": [
"outreach.example.net"
]
}
]
}'Response 200
data is a SenderRouting.
Show the 4 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Count contacts by recipient provider
/v1/campaigns/{campaignId}/recipient-providerscampaigns.list-recipient-providers- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
Counts the campaign's contacts that can still get an email under every mailbox provider and security gateway Kenso tracks, including those with 0 contacts, most contacts first. Use it to plan sender routing rules.
Each contact is placed by the domain of the address Kenso emails. A contact counts once under its mailbox provider and once under its security gateway. pendingCount counts contacts whose provider is still being detected, and noProviderCount those with no known provider. At most 100,000 contacts are counted; past that, isPartial is true.
Errors:
400 validation_failed: the workspace does not have the sender routing feature (detail codefeature_disabled).404 not_found: the campaign does not exist in this workspace.
Requires Campaigns view.
curl -X GET "https://api.ken.so/v1/campaigns/812/recipient-providers" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a RecipientProviderCounts.
Show the 4 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
More in Campaigns:Email sequencesLinkedIn sequencesSegment email sequencesSegment LinkedIn sequencesSequence variablesSequences with conditionsSequence importSegmentsLead listsShare linksClient approvalsSending capacityAuto-pausesCampaign languagesLocalized stepsText translationMarket packsCountry complianceCampaign imagesAll resources