Kenso
Get early access

Voice note previews

The Voice note previews endpoints of the Kenso API.

1 endpointKen-Version: 1.1AuthenticationWorkspacesErrors

Preview a voice note step for up to 3 leads

POST/v1/voice-note-previewsvoice-note-previews.create

Needs the linkedin_voice_notes feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Body { campaignId, contactIds (1 to 3 contacts of that campaign), step: { body, subject, voice } }, where voice is the voice object of a voice_note sequence step. Ken writes and speaks each lead's note now, free; each lead takes one unit of the workspace's daily limit (15) and a lead whose preview failed gives it back. Answers 201{ items: [{ contactId, voiceNote }] }: each voiceNote is ready with audioUrl, or failed with failureReason; one lead failing never fails the call. A bad step or contact list is 400, a campaign or contact outside the workspace 404, an imported voice without the workspace's ElevenLabs key 409 provider_key_missing (502 provider_rejected when its saved key is marked invalid), past the limit 429 quota_exceeded with Retry-After, quotaResetAt and the limit and reset time on error.details[0], and 503 voice_notes_unavailable while voice notes are off on the server or when the workspace's ElevenLabs key could not be read just now (retry later). Requires campaigns edit.

Parameters

Name
In
Type
Required
Description
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
optional
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Optional: without it the request uses 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
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
campaignId
integer (int64)
optional
The campaign whose leads are previewed.
contactIds
array of integer (int64)
optional
1 to 3 contacts of that campaign.
step
VoiceNotePreviewStep
optional

Response 201

data is a VoiceNotePreviewsModel.

Field
Type
Description
items
array of VoiceNotePreviewModel
Request
curl -X POST "https://api.ken.so/v1/voice-note-previews" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 1.1" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "campaignId": 812,
  "contactIds": [
    812
  ],
  "step": {
    "body": "string",
    "subject": "string",
    "voice": {
      "provider": "string",
      "voiceId": "string",
      "speed": 0.5,
      "wordsMode": "string",
      "instructions": "string",
      "script": "string",
      "model": "string",
      "matchLeadLanguage": true
    }
  }
}'
Response 201
{
  "success": true,
  "data": {
    "items": [
      {
        "contactId": 812,
        "voiceNote": {
          "voiceNoteId": 812,
          "status": "string",
          "durationMs": 1,
          "language": "string",
          "provider": "string",
          "voiceId": "string",
          "scriptText": "string",
          "failureReason": "string",
          "audioAvailable": true,
          "audioUrl": "https://example.com"
        }
      }
    ]
  }
}
More in the API:Contact behaviorSaved list membersVoice notesVoicesAll resources