Custom variables

A campaign's custom contact fields and whether AI may read them.

Campaigns and sequences4 endpointsKen-Version: 2026-11-02Authentication Workspaces Errors

List a campaign's custom variables

GET/v1/campaigns/{campaignId}/custom-variablescustom-variables.list

Try it on developer.ken.so

Ordered by key. q matches the key or the name. Requires ReadAccess.

Parameters

Name

Type

Required

Description

campaignId

In: path

integer (int64)

required

In: query

string

optional

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 CustomVariableModel. Each item has these fields. The response also carries pagination.

Field

Type

Description

variableKey

string

name

string

useAsAiContext

boolean

isRequiredForSending

boolean

Request

curl -X GET "https://api.ken.so/v1/campaigns/812/custom-variables" \
  -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": [
    {
      "variableKey": "string",
      "name": "string",
      "useAsAiContext": true,
      "isRequiredForSending": true
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6ODE1fQ",
    "hasMore": true,
    "total": 1,
    "isTotalCapped": true
  }
}

Declare one custom variable

POST/v1/campaigns/{campaignId}/custom-variablescustom-variables.create

Try it on developer.ken.so

Returns 201 and Location. An existing key is updated. Requires WriteAccess.

Parameters

Name

Type

Required

Description

campaignId

In: path

integer (int64)

required

Ken-Version

In: header

string, one of: 2026-11-02, 1.1

required

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

variableKey

string

optional

name

string

optional

useAsAiContext

boolean

optional

isRequiredForSending

boolean

optional

Response 201

data is a CustomVariableModel.

Field

Type

Description

variableKey

string

name

string

useAsAiContext

boolean

isRequiredForSending

boolean

Request

curl -X POST "https://api.ken.so/v1/campaigns/812/custom-variables" \
  -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 '{
  "variableKey": "string",
  "name": "string",
  "useAsAiContext": true,
  "isRequiredForSending": true
}'

Response 201

{
  "success": true,
  "data": {
    "variableKey": "string",
    "name": "string",
    "useAsAiContext": true,
    "isRequiredForSending": true
  }
}

Update one custom variable

PATCH/v1/campaigns/{campaignId}/custom-variables/{variableKey}custom-variables.update

Try it on developer.ken.so

Absent fields stay unchanged. Requires WriteAccess.

Parameters

Name

Type

Required

Description

campaignId

In: path

integer (int64)

required

variableKey

In: path

string

required

Ken-Version

In: header

string, one of: 2026-11-02, 1.1

required

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

useAsAiContext

boolean

optional

isRequiredForSending

boolean

optional

Response 200

data is a CustomVariableModel.

Field

Type

Description

variableKey

string

name

string

useAsAiContext

boolean

isRequiredForSending

boolean

Request

curl -X PATCH "https://api.ken.so/v1/campaigns/812/custom-variables/string" \
  -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",
  "useAsAiContext": true,
  "isRequiredForSending": true
}'

Response 200

{
  "success": true,
  "data": {
    "variableKey": "string",
    "name": "string",
    "useAsAiContext": true,
    "isRequiredForSending": true
  }
}

Remove one custom variable

DELETE/v1/campaigns/{campaignId}/custom-variables/{variableKey}custom-variables.delete

Try it on developer.ken.so

Requires WriteAccess. Returns 204.

Parameters

Name

Type

Required

Description

campaignId

In: path

integer (int64)

required

variableKey

In: path

string

required

Ken-Version

In: header

string, one of: 2026-11-02, 1.1

required

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/campaigns/812/custom-variables/string" \
  -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

More in Campaigns and sequences:Campaigns Segments Email sequences Segment email sequences LinkedIn sequences Segment LinkedIn sequences Sequence variables Image variables Campaign images Lists Tracking links Auto pauses Campaign compliance Campaign languages Campaign localizations Markets Analytics All resources