Skip to Content
Campaigns

Campaign images

The current images of a campaign's leads, and one image with a fresh preview link.

Campaigns2 endpointsKen-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.

List contacts' images in a campaign

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

Try it on developer.ken.so

Returns the current images of the contacts you name: one for each image variable that makes an image per contact, and the contact's own custom_image. Use it to show images next to a page of contacts.

contactIds is required: from 1 to 200 contact ids, separated by commas. variableKey keeps the images of one image variable, or custom_image for the contacts' own images. A key that matches no image variable of the campaign returns an empty list. The list has one item per contact and key that has an image, in any status, ordered by contactId and then variableKey. A contact with no image, or not in the campaign, gets no item. Images of a deleted image variable are left out. A ready image has a previewUrl that works until previewExpiresAt, 1 hour after the call. The whole result comes in one page, so hasMore is always false.

Errors:

  • 400 validation_failed: contactIds is missing, names more than 200 ids, or holds a value that is not a positive whole number.
  • 404 not_found: the campaign does not exist in this workspace.

Requires Campaigns view.

Parameters

NameInTypeRequiredDescription
campaignIdpathinteger (int64)requiredId of the campaign.
contactIdsquerystringoptionalIds of the contacts, separated by commas, from 1 to 200, such as 101,102,103.
variableKeyquerystringoptionalOptional. The key of one image variable, or custom_image for the contacts' own images. Omitted returns every key.
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/images?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 CampaignImage. Each item has these fields. The response also carries pagination.

Show the 11 response fields and an example

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

Get a campaign image

GET/v1/campaign-images/{imageKey}campaign-images.get
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key
Needs the campaign_images feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Returns one image by its key, with a new preview link. Call it again when a previewUrl has expired.

imageKey is the 26-character key from the image list or from an image variable. A ready image has a previewUrl that works until previewExpiresAt, 1 hour after the call. A pending or failed image has no preview link.

Errors:

  • 404 not_found: no image in this workspace has this key, or the image was deleted.

Requires Campaigns view.

Parameters

NameInTypeRequiredDescription
imageKeypathstringrequiredThe image's 26-character key.
Request
curl -X GET "https://api.ken.so/v1/campaign-images/01JC8Z3K6Q2W4M7N9P5R1T3V5X" \
  -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 CampaignImage.

Show the 11 response fields and an example

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


On this page