Skip to Content
Campaigns

Localized steps

A localization is one email or LinkedIn step of a campaign, written in one of the languages the campaign turns on. Kenso writes localizations in the background and checks each one. When the campaign's languageMode is auto, Kenso sends each contact the approved localization of their language. Ask Kenso to write the localizations, poll the list until they are written, then approve, regenerate or edit each one.

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

Path parameters

The endpoints whose path names one of these take it as described here. An endpoint's own table lists a path parameter only when it describes it differently.

NameInTypeRequiredDescription
campaignIdpathinteger (int64)requiredId of the campaign.
localizationIdpathinteger (int64)requiredId of the localization.

Headers

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

NameInTypeRequiredDescription
Ken-Versionheaderstring, one of: 2026-11-02, 1.1optionalThe API version, a date in YYYY-MM-DD form. 1.1 is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and 404 where the path exists only in this version. A date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy.
X-Ken-Workspace-Idheaderinteger (int64)optionalThe id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers 400 workspace_required. A workspace you are not a member of answers 404 not_found.

List a campaign's localizations

GET/v1/campaigns/{campaignId}/localizationscampaign-localizations.list
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key
Needs the multilingual_outreach feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Returns the localizations of the campaign's current email and LinkedIn steps. Use it to review the localized text, and to poll while Kenso writes it.

Items come email first, then by step order, variant and language. Filter with language, stepId and channel. An email and a LinkedIn step can share an id, so add channel when you filter by stepId. generating is true while Kenso has the localization queued: read the list again until it is false. stale is true when the step text or the market pack changed after Kenso wrote the localization: generate it again. The whole result comes in one page, so hasMore is always false.

Errors:

  • 400 validation_failed: channel is not email or linkedin.
  • 404 not_found: the campaign does not exist in this workspace.

Requires Campaigns view.

Parameters

NameInTypeRequiredDescription
languagequerystringoptionalOnly the localizations in this language, as a locale such as fr-FR, in any casing. Omit it for every language.
stepIdqueryinteger (int64)optionalOnly the localizations of the email or LinkedIn step with this id. An email step and a LinkedIn step can share an id: add channel to pick one.
channelquerystringoptionalOnly the localizations of one channel: email or linkedin. Omit it for both.
limitqueryinteger (int32)optionalItems per page, from 1 to 200. Omit limit and cursor to get every item in one response, as before; with only cursor, 50 per page.
cursorquerystringoptionalThe nextCursor of the previous page. Omit it for the first page.
Request
curl -X GET "https://api.ken.so/v1/campaigns/812/localizations?limit=1" \
  -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 CampaignLocalization. Each item has these fields. The response also carries pagination.

Show the 23 response fields and an example

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

Edit a localization's text

PATCH/v1/campaigns/{campaignId}/localizations/{localizationId}campaign-localizations.update
Permission
Campaigns edit
Rate limit
4,800 requests a minute per API key
Needs the multilingual_outreach feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Replaces the text of one localization with your own. Use it to fix wording by hand.

Send subjectLine, bodyContent or both. A field you leave out keeps its stored text. A LinkedIn localization has no subject. Kenso sets the unsubscribe link text to the market pack's wording, runs the rule checks on the new text without a model call, and stores their result in qaReport. Kenso also stores text that breaks a rule, so you can keep working on it, but approval waits until the rules pass. Send channel only when an email and a LinkedIn localization of the campaign share the id.

editedByHuman becomes true and the localization becomes a draft. It loses any approval, so a live campaign stops sending it until it is approved again. The English mirror and qaScore keep their values, which describe the text before the edit.

When campaign images or videos are on for the workspace, Kenso checks image and video tokens in an email text as a sequence save does, and stores nothing when the check fails. A save refuses, for example, more than two images, an image in the subject or in a handwritten letter, and an image that is not on its own line or in its own paragraph.

Errors:

  • 400 validation_failed with detail code required: neither field was sent, the body is blank, or the subject is blank for a step that has one.
  • 400 validation_failed with detail code not_supported: subjectLine was sent for a LinkedIn localization.
  • 400 validation_failed with detail code invalid: the text has image or video tokens a sequence save would refuse. The message says why.
  • 400 validation_failed with detail code unsupported_language: Kenso has no market pack to check this language with.
  • 400 validation_failed with detail code channel_required: an email and a LinkedIn localization share this id. Add channel.
  • 400 validation_failed with detail code invalid_value: channel is not email or linkedin.
  • 404 not_found: the campaign or the localization does not exist in this workspace, or the localization's step was removed.
  • 409 localization_generating: Kenso is writing this localization and would overwrite the edit. Read it again once generating is false.
  • 409 conflict: the localization changed while Kenso saved the edit. Read it again and retry.

Requires Campaigns edit.

Parameters

NameInTypeRequiredDescription
channelquerystringoptionalemail or linkedin. Needed only when an email and a LinkedIn localization of the campaign share the id.

Request body

application/json, optional.

The new subject, body or both.

FieldTypeRequiredDescription
subjectLinestringoptionalThe localized subject. Only for an email localization. It cannot be blank when the step has a subject.
bodyContentstringoptionalThe localized body. It cannot be blank.
Request
curl -X PATCH "https://api.ken.so/v1/campaigns/812/localizations/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 '{
  "subjectLine": "string",
  "bodyContent": "string"
}'

Response 200

data is a CampaignLocalization.

Show the 23 response fields and an example

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

Generate a campaign's localizations

POST/v1/campaigns/{campaignId}/localizationscampaign-localizations.generate
Permission
Campaigns edit
Credits
Varies with the request (translation)
Rate limit
4,800 requests a minute per API key
Needs the multilingual_outreach feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Queues Kenso to write the campaign's steps in the languages it turns on. Call it after you turn on a language or change step text. Kenso writes the queued localizations in the background.

The body is optional, for example { "languages": ["fr-FR"], "stepIds": [11], "channel": "email" }. An absent or empty field means every enabled language, every step and both channels. Kenso writes only active steps with text. It skips steps built in Studio and LinkedIn connection requests with an AI-written note. For each step and language:

  • With no localization yet, Kenso creates one as a queued draft.
  • Kenso queues again a localization that is stale, failed or needs_review, or that it wrote from older step text or an older market pack.
  • A current draft or approved localization, and one already queued, stay as they are.
  • Kenso queues again a localization a member edited only when stepIds names its step, so a new market pack never replaces a member's text unasked.

The response is 202 with every localization of the campaign, the same list as GET /v1/campaigns/{campaignId}/localizations. A queued localization has generating true until Kenso has written it, so poll the list to follow progress. Each localization Kenso writes costs credits. With no credits left, the localization ends failed with lastError set to insufficient_credits.

Errors:

  • 400 validation_failed with detail code no_enabled_languages: the campaign turns on no language. Set enabledLanguages on the campaign first.
  • 400 validation_failed with detail code language_not_enabled: a locale in languages is not in the campaign's enabledLanguages.
  • 400 validation_failed with detail code unsupported_language: Kenso has no market pack to write an enabled language with.
  • 400 validation_failed with detail code step_not_localizable: a step in stepIds is not an active step of the campaign with text to localize.
  • 400 validation_failed with detail code invalid_value: channel is not email or linkedin.
  • 404 not_found: the campaign does not exist in this workspace.
  • 409 invalid_state with detail code localization_disabled: localization is not turned on for this workspace yet, so Kenso queued nothing.

Requires Campaigns edit.

Request body

application/json, optional.

Optional. Which languages, steps and channel to write.

FieldTypeRequiredDescription
languagesarray of stringoptionalLocales to write, such as fr-FR. Each must be in the campaign's enabledLanguages.
stepIdsarray of integer (int64)optionalIds of the campaign's email or LinkedIn steps to write. An email and a LinkedIn step can share an id: add channel to pick one. Naming a step also queues its localizations that a member edited.
channelstringoptionalWrite only one channel's steps: email or linkedin. Absent means both.
Request
curl -X POST "https://api.ken.so/v1/campaigns/812/localizations" \
  -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 '{
  "languages": [
    "fr-FR"
  ],
  "stepIds": [
    812
  ],
  "channel": "email"
}'

Response 202

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

Show the 23 response fields and an example

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

Approve a localization

POST/v1/campaigns/{campaignId}/localizations/{localizationId}/approvecampaign-localizations.approve
Permission
Campaigns edit
Rate limit
4,800 requests a minute per API key
Needs the multilingual_outreach feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Approves one localization for sending, so an auto campaign sends it to the contacts of that language. Kenso records the caller and the time.

Kenso approves only a current draft that passed its checks: the rule checks passed, and qaScore reached the market pack's threshold. A localization a member edited needs only the rule checks. Read qaReport to see what failed. Send channel only when an email and a LinkedIn localization of the campaign share the id.

Errors:

  • 400 validation_failed with detail code channel_required: an email and a LinkedIn localization share this id. Add channel.
  • 400 validation_failed with detail code invalid_value: channel is not email or linkedin.
  • 404 not_found: the campaign or the localization does not exist in this workspace, or the localization's step was removed.
  • 409 localization_generating: Kenso is writing this localization. Read it again once generating is false.
  • 409 localization_not_approvable with detail code not_draft, stale, qa_failed or score_below_threshold: the localization is not a current draft that passed its checks. Generate a stale one again, and edit or regenerate the others.
  • 409 conflict: the localization changed while Kenso saved the approval. Read it again and retry.

Requires Campaigns edit.

Parameters

NameInTypeRequiredDescription
channelquerystringoptionalemail or linkedin. Needed only when an email and a LinkedIn localization of the campaign share the id.
Request
curl -X POST "https://api.ken.so/v1/campaigns/812/localizations/812/approve" \
  -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 CampaignLocalization.

Show the 23 response fields and an example

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

Regenerate a localization

POST/v1/campaigns/{campaignId}/localizations/{localizationId}/regeneratecampaign-localizations.regenerate
Permission
Campaigns edit
Credits
Varies with the request (translation)
Rate limit
4,800 requests a minute per API key
Needs the multilingual_outreach feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Queues Kenso to write one localization again, optionally with an instruction. Use it when a draft needs changes you do not want to make by hand.

The body is optional, for example { "instruction": "Shorter, and less formal." }. With an instruction, Kenso rewrites the current text to follow it. Without one, Kenso writes the localization anew. Both replace text a member edited. The localization becomes a draft at once and loses any approval, so a live campaign stops sending it until it is approved again. Meanwhile the campaign's languageFallback decides what the contacts of that language get: the source text, or a hold. The response is 202 with the localization, and generating stays true until Kenso has written it. Send channel only when an email and a LinkedIn localization of the campaign share the id.

Errors:

  • 400 validation_failed with detail code too_long: instruction is longer than 2,000 characters.
  • 400 validation_failed with detail code language_not_enabled: the campaign no longer turns on this localization's language.
  • 400 validation_failed with detail code step_not_localizable: the step is no longer active or has no text to localize.
  • 400 validation_failed with detail code unsupported_language: Kenso has no market pack to write this language with.
  • 400 validation_failed with detail code channel_required: an email and a LinkedIn localization share this id. Add channel.
  • 400 validation_failed with detail code invalid_value: channel is not email or linkedin.
  • 404 not_found: the campaign or the localization does not exist in this workspace, or the localization's step was removed.
  • 409 localization_generating: Kenso already has this localization queued.
  • 409 invalid_state with detail code localization_disabled: localization is not turned on for this workspace yet.
  • 409 conflict: the localization changed while Kenso saved the request. Read it again and retry.

Requires Campaigns edit.

Parameters

NameInTypeRequiredDescription
channelquerystringoptionalemail or linkedin. Needed only when an email and a LinkedIn localization of the campaign share the id.

Request body

application/json, optional.

Optional. An instruction for the new text.

FieldTypeRequiredDescription
instructionstringoptionalWhat to change, in a sentence or two, such as Shorter, and less formal. Up to 2,000 characters. Absent writes the localization anew.
Request
curl -X POST "https://api.ken.so/v1/campaigns/812/localizations/812/regenerate" \
  -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 '{
  "instruction": "string"
}'

Response 202

data is a CampaignLocalization.

Show the 23 response fields and an example

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


On this page