Contact exports

Export contacts as a file and download it.

Contacts and lists2 endpointsKen-Version: 2026-11-02Authentication Workspaces Errors

Create a contact export and return its job

POST/v1/contact-exportscontact-exports.create

kind is contacts (workspace filters), campaign, clicked, advanced, or events. Campaign kinds require campaignId in the current workspace. events also requires occurredAfter and occurredBefore. Requires ExportAccess. Poll GET /v1/jobs/{jobId}?type=contact_export. The job's downloadUrl streams the file. Contacts from a Kenso library list are never exported. For kinds contacts, campaign and advanced the job's excludedLibraryContacts says how many were left out, including 0. Kind contacts also takes campaignIds (1 to 50 campaigns of the workspace, not with campaignId), listId (a contact's import list), createdAfter (inclusive) and createdBefore (exclusive), maxRows (1 to 50000) and skipRows (in contact id order). Other kinds refuse them. readyOnly still needs one campaignId.

Parameters

Name

Type

Required

Description

Ken-Version

In: header

string, one of: 2026-11-02, 1.1

required

The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.

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, required.

Field

Type

Required

Description

kind

string

optional

contacts (workspace filters, 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.

segmentId

integer (int64)

optional

Kind contacts only: the campaign segment to export.

isQualified

boolean

optional

Kinds contacts and campaign: only qualified (true) or only unqualified (false) contacts.

hasValidEmail

boolean

optional

Kind contacts: only contacts with (true) or without (false) a valid email.

doNotContact

boolean

optional

Kind contacts: only do-not-contact (true) or only contactable (false) contacts.

string

optional

Kind contacts: search text, at most 200 characters.

contactIds

array of integer (int64)

optional

Kind contacts: export only these contacts, at most 1,000 ids.

excludedContactIds

array of integer (int64)

optional

Kind contacts: leave these contacts out, at most 1,000 ids.

fields

array of string

optional

The columns to write, at most 80 names. Omitted writes the kind's default columns.

readyOnly

boolean

optional

Kind contacts only, with campaignId: only contacts ready to send.

includeEmails

boolean

optional

Kinds campaign, clicked and advanced: include email columns. Default true.

includeCompany

boolean

optional

Kinds campaign, clicked and advanced: include company columns. Default true.

includeClickEvents

boolean

optional

Kind advanced: include click events. Default true.

includeTotalClicks

boolean

optional

Kind advanced: include the total click count. Default true.

occurredAfter

string (date-time)

optional

Kind events: start of the range (required).

occurredBefore

string (date-time)

optional

Kind events: end of the range (required).

campaignIds

array of integer (int64)

optional

Kind contacts only: 1 to 50 campaigns of the workspace. Not together with campaignId.

listId

integer (int64)

optional

Kind contacts only: contacts of this import list (a contact's listId).

createdAfter

string (date-time)

optional

Kind contacts only: contacts created at or after this time.

createdBefore

string (date-time)

optional

Kind contacts only: contacts created before this time (exclusive).

maxRows

integer (int32)

optional

Kind contacts only: at most this many rows, 1 to 50000.

skipRows

integer (int32)

optional

Kind contacts only: skip this many matching rows first, in contact id order.

Response 202

data is a JobModel.

Field

Type

Description

integer (int64)

type

string

status

string

progress

JobProgressModel

resource

JobResourceModel

createdAt

string (date-time)

downloadUrl

string

error

JobErrorModel

result

object

Upstream payload for a scraping job get. Omitted for other types and for lists.

domainsListed

integer (int32)

Listed-domain count stored by a completed domain health sweep. Omitted until that count exists.

excludedLibraryContacts

integer (int32)

Contacts from a Kenso library list a contact export left out (they are never exported), including 0. Only on contact_export jobs of kind contacts, campaign and advanced; omitted otherwise.

inboxImport

InboxImportJobModel

Counts and per-row results of an inbox_import job. Passwords are never returned.

personImport

PersonImportJobModel

Counts of a contact_import job with target people: each row created a person, updated (matched) one, or was skipped (no email, LinkedIn URL, or name with a business company domain, or intake refused it).

skipped

ContactImportSkipsModel

Rows a campaign contact_import job skipped, by reason. The duplicate counts name the rule that dropped the row: a contact already in this campaign, a contact in another campaign of the workspace (the campaign dedups against other campaigns), an earlier row of the same import, or the campaign's recently-emailed window.

Request

curl -X POST "https://api.ken.so/v1/contact-exports" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_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": [
    "string"
  ],
  "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

{
  "success": true,
  "data": {
    "id": 812,
    "type": "string",
    "status": "string",
    "progress": {
      "completed": 1,
      "total": 1
    },
    "resource": {
      "type": "string",
      "id": 812
    },
    "createdAt": "2026-09-23T15:02:11Z",
    "downloadUrl": "https://example.com",
    "error": {
      "code": "string",
      "message": "string"
    },
    "result": null,
    "domainsListed": 1,
    "excludedLibraryContacts": 1,
    "inboxImport": {
      "connectedCount": 1,
      "failedCount": 1,
      "skippedCount": 1,
      "startedAt": "2026-09-23T15:02:11Z",
      "updatedAt": "2026-09-23T15:02:11Z",
      "completedAt": "2026-09-23T15:02:11Z",
      "rows": [
        {
          "index": 1,
          "email": "[email protected]",
          "status": "string",
          "inboxId": 812,
          "errorCode": "string",
          "message": "string"
        }
      ]
    },
    "personImport": {
      "source": "string",
      "createdCount": 1,
      "updatedCount": 1,
      "skippedCount": 1,
      "startedAt": "2026-09-23T15:02:11Z",
      "completedAt": "2026-09-23T15:02:11Z"
    },
    "skipped": {
      "duplicateInCampaign": 1,
      "duplicateInOtherCampaign": 1,
      "duplicateInSource": 1,
      "alreadyContacted": 1,
      "blocklist": 1,
      "failedValidation": 1,
      "salesNavigatorProfileUnresolved": 1,
      "other": 1,
      "missingKey": 1,
      "invalidEmail": 1,
      "noMx": 1,
      "catchAll": 1,
      "personalEmail": 1,
      "roleAddress": 1,
      "companyContacted": 1,
      "companyCap": 1
    }
  }
}

Download a contact export file

GET/v1/contact-exports/{exportId}/contentcontact-exports.content

Try it on developer.ken.so

Streams CSV, or a ZIP when a campaign export is one file per segment. Each download is sized from a live count and charged to the export row quota before any row is read; a file over the per-request row cap is 429 quota_exceeded. Requires ExportAccess. A missing or expired export is not_found.

Parameters

Name

Type

Required

Description

exportId

In: path

integer (int64)

required

Ken-Version

In: header

string, one of: 2026-11-02, 1.1

required

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).

Response 200

The body is a string (binary).

Request

curl -X GET "https://api.ken.so/v1/contact-exports/812/content" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"

Response 200

"<binary>"

More in Contacts and lists:Contacts Contact imports Contact fields Companies People Tags Blocklist entries Blocklist rules Jobs All resources