Kenso
Get early access

Segments

Split a campaign's audience into segments, preview their filters, switch them on or off and restore saved versions.

Campaigns and sequences13 endpointsKen-Version: 2026-11-02AuthenticationWorkspacesErrors

List segments of a campaign in the current workspace

GET/v1/campaigns/{campaignId}/segmentssegments.list

Try it on developer.ken.so

Ordered by id. q matches the name. isActive filters that flag. includeMetrics=false skips the contact counts and omits contactCount, rawContactCount and readyContactCount: use it when only ids and names are needed. Read-only. Requires ReadAccess.

Parameters

Name
In
Type
Required
Description
campaignId
In: path
integer (int64)
required
Q
In: query
string
optional
IsActive
In: query
boolean
optional
Limit
In: query
integer (int32)
optional
Cursor
In: query
string
optional
IncludeMetrics
In: query
boolean
optional
Default true. False skips the contact counts (contactCount, rawContactCount, readyContactCount are omitted): a names-only read for pickers.
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Response 200

data is a list of SegmentModel. Each item has these fields. The response also carries pagination.

Field
Type
Description
id
integer (int64)
campaignId
integer (int64)
name
string
description
string
isDefault
boolean
isActive
boolean
sortOrder
integer (int32)
segmentationType
string
abTestPercentage
integer (int32)
contactCount
integer (int32)
Omitted when the list was read with includeMetrics=false.
rawContactCount
integer (int32)
Omitted when the list was read with includeMetrics=false.
readyContactCount
integer (int32)
Omitted when the list was read with includeMetrics=false.
filterCriteria
CampaignSegmentFilterCriteriaDTO
createdAt
string (date-time)
modifiedAt
string (date-time)
Request
curl -X GET "https://api.ken.so/v1/campaigns/812/segments" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"
Response 200
{
  "success": true,
  "data": [
    {
      "id": 1207,
      "campaignId": 4821,
      "name": "Engineering leaders",
      "description": "VPs and heads of engineering at B2B SaaS companies with 50 to 500 employees.",
      "isDefault": false,
      "isActive": true,
      "sortOrder": 1,
      "segmentationType": "ai",
      "contactCount": 640,
      "rawContactCount": 712,
      "readyContactCount": 598,
      "createdAt": "2026-09-23T15:02:11Z",
      "modifiedAt": "2026-10-14T09:41:27Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6ODE1fQ",
    "hasMore": true,
    "total": 1,
    "isTotalCapped": true
  }
}

Create a segment on a campaign in the current workspace

POST/v1/campaigns/{campaignId}/segmentssegments.create

Try it on developer.ken.so

Returns 201 and Location. Requires WriteAccess.

Parameters

Name
In
Type
Required
Description
campaignId
In: path
integer (int64)
required
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Request body

application/json, optional.

Field
Type
Required
Description
name
string
optional
description
string
optional
segmentationType
string
optional
abTestPercentage
integer (int32)
optional
sortOrder
integer (int32)
optional
filterCriteria
CampaignSegmentFilterCriteriaDTO
optional

Response 201

data is a SegmentModel.

Field
Type
Description
id
integer (int64)
campaignId
integer (int64)
name
string
description
string
isDefault
boolean
isActive
boolean
sortOrder
integer (int32)
segmentationType
string
abTestPercentage
integer (int32)
contactCount
integer (int32)
Omitted when the list was read with includeMetrics=false.
rawContactCount
integer (int32)
Omitted when the list was read with includeMetrics=false.
readyContactCount
integer (int32)
Omitted when the list was read with includeMetrics=false.
filterCriteria
CampaignSegmentFilterCriteriaDTO
createdAt
string (date-time)
modifiedAt
string (date-time)
Request
curl -X POST "https://api.ken.so/v1/campaigns/812/segments" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Engineering leaders",
  "description": "VPs and heads of engineering at B2B SaaS companies with 50 to 500 employees.",
  "segmentationType": "ai",
  "sortOrder": 1
}'
Response 201
{
  "success": true,
  "data": {
    "id": 1207,
    "campaignId": 4821,
    "name": "Engineering leaders",
    "description": "VPs and heads of engineering at B2B SaaS companies with 50 to 500 employees.",
    "isDefault": false,
    "isActive": true,
    "sortOrder": 1,
    "segmentationType": "ai",
    "contactCount": 640,
    "rawContactCount": 712,
    "readyContactCount": 598,
    "createdAt": "2026-09-23T15:02:11Z",
    "modifiedAt": "2026-10-14T09:41:27Z"
  }
}

Preview a segment filter against the campaign

POST/v1/campaigns/{campaignId}/segments/previewsegments.preview

Try it on developer.ken.so

Returns the match count, a contact sample, and the filter catalog (filterOptions). Omit the body to read the catalog only, or read it without a campaign at GET /v1/segments/filter-options. A body, including an empty object, runs the match preview. segmentId scopes a match preview to an existing segment. Read-only. Requires ReadAccess.

Parameters

Name
In
Type
Required
Description
campaignId
In: path
integer (int64)
required
segmentId
In: query
integer (int64)
optional
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Request body

application/json, optional.

Field
Type
Required
Description
fullName
StringFilter
optional
titles
array of string
optional
excludeTitles
array of string
optional
lastJobTitle
StringFilter
optional
headlines
array of string
optional
excludeHeadlines
array of string
optional
summaryContains
string
optional
seniorityLevels
array of string
optional
excludeSeniorityLevels
array of string
optional
functions
array of string
optional
excludeFunctions
array of string
optional
employmentTypes
array of string
optional
isDecisionMaker
boolean
optional
changedJobRecently
boolean
optional
yearsOfExperience
FloatRange
optional
yearsInCurrentRole
FloatRange
optional
yearsInCurrentCompany
FloatRange
optional
profileCountries
array of string
optional
excludeProfileCountries
array of string
optional
profileState
string
optional
profileCity
string
optional
skillsContains
string
optional
certificationsContains
string
optional
languages
array of string
optional
emailValidity
array of string
optional
emailProviders
array of string
optional
excludeEmailProviders
array of string
optional
isPersonalEmail
boolean
optional
hasLinkedInUrl
boolean
optional
hasPhone
boolean
optional
hasValidPhone
boolean
optional
companyNames
array of string
optional
excludeCompanyNames
array of string
optional
companyDomainContains
string
optional
companyDescriptionContains
string
optional
companySpecialitiesContains
string
optional
industries
array of string
optional
excludeIndustries
array of string
optional
companyHeadcount
IntRange
optional
companyFollowers
IntRange
optional
companyFoundedYear
IntRange
optional
companyTypes
array of string
optional
lastFundingRounds
array of string
optional
totalFunding
LongRange
optional
technologies
array of string
optional
excludeTechnologies
array of string
optional
companyHqCountries
array of string
optional
excludeCompanyHqCountries
array of string
optional
companyHqState
string
optional
companyHqCity
string
optional
doNotContact
boolean
optional
createdAt
DateRange
optional
totalClicks
IntRange
optional
leadQualityScore
IntRange
optional
aiVariableFilters
array of AiVariableFilterDto
optional
customVariableFilters
array of CustomVariableFilterDto
optional

Response 200

data is a SegmentPreviewModel.

Field
Type
Description
matchingCount
integer (int32)
totalCampaignContacts
integer (int32)
sampleContacts
array of SegmentPreviewContactModel
filterOptions
SegmentFilterMetadataDTO
Request
curl -X POST "https://api.ken.so/v1/campaigns/812/segments/preview" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "fullName": {
    "contains": "string",
    "notContains": "string"
  },
  "titles": [
    "string"
  ],
  "excludeTitles": [
    "string"
  ],
  "lastJobTitle": {
    "contains": "string",
    "notContains": "string"
  },
  "headlines": [
    "string"
  ],
  "excludeHeadlines": [
    "string"
  ],
  "summaryContains": "string",
  "seniorityLevels": [
    "string"
  ],
  "excludeSeniorityLevels": [
    "string"
  ],
  "functions": [
    "string"
  ],
  "excludeFunctions": [
    "string"
  ],
  "employmentTypes": [
    "string"
  ],
  "isDecisionMaker": true,
  "changedJobRecently": true,
  "yearsOfExperience": {
    "min": 0.5,
    "max": 0.5
  },
  "yearsInCurrentRole": {
    "min": 0.5,
    "max": 0.5
  },
  "yearsInCurrentCompany": {
    "min": 0.5,
    "max": 0.5
  },
  "profileCountries": [
    "string"
  ],
  "excludeProfileCountries": [
    "string"
  ],
  "profileState": "string",
  "profileCity": "string",
  "skillsContains": "string",
  "certificationsContains": "string",
  "languages": [
    "string"
  ],
  "emailValidity": [
    "string"
  ],
  "emailProviders": [
    "string"
  ],
  "excludeEmailProviders": [
    "string"
  ],
  "isPersonalEmail": true,
  "hasLinkedInUrl": true,
  "hasPhone": true,
  "hasValidPhone": true,
  "companyNames": [
    "string"
  ],
  "excludeCompanyNames": [
    "string"
  ],
  "companyDomainContains": "string",
  "companyDescriptionContains": "string",
  "companySpecialitiesContains": "string",
  "industries": [
    "string"
  ],
  "excludeIndustries": [
    "string"
  ],
  "companyHeadcount": {
    "min": 1,
    "max": 1
  },
  "companyFollowers": {
    "min": 1,
    "max": 1
  },
  "companyFoundedYear": {
    "min": 1,
    "max": 1
  },
  "companyTypes": [
    "string"
  ],
  "lastFundingRounds": [
    "string"
  ],
  "totalFunding": {
    "min": 1,
    "max": 1
  },
  "technologies": [
    "string"
  ],
  "excludeTechnologies": [
    "string"
  ],
  "companyHqCountries": [
    "string"
  ],
  "excludeCompanyHqCountries": [
    "string"
  ],
  "companyHqState": "string",
  "companyHqCity": "string",
  "doNotContact": true,
  "createdAt": {
    "from": "2026-09-23T15:02:11Z",
    "to": "2026-09-23T15:02:11Z"
  },
  "totalClicks": {
    "min": 1,
    "max": 1
  },
  "leadQualityScore": {
    "min": 1,
    "max": 1
  },
  "aiVariableFilters": [
    {
      "promptId": 812,
      "operator": "Exists",
      "value": "string"
    }
  ],
  "customVariableFilters": [
    {
      "variableKey": "string",
      "operator": "Contains",
      "value": "string"
    }
  ]
}'
Response 200
{
  "success": true,
  "data": {
    "matchingCount": 1,
    "totalCampaignContacts": 1,
    "sampleContacts": [
      {
        "id": 812,
        "fullName": "string",
        "title": "string",
        "companyName": "string",
        "location": "string",
        "email": "[email protected]",
        "emailValidity": "string"
      }
    ],
    "filterOptions": {
      "seniorityLevels": [
        {
          "value": "string",
          "label": "string",
          "category": "string"
        }
      ],
      "functions": [
        {
          "value": "string",
          "label": "string",
          "category": "string"
        }
      ],
      "industries": [
        {
          "value": "string",
          "label": "string",
          "category": "string"
        }
      ],
      "companyTypes": [
        {
          "value": "string",
          "label": "string",
          "category": "string"
        }
      ],
      "employmentTypes": [
        {
          "value": "string",
          "label": "string",
          "category": "string"
        }
      ],
      "lastFundingRounds": [
        {
          "value": "string",
          "label": "string",
          "category": "string"
        }
      ],
      "technologies": [
        {
          "value": "string",
          "label": "string",
          "category": "string"
        }
      ],
      "emailValidity": [
        {
          "value": "string",
          "label": "string",
          "category": "string"
        }
      ],
      "emailProviders": [
        {
          "value": "string",
          "label": "string",
          "category": "string"
        }
      ],
      "languages": [
        {
          "value": "string",
          "label": "string",
          "category": "string"
        }
      ]
    }
  }
}

Return one segment in the current workspace

GET/v1/segments/{segmentId}segments.get

Try it on developer.ken.so

A missing or cross-workspace id is not_found. Requires ReadAccess.

Parameters

Name
In
Type
Required
Description
segmentId
In: path
integer (int64)
required
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Response 200

data is a SegmentModel.

Field
Type
Description
id
integer (int64)
campaignId
integer (int64)
name
string
description
string
isDefault
boolean
isActive
boolean
sortOrder
integer (int32)
segmentationType
string
abTestPercentage
integer (int32)
contactCount
integer (int32)
Omitted when the list was read with includeMetrics=false.
rawContactCount
integer (int32)
Omitted when the list was read with includeMetrics=false.
readyContactCount
integer (int32)
Omitted when the list was read with includeMetrics=false.
filterCriteria
CampaignSegmentFilterCriteriaDTO
createdAt
string (date-time)
modifiedAt
string (date-time)
Request
curl -X GET "https://api.ken.so/v1/segments/812" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"
Response 200
{
  "success": true,
  "data": {
    "id": 1207,
    "campaignId": 4821,
    "name": "Engineering leaders",
    "description": "VPs and heads of engineering at B2B SaaS companies with 50 to 500 employees.",
    "isDefault": false,
    "isActive": true,
    "sortOrder": 1,
    "segmentationType": "ai",
    "contactCount": 640,
    "rawContactCount": 712,
    "readyContactCount": 598,
    "createdAt": "2026-09-23T15:02:11Z",
    "modifiedAt": "2026-10-14T09:41:27Z"
  }
}

Update a segment

PATCH/v1/segments/{segmentId}segments.update

Try it on developer.ken.so

Absent fields stay unchanged. JSON null clears description and abTestPercentage. Requires WriteAccess.

Parameters

Name
In
Type
Required
Description
segmentId
In: path
integer (int64)
required
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Request body

application/json, optional.

Field
Type
Required
Description
name
string
optional
description
string
optional
segmentationType
string
optional
abTestPercentage
integer (int32)
optional
sortOrder
integer (int32)
optional
filterCriteria
CampaignSegmentFilterCriteriaDTO
optional

Response 200

data is a SegmentModel.

Field
Type
Description
id
integer (int64)
campaignId
integer (int64)
name
string
description
string
isDefault
boolean
isActive
boolean
sortOrder
integer (int32)
segmentationType
string
abTestPercentage
integer (int32)
contactCount
integer (int32)
Omitted when the list was read with includeMetrics=false.
rawContactCount
integer (int32)
Omitted when the list was read with includeMetrics=false.
readyContactCount
integer (int32)
Omitted when the list was read with includeMetrics=false.
filterCriteria
CampaignSegmentFilterCriteriaDTO
createdAt
string (date-time)
modifiedAt
string (date-time)
Request
curl -X PATCH "https://api.ken.so/v1/segments/812" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "description": "string",
  "segmentationType": "string",
  "abTestPercentage": 1,
  "sortOrder": 1,
  "filterCriteria": {
    "fullName": {
      "contains": "string",
      "notContains": "string"
    },
    "titles": [
      "string"
    ],
    "excludeTitles": [
      "string"
    ],
    "lastJobTitle": {
      "contains": "string",
      "notContains": "string"
    },
    "headlines": [
      "string"
    ],
    "excludeHeadlines": [
      "string"
    ],
    "summaryContains": "string",
    "seniorityLevels": [
      "string"
    ],
    "excludeSeniorityLevels": [
      "string"
    ],
    "functions": [
      "string"
    ],
    "excludeFunctions": [
      "string"
    ],
    "employmentTypes": [
      "string"
    ],
    "isDecisionMaker": true,
    "changedJobRecently": true,
    "yearsOfExperience": {
      "min": 0.5,
      "max": 0.5
    },
    "yearsInCurrentRole": {
      "min": 0.5,
      "max": 0.5
    },
    "yearsInCurrentCompany": {
      "min": 0.5,
      "max": 0.5
    },
    "profileCountries": [
      "string"
    ],
    "excludeProfileCountries": [
      "string"
    ],
    "profileState": "string",
    "profileCity": "string",
    "skillsContains": "string",
    "certificationsContains": "string",
    "languages": [
      "string"
    ],
    "emailValidity": [
      "string"
    ],
    "emailProviders": [
      "string"
    ],
    "excludeEmailProviders": [
      "string"
    ],
    "isPersonalEmail": true,
    "hasLinkedInUrl": true,
    "hasPhone": true,
    "hasValidPhone": true,
    "companyNames": [
      "string"
    ],
    "excludeCompanyNames": [
      "string"
    ],
    "companyDomainContains": "string",
    "companyDescriptionContains": "string",
    "companySpecialitiesContains": "string",
    "industries": [
      "string"
    ],
    "excludeIndustries": [
      "string"
    ],
    "companyHeadcount": {
      "min": 1,
      "max": 1
    },
    "companyFollowers": {
      "min": 1,
      "max": 1
    },
    "companyFoundedYear": {
      "min": 1,
      "max": 1
    },
    "companyTypes": [
      "string"
    ],
    "lastFundingRounds": [
      "string"
    ],
    "totalFunding": {
      "min": 1,
      "max": 1
    },
    "technologies": [
      "string"
    ],
    "excludeTechnologies": [
      "string"
    ],
    "companyHqCountries": [
      "string"
    ],
    "excludeCompanyHqCountries": [
      "string"
    ],
    "companyHqState": "string",
    "companyHqCity": "string",
    "doNotContact": true,
    "createdAt": {
      "from": "2026-09-23T15:02:11Z",
      "to": "2026-09-23T15:02:11Z"
    },
    "totalClicks": {
      "min": 1,
      "max": 1
    },
    "leadQualityScore": {
      "min": 1,
      "max": 1
    },
    "aiVariableFilters": [
      {
        "promptId": 812,
        "operator": "Exists",
        "value": "string"
      }
    ],
    "customVariableFilters": [
      {
        "variableKey": "string",
        "operator": "Contains",
        "value": "string"
      }
    ]
  }
}'
Response 200
{
  "success": true,
  "data": {
    "id": 1207,
    "campaignId": 4821,
    "name": "Engineering leaders",
    "description": "VPs and heads of engineering at B2B SaaS companies with 50 to 500 employees.",
    "isDefault": false,
    "isActive": true,
    "sortOrder": 1,
    "segmentationType": "ai",
    "contactCount": 640,
    "rawContactCount": 712,
    "readyContactCount": 598,
    "createdAt": "2026-09-23T15:02:11Z",
    "modifiedAt": "2026-10-14T09:41:27Z"
  }
}

Soft-delete a segment

DELETE/v1/segments/{segmentId}segments.delete

Try it on developer.ken.so

Moves the segment's contacts to Default (or the remaining A/B buckets) and soft-deletes the segment's email sequence, LinkedIn steps and prompts with it. Returns 400 validation_failed when its contacts would move to Default and the segment has an email or LinkedIn sequence that neither Default nor the campaign root has. Requires Campaigns edit access (owners, admins and editors by default). Returns 204.

Parameters

Name
In
Type
Required
Description
segmentId
In: path
integer (int64)
required
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Response 204

Request
curl -X DELETE "https://api.ken.so/v1/segments/812" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"
Response 204
HTTP/1.1 204 No Content

Activate a segment

POST/v1/segments/{segmentId}/activatesegments.activate

Try it on developer.ken.so

Idempotent when the segment is already active. Requires WriteAccess.

Parameters

Name
In
Type
Required
Description
segmentId
In: path
integer (int64)
required
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Response 200

data is a SegmentModel.

Field
Type
Description
id
integer (int64)
campaignId
integer (int64)
name
string
description
string
isDefault
boolean
isActive
boolean
sortOrder
integer (int32)
segmentationType
string
abTestPercentage
integer (int32)
contactCount
integer (int32)
Omitted when the list was read with includeMetrics=false.
rawContactCount
integer (int32)
Omitted when the list was read with includeMetrics=false.
readyContactCount
integer (int32)
Omitted when the list was read with includeMetrics=false.
filterCriteria
CampaignSegmentFilterCriteriaDTO
createdAt
string (date-time)
modifiedAt
string (date-time)
Request
curl -X POST "https://api.ken.so/v1/segments/812/activate" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"
Response 200
{
  "success": true,
  "data": {
    "id": 1207,
    "campaignId": 4821,
    "name": "Engineering leaders",
    "description": "VPs and heads of engineering at B2B SaaS companies with 50 to 500 employees.",
    "isDefault": false,
    "isActive": true,
    "sortOrder": 1,
    "segmentationType": "ai",
    "contactCount": 640,
    "rawContactCount": 712,
    "readyContactCount": 598,
    "createdAt": "2026-09-23T15:02:11Z",
    "modifiedAt": "2026-10-14T09:41:27Z"
  }
}

Deactivate a segment

POST/v1/segments/{segmentId}/deactivatesegments.deactivate

Try it on developer.ken.so

Idempotent when the segment is already inactive. Requires WriteAccess.

Parameters

Name
In
Type
Required
Description
segmentId
In: path
integer (int64)
required
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Response 200

data is a SegmentModel.

Field
Type
Description
id
integer (int64)
campaignId
integer (int64)
name
string
description
string
isDefault
boolean
isActive
boolean
sortOrder
integer (int32)
segmentationType
string
abTestPercentage
integer (int32)
contactCount
integer (int32)
Omitted when the list was read with includeMetrics=false.
rawContactCount
integer (int32)
Omitted when the list was read with includeMetrics=false.
readyContactCount
integer (int32)
Omitted when the list was read with includeMetrics=false.
filterCriteria
CampaignSegmentFilterCriteriaDTO
createdAt
string (date-time)
modifiedAt
string (date-time)
Request
curl -X POST "https://api.ken.so/v1/segments/812/deactivate" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"
Response 200
{
  "success": true,
  "data": {
    "id": 1207,
    "campaignId": 4821,
    "name": "Engineering leaders",
    "description": "VPs and heads of engineering at B2B SaaS companies with 50 to 500 employees.",
    "isDefault": false,
    "isActive": true,
    "sortOrder": 1,
    "segmentationType": "ai",
    "contactCount": 640,
    "rawContactCount": 712,
    "readyContactCount": 598,
    "createdAt": "2026-09-23T15:02:11Z",
    "modifiedAt": "2026-10-14T09:41:27Z"
  }
}

List saved versions of a segment, newest first

GET/v1/segments/{segmentId}/versionssegments.list-versions

Try it on developer.ken.so

limit is 1 to 100 and defaults to 20. cursor is the opaque cursor from the previous page. Requires ReadAccess.

Parameters

Name
In
Type
Required
Description
segmentId
In: path
integer (int64)
required
limit
In: query
integer (int32)
optional
cursor
In: query
string
optional
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Response 200

data is a list of SegmentVersionModel. Each item has these fields. The response also carries pagination.

Field
Type
Description
id
integer (int64)
versionNumber
integer (int32)
createdAt
string (date-time)
createdByUserId
integer (int64)
createdByEmail
string
isRevert
boolean
revertedFromVersionId
integer (int64)
revertedFromVersionNumber
integer (int32)
revertedFromCreatedAt
string (date-time)
Request
curl -X GET "https://api.ken.so/v1/segments/812/versions?limit=1" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"
Response 200
{
  "success": true,
  "data": [
    {
      "id": 812,
      "versionNumber": 1,
      "createdAt": "2026-09-23T15:02:11Z",
      "createdByUserId": 812,
      "createdByEmail": "[email protected]",
      "isRevert": true,
      "revertedFromVersionId": 812,
      "revertedFromVersionNumber": 1,
      "revertedFromCreatedAt": "2026-09-23T15:02:11Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6ODE1fQ",
    "hasMore": true,
    "total": 1,
    "isTotalCapped": true
  }
}

Save a segment as a new version

POST/v1/segments/{segmentId}/versionssegments.save-version

Try it on developer.ken.so

Applies the body to the segment and writes one version row. The body takes the PATCH /v1/segments/{segmentId} fields plus sourceVersionId. Absent fields keep the live segment's value, or the sourceVersionId version's value when one is given, so a save with no body saves the current state. JSON null clears description and abTestPercentage. A sourceVersionId of another segment is not_found, and another save in progress for the segment is 409 conflict. When the save lands but version history is not captured, version is null and versionWarning says so. Requires WriteAccess.

Parameters

Name
In
Type
Required
Description
segmentId
In: path
integer (int64)
required
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Request body

application/json, optional.

Field
Type
Required
Description
sourceVersionId
integer (int64)
optional
The version to build on. Omit it to build on the live segment.
name
string
optional
description
string
optional
segmentationType
string
optional
manual, ai or ab_test.
abTestPercentage
integer (int32)
optional
0 to 100.
sortOrder
integer (int32)
optional
filterCriteria
CampaignSegmentFilterCriteriaDTO
optional

Response 200

data is a SegmentVersionSaveModel.

Field
Type
Description
segment
SegmentModel
version
SegmentVersionModel
versionWarning
string
Set when the save landed but version history was not captured.
Request
curl -X POST "https://api.ken.so/v1/segments/812/versions" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "sourceVersionId": 812,
  "name": "string",
  "description": "string",
  "segmentationType": "string",
  "abTestPercentage": 1,
  "sortOrder": 1,
  "filterCriteria": {
    "fullName": {
      "contains": "string",
      "notContains": "string"
    },
    "titles": [
      "string"
    ],
    "excludeTitles": [
      "string"
    ],
    "lastJobTitle": {
      "contains": "string",
      "notContains": "string"
    },
    "headlines": [
      "string"
    ],
    "excludeHeadlines": [
      "string"
    ],
    "summaryContains": "string",
    "seniorityLevels": [
      "string"
    ],
    "excludeSeniorityLevels": [
      "string"
    ],
    "functions": [
      "string"
    ],
    "excludeFunctions": [
      "string"
    ],
    "employmentTypes": [
      "string"
    ],
    "isDecisionMaker": true,
    "changedJobRecently": true,
    "yearsOfExperience": {
      "min": 0.5,
      "max": 0.5
    },
    "yearsInCurrentRole": {
      "min": 0.5,
      "max": 0.5
    },
    "yearsInCurrentCompany": {
      "min": 0.5,
      "max": 0.5
    },
    "profileCountries": [
      "string"
    ],
    "excludeProfileCountries": [
      "string"
    ],
    "profileState": "string",
    "profileCity": "string",
    "skillsContains": "string",
    "certificationsContains": "string",
    "languages": [
      "string"
    ],
    "emailValidity": [
      "string"
    ],
    "emailProviders": [
      "string"
    ],
    "excludeEmailProviders": [
      "string"
    ],
    "isPersonalEmail": true,
    "hasLinkedInUrl": true,
    "hasPhone": true,
    "hasValidPhone": true,
    "companyNames": [
      "string"
    ],
    "excludeCompanyNames": [
      "string"
    ],
    "companyDomainContains": "string",
    "companyDescriptionContains": "string",
    "companySpecialitiesContains": "string",
    "industries": [
      "string"
    ],
    "excludeIndustries": [
      "string"
    ],
    "companyHeadcount": {
      "min": 1,
      "max": 1
    },
    "companyFollowers": {
      "min": 1,
      "max": 1
    },
    "companyFoundedYear": {
      "min": 1,
      "max": 1
    },
    "companyTypes": [
      "string"
    ],
    "lastFundingRounds": [
      "string"
    ],
    "totalFunding": {
      "min": 1,
      "max": 1
    },
    "technologies": [
      "string"
    ],
    "excludeTechnologies": [
      "string"
    ],
    "companyHqCountries": [
      "string"
    ],
    "excludeCompanyHqCountries": [
      "string"
    ],
    "companyHqState": "string",
    "companyHqCity": "string",
    "doNotContact": true,
    "createdAt": {
      "from": "2026-09-23T15:02:11Z",
      "to": "2026-09-23T15:02:11Z"
    },
    "totalClicks": {
      "min": 1,
      "max": 1
    },
    "leadQualityScore": {
      "min": 1,
      "max": 1
    },
    "aiVariableFilters": [
      {
        "promptId": 812,
        "operator": "Exists",
        "value": "string"
      }
    ],
    "customVariableFilters": [
      {
        "variableKey": "string",
        "operator": "Contains",
        "value": "string"
      }
    ]
  }
}'
Response 200
{
  "success": true,
  "data": {
    "segment": {
      "id": 1207,
      "campaignId": 4821,
      "name": "Engineering leaders",
      "description": "VPs and heads of engineering at B2B SaaS companies with 50 to 500 employees.",
      "isDefault": false,
      "isActive": true,
      "sortOrder": 1,
      "segmentationType": "ai",
      "contactCount": 640,
      "rawContactCount": 712,
      "readyContactCount": 598,
      "createdAt": "2026-09-23T15:02:11Z",
      "modifiedAt": "2026-10-14T09:41:27Z"
    },
    "version": {
      "id": 812,
      "versionNumber": 1,
      "createdAt": "2026-09-23T15:02:11Z",
      "createdByUserId": 812,
      "createdByEmail": "[email protected]",
      "isRevert": true,
      "revertedFromVersionId": 812,
      "revertedFromVersionNumber": 1,
      "revertedFromCreatedAt": "2026-09-23T15:02:11Z"
    },
    "versionWarning": "string"
  }
}

Return one segment version and its snapshot

GET/v1/segments/{segmentId}/versions/{versionId}segments.get-version

Try it on developer.ken.so

segmentationType and status on the snapshot are lowercase snake_case. Requires ReadAccess.

Parameters

Name
In
Type
Required
Description
segmentId
In: path
integer (int64)
required
versionId
In: path
integer (int64)
required
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Response 200

data is a SegmentVersionDetailModel.

Field
Type
Description
id
integer (int64)
versionNumber
integer (int32)
createdAt
string (date-time)
createdByUserId
integer (int64)
createdByEmail
string
isRevert
boolean
revertedFromVersionId
integer (int64)
revertedFromVersionNumber
integer (int32)
revertedFromCreatedAt
string (date-time)
snapshot
SegmentSnapshotModel
Request
curl -X GET "https://api.ken.so/v1/segments/812/versions/812" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"
Response 200
{
  "success": true,
  "data": {
    "id": 812,
    "versionNumber": 1,
    "createdAt": "2026-09-23T15:02:11Z",
    "createdByUserId": 812,
    "createdByEmail": "[email protected]",
    "isRevert": true,
    "revertedFromVersionId": 812,
    "revertedFromVersionNumber": 1,
    "revertedFromCreatedAt": "2026-09-23T15:02:11Z",
    "snapshot": {
      "schemaVersion": 1,
      "segment": {
        "name": "string",
        "description": "string",
        "isActive": true,
        "sortOrder": 1,
        "segmentationType": "string",
        "abTestPercentage": 1,
        "status": "string"
      },
      "filterCriteria": {
        "fullNameContains": "string",
        "fullNameNotContains": "string",
        "lastJobTitleContains": "string",
        "lastJobTitleNotContains": "string",
        "summaryContains": "string",
        "profileStateContains": "string",
        "profileCityContains": "string",
        "skillsContains": "string",
        "certificationsContains": "string",
        "titles": "string",
        "excludeTitles": "string",
        "headlines": "string",
        "excludeHeadlines": "string",
        "seniorityLevels": "string",
        "excludeSeniorityLevels": "string",
        "functions": "string",
        "excludeFunctions": "string",
        "employmentTypes": "string",
        "profileCountries": "string",
        "excludeProfileCountries": "string",
        "languages": "string",
        "emailValidity": "string",
        "emailProviders": "string",
        "excludeEmailProviders": "string",
        "isDecisionMaker": true,
        "changedJobRecently": true,
        "isPersonalEmail": true,
        "hasLinkedInUrl": true,
        "hasPhone": true,
        "hasValidPhone": true,
        "yearsOfExperienceMin": 0.5,
        "yearsOfExperienceMax": 0.5,
        "yearsInCurrentRoleMin": 0.5,
        "yearsInCurrentRoleMax": 0.5,
        "yearsInCurrentCompanyMin": 0.5,
        "yearsInCurrentCompanyMax": 0.5,
        "companyDomainContains": "string",
        "companyDescriptionContains": "string",
        "companySpecialitiesContains": "string",
        "companyHqStateContains": "string",
        "companyHqCityContains": "string",
        "companyNames": "string",
        "excludeCompanyNames": "string",
        "industries": "string",
        "excludeIndustries": "string",
        "companyTypes": "string",
        "lastFundingRounds": "string",
        "technologies": "string",
        "excludeTechnologies": "string",
        "companyHqCountries": "string",
        "excludeCompanyHqCountries": "string",
        "companyHeadcountMin": 1,
        "companyHeadcountMax": 1,
        "companyFollowersMin": 1,
        "companyFollowersMax": 1,
        "companyFoundedYearMin": 1,
        "companyFoundedYearMax": 1,
        "totalFundingMin": 1,
        "totalFundingMax": 1,
        "doNotContact": true,
        "createdFrom": "2026-09-23T15:02:11Z",
        "createdTo": "2026-09-23T15:02:11Z",
        "totalClicksMin": 1,
        "totalClicksMax": 1,
        "leadQualityScoreMin": 1,
        "leadQualityScoreMax": 1,
        "aiVariableFiltersJson": "string",
        "customVariableFiltersJson": "string"
      }
    }
  }
}

Restore a segment to a saved version

POST/v1/segments/{segmentId}/versions/{versionId}/restoresegments.restore-version

Try it on developer.ken.so

dryRun returns the cascade preview and does not write. Each child includes the resolved snapshot the revert dialog renders. An applying restore that would clear campaign AI output returns 409 conflict with error.impact until confirm is true. Cascade kind and status are lowercase snake_case. Requires WriteAccess.

Parameters

Name
In
Type
Required
Description
segmentId
In: path
integer (int64)
required
versionId
In: path
integer (int64)
required
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Request body

application/json, optional.

Field
Type
Required
Description
confirm
boolean
optional
dryRun
boolean
optional

Response 200

data is a SegmentRestoreModel.

Field
Type
Description
dryRun
boolean
newVersionNumber
integer (int32)
versionWarning
string
version
SegmentVersionModel
snapshot
SegmentSnapshotModel
children
array of SegmentVersionChildModel
Request
curl -X POST "https://api.ken.so/v1/segments/812/versions/812/restore" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "confirm": true,
  "dryRun": true
}'
Response 200
{
  "success": true,
  "data": {
    "dryRun": true,
    "newVersionNumber": 1,
    "versionWarning": "string",
    "version": {
      "id": 812,
      "versionNumber": 1,
      "createdAt": "2026-09-23T15:02:11Z",
      "createdByUserId": 812,
      "createdByEmail": "[email protected]",
      "isRevert": true,
      "revertedFromVersionId": 812,
      "revertedFromVersionNumber": 1,
      "revertedFromCreatedAt": "2026-09-23T15:02:11Z"
    },
    "snapshot": {
      "schemaVersion": 1,
      "segment": {
        "name": "string",
        "description": "string",
        "isActive": true,
        "sortOrder": 1,
        "segmentationType": "string",
        "abTestPercentage": 1,
        "status": "string"
      },
      "filterCriteria": {
        "fullNameContains": "string",
        "fullNameNotContains": "string",
        "lastJobTitleContains": "string",
        "lastJobTitleNotContains": "string",
        "summaryContains": "string",
        "profileStateContains": "string",
        "profileCityContains": "string",
        "skillsContains": "string",
        "certificationsContains": "string",
        "titles": "string",
        "excludeTitles": "string",
        "headlines": "string",
        "excludeHeadlines": "string",
        "seniorityLevels": "string",
        "excludeSeniorityLevels": "string",
        "functions": "string",
        "excludeFunctions": "string",
        "employmentTypes": "string",
        "profileCountries": "string",
        "excludeProfileCountries": "string",
        "languages": "string",
        "emailValidity": "string",
        "emailProviders": "string",
        "excludeEmailProviders": "string",
        "isDecisionMaker": true,
        "changedJobRecently": true,
        "isPersonalEmail": true,
        "hasLinkedInUrl": true,
        "hasPhone": true,
        "hasValidPhone": true,
        "yearsOfExperienceMin": 0.5,
        "yearsOfExperienceMax": 0.5,
        "yearsInCurrentRoleMin": 0.5,
        "yearsInCurrentRoleMax": 0.5,
        "yearsInCurrentCompanyMin": 0.5,
        "yearsInCurrentCompanyMax": 0.5,
        "companyDomainContains": "string",
        "companyDescriptionContains": "string",
        "companySpecialitiesContains": "string",
        "companyHqStateContains": "string",
        "companyHqCityContains": "string",
        "companyNames": "string",
        "excludeCompanyNames": "string",
        "industries": "string",
        "excludeIndustries": "string",
        "companyTypes": "string",
        "lastFundingRounds": "string",
        "technologies": "string",
        "excludeTechnologies": "string",
        "companyHqCountries": "string",
        "excludeCompanyHqCountries": "string",
        "companyHeadcountMin": 1,
        "companyHeadcountMax": 1,
        "companyFollowersMin": 1,
        "companyFollowersMax": 1,
        "companyFoundedYearMin": 1,
        "companyFoundedYearMax": 1,
        "totalFundingMin": 1,
        "totalFundingMax": 1,
        "doNotContact": true,
        "createdFrom": "2026-09-23T15:02:11Z",
        "createdTo": "2026-09-23T15:02:11Z",
        "totalClicksMin": 1,
        "totalClicksMax": 1,
        "leadQualityScoreMin": 1,
        "leadQualityScoreMax": 1,
        "aiVariableFiltersJson": "string",
        "customVariableFiltersJson": "string"
      }
    },
    "children": [
      {
        "kind": "string",
        "parentId": 812,
        "status": "string",
        "versionId": 812,
        "versionNumber": 1,
        "createdAt": "2026-09-23T15:02:11Z",
        "newVersionNumber": 1,
        "versionWarning": "string",
        "snapshot": null
      }
    ]
  }
}

Return the segment filter catalog

GET/v1/segments/filter-optionssegments.get-filter-options

Try it on developer.ken.so

The values a segment filter accepts: seniority levels, functions, industries, company types, employment types, funding rounds, technologies, email validity, email providers and languages, each as value, label and an optional category. The catalog is the same for every workspace and is the filterOptions object POST /v1/campaigns/{campaignId}/segments/preview returns; this read needs no campaign. It replaces GET /v1/campaigns/segments/filter-metadata. Read-only. Requires ReadAccess.

Parameters

Name
In
Type
Required
Description
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Response 200

data is a SegmentFilterMetadataDTO.

Field
Type
Description
seniorityLevels
array of FilterOptionItem
functions
array of FilterOptionItem
industries
array of FilterOptionItem
companyTypes
array of FilterOptionItem
employmentTypes
array of FilterOptionItem
lastFundingRounds
array of FilterOptionItem
technologies
array of FilterOptionItem
emailValidity
array of FilterOptionItem
emailProviders
array of FilterOptionItem
languages
array of FilterOptionItem
Request
curl -X GET "https://api.ken.so/v1/segments/filter-options" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"
Response 200
{
  "success": true,
  "data": {
    "seniorityLevels": [
      {
        "value": "string",
        "label": "string",
        "category": "string"
      }
    ],
    "functions": [
      {
        "value": "string",
        "label": "string",
        "category": "string"
      }
    ],
    "industries": [
      {
        "value": "string",
        "label": "string",
        "category": "string"
      }
    ],
    "companyTypes": [
      {
        "value": "string",
        "label": "string",
        "category": "string"
      }
    ],
    "employmentTypes": [
      {
        "value": "string",
        "label": "string",
        "category": "string"
      }
    ],
    "lastFundingRounds": [
      {
        "value": "string",
        "label": "string",
        "category": "string"
      }
    ],
    "technologies": [
      {
        "value": "string",
        "label": "string",
        "category": "string"
      }
    ],
    "emailValidity": [
      {
        "value": "string",
        "label": "string",
        "category": "string"
      }
    ],
    "emailProviders": [
      {
        "value": "string",
        "label": "string",
        "category": "string"
      }
    ],
    "languages": [
      {
        "value": "string",
        "label": "string",
        "category": "string"
      }
    ]
  }
}
More in Campaigns and sequences:CampaignsEmail sequencesSegment email sequencesLinkedIn sequencesSegment LinkedIn sequencesSequence variablesCustom variablesImage variablesCampaign imagesListsTracking linksAuto pausesCampaign complianceCampaign languagesCampaign localizationsMarketsAnalyticsAll resources