Skip to Content
Campaigns

Share links

Share campaigns and results with your clients.

Campaigns8 endpointsKen-Version: 2026-11-02AuthenticationWorkspacesErrors
MarkdownOpenAPI

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.

NameInTypeRequiredDescription
shareIdpathinteger (int64)requiredId of the share.

Headers

The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.

NameInTypeRequiredDescription
Ken-Versionheaderstring, one of: 2026-11-02, 1.1optionalThe 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-Idheaderinteger (int64)optionalThe 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 shares

GET/v1/sharesshares.list
Permission
Share view
Rate limit
12,000 requests a minute per API key
Needs the share feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Lists the workspace's share links, newest first. Revoked shares are left out.

Filter with campaignId, accountId (shares that include that account's plan) and status. Page with limit and cursor. changesRequestedCount counts every share that is not revoked and has changes requested, whatever the filters. Each share's url is an empty string unless you have Share edit and the share permission.

Errors:

  • 400 validation_failed: limit is not from 1 to 200, cursor is invalid, or status holds an unknown value.

Requires Share view.

Parameters

NameInTypeRequiredDescription
limitqueryinteger (int32)optionalNumber of shares per page, from 1 to 200, default 50.
cursorquerystringoptionalThe nextCursor from the previous page. Omit it for the first page.
campaignIdqueryinteger (int64)optionalOnly the shares of the campaign with this id. Omit it for every campaign.
accountIdqueryinteger (int64)optionalOnly the shares that include the plan of the account with this id. Omit it for every account.
statusquerystringoptionalOnly the shares in these statuses, as a comma-separated list of not_opened, viewed, n_of_m_approved, changes_requested and approved. Omit it for every status.
Request
curl -X GET "https://api.ken.so/v1/shares?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 Share. Each item has these fields. The response also carries pagination, changesRequestedCount.

Show the 35 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Create a share

POST/v1/sharesshares.create
Permission
Share edit and the share permission
Rate limit
4,800 requests a minute per API key
Needs the share feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Creates a share link, freezes a snapshot of each shared item, and emails the link to every recipient that is an email address. Returns 201 with the new share and its url.

Send items and permission. campaignId is required unless the share holds only account plans, and accountIds is required with plan. The request body fields list every option and its rules.

Copy is one item, lead lists are one item per active segment, and plans are one item per account. On an approve share, the copy and lead list items are the same approval items the campaign's launch waits on, so a decision on the link also counts for launch. Kenso does not email a recipient that already got a share email from this workspace in the last 24 hours, and lists them in alreadyEmailedRecipients. Each address Kenso emails counts against the workspace's daily share email cap.

Errors:

  • 400 validation_failed: a field is missing or invalid. A campaign with no copy or no active segment gives an items detail with code empty, and an account that is not in this workspace gives an accountIds[n] detail with code not_found.
  • 404 not_found: the campaign does not exist in this workspace.
  • 429 quota_exceeded: the emails would pass the workspace's daily share email cap (detail code share_email_quota). Kenso creates nothing and emails no one.

Requires Share edit and the share permission.

Request body

application/json, optional.

FieldTypeRequiredDescription
namestringoptionalName of the share, at most 255 characters. Omitted, Kenso names it after the campaign and the shared items, such as "Q4 RevOps · lead list and copy".
companystringoptionalWho the share is for, shown on the share page, at most 255 characters. Omitted, it is the workspace name.
campaignIdinteger (int64)optionalId of the campaign to share. Required unless items holds only plan.
accountIdsarray of integer (int64)optionalIds of the accounts whose plans to share, from 1 to 100. Required with plan and ignored without it.
itemsarray of stringoptionalWhat to share, at least one of: leads (the lead lists), copy (the email copy), settings (the campaign settings), icp (the targeting), report (the weekly report) and plan (account plans).
permissionstringrequiredWhat reviewers can do: view, comment or approve. Required.
expirystringoptionalHow long the link works, counted from creation: 7_days, 30_days or never. Omitted means 30_days.
recipientsarray of stringoptionalUp to 20 email addresses or names, each at most 254 characters. Kenso emails the link to the email addresses and only records the names.
holdLaunchbooleanoptionalTrue keeps the campaign from launching or resuming until reviewers approve every item. Needs approve and a leads, copy or settings item. Defaults to false.
recurringReportbooleanoptionalTrue emails the recipients a fresh weekly report every Monday at 8 AM. Needs a report item. Defaults to false.
Request
curl -X POST "https://api.ken.so/v1/shares" \
  -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": "string",
  "company": "string",
  "campaignId": 812,
  "accountIds": [
    812
  ],
  "items": [
    "string"
  ],
  "permission": "view",
  "expiry": "7_days",
  "recipients": [
    "string"
  ],
  "holdLaunch": true,
  "recurringReport": true
}'

Response 201

data is a Share.

Show the 35 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Get a share

GET/v1/shares/{shareId}shares.get
Permission
Share view
Rate limit
12,000 requests a minute per API key
Needs the share feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Returns one share with its items, comments, access summary and log. url is an empty string unless you have Share edit and the share permission.

Errors:

  • 404 not_found: no share with this id exists in this workspace, or it was revoked.

Requires Share view.

Request
curl -X GET "https://api.ken.so/v1/shares/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 Share.

Show the 35 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Update a share

PATCH/v1/shares/{shareId}shares.update
Permission
Share edit and the share permission
Rate limit
4,800 requests a minute per API key
Needs the share feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Changes a share's settings. Fields you leave out stay as they are. You can change name, company, recipients (the list you send replaces the old one), expiry (counted from when the share was created), holdLaunch and recurringReport. The shared items and the permission are fixed: create a new share to change them.

Kenso does not email the link to recipients you add. Each new email address still counts against the workspace's daily share email cap, because it gets the later reminders and weekly reports. When the update ends the share's launch hold, Kenso resumes a campaign the hold kept paused, unless another approval still blocks it.

Errors:

  • 400 validation_failed: a field is invalid, such as a blank name, more than 20 recipients, or holdLaunch on a share that is not an approve share with lead lists, copy or settings.
  • 404 not_found: no share with this id exists in this workspace, or it was revoked.
  • 429 quota_exceeded: the new addresses would pass the workspace's daily share email cap (detail code share_email_quota). Kenso changes nothing.

Requires Share edit and the share permission.

Request body

application/json, optional.

FieldTypeRequiredDescription
namestringoptionalNew name of the share, at most 255 characters. It cannot be blank.
companystringoptionalWho the share is for, shown on the share page, at most 255 characters.
recipientsarray of stringoptionalThe full recipient list, up to 20 email addresses or names. It replaces the old list. Kenso does not email the link to new recipients, but they get later reminders and weekly reports.
expirystringoptionalHow long the link works: 7_days, 30_days or never, counted from when the share was created, not from now.
holdLaunchbooleanoptionalTrue keeps the campaign from launching or resuming until reviewers approve every item. Needs an approve share with a leads, copy or settings item.
recurringReportbooleanoptionalTrue emails the recipients a fresh weekly report every Monday at 8 AM. Needs a report item.
Request
curl -X PATCH "https://api.ken.so/v1/shares/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 '{
  "name": "string",
  "company": "string",
  "recipients": [
    "string"
  ],
  "expiry": "7_days",
  "holdLaunch": true,
  "recurringReport": true
}'

Response 200

data is a Share.

Show the 35 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Revoke a share

DELETE/v1/shares/{shareId}shares.revoke
Permission
Share edit and the share permission
Rate limit
4,800 requests a minute per API key
Needs the share feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Turns a share link off for good. The link then answers 410 share_inactive, and the share leaves the list. Decisions already made stay. If the share held a campaign's launch, Kenso resumes a campaign the hold kept paused, unless another approval still blocks it. Returns 204.

Errors:

  • 404 not_found: no share with this id exists in this workspace, or it was already revoked.

Requires Share edit and the share permission.

Request
curl -X DELETE "https://api.ken.so/v1/shares/812" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"

Response 204

Response 204
HTTP/1.1 204 No Content

Preview a new share

POST/v1/shares/previewshares.preview-draft
Permission
Share edit and the share permission
Rate limit
4,800 requests a minute per API key
Needs the share feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Shows what a reviewer would see for a share you have not created yet. Send the same body as POST /v1/shares. Kenso builds the items the way create does, with copy rendered for sample contacts, but saves nothing and emails no one.

Items in the preview are numbered from 1 and show as not reviewed. The exception is copy and lead lists on an approve share whose current version is already approved.

Errors:

  • 400 validation_failed: the body fails a check that POST /v1/shares makes.
  • 404 not_found: the campaign does not exist in this workspace.

Requires Share edit and the share permission.

Request body

application/json, optional.

FieldTypeRequiredDescription
namestringoptionalName of the share, at most 255 characters. Omitted, Kenso names it after the campaign and the shared items, such as "Q4 RevOps · lead list and copy".
companystringoptionalWho the share is for, shown on the share page, at most 255 characters. Omitted, it is the workspace name.
campaignIdinteger (int64)optionalId of the campaign to share. Required unless items holds only plan.
accountIdsarray of integer (int64)optionalIds of the accounts whose plans to share, from 1 to 100. Required with plan and ignored without it.
itemsarray of stringoptionalWhat to share, at least one of: leads (the lead lists), copy (the email copy), settings (the campaign settings), icp (the targeting), report (the weekly report) and plan (account plans).
permissionstringrequiredWhat reviewers can do: view, comment or approve. Required.
expirystringoptionalHow long the link works, counted from creation: 7_days, 30_days or never. Omitted means 30_days.
recipientsarray of stringoptionalUp to 20 email addresses or names, each at most 254 characters. Kenso emails the link to the email addresses and only records the names.
holdLaunchbooleanoptionalTrue keeps the campaign from launching or resuming until reviewers approve every item. Needs approve and a leads, copy or settings item. Defaults to false.
recurringReportbooleanoptionalTrue emails the recipients a fresh weekly report every Monday at 8 AM. Needs a report item. Defaults to false.
Request
curl -X POST "https://api.ken.so/v1/shares/preview" \
  -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": "string",
  "company": "string",
  "campaignId": 812,
  "accountIds": [
    812
  ],
  "items": [
    "string"
  ],
  "permission": "view",
  "expiry": "7_days",
  "recipients": [
    "string"
  ],
  "holdLaunch": true,
  "recurringReport": true
}'

Response 200

data is a SharePublic.

Show the 18 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Remind a share's recipients

POST/v1/shares/{shareId}/remindersshares.remind
Permission
Share edit and the share permission
Rate limit
4,800 requests a minute per API key
Needs the share feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Emails the link again to the share's recipients that are email addresses, and logs a share_reminder_sent entry. Returns 202 with recipientCount, the number of addresses emailed.

Kenso sends at most one reminder per share every 24 hours. It skips a recipient that got a share email from this workspace in the last 24 hours, and lists them in alreadyEmailedRecipients. Each address Kenso emails counts against the workspace's daily share email cap.

Errors:

  • 400 validation_failed: the share has no recipients.
  • 404 not_found: no share with this id exists in this workspace, or it was revoked.
  • 409 no_email_recipients: every recipient is a name, so there is nobody to email.
  • 410 share_expired: the share has expired.
  • 429 quota_exceeded: the share got a reminder in the last 24 hours (detail code reminder_cooldown), the emails would pass the daily share email cap (share_email_quota), or every recipient got a share email in the last 24 hours (recipients_emailed_today). The response carries Retry-After, and Kenso sends nothing.

Requires Share edit and the share permission.

Request
curl -X POST "https://api.ken.so/v1/shares/812/reminders" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"

Response 202

data is a ShareReminder.

Show the 4 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Preview a share

GET/v1/shares/{shareId}/previewshares.preview
Permission
Share view
Rate limit
12,000 requests a minute per API key
Needs the share feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Returns the share page exactly as a reviewer sees it at the share's url, without counting a view. It works on an expired share too.

Errors:

  • 404 not_found: no share with this id exists in this workspace, or it was revoked.

Requires Share view.

Request
curl -X GET "https://api.ken.so/v1/shares/812/preview" \
  -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 SharePublic.

Show the 18 response fields and an example

The fields and an example are also on this endpoint's Markdown page.


On this page