Skip to Content
Contacts and companies

Contact exports

Export contacts as a file and download it.

Contacts and companies2 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.

Create a contact export

POST/v1/contact-exportscontact-exports.create
Permission
Campaigns view and the export permission
Rate limit
10 requests a minute per API key

Try it on developer.ken.so

Saves what the export should hold and returns its job. The job is already succeeded and its downloadUrl points at GET /v1/contact-exports/{exportId}/content, so you can download the file right away. The export id is the job id. You can read the job again with GET /v1/jobs/{jobId}?type=contact_export.

The kind field picks what the file holds:

  • contacts (the default): contacts across the workspace that match the filters in the body.
  • campaign: the contacts of one campaign. Without fields, the file adds a column for each of the campaign's personalization prompts.
  • clicked: the contacts of one campaign who clicked a tracking link, with their click data.
  • advanced: the contacts of one campaign, with their click events and total click count.
  • events: the events of one campaign's contacts between occurredAfter and occurredBefore.

Every kind except contacts needs campaignId. Kind contacts needs it only with readyOnly. Only kind contacts takes segmentId, readyOnly, campaignIds, listId, createdAfter, createdBefore, maxRows and skipRows. Other kinds refuse them.

Creating an export does not use your export row limit. Each download does. Kenso never exports contacts from a Kenso library list. For kinds contacts, campaign and advanced, the job's excludedLibraryContacts says how many it left out.

Errors:

  • 400 validation_failed: the body is not a JSON object, or a field breaks the rule in its description.
  • 400 validation_failed: kind contacts matches more than 50,000 contacts. Narrow the filters or set maxRows.
  • 404 not_found: campaignId, an id in campaignIds, listId or segmentId is not in the workspace, or the list or segment is not in the campaigns you sent.
  • 429 quota_exceeded: another kind would hold more than 50,000 rows.

Requires Campaigns view and the export permission.

Request body

application/json, required.

FieldTypeRequiredDescription
kindstringoptionalWhat the export holds: contacts (contacts across the workspace, the default), campaign, clicked, advanced or events.
campaignIdinteger (int64)optionalThe campaign to export. Required for every kind except contacts, and for contacts with readyOnly. With kind contacts, it limits the export to this campaign.
segmentIdinteger (int64)optionalKind contacts only: export only this segment's contacts. When you send campaignId or campaignIds, the segment must belong to one of those campaigns.
isQualifiedbooleanoptionalKinds contacts and campaign: true exports only qualified contacts, false only unqualified ones. Omitted exports both.
hasValidEmailbooleanoptionalKind contacts only: true exports only contacts with a valid email, false only contacts without one. Omitted exports both.
doNotContactbooleanoptionalKind contacts only: true exports only do-not-contact contacts, false only contactable ones. Omitted exports both.
qstringoptionalKind contacts only: search text the contacts must match, at most 200 characters.
contactIdsarray of integer (int64)optionalKind contacts only: export only these contacts, at most 1,000 ids.
excludedContactIdsarray of integer (int64)optionalKind contacts only: leave these contacts out, at most 1,000 ids.
fieldsarray of stringoptionalThe columns to write, at most 80 snake_case names such as first_name, email or company_domain. Omitted writes the kind's default columns, and kind events ignores it.
readyOnlybooleanoptionalKind contacts only: true exports only contacts that are ready to send. Needs campaignId. Defaults to false.
includeEmailsbooleanoptionalKinds campaign, clicked and advanced: include the email columns. Defaults to true.
includeCompanybooleanoptionalKinds campaign, clicked and advanced: include the company columns. Defaults to true.
includeClickEventsbooleanoptionalKind advanced only: include each contact's click events. Defaults to true.
includeTotalClicksbooleanoptionalKind advanced only: include each contact's total click count. Defaults to true.
occurredAfterstring (date-time)optionalKind events, required: the start of the time range, as an ISO 8601 timestamp. The range can span at most 366 days.
occurredBeforestring (date-time)optionalKind events, required: the end of the time range, as an ISO 8601 timestamp. It must not be before occurredAfter.
campaignIdsarray of integer (int64)optionalKind contacts only: export the contacts of these campaigns, from 1 to 50 campaign ids of the workspace. Send either this or campaignId, not both.
listIdinteger (int64)optionalKind contacts only: export only the contacts of this import list, the listId on a contact. When you send campaignId or campaignIds, the list must belong to one of those campaigns.
createdAfterstring (date-time)optionalKind contacts only: export only contacts created at or after this time.
createdBeforestring (date-time)optionalKind contacts only: export only contacts created before this time. It must be later than createdAfter.
maxRowsinteger (int32)optionalKind contacts only: write at most this many rows, from 1 to 50,000.
skipRowsinteger (int32)optionalKind contacts only: skip this many matching contacts first, in contact id order. Use it with maxRows to export in parts. 0 or more.
Request
curl -X POST "https://api.ken.so/v1/contact-exports" \
  -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 '{
  "kind": "string",
  "campaignId": 812,
  "segmentId": 812,
  "isQualified": true,
  "hasValidEmail": true,
  "doNotContact": true,
  "q": "string",
  "contactIds": [
    812
  ],
  "excludedContactIds": [
    812
  ],
  "fields": [
    "first_name"
  ],
  "readyOnly": true,
  "includeEmails": true,
  "includeCompany": true,
  "includeClickEvents": true,
  "includeTotalClicks": true,
  "occurredAfter": "2026-09-23T15:02:11Z",
  "occurredBefore": "2026-09-23T15:02:11Z",
  "campaignIds": [
    812
  ],
  "listId": 812,
  "createdAfter": "2026-09-23T15:02:11Z",
  "createdBefore": "2026-09-23T15:02:11Z",
  "maxRows": 1,
  "skipRows": 1
}'

Response 202

data is a Job.

Show the 14 response fields and an example

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

Download a contact export

GET/v1/contact-exports/{exportId}/contentcontact-exports.content
Permission
Campaigns view and the export permission
Rate limit
240 requests a minute per API key

Try it on developer.ken.so

Streams the export's file. This is the path in the job's downloadUrl. Kenso builds the file at each download from what you set when you created the export, so the rows reflect your contacts at that moment.

The file is a CSV. A kind campaign export of a campaign with more than one active segment is a ZIP with one CSV per segment. A kind events file has the columns eventId, eventType, timestamp and contactId. A cell that starts like a spreadsheet formula gets a leading apostrophe.

Each download charges its rows to the workspace's daily export row limit. You can download an export for 24 hours after you create it.

Errors:

  • 400 validation_failed: Kenso cannot build the file, for example a kind clicked export of a campaign with no clicks, a kind campaign export without fields of a campaign with no personalization prompts, or a kind contacts export that now matches more than 50,000 contacts.
  • 404 not_found: no export with this id exists in the workspace, or it is older than 24 hours.
  • 429 quota_exceeded: the file would hold more than 50,000 rows.
  • 429 rate_limited: the workspace reached its daily export row limit.

Requires Campaigns view and the export permission.

Parameters

NameInTypeRequiredDescription
exportIdpathinteger (int64)requiredThe export's id, the same as the id of its contact_export job.
Request
curl -X GET "https://api.ken.so/v1/contact-exports/812/content" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"

Response 200

The body is a string (binary).

Show an example response

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


On this page