Contact exports
Export contacts as a file and download it.
Headers
The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Ken-Version | header | string, one of: 2026-11-02, 1.1 | optional | The 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-Id | header | integer (int64) | optional | The 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
/v1/contact-exportscontact-exports.create- Permission
- Campaigns view and the
exportpermission - Rate limit
- 10 requests a minute per API key
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. Withoutfields, 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 betweenoccurredAfterandoccurredBefore.
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: kindcontactsmatches more than 50,000 contacts. Narrow the filters or setmaxRows.404 not_found:campaignId, an id incampaignIds,listIdorsegmentIdis 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.
| Field | Type | Required | Description |
|---|---|---|---|
kind | string | optional | What the export holds: contacts (contacts across the workspace, the default), campaign, clicked, advanced or events. |
campaignId | integer (int64) | optional | The campaign to export. Required for every kind except contacts, and for contacts with readyOnly. With kind contacts, it limits the export to this campaign. |
segmentId | integer (int64) | optional | Kind contacts only: export only this segment's contacts. When you send campaignId or campaignIds, the segment must belong to one of those campaigns. |
isQualified | boolean | optional | Kinds contacts and campaign: true exports only qualified contacts, false only unqualified ones. Omitted exports both. |
hasValidEmail | boolean | optional | Kind contacts only: true exports only contacts with a valid email, false only contacts without one. Omitted exports both. |
doNotContact | boolean | optional | Kind contacts only: true exports only do-not-contact contacts, false only contactable ones. Omitted exports both. |
q | string | optional | Kind contacts only: search text the contacts must match, at most 200 characters. |
contactIds | array of integer (int64) | optional | Kind contacts only: export only these contacts, at most 1,000 ids. |
excludedContactIds | array of integer (int64) | optional | Kind contacts only: leave these contacts out, at most 1,000 ids. |
fields | array of string | optional | The 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. |
readyOnly | boolean | optional | Kind contacts only: true exports only contacts that are ready to send. Needs campaignId. Defaults to false. |
includeEmails | boolean | optional | Kinds campaign, clicked and advanced: include the email columns. Defaults to true. |
includeCompany | boolean | optional | Kinds campaign, clicked and advanced: include the company columns. Defaults to true. |
includeClickEvents | boolean | optional | Kind advanced only: include each contact's click events. Defaults to true. |
includeTotalClicks | boolean | optional | Kind advanced only: include each contact's total click count. Defaults to true. |
occurredAfter | string (date-time) | optional | Kind events, required: the start of the time range, as an ISO 8601 timestamp. The range can span at most 366 days. |
occurredBefore | string (date-time) | optional | Kind events, required: the end of the time range, as an ISO 8601 timestamp. It must not be before occurredAfter. |
campaignIds | array of integer (int64) | optional | Kind contacts only: export the contacts of these campaigns, from 1 to 50 campaign ids of the workspace. Send either this or campaignId, not both. |
listId | integer (int64) | optional | Kind 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. |
createdAfter | string (date-time) | optional | Kind contacts only: export only contacts created at or after this time. |
createdBefore | string (date-time) | optional | Kind contacts only: export only contacts created before this time. It must be later than createdAfter. |
maxRows | integer (int32) | optional | Kind contacts only: write at most this many rows, from 1 to 50,000. |
skipRows | integer (int32) | optional | Kind contacts only: skip this many matching contacts first, in contact id order. Use it with maxRows to export in parts. 0 or more. |
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
/v1/contact-exports/{exportId}/contentcontact-exports.content- Permission
- Campaigns view and the
exportpermission - Rate limit
- 240 requests a minute per API key
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 kindclickedexport of a campaign with no clicks, a kindcampaignexport withoutfieldsof a campaign with no personalization prompts, or a kindcontactsexport 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
exportId | path | integer (int64) | required | The export's id, the same as the id of its contact_export job. |
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.
More in Contacts and companies:ContactsContact importsTagsBlocklistBlocklist rulesContact fieldsCompaniesCompany dataContact behaviorAll resources