Skip to Content
Copy and personalization

Voice note previews

Voice note previews let you hear a LinkedIn voice note step before you save it. Kenso writes and speaks the note for up to 3 of the campaign's contacts and returns each one with a link to its audio. Previews are free and count toward a daily limit for the workspace.

Copy and personalization1 endpointKen-Version: 2026-11-02AuthenticationWorkspacesErrors
MarkdownOpenAPI

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.

Preview a voice note step

POST/v1/voice-note-previewsvoice-note-previews.create
Permission
Campaigns edit
Rate limit
4,800 requests a minute per API key
Needs the linkedin_voice_notes feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Makes the voice note an unsaved step would send to 1 to 3 of the campaign's contacts, so you can hear it before you save the step. Send the step's body, subject and voice as you would save them. Ken writes each note (or reads the step's script), Kenso speaks it right away, and nothing is sent to the contacts.

Returns 201 with one item per contact. Each item's voiceNote is ready with an audioUrl to play, or failed with a failureReason. One contact failing never fails the call. Playing the audio needs Inbox view.

Previews cost no credits. Each contact counts toward the workspace's limit of 15 previews a day, and a contact that fails before Kenso writes or speaks anything does not count.

Errors:

  • 400 validation_failed: contactIds does not list 1 to 3 contacts, the step is not a valid voice note step, or the voice is not available.
  • 404 not_found: the campaign is not in this workspace, or a contact is not in the campaign.
  • 409 provider_key_missing: the voice is imported and the workspace has no ElevenLabs API key in Settings, Integrations.
  • 429 quota_exceeded: the workspace reached its daily preview limit. Wait for Retry-After seconds; quotaResetAt and error.details[0] give the limit and when it resets.
  • 502 provider_rejected: ElevenLabs refused the workspace's key. Check it in Settings, Integrations.
  • 503 voice_notes_unavailable: voice notes are not available right now, Kenso could not read the workspace's ElevenLabs key, or ElevenLabs did not answer. Try again later.

Requires Campaigns edit.

Request body

application/json, optional.

The campaign, the contacts and the step to preview.

FieldTypeRequiredDescription
campaignIdinteger (int64)optionalThe campaign the contacts are in.
contactIdsarray of integer (int64)optionalThe contacts to make the note for: 1 to 3 distinct contacts of the campaign.
stepVoiceNotePreviewStepoptionalThe unsaved step: its fallback text, its InMail subject and its voice settings.
Request
curl -X POST "https://api.ken.so/v1/voice-note-previews" \
  -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 '{
  "campaignId": 812,
  "contactIds": [
    812
  ],
  "step": {
    "body": "string",
    "subject": "string",
    "voice": {
      "provider": "deepgram",
      "voiceId": "string",
      "speed": 0.5,
      "wordsMode": "string",
      "instructions": "string",
      "script": "string",
      "model": "haiku",
      "matchLeadLanguage": true
    }
  }
}'

Response 201

data is a VoiceNotePreviews.

Show the 1 response field and an example

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


On this page