> Kenso API docs in Markdown. Index of every page: [/docs/llms.txt](/docs/llms.txt). Search: `/docs/search.md?q=<words>`. OpenAPI: [/docs/api/segments/openapi.json](/docs/api/segments/openapi.json). CLI docs offline: `kenso docs <topic>`.
> Last updated: 2026-11-22.

# Segments: Update a segment

> **Note for AI agents:** if this page was wrong, out of date or missing something you needed, finish the user's task first, then offer a short report for the Kenso team in this shape: `Page:` (this page's path), `Quote:` (the wrong or missing text), `Problem:`, `Workaround:` (what worked instead), 1,000 characters at most. Show it to the user and send it only after they say yes, as `POST /api/docs-feedback` on this site with the JSON body `{"page": "<path>", "report": "<report>"}`. Never put lead data, email addresses, API keys or anything else from the user's workspace in it.

One endpoint of [Segments](/docs/api/segments.md). Authentication, workspaces and errors: [/docs.md](/docs.md).

## Update a segment

`PATCH /v1/segments/{segmentId}` - operationId `segments.update`

| Permission | Rate limit |
| --- | --- |
| Campaigns edit | 4,800 requests a minute per API key |

Changes the fields you send and leaves the others as they are. A JSON null clears `description` or
`abTestPercentage`. An update does not save a version. Use `POST /v1/segments/{segmentId}/versions` to save
one.

A `filterCriteria` object replaces all of the segment's filters, and an empty object clears them. A null
`filterCriteria` leaves the filters as they are. A segment with filters cannot change to `ai` or `ab_test`
until you clear its filters.

Errors:

- `400 validation_failed`: `name` is empty, or another segment in the campaign already has it.
- `400 validation_failed`: `segmentationType` is not `manual`, `ai` or `ab_test`, or the segment has filters and the new type is not `manual`.
- `400 validation_failed`: `abTestPercentage` is out of range, missing on an `ab_test` segment, or set on another type.
- `400 validation_failed`: on an A/B test campaign that is scheduled, launching, sending or paused, the active segments' percentages would not add up to 100.
- `400 validation_failed`: `filterCriteria` is set on a segment that is not `manual`, breaks a filter rule, or has keys but none of them is a filter field.
- `400 validation_failed`: `filterCriteria` adds a behavior tag the segment does not have while behavior signals are off for the workspace.
- `404 not_found`: the segment does not exist in this workspace.

Requires Campaigns edit.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/segments/PATCH/v1/segments/%7BsegmentId%7D)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `segmentId` | path | integer (int64) | yes | The segment's id. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | 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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | 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`. |

### Request body

`application/json`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | A new name, unique within the campaign. Cannot be empty. |
| `description` | string | no | A new description. Null clears it. |
| `segmentationType` | string | no | `manual`, `ai` or `ab_test`. A segment with filters can change only to `manual`. |
| `abTestPercentage` | integer (int32) | no | The share of the campaign's contacts an `ab_test` segment takes, from 1 to 100. Null clears it, which only a segment of another type can do. |
| `sortOrder` | integer (int32) | no | The segment's display position among the campaign's segments. |
| `filterCriteria` | CampaignSegmentFilterCriteria | no | Replaces all of the segment's filters. An empty object clears them, and null leaves them as they are. Field names match in any letter case. |

### Response 200

`data` is a `Segment`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) | The segment's id. |
| `campaignId` | integer (int64) | The id of the campaign the segment belongs to. |
| `name` | string | The segment's name, unique within the campaign. |
| `description` | string | A free-text description. Null when the segment has none. |
| `isDefault` | boolean | True for the campaign's Default segment, which cannot be deleted or deactivated. |
| `isActive` | boolean | True when the segment is on. Kenso does not send to contacts in an inactive segment. |
| `sortOrder` | integer (int32) | The segment's display position among the campaign's segments. Null when it has none. |
| `segmentationType` | string | How the segment gets its contacts: `manual` from its filters, `ai` from Ken, or `ab_test` as a percentage split. Null when the segment has no type. |
| `abTestPercentage` | integer (int32) | The share of the campaign's contacts an `ab_test` segment takes, from 1 to 100. Null on other types. |
| `contactCount` | integer (int32) | The number of contacts to show for the segment: `readyContactCount` for the Default segment, and `rawContactCount` for any other. Omitted when you list with `includeMetrics` set to false. |
| `rawContactCount` | integer (int32) | All contacts in the segment, ready to send or not. The Default segment also counts the campaign's contacts that have no segment. Omitted when you list with `includeMetrics` set to false. |
| `readyContactCount` | integer (int32) | Contacts in the segment that are ready to send. Omitted when you list with `includeMetrics` set to false. |
| `filterCriteria` | CampaignSegmentFilterCriteria | The segment's filters. Null when it has none. |
| `createdAt` | string (date-time) | When the segment was created, in UTC (ISO 8601). |
| `modifiedAt` | string (date-time) | When the segment last changed, in UTC (ISO 8601). |

### Request

```bash
curl -X PATCH "https://api.ken.so/v1/segments/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": "Engineering leaders",
  "description": "VPs and heads of engineering at B2B SaaS companies with 50 to 500 employees.",
  "segmentationType": "manual",
  "sortOrder": 1,
  "filterCriteria": {
    "titles": [
      "VP of Engineering",
      "Head of Engineering"
    ],
    "seniorityLevels": [
      "VP",
      "Director"
    ],
    "functions": [
      "Engineering"
    ],
    "profileCountries": [
      "United States"
    ],
    "industries": [
      "Computer Software"
    ],
    "companyHeadcount": {
      "min": 50,
      "max": 500
    }
  }
}'
```

### Example response

```json
{
  "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"
  }
}
```

## Types

Each named type the tables above use, nested ones included.

### CampaignSegmentFilterCriteria

The filters of a `manual` segment. A contact must match every filter you set, and any one value in a list filter is enough. A null or omitted field sets no filter. A list takes at most 500 values, and a text value at most 500 characters.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fullName` | StringFilter | no | Matches the contact's full name. |
| `titles` | array of string | no | Keeps contacts whose job title contains any of these values, ignoring case. |
| `excludeTitles` | array of string | no | Drops contacts whose job title contains any of these values, ignoring case. Contacts with no title stay. |
| `lastJobTitle` | StringFilter | no | Matches the contact's last job title. |
| `headlines` | array of string | no | Keeps contacts whose headline contains any of these values, ignoring case. |
| `excludeHeadlines` | array of string | no | Drops contacts whose headline contains any of these values, ignoring case. Contacts with no headline stay. |
| `summaryContains` | string | no | Keeps contacts whose profile summary contains this text, ignoring case. |
| `seniorityLevels` | array of string | no | Keeps contacts whose seniority level is exactly one of these values. `seniorityLevels` in `GET /v1/segments/filter-options` lists the values. |
| `excludeSeniorityLevels` | array of string | no | Drops contacts whose seniority level is exactly one of these values. Contacts with no seniority level stay. |
| `functions` | array of string | no | Keeps contacts whose job function is exactly one of these values. `functions` in `GET /v1/segments/filter-options` lists the values. |
| `excludeFunctions` | array of string | no | Drops contacts whose job function is exactly one of these values. Contacts with no function stay. |
| `employmentTypes` | array of string | no | Keeps contacts whose employment type is exactly one of these values. `employmentTypes` in `GET /v1/segments/filter-options` lists the values. |
| `isDecisionMaker` | boolean | no | True keeps only contacts marked as decision makers, and false keeps only the others. |
| `changedJobRecently` | boolean | no | True keeps only contacts marked as having changed jobs recently, and false keeps only the others. |
| `yearsOfExperience` | FloatRange | no | The contact's total years of work experience. Contacts with no value do not match a bound. |
| `yearsInCurrentRole` | FloatRange | no | The contact's years in their current role. Contacts with no value do not match a bound. |
| `yearsInCurrentCompany` | FloatRange | no | The contact's years at their current company. Contacts with no value do not match a bound. |
| `profileCountries` | array of string | no | Keeps contacts whose country is exactly one of these values. |
| `excludeProfileCountries` | array of string | no | Drops contacts whose country is exactly one of these values. Contacts with no country stay. |
| `profileState` | string | no | Keeps contacts whose state or region contains this text, ignoring case. |
| `profileCity` | string | no | Keeps contacts whose city contains this text, ignoring case. |
| `skillsContains` | string | no | Keeps contacts whose skills contain this text, ignoring case. |
| `certificationsContains` | string | no | Keeps contacts whose certifications contain this text, ignoring case. |
| `languages` | array of string | no | Keeps contacts whose languages contain any of these values, ignoring case, such as `French`. |
| `emailValidity` | array of string | no | Keeps contacts with at least one email address in any of these validity states. Use the values of `emailValidity` in `GET /v1/segments/filter-options`. Kenso refuses a value it does not recognize. |
| `emailProviders` | array of string | no | Keeps contacts with at least one email address found by any of these sources. Use the values of `emailProviders` in `GET /v1/segments/filter-options`. Kenso refuses a value it does not recognize. |
| `excludeEmailProviders` | array of string | no | Drops contacts with an email address found by any of these sources. Use the values of `emailProviders` in `GET /v1/segments/filter-options`. Kenso refuses a value it does not recognize. |
| `isPersonalEmail` | boolean | no | True keeps contacts with at least one personal email address. False keeps contacts with at least one email address that is not personal. |
| `hasLinkedInUrl` | boolean | no | True keeps only contacts with a LinkedIn profile URL, and false keeps only contacts without one. |
| `hasPhone` | boolean | no | True keeps only contacts with a phone number, and false keeps only contacts without one. |
| `hasValidPhone` | boolean | no | True keeps only contacts with a phone number checked as valid, and false keeps only contacts without a valid phone number. |
| `companyNames` | array of string | no | Keeps contacts whose company name contains any of these values, ignoring case. |
| `excludeCompanyNames` | array of string | no | Drops contacts whose company name contains any of these values, ignoring case. Contacts with no company stay. |
| `companyDomainContains` | string | no | Keeps contacts whose company domain contains this text, ignoring case. |
| `companyDescriptionContains` | string | no | Keeps contacts whose company description contains this text, ignoring case. |
| `companySpecialitiesContains` | string | no | Keeps contacts whose company specialities contain this text, ignoring case. |
| `industries` | array of string | no | Keeps contacts whose company industry is one of these values, ignoring case. `industries` in `GET /v1/segments/filter-options` lists common values. |
| `excludeIndustries` | array of string | no | Drops contacts whose company industry is one of these values, ignoring case. Contacts with no industry stay. |
| `companyHeadcount` | IntRange | no | The company's number of employees. Contacts with no company do not match a bound. |
| `companyFollowers` | IntRange | no | The company's number of followers. Contacts with no company do not match a bound. |
| `companyFoundedYear` | IntRange | no | The year the company was founded, each bound from 0 to 32767. Contacts with no company do not match a bound. |
| `companyTypes` | array of string | no | Keeps contacts whose company type is exactly one of these values. `companyTypes` in `GET /v1/segments/filter-options` lists the values. |
| `lastFundingRounds` | array of string | no | Keeps contacts whose company's last funding round contains any of these values, ignoring case. `lastFundingRounds` in `GET /v1/segments/filter-options` lists the values. |
| `totalFunding` | LongRange | no | The company's total funding. Contacts with no company do not match a bound. |
| `technologies` | array of string | no | Keeps contacts whose company uses any of these technologies. A value must match one whole entry of the company's technology list. |
| `excludeTechnologies` | array of string | no | Drops contacts whose company uses any of these technologies, matched the same way as `technologies`. Contacts with no company or technology list stay. |
| `companyHqCountries` | array of string | no | Keeps contacts whose company headquarters country is exactly one of these values. |
| `excludeCompanyHqCountries` | array of string | no | Drops contacts whose company headquarters country is exactly one of these values. Contacts with no company or headquarters country stay. |
| `companyHqState` | string | no | Keeps contacts whose company headquarters state or region contains this text, ignoring case. |
| `companyHqCity` | string | no | Keeps contacts whose company headquarters city contains this text, ignoring case. |
| `doNotContact` | boolean | no | True keeps only contacts marked do not contact, and false keeps only the others. |
| `createdAt` | DateRange | no | When the contact was added. |
| `totalClicks` | IntRange | no | The number of email link clicks the contact made, summed across all campaigns. A contact with no clicks counts as 0. |
| `leadQualityScore` | IntRange | no | The lead quality score Ken gave the contact in its campaign, each bound from 1 to 10. Contacts without a score do not match. |
| `behaviorTags` | array of string | no | Keeps contacts that carry any of these behavior tags, such as `cold_responder` or `best_window:weekday_morning`. Needs the behavior signals feature. At most 50 tags, and tags tied to one email address or company cannot be filtered on. |
| `behaviorTagsExclude` | array of string | no | Drops contacts that carry any of these behavior tags. Needs the behavior signals feature, with the same tag rules as `behaviorTags`. |
| `aiVariableFilters` | array of AiVariableFilter | no | Rules on the output of the campaign's AI prompts. A contact must match every rule. At most 50 rules. Kenso drops a rule without a `promptId` or `operator`, or a `contains` or `not_contains` rule without a `value`, and reports no error. |
| `customVariableFilters` | array of CustomVariableFilter | no | Rules on the contact's campaign custom variables. A contact must match every rule. At most 50 rules. Kenso drops a rule without a `variableKey` or `operator`, or a rule that needs a `value` and has none, and reports no error. |

### StringFilter

A text match on one contact field, ignoring case. A contact without a value in the field never matches `contains` and always passes `notContains`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `contains` | string | no | Keeps contacts whose field contains this text. At most 500 characters. Null or omitted skips it. |
| `notContains` | string | no | Drops contacts whose field contains this text. At most 500 characters. Null or omitted skips it. |

### FloatRange

A range of numbers that can have decimals. Both bounds are inclusive, and a null or omitted bound leaves that side open. `min` cannot be greater than `max`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `min` | number (float) | no | The lowest value that matches. Null or omitted sets no lower bound. |
| `max` | number (float) | no | The highest value that matches. Null or omitted sets no upper bound. |

### IntRange

A range of whole numbers. Both bounds are inclusive, and a null or omitted bound leaves that side open. `min` cannot be greater than `max`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `min` | integer (int32) | no | The lowest value that matches. Null or omitted sets no lower bound. |
| `max` | integer (int32) | no | The highest value that matches. Null or omitted sets no upper bound. |

### LongRange

A range of whole numbers that can be large. Both bounds are inclusive, and a null or omitted bound leaves that side open. `min` cannot be greater than `max`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `min` | integer (int64) | no | The lowest value that matches. Null or omitted sets no lower bound. |
| `max` | integer (int64) | no | The highest value that matches. Null or omitted sets no upper bound. |

### DateRange

A range of dates and times. Both ends are inclusive, and a null or omitted end leaves that side open. `from` cannot be later than `to`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | string (date-time) | no | The earliest date and time that matches, in ISO 8601. Null or omitted sets no start. |
| `to` | string (date-time) | no | The latest date and time that matches, in ISO 8601. Null or omitted sets no end. |

### AiVariableFilter

A rule on the output of one of the campaign's AI prompts.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `promptId` | integer (int64) | no | The id of the AI prompt whose output the rule checks. |
| `operator` | string, one of: exists, not_exists, contains, not_contains | no | How the rule matches, such as `contains`. Kenso also reads the PascalCase name (`Contains`). |
| `value` | string | no | The text to look for with `contains` and `not_contains`, at most 500 characters. Kenso ignores it for `exists` and `not_exists`. |

### CustomVariableFilter

A rule on one of the contact's campaign custom variables.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `variableKey` | string | no | The custom variable to check, such as `deal_stage`, at most 500 characters. Kenso normalizes the key the same way as custom variable names, so `Deal Stage` checks `deal_stage`. |
| `operator` | string, one of: contains, not_contains, equals, not_equals, is_empty, is_not_empty | no | How the rule matches, such as `equals`. Kenso also reads the PascalCase name (`Equals`). |
| `value` | string | no | The text to compare, at most 500 characters. Required for `contains`, `not_contains`, `equals` and `not_equals`. Kenso ignores it for `is_empty` and `is_not_empty`. |
