Share links
Share campaigns and results with your clients.
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 |
|---|---|---|---|---|
shareId | path | integer (int64) | required | Id of the share. |
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 shares
/v1/sharesshares.list- Permission
- Share view
- Rate limit
- 12,000 requests a minute per API key
share feature on your workspace. Until it is on, calls answer 404.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:limitis not from 1 to 200,cursoris invalid, orstatusholds an unknown value.
Requires Share view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer (int32) | optional | Number of shares per page, from 1 to 200, default 50. |
cursor | query | string | optional | The nextCursor from the previous page. Omit it for the first page. |
campaignId | query | integer (int64) | optional | Only the shares of the campaign with this id. Omit it for every campaign. |
accountId | query | integer (int64) | optional | Only the shares that include the plan of the account with this id. Omit it for every account. |
status | query | string | optional | Only 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. |
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
/v1/sharesshares.create- Permission
- Share edit and the
sharepermission - Rate limit
- 4,800 requests a minute per API key
share feature on your workspace. Until it is on, calls answer 404.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 anitemsdetail with codeempty, and an account that is not in this workspace gives anaccountIds[n]detail with codenot_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 codeshare_email_quota). Kenso creates nothing and emails no one.
Requires Share edit and the share permission.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | optional | Name 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". |
company | string | optional | Who the share is for, shown on the share page, at most 255 characters. Omitted, it is the workspace name. |
campaignId | integer (int64) | optional | Id of the campaign to share. Required unless items holds only plan. |
accountIds | array of integer (int64) | optional | Ids of the accounts whose plans to share, from 1 to 100. Required with plan and ignored without it. |
items | array of string | optional | What 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). |
permission | string | required | What reviewers can do: view, comment or approve. Required. |
expiry | string | optional | How long the link works, counted from creation: 7_days, 30_days or never. Omitted means 30_days. |
recipients | array of string | optional | Up to 20 email addresses or names, each at most 254 characters. Kenso emails the link to the email addresses and only records the names. |
holdLaunch | boolean | optional | True keeps the campaign from launching or resuming until reviewers approve every item. Needs approve and a leads, copy or settings item. Defaults to false. |
recurringReport | boolean | optional | True emails the recipients a fresh weekly report every Monday at 8 AM. Needs a report item. Defaults to false. |
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
/v1/shares/{shareId}shares.get- Permission
- Share view
- Rate limit
- 12,000 requests a minute per API key
share feature on your workspace. Until it is on, calls answer 404.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.
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
/v1/shares/{shareId}shares.update- Permission
- Share edit and the
sharepermission - Rate limit
- 4,800 requests a minute per API key
share feature on your workspace. Until it is on, calls answer 404.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 blankname, more than 20 recipients, orholdLaunchon 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 codeshare_email_quota). Kenso changes nothing.
Requires Share edit and the share permission.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | optional | New name of the share, at most 255 characters. It cannot be blank. |
company | string | optional | Who the share is for, shown on the share page, at most 255 characters. |
recipients | array of string | optional | The 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. |
expiry | string | optional | How long the link works: 7_days, 30_days or never, counted from when the share was created, not from now. |
holdLaunch | boolean | optional | True keeps the campaign from launching or resuming until reviewers approve every item. Needs an approve share with a leads, copy or settings item. |
recurringReport | boolean | optional | True emails the recipients a fresh weekly report every Monday at 8 AM. Needs a report item. |
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
/v1/shares/{shareId}shares.revoke- Permission
- Share edit and the
sharepermission - Rate limit
- 4,800 requests a minute per API key
share feature on your workspace. Until it is on, calls answer 404.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.
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
HTTP/1.1 204 No ContentPreview a new share
/v1/shares/previewshares.preview-draft- Permission
- Share edit and the
sharepermission - Rate limit
- 4,800 requests a minute per API key
share feature on your workspace. Until it is on, calls answer 404.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 thatPOST /v1/sharesmakes.404 not_found: the campaign does not exist in this workspace.
Requires Share edit and the share permission.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | optional | Name 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". |
company | string | optional | Who the share is for, shown on the share page, at most 255 characters. Omitted, it is the workspace name. |
campaignId | integer (int64) | optional | Id of the campaign to share. Required unless items holds only plan. |
accountIds | array of integer (int64) | optional | Ids of the accounts whose plans to share, from 1 to 100. Required with plan and ignored without it. |
items | array of string | optional | What 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). |
permission | string | required | What reviewers can do: view, comment or approve. Required. |
expiry | string | optional | How long the link works, counted from creation: 7_days, 30_days or never. Omitted means 30_days. |
recipients | array of string | optional | Up to 20 email addresses or names, each at most 254 characters. Kenso emails the link to the email addresses and only records the names. |
holdLaunch | boolean | optional | True keeps the campaign from launching or resuming until reviewers approve every item. Needs approve and a leads, copy or settings item. Defaults to false. |
recurringReport | boolean | optional | True emails the recipients a fresh weekly report every Monday at 8 AM. Needs a report item. Defaults to false. |
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
/v1/shares/{shareId}/remindersshares.remind- Permission
- Share edit and the
sharepermission - Rate limit
- 4,800 requests a minute per API key
share feature on your workspace. Until it is on, calls answer 404.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 codereminder_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 carriesRetry-After, and Kenso sends nothing.
Requires Share edit and the share permission.
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
/v1/shares/{shareId}/previewshares.preview- Permission
- Share view
- Rate limit
- 12,000 requests a minute per API key
share feature on your workspace. Until it is on, calls answer 404.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.
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.
More in Campaigns:CampaignsEmail sequencesLinkedIn sequencesSegment email sequencesSegment LinkedIn sequencesSequence variablesSequences with conditionsSequence importSegmentsLead listsClient approvalsSending capacityAuto-pausesCampaign languagesLocalized stepsText translationMarket packsCountry complianceCampaign imagesAll resources