Kenso MCP tools

Contacts contacts

The workspace's campaign contacts and their company records. To change several contacts, call search once: search(operation="contacts-bulk-update", items=[{"contactId": 1, "outreachLanguage": "de-DE"}, ...]), never update per contact. search, not list, takes campaign_ids, ready_only, filters and sort. Who clicked a campaign's links, by name: search with campaign_ids, sort="totalClicks", direction="desc". A company record by name or exact domain: companies-list. An attached CSV, as is: contact-imports-create with source csv and csv_content. Export: contact-exports-create with campaign_id (campaign_ids for several). Copy another campaign's contacts in: contact-imports-create with source campaign and source_campaign_id, no reads first. create adds rows listed in the message. Delete several contacts in one call: bulk-delete with ids.

Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through contacts_read and changes through contacts_write. Each takes operation plus that operation's parameters, and your workspace role decides which operations you see.

Each operation with a route calls the Kenso API at https://api.ken.so with Authorization: Bearer <Kenso API key>, Ken-Version: 1.1 and X-Ken-Workspace-Id: <workspace id>. You can call that route directly with the same headers.

Operations: bulk-delete, content, contact-exports-create, contact-imports-create, create, google-sheets-create, delete, events, companies-get, get, companies-list, contact-fields-list, list, saved-list-members-list, list-website-pages, search, update, export_contacts

bulk-delete

Write. POST https://api.ken.so/v1/contacts/bulk-delete

Body (json): ids array

Soft-delete up to 1,000 contacts by id. Ids outside the workspace are reported in failed and are not deleted.

POST /api/v1/contacts/bulk-delete. Public. Sends Ken-Version 1.1.
Requires Campaigns edit.

content

Read. GET https://api.ken.so/v1/contact-exports/{exportId}/content

Path: exportId

Download a contact export file. Streams CSV, or a ZIP when a campaign export is one file per segment.

GET /api/v1/contact-exports/{exportId}/content. Public. Sends Ken-Version 1.1.

Requires export access. A missing or expired export is not_found. The
response data holds fileName, contentType and size (bytes). A CSV comes
back as fileContent, its text. A ZIP comes back as contentBase64, its
bytes in base64; one over 2 MiB (2,097,152 bytes) is refused with a
validation error: download it in the Kenso app instead.

contact-exports-create

Write. POST https://api.ken.so/v1/contact-exports

Create a contact export and return its job. kind is contacts, campaign, clicked, advanced, or events. Defaults to contacts.

POST /api/v1/contact-exports. Public. Sends Ken-Version 1.1. Requires export access.

Campaign kinds require campaign_id. events also requires occurred_after and
occurred_before, spanning at most 366 days. segment_id and ready_only apply
only to kind contacts. ready_only also requires campaign_id. Poll the
contact_export job, then download with contacts(operation="content").

Kind contacts also takes campaign_ids (1 to 50 campaigns of this workspace,
not with campaign_id; a campaign of another workspace is not_found),
list_id (contacts imported through that import list; a list of another
workspace is not_found, and so is one outside campaign_id, or outside
campaign_ids, when those are sent), created_after
(inclusive) and created_before (exclusive), ISO-8601 timestamps of when the
contact was added (no offset means UTC; sent as normalized ISO 8601), max_rows (1 to 50,000) and
skip_rows (0 or more, in contact id order). The job's total counts the
capped export. Any other kind refuses them.

Contacts from a Kenso library list are never exported. For kinds contacts,
campaign and advanced the job has excludedLibraryContacts, how many the export
left out (including 0); clicked and events jobs omit it.

contact-imports-create

Write. POST https://api.ken.so/v1/contact-imports

Start a contact import and return its job. source is campaign, segment, search, blitz, loopster, people, event, linkedin_connections, sales_navigator, linkedin_url, csv, google_sheets, airtable or saved_list. target people imports the rows as workspace people. Poll the contact_import job.

POST /api/v1/contact-imports. Public. Sends Ken-Version 1.1. Requires Campaigns edit and the `import` permission.

target is campaign (the default: the rows become contacts of campaign_id,
which is then required) or people. target people runs the rows through
person intake as workspace people with source import (an existing person
with the same email or LinkedIn URL is updated): campaign_id is ignored,
and source is csv, search, blitz, event, linkedin_connections, sales_navigator,
google_sheets or airtable (each behind its own feature, as for a
campaign). It needs the lead_intake feature (404 while it is off) and
Accounts edit (403 without it). A row needs an email, a LinkedIn URL, or a
name with a business company domain; other rows are skipped. The job
starts queued; its personImport holds source, createdCount, updatedCount
and skippedCount. The rest of this text describes target campaign.

campaign copies source_campaign_id into campaign_id.
Options, each refused with a source that does not take it and with target
people: campaign takes import_limit (at least 1), import_offset (0 or more),
only_import_qualified_contacts, only_import_valid_contacts,
deduplicate_campaign_ids (1 to 50 campaigns of this workspace, skipping
contacts already in them; a campaign of another workspace is not_found),
deduplication_mode (none, by_email the default, by_data), allow_reimport,
copy_data_enrichment and copy_email_enrichment (keep the source's data and
email enrichment results; default false). search takes import_limit,
trigger_post_processing (default true) and tag_ids (1 to 50 contact tags of
this workspace); blitz and loopster take none of them. csv takes import_limit and
tag_ids too, as form fields.
segment copies source_segment_id, a segment of any campaign of this
workspace, into campaign_id as a new segment with the source segment's
name; copy_qualification, copy_email_enrichment and copy_email_verification
(default false) keep those results. A segment of another workspace is
not_found, a segment name already in campaign_id is validation_failed, and
an import still running there is 409. A source campaign of another
workspace is not_found too: an import works in one workspace.
search sends up to 1,000
contact objects (Kenso Search field names, snake_case accepted). A search row
counts as free Kenso Search work only with the searchToken Kenso returned on
it (each search-people, lookup-person or buyer preview person carries one;
send it with the person's linkedInUrl unchanged); a row without one still
imports (DEV-6219). blitz sends up
to 1,000 people picked from a blitz tool page the same way (full_name, title,
linkedin_url, company_name, company_domain, company_linkedin_url): the same
dedupe, blocklist, limits and lead charge as search, recorded as a Blitz run
and never counted as free Kenso Search work (DEV-6902). loopster sends
records, 1 to 1,000 people from loopster(operation="people-search")
pages as returned (id, position, fields), with search_id, the page's
meta.searchId: records without a LinkedIn URL get it from a temporary
Loopster table Kenso trashes afterwards, so search_id is required then
(about 24 hours; later it is search_expired). A Loopster run, never Kenso
Search work, with no target people (DEV-6899).
people sends
person_ids, 1 to 1,000 people from the people tool: each becomes a contact
with their name, email, title, LinkedIn URL and the company of their
highest-priority account (needs the Accounts feature; 404 when it is off).
event sends event_id, an outbound event from the outbound_events tool: its
attendee rows with an email or a LinkedIn URL become contacts (name, title,
email, LinkedIn URL, company), at most 5,000. roles narrows them (attendee,
exhibitor, speaker, sponsor; default every role). Rows whose company is a
workspace account are left out, because the Accounts lane works them, unless
include_accounts is true (with account scope own, only rows on the caller's own
accounts are added). Needs the Accounts and Event outbound features (404
when either is off); an event with no such row is validation_failed.
linkedin_connections sends connection_ids, 1 to 1,000 LinkedIn connections from
linkedin_connections(operation="connections-list"): each becomes a contact with first and last name,
title, LinkedIn URL, company name and company domain, and a connection without a
company is skipped. It needs the LinkedIn network feature for the workspace; while it
is off the source is 400 validation_failed, like an unknown source. Every source
except segment adds its contacts to the campaign's default segment, so
segment_id is refused (validation_failed).
sales_navigator sends linkedin_account_id (a seat you connected yourself;
another member's seat is not_found) and url (a Sales Navigator lead search
or lead list): its people with their name, current title, LinkedIn profile
and company. One import reads at most 8 pages (about 200 to 400 people); a
list it cannot read to the end imports nothing and is validation_failed with
code incomplete_read on url, so check the preview's total first and narrow
or split a longer list. Internal, behind the sales_navigator feature (while it
is off the source is validation_failed). A seat without Sales Navigator is
409 sales_navigator_required. Preview the url first with
linkedin(operation="preview-sales-navigator", ...).
csv uploads csv_content (the CSV text: read the file yourself and pass
its text) as multipart field file. The hosted MCP refuses file_path,
because it cannot read your machine; off the hosted MCP, file_path opens
only a .csv inside the MCP export directory. emails_found_by_ken (csv
only, Kenso staff only: 403 forbidden for a member; only into the Kenso
email pool workspace, validation_failed on it for any other workspace)
stamps every imported email found_by_ken, so the cross-workspace Kenso
DB lookup may serve it; a column "Email 1 Validity" right after the email
column carries its verdict (safe, catch_all, invalid, risky). Behind the
csv_import_check feature (a field sent while it is off is
validation_failed on it), csv
with target campaign takes the List check choices of
saved_searches(operation="contact-imports-scan"): fixes (a list of
missingKey, invalidEmail, noMx, catchAll, personalEmail, roleAddress,
companyContacted, companyCap) drops the rows the check flags for them, each
counted once under the first that matches in the job's skipped;
include_recently_contacted true keeps the rows the campaign's
recently-emailed window would skip, for this import only; cleanup true
cleans the name, email, title, company, domain, LinkedIn URL and phone cells
as the scan's cleanup notes say. Omitted, they are off. google_sheets reads
spreadsheet_id (an id or a Google Sheets URL) and the optional sheet (a tab
title; omitted reads the first tab) with the caller's own Kenso Workspace
Google connection: row 1 is the header and the rows import like a CSV.
column_mappings (csv_column, target_field, custom_variable_name,
use_as_ai_context, is_required_for_sending) sets the columns; omitted, the
import maps the headers itself. integrations(operation="google-sheets-preview")
shows the rows and suggested mappings. column_mappings works for csv too
(sent as the form field columnMappings): a csv_column the file's header row
lacks is validation_failed on columnMappings.
saved_searches(operation="contact-imports-scan") suggests the mappings
for any file from its header and sample rows. google_sheets needs the
google_sheets feature (an unknown source while it is off); no Google
connection is 409 reconnect_required, and a sheet the member did not pick
for Kenso with Google Picker is 409 sheet_not_shared. airtable reads every
record of table_id (a table id or name) in base_id (app...), in view_id's
order and filter when set (a view id or name), with the workspace's own
Airtable token: the headers are the field names, primary field first, every
cell as text, and the file is named after the table. A table or view of
more than 10,000 records is 400 validation_failed on tableId: import it in
parts, through views that each show fewer records. column_mappings works
as for google_sheets. integrations(operation="airtable-tables-list") lists
the tables, fields and views. airtable needs the airtable feature (an
unknown source while it is off); no saved token is 409 not_connected and a
token without data.records:read or access to the base is 409
scope_required. Returns 202 and a job. The import's dedupe, blocklist and
contact limits apply to every source.

saved_list imports the members of saved_list_id: a list of this workspace
(a private one only for its owner), a list shared with it, or a library
list. member_filters narrows them (country, seniority, title, industry,
headcount_band: text, title matches part of the title; has_sendable_email:
true or false). For a company list, roles (1 to 20 job titles) imports up
to 5 people per company found in Kenso Search, for at most 500 companies;
without roles every company is one contact for the company itself. roles on
a list of people is validation_failed on roles. find_people true is
validation_failed: import the companies, then add the data.find_people
step to a workflow on the campaign. Members this list already put in the
campaign are skipped, so a retry imports only the rest. A library list's
cached safe emails land safe with no email charge on a paid plan; a Free
workspace gets no emails from a library list. A member copied out of a
library list follows the same rules in any list. column_mappings is
refused: the list sets its own columns. More than 100,000 contacts is
validation_failed on memberFilters. It needs the saved_lists feature (an
unknown source while it is off).

linkedin_url imports the people of a LinkedIn post (its reactions and
comments), a people search, or a Sales Navigator search or lead list into
campaign_id, in the background. It needs the linkedin_url_import flag (404
when off). url is required (at most 8,000 characters); linkedin_account_id
picks the seat that reads LinkedIn, a seat you connected yourself (another
member's seat is linkedin_account_unavailable; default: your own connected
seat that fits the URL); max_leads defaults to 500 (at most 2,000 for a
post, 1,000 for a people search, 2,500 for Sales Navigator); post_kinds is
reaction, comment or both (default), for posts only. 400 codes:
unsupported_linkedin_url, sales_navigator_required,
linkedin_account_unavailable, linkedin_account_required.

Imported rows are profiles, not contacts. A contact is a profile that is
qualified and has a safe email. A campaign accepts up to 10 times its
contact limit in profiles; a contact limit of 0 or less (the default for a
new campaign) means unlimited profiles. Import more profiles than the contact target.
Verification and qualification shrink profiles down to contacts. An import
does not spend the contact allowance. The allowance is spent in the month
the profile becomes qualified and a safe email is known. The contact
allowance resets every month on the workspace billing date while status is
Active or Trialing. Canceled, PastDue, Unpaid, Paused, and Incomplete do
not open a new month and do not accept a new contact. The contact
allowance applies to Free and Premium (VIP) workspaces; Platform, Dfy and
the grandfathered plans have unlimited contacts.

Emails: when the campaign finds emails for imported rows, an address Kenso
already holds for that person (recently verified, hasKenEmail in Kenso
Search) is free on paid plans; any other email Ken finds costs 1 credit.
For a Kenso Search selection, saved_searches(operation="preview-import", ...)
counts those people before the import.

create

Write. POST https://api.ken.so/v1/campaigns/{campaignId}/contacts

Path: campaignId

Body (json): contacts array

Add up to 1,000 contacts to a campaign. Accepted and updated rows are succeeded. Rows can carry custom variables and verified-email validity. data.results says what happened to each row, with a reason for each skipped or failed one. Safe to retry.

POST /api/v1/campaigns/{campaignId}/contacts. Public. Sends Ken-Version 1.1.

Requires Campaigns edit. Each contact may set email, first_name, last_name,
title, linked_in_url, company_name, company_domain, custom_image_url,
custom_video, custom_variables, email_validity and use_ken_email.
use_ken_email (also useKenEmail, true or false) on a row with no email takes
the address from Kenso's email pool when it holds a recently verified one
for the person (by LinkedIn profile, else name with company name or domain),
free, for the first 25 such rows of the call. A row still without an email
is refused (email is required) unless the campaign is LinkedIn-only.
custom_image_url is the https URL of the lead's own image, shown in emails as
{{custom_image}}; Kenso downloads and hosts it, and an empty string clears it.
It needs campaign images on the workspace. A malformed URL fails its row
before it is written; a refused image fails its row with the contact's id,
the contact itself saved.
custom_video is the lead's own video, a Loom, YouTube, Vimeo, Wistia,
Vidyard, Sendspark or HeyGen share link or embed code, shown in emails as
{{custom_video}}; an empty string clears it. It needs campaign videos on the
workspace. A link no supported provider matches fails its row
(validation_failed) before it is written; a refused video (videos off) fails
its row with the contact's id, the contact itself saved; a video a sent or
queued step already uses fails its row with code video_in_use and the
contact's id, the contact saved and the old video kept.

custom_variables (also customVariables, custom_fields, customFields; one per
row) is an object of personalization values such as rd_subject_1,
rd_first_line, rd_link. Each value is a string, number, boolean or null;
numbers and booleans are sent as text, as on contacts(operation="update"):
true as "true", 1.0 as "1", 1.5 as "1.5". A nested object or list is refused
before any call. Values merge into the
contact's existing custom variables, and a null or empty value deletes that
key on an existing contact. A key new to the campaign is added to its
custom-variable catalog with AI context off. A blank key, a key that is not
usable as a {token}, a reserved key, or more than 50 keys fails only that
row (validation_failed, message starting contacts[i].customVariables).

email_validity (also emailValidity) is one of unknown, invalid, risky,
verified, safe, catch_all. The retired casing is accepted: Safe, CatchAll
and catch-all map to safe and catch_all. Omitted keeps the verdict stored on
an existing email. Pass safe for already-verified leads. In a campaign
without AI qualification, a safe row (not blocklisted) is qualified on
import, so it becomes a contact and spends one contact allowance in that
call. With no allowance left the row is still added but stays unqualified
and does not send. The allowance resets every month on the workspace
billing date while the subscription is Active or Trialing, and applies to
Free and Premium (VIP) workspaces; Platform, Dfy and the grandfathered
plans have unlimited contacts.

The upsert runs in batches of 100. A later batch can fail without rolling
back earlier rows. data.succeeded lists saved contact ids and data.failed
every other row with its index. data.results has one item per input row,
in request order: index, status (created, updated, skipped or failed), id
when saved, and for a skipped or failed row a reason (duplicate,
blocklisted, already_contacted, limit_reached, invalid_email, excluded,
validation or other) and a message. A saved row carries sendable, false
when the contact will not send (added unqualified with no contact
allowance left, or do-not-contact).

Example (Reverse Demo row):
    contacts(operation="create", campaign_id=8233, contacts=[{
        "email": "jordan@patientdesk.ai",
        "first_name": "Jordan",
        "last_name": "Lee",
        "company_domain": "patientdesk.ai",
        "email_validity": "safe",
        "custom_variables": {
            "rd_subject_1": "Quick question",
            "rd_first_line": "Saw the YC launch",
            "rd_link": "https://docs.google.com/...",
        },
    }])

google-sheets-create

Write. POST https://api.ken.so/v1/google-sheets

Write CSV text to a new Google Sheet in the caller's Drive. Returns the new spreadsheet's id and URL and the number of rows written.

POST /api/v1/google-sheets. Internal. Sends Ken-Version 1.1. Multipart
field file is the CSV, campaignId the optional campaign.

csv_content is UTF-8 CSV text: row 1 is the header (at most 100 columns),
then at most 50,000 data rows. This is how a campaign's Leads tab exports
what it shows: the same file its Download CSV saves. campaign_id, a
campaign of the workspace, names the sheet "Kenso export - <campaign name> -
<yyyy-MM-dd>" (else "Contacts") and the export's audit line. Cells are
text, never formulas; a cell that starts like a formula keeps one leading
apostrophe (numbers and phone numbers such as +15551234567 do not). A row
shorter than the header is padded, a longer one cut. data holds
spreadsheetId, spreadsheetUrl and rowCount (answered 201). Requires export
access and the google_sheets feature (404 while it is off). A file that is
not CSV, has no header or too many columns is 400 validation_failed; no
Google connection is 409 reconnect_required; Google refusing the write is
409 invalid_state, failing or rate-limiting 503 provider_unavailable. The
rows count against the workspace's export row limit (429).

delete

Write. DELETE https://api.ken.so/v1/contacts/{contactId}

Path: contactId

Soft-delete one contact. Requires Campaigns edit. Returns 204.

DELETE /api/v1/contacts/{contactId}. Public. Sends Ken-Version 1.1.

events

Read. GET https://api.ken.so/v1/contacts/{contactId}/events

Path: contactId

Query: cursor string, limit integer, occurredAfter date-time, occurredBefore date-time, type string

List one contact's timeline: sends, opens, link clicks, replies. Each event has type, occurredAt and campaignId. event_type="email_clicked" keeps the link clicks. A cursor is valid only with the same limit that issued it. Who clicked across a campaign: search with sort="totalClicks".

GET /api/v1/contacts/{contactId}/events. Public. Sends Ken-Version 1.1.

Event ids are strings. occurred_before must be later than occurred_after,
and the range cannot exceed 366 days. event_type filters one event type:
email_sent, email_opened, email_clicked, contact_replied, email_bounced,
contact_unsubscribed or video_event (new types can appear).

companies-get

Read. GET https://api.ken.so/v1/companies/{companyId}

Path: companyId

Return one company in the current workspace. A missing or cross-workspace id is not_found.

GET /api/v1/companies/{companyId}. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id. Requires Campaigns view.

get

Read. GET https://api.ken.so/v1/contacts/{contactId}

Path: contactId

Return one contact in the current workspace. A missing or cross-workspace id is not_found.

GET /api/v1/contacts/{contactId}. Public. Sends Ken-Version 1.1.
qualityScore is the lead score. qualityReasoning is why Ken assigned it.
companyEmailName is the email-ready company name (for example "Pally" for
"Pally (YC S25)"). Use it in copy. companyName stays the raw name.
Reads also include profileImage, qualificationResponse, segmentationReasoning,
experiencesJson, customVariables, emailsSent, clicks, replies, unsubscribes,
bounces, and positiveReplies.
LinkedIn activity: connectionRequestsSent and linkedInMessagesSent (messages and
InMails) count confirmed sends; connectionsAccepted and linkedInReplies count the
contact's LinkedIn lanes that were accepted or replied. All four are omitted for a
contact with no LinkedIn lane and no confirmed LinkedIn send.
Stored profile and company values are headline,
location, companyLogo, companyDomain, companySize, companyType,
companyFoundedYear, headquartersCity, headquartersState, headquartersCountry,
seniorityLevel, function, yearsOfExperience, languages, phoneNumber, summary,
skills, and education. segmentName is the catalog name for the leads column
campaign_segment_name. companySize is the stored employee-count range.
emailValidity is the snake_case verdict on the first Safe or Verified email.
Personalization responses are personalization1 through personalization20,
written as sibling fields. linkedInUrlNameMismatch, emailEnrichmentProviders,
and missingRequiredVariableKeys are computed, not stored columns. Blank text,
placeholder logos, an empty provider list, and an empty missing-key list are
omitted. profileImage is omitted for a blank, a LinkedIn placeholder, or an
expired signed URL. Blank qualification or segmentation text, an empty
customVariables map, and missing stats are omitted. customVariables keeps
registered campaign keys that have a value. experiencesJson is the work-history JSON. linkedInSendBlockedReason, when set, says the contact's LinkedIn sequence is held: "missing_required_variables: <names>" lists the {{name}} tokens in a LinkedIn step that nothing fills (no campaign variable, no {{name|text}} fallback, no AI variable fallback). Fix the step's text or add a fallback; a held contact is not restarted by the fix. Also city, state, country, countryIso2, isDecisionMaker, companyIndustry,
companyLocation, companyTechnologies, and phoneNumberValidity.
phoneNumberValidity is the snake_case verdict and is omitted when the phone
is blank. isDecisionMaker stays present when false. Blank text is omitted.
Last-job, employment, and company profile columns are lastJobTitle,
lastJobDescription, employmentType, employmentLocation, companyLinkedInUrl,
companyLinkedInIdent, companyEmployeeCount, companySpecialities,
companyDescription, companyCrunchBaseUrl, and companyJsonLocation. A missing
companyEmployeeCount is omitted. Also profileUrn, isOpenLink, jsonGeoLocation,
and campaignListId. Blank text is omitted. isOpenLink is present when false
and can be absent. A missing campaignListId is omitted. There is no totalCount.
GET /v1/contacts replaces scoring/scores.
accountPlay {status, accountId, accountName, accountStage} is set when account-play
protection touches the contact in its campaign: status skipped (held before the
first step), stopped (sequence stopped for good) or would_skip (shadow, sending
unchanged). The account fields are omitted when no active account matches now.
accountPlay is omitted for a caller without Accounts View.
securityGateway and mailboxProvider {status, slug?, name?} judge the first Safe or
Verified email (sends go there): gateway detected / none / pending, mailbox host
detected / unknown / pending (slugs like proofpoint, google_workspace). Omitted
unless the workspace has security gateways.
outreachLanguage is the locale Ken writes in (fr-FR), omitted until resolved;
also outreachFormality (formal, informal), outreachLanguageSource (manual, reply,
declared, country, hq, default), outreachLanguageConfidence (0 to 1) and
outreachLanguageLocked (true when a person set it).
dataFlags (this read only; the list, search and update leave it out) is an object
of flags about the contact's data by flag name, as stored: previousEmployerEmail
(a found work email is on a previous employer's domain) or jobChange (the person
moved to a new company), each with currentCompanyDomain and detectedAt. Other
names can appear later. {} when there are none.
personalEmails (this read only) is [{email, source, foundAt}], newest first:
personal addresses a data provider (source, such as loopster) found for the
person. They are for the person reading the contact, never for sending: Kenso
does not send to, verify or export them, so never use one as a send address or
copy it into a contact's email: an update that sets email to one of the
contact's personal emails is refused with a 400 validation_failed and changes
nothing. [] when there are none.
linkedInWait (this read only) is {reason, message, linkedinAccountId,
pendingInvites, pendingInviteCap} when the contact's LinkedIn connection request
cannot go out yet, and omitted otherwise. reason pending_invite_cap: every LinkedIn
account that can send it has reached the sent invites not yet accepted Kenso lets
one keep open; message is ready to show. linkedinAccountId and pendingInvites are
null when the contact is not tied to one of several accounts at the cap.

companies-list

Read. GET https://api.ken.so/v1/companies

Query: cursor string, domain string, limit integer, q string

List companies in the current workspace. Ordered by id. q matches the name. domain is an exact match.

GET /api/v1/companies. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id. q is at most 200 characters.
Requires Campaigns view. Each row has id, name, domain, linkedInUrl, industry,
employeeCount, location, createdAt, and updatedAt.

contact-fields-list

Read. GET https://api.ken.so/v1/contact-fields

Query: cursor string, limit integer

List the contact field catalog. Keys are camelCase. qualityReasoning sits beside qualityScore. Requires Campaigns view.

GET /api/v1/contact-fields. Public. Sends Ken-Version 1.1.
Replaces the leads column, CSV export, and CSV import catalogs.
usages is list, export, and/or import. limit is 1 to 200. Omit it for 50.

list

Read. GET https://api.ken.so/v1/contacts

Query: campaignId integer, companyId integer, createdAfter date-time, createdBefore date-time, cursor string, doNotContact boolean, email string, isQualified boolean, limit integer, q string, segmentId integer

List contacts in the current workspace. Ordered by id. Filters match one campaign, company, segment, email, or name.

GET /api/v1/contacts. Public. Sends Ken-Version 1.1.

client_id is the workspace, sent as X-Ken-Workspace-Id. created_before must
be later than created_after. q matches the name. Contacts include qualityScore
and qualityReasoning, plus profileImage, qualificationResponse,
segmentationReasoning, experiencesJson, customVariables, emailsSent, clicks,
replies, unsubscribes, bounces, and positiveReplies.
LinkedIn activity: connectionRequestsSent and linkedInMessagesSent (messages and
InMails) count confirmed sends; connectionsAccepted and linkedInReplies count the
contact's LinkedIn lanes that were accepted or replied. All four are omitted for a
contact with no LinkedIn lane and no confirmed LinkedIn send.
companyEmailName is the
email-ready company name (for example "Pally" for "Pally (YC S25)"). Use it in
copy. companyName stays the raw name. Stored profile and company
values are headline, location, companyLogo, companyDomain, companySize,
companyType, companyFoundedYear, headquartersCity, headquartersState,
headquartersCountry, seniorityLevel, function, yearsOfExperience, languages,
phoneNumber, summary, skills, and education. segmentName is the catalog name
for the leads column campaign_segment_name. companySize is the stored
employee-count range. emailValidity is the snake_case verdict on the first
Safe or Verified email. Personalization responses are personalization1 through
personalization20, written as sibling fields. linkedInUrlNameMismatch,
emailEnrichmentProviders, and missingRequiredVariableKeys are computed, not
stored columns. Blank text, placeholder logos, an empty provider list, and an
empty missing-key list are omitted. profileImage is omitted for a blank, a
LinkedIn placeholder, or an expired signed URL. Blank qualification or
segmentation text, an empty customVariables map, and missing stats are omitted.
customVariables keeps registered campaign keys that have a value.
experiencesJson is the work-history JSON. linkedInSendBlockedReason, when set, says the contact's LinkedIn sequence is held: "missing_required_variables: <names>" lists the {{name}} tokens in a LinkedIn step that nothing fills (no campaign variable, no {{name|text}} fallback, no AI variable fallback). Fix the step's text or add a fallback; a held contact is not restarted by the fix. Also city, state, country,
countryIso2, isDecisionMaker, companyIndustry, companyLocation,
companyTechnologies, and phoneNumberValidity. phoneNumberValidity is the
snake_case verdict and is omitted when the phone is blank. isDecisionMaker
stays present when false. Blank text is omitted. Last-job, employment, and
company profile columns are lastJobTitle, lastJobDescription, employmentType,
employmentLocation, companyLinkedInUrl, companyLinkedInIdent,
companyEmployeeCount, companySpecialities, companyDescription,
companyCrunchBaseUrl, and companyJsonLocation. A missing companyEmployeeCount
is omitted. Also profileUrn, isOpenLink, jsonGeoLocation, and campaignListId.
Blank text is omitted. isOpenLink is present when false and can be absent.
A missing campaignListId is omitted. There is no totalCount.
accountPlay {status, accountId, accountName, accountStage} is set when account-play
protection touches the contact in its campaign: status skipped (held before the
first step), stopped (sequence stopped for good) or would_skip (shadow, sending
unchanged). The account fields are omitted when no active account matches now.
accountPlay is omitted for a caller without Accounts View.
securityGateway and mailboxProvider {status, slug?, name?} judge the first Safe or
Verified email (sends go there): gateway detected / none / pending, mailbox host
detected / unknown / pending (slugs like proofpoint, google_workspace). Omitted
unless the workspace has security gateways.
outreachLanguage is the locale Ken writes in (fr-FR), omitted until resolved;
also outreachFormality (formal, informal), outreachLanguageSource (manual, reply,
declared, country, hq, default), outreachLanguageConfidence (0 to 1) and
outreachLanguageLocked (true when a person set it).

saved-list-members-list

Read. GET https://api.ken.so/v1/saved-list-members

Query: cursor string, limit integer, q string

Find people and companies by name, title or company across the workspace's saved lists. Searches its own lists and lists shared with it, never the library. Never emails or phones.

GET /api/v1/saved-list-members. Public. Sends Ken-Version 1.1. Needs the saved_lists
feature. Requires the Search page (view).

q (required, 2-200 characters) matches a part of a member's full name, title or company
name, any case. Searched lists: the workspace's own (a private list only for its owner)
and lists shared with it through an accepted invite; never library lists (read one with
saved_lists(operation="list-members", saved_list_id=..., q=...)). Opted-out members
never show. Hits come ordered by list id, then member id; limit 1-100 (default 50);
cursor is the previous page's nextCursor. There is no total. Each request examines up to
50,000 members per list owner, so with a rare q over large lists a page can hold fewer
than limit hits, even none, with pagination.hasMore true: keep paging with nextCursor
before saying nothing matched.
A hit is a member as saved_lists list-members returns it (id, identityKey, firstName,
lastName, title, seniority, companyName, companyDomain, industry, headcountBand,
country, state, city, linkedinUrl, hasSendableEmail, emailCount, phoneCount, sources,
custom) plus savedListId, savedListName and savedListKind (people or companies). A
person on two lists is two hits, one per list, each with that list's member id. Each hit
returned counts one row of the workspace's apiReadRows quota; past it, quota_exceeded.

Example: contacts(operation="saved-list-members-list", q="head of sales")

list-website-pages

Read. GET https://api.ken.so/v1/contacts/{contactId}/website-pages

Path: contactId

List every scraped page of the contact's company website, as markdown, with its scrape date. Markdown is capped per page (default 2000 chars) and at 100000 chars per call.

GET /api/v1/contacts/{contactId}/website-pages. Public. Sends Ken-Version 1.1.
A missing or cross-workspace id is not_found. One row per distinct page,
newest copy kept, at most 50 rows, never paged (pagination.hasMore is
false). Ordered home, about, pricing, products, customer pages
(case_studies, testimonials, reviews), careers, then the rest. Each row has
pageType (snake_case, or other), url and title (omitted when unknown),
markdown, scrapedAt (ISO 8601 UTC), and source: archive (Common Crawl copy;
scrapedAt is the capture date), live (scraped by Kenso), or imported (CSV
upload; scrapedAt is the upload time). A contact without a company returns
an empty list.

The API stores up to 20000 chars per page. To keep the response inside an
agent's context window, this tool cuts each page's markdown at
max_markdown_chars (1..20000, default 2000) and stops adding markdown once
the call has returned 100000 chars. A cut row gets truncated: true; rows
past the budget come back with empty markdown. Raise max_markdown_chars
and filter with page_types to read one page in full.

Args:
    contact_id: Contact id in the current workspace.
    include_markdown: False drops markdown and returns page metadata only.
    max_markdown_chars: Per-page markdown cap, 1..20000. Default 2000.
    page_types: Keep only these page types (for example ["home", "pricing"]).

Read. POST https://api.ken.so/v1/contacts/search

Body (json): awaitingFirstEmail boolean, campaignIds array, companyId integer, contactIds array, createdAfter date-time, createdBefore date-time, cursor string, direction string, doNotContact boolean, email string, filters array, isQualified boolean, limit integer, mailboxProvider array, q string, readyOnly boolean, securityGateway array, segmentId integer, sort string

Search contacts in the current workspace, in any sort order. Same filters as the list, plus filters, ready_only, awaiting_first_email, contact_ids, security_gateway and mailbox_provider. Who clicked a campaign's links, most first: campaign_ids=[id], sort="totalClicks", direction="desc".

POST /api/v1/contacts/search. Public. Sends Ken-Version 1.1.
campaign_ids accepts at most 50 ids. filters, readyOnly, and contactIds
are accepted. filters are lead filter groups, at most 20, each
{operator, conditions: {field, operator, value, dataType}, children}: a group
operator is and or or; a condition operator is equals, not_equals, contains,
not_contains, starts_with, ends_with, greater_than, greater_than_or_equal,
less_than, less_than_or_equal, between, in, not_in, is_null or is_not_null;
dataType is string, number, boolean, date_time, guid or enum. Each also takes
its integer, counting from 0 in the order listed. readyOnly requires
exactly one campaign id. awaiting_first_email (awaitingFirstEmail) keeps only the
campaign's ready leads still waiting for their first email, the leads its
readyLeadCount counts (narrower than readyOnly, which also keeps leads already
emailed); it also requires exactly one campaign id.
contactIds accepts at most 1000 ids. Ordered by id
unless sort is set. There is no totalCount.
sort is one of name, email, company, title, location, leadQualityScore,
emailsSent, totalClicks (link clicks, the contact's clicks), replies,
unsubscribes, bounces and yearsOfExperience; direction is asc (default) or
desc and needs sort. Keep the same sort while you page with cursor.
A contact's own clicks, opens and replies one by one, with their times:
contacts(operation="events", contact_id=..., event_type="email_clicked").
security_gateway (gateway slugs, none, pending) and mailbox_provider (host slugs,
unknown, pending) keep contacts whose email matches one value, at most 100 each;
both must match. A campaign's slugs: analytics_campaign(operation="get-mail-providers").
Without security gateways on the workspace the search is a 400.
filters may use field behaviorTag with in, not_in, equals or not_equals and behavior tags
as values (for example cold_responder, prefers_linkedin, best_window:weekday_morning,
objection:timing): contacts whose workspace behavior tags (and, with
behavior_signals_network, network tags) include any; NotIn and NotEquals keep the rest.
Without the behavior_signals feature the search is a 400. email_confirmed,
email_dead_end and left_company describe one address, so they cannot be filtered:
read them on the contact's behavior. Exports and bulk actions refuse behaviorTag.
Contacts include qualityScore and qualityReasoning, plus profileImage,
qualificationResponse, segmentationReasoning, experiencesJson, customVariables,
emailsSent, clicks, replies, unsubscribes, bounces, and positiveReplies.
LinkedIn activity: connectionRequestsSent and linkedInMessagesSent (messages and
InMails) count confirmed sends; connectionsAccepted and linkedInReplies count the
contact's LinkedIn lanes that were accepted or replied. All four are omitted for a
contact with no LinkedIn lane and no confirmed LinkedIn send.
companyEmailName is the email-ready company name (for example "Pally" for
"Pally (YC S25)"). Use it in copy. companyName stays the raw name.
Stored profile and company values are headline, location, companyLogo,
companyDomain, companySize, companyType, companyFoundedYear, headquartersCity,
headquartersState, headquartersCountry, seniorityLevel, function,
yearsOfExperience, languages, phoneNumber, summary, skills, and education.
segmentName is the catalog name for the leads column campaign_segment_name.
companySize is the stored employee-count range. emailValidity is the snake_case
verdict on the first Safe or Verified email. Personalization responses are
personalization1 through personalization20, written as sibling fields.
linkedInUrlNameMismatch, emailEnrichmentProviders, and missingRequiredVariableKeys
are computed, not stored columns. Blank text, placeholder logos, an empty
provider list, and an empty missing-key list are omitted. profileImage is
omitted for a blank, a LinkedIn placeholder, or an expired signed URL. Blank
qualification or segmentation text, an empty customVariables map, and missing
stats are omitted. customVariables keeps registered campaign keys that have a
value. experiencesJson is the work-history JSON. linkedInSendBlockedReason, when set, says the contact's LinkedIn sequence is held: "missing_required_variables: <names>" lists the {{name}} tokens in a LinkedIn step that nothing fills (no campaign variable, no {{name|text}} fallback, no AI variable fallback). Fix the step's text or add a fallback; a held contact is not restarted by the fix. Also city, state, country,
countryIso2, isDecisionMaker, companyIndustry, companyLocation,
companyTechnologies, and phoneNumberValidity. phoneNumberValidity is the
snake_case verdict and is omitted when the phone is blank. isDecisionMaker
stays present when false. Blank text is omitted. Last-job, employment, and
company profile columns are lastJobTitle, lastJobDescription, employmentType,
employmentLocation, companyLinkedInUrl, companyLinkedInIdent,
companyEmployeeCount, companySpecialities, companyDescription,
companyCrunchBaseUrl, and companyJsonLocation. A missing companyEmployeeCount
is omitted. Also profileUrn, isOpenLink, jsonGeoLocation, and campaignListId.
Blank text is omitted. isOpenLink is present when false and can be absent.
A missing campaignListId is omitted.
accountPlay {status, accountId, accountName, accountStage} is set when account-play
protection touches the contact in its campaign: status skipped (held before the
first step), stopped (sequence stopped for good) or would_skip (shadow, sending
unchanged). The account fields are omitted when no active account matches now.
accountPlay is omitted for a caller without Accounts View.
securityGateway and mailboxProvider {status, slug?, name?} judge the first Safe or
Verified email (sends go there): gateway detected / none / pending, mailbox host
detected / unknown / pending (slugs like proofpoint, google_workspace). Omitted
unless the workspace has security gateways.
outreachLanguage is the locale Ken writes in (fr-FR), omitted until resolved;
also outreachFormality (formal, informal), outreachLanguageSource (manual, reply,
declared, country, hq, default), outreachLanguageConfidence (0 to 1) and
outreachLanguageLocked (true when a person set it).

update

Write. PATCH https://api.ken.so/v1/contacts/{contactId}

Path: contactId

Update fields on one contact. Absent fields stay unchanged. Null clears a string. is_qualified and do_not_contact cannot be null. custom_variables merges: a string sets a key, null or "" removes it.

PATCH /api/v1/contacts/{contactId}. Public. Sends Ken-Version 1.1.

Requires Campaigns edit. Fields: first_name, last_name, title, linked_in_url,
location, email, is_qualified, do_not_contact, outreach_language,
custom_variables, custom_image_url, custom_video.

is_qualified is a verdict set by hand, and it stands: true or false, AI
qualification never decides the contact again until an AI flow reset. Send
it only to set the verdict, never to echo the value the contact already has.

custom_variables (customVariables) is an object of key -> string, number,
boolean or null, e.g. {"rd_link": "https://...", "old_note": null}. A number
or boolean is sent as text: true as "true", 1.0 as "1", 1.5 as "1.5"; a list
or object is refused before the call. It merges into the
contact's custom variables with the campaign lead upsert's rules: a string
sets the key, null or "" removes it, keys you do not send stay. Keys are
normalized to snake_case, reserved lead fields are refused, long values are
cut, and a new key joins the campaign's custom-variable catalog (at most 50
per campaign). The object itself cannot be null.

outreach_language is the locale Ken writes to the contact in: a locale whose
language has a market pack or a country entry (fr-FR, es-MX, de-AT, or a bare
code like fr). It is stored with source manual, confidence 1 and locked, so no
import, enrichment or reply replaces it. Null clears and unlocks it. Any other
value is a 400 validation_failed on outreachLanguage.

email cannot be one of the contact's personalEmails (the contact read lists
them): Kenso never sends to those, so it is a 400 validation_failed and nothing
changes.

custom_image_url is the https URL of the lead's own image, shown in emails as
{{custom_image}}. Kenso downloads and hosts it. An empty string or null clears
it. Needs campaign images on the workspace; otherwise a 400 validation_failed.

custom_video is the lead's own video: a share link or embed code from Loom,
YouTube, Vimeo, Wistia, Vidyard, Sendspark or HeyGen, at most 20,480
characters. Kenso shows it in emails as {{custom_video}}, a thumbnail that
links to the video's page. An empty string or null clears it. Needs campaign
videos on the workspace and a contact in a campaign; an unsupported or
invalid link, a contact with no campaign, or videos off is a 400
validation_failed. A video a sent or queued step already uses cannot change:
409 video_in_use, and the old video stays. Another change to the same video
at the same moment is a 409 conflict; retry it. The contact read returns
customVideo (status, provider, source, watchUrl, previewUrl,
previewExpiresAt, error) when the lead has one and videos are on.

export_contacts

Write.

Export campaign contacts to various formats and platforms.

Export campaign contacts to various formats and platforms.

Scope: campaign-scoped. Operates on contacts that belong to one Kenso
campaign (campaign_id). Filter vocabulary: outreach_id + qualified for CSV
exports. There is no search-index CSV export tool; import people into a
campaign with saved_searches(operation="import_to_campaign"), then export via this tool. For
raw SQL exports use
db(operation="create"). To IMPORT search results into a campaign
use saved_searches(operation="import_to_campaign") (no alias).

Returns: dict with success/data envelope. CSV variants populate
data.fileUrl/fileName/recordCount and add outreach_id_used (and warning
when outreach_id was omitted). The Instantly push (Kenso staff only)
populates platform-specific fields like exportId. See "Returns" section
below for the full shape.

Export contacts from campaigns to CSV files. Kenso staff can also push
them to Kenso's own Instantly account (export_type="instantly").

Synchronous - no polling required
---------------------------------
All ``export_contacts`` export types are synchronous from the caller's
perspective. The response carries the final result inline (the CSV text
or ZIP base64 for CSV exports, or platform integration acknowledgements for
instantly). There is no companion status operation because the Kenso
export endpoints do not expose async job IDs to MCP callers - the returned
``data.fileContent`` (or ``data.contentBase64``) is the final file. Use
``saved_searches(operation="export_status")`` for the Kenso Search async
import pipeline and ``db(operation="status")`` for the MCP DB
export queue; both share the canonical polling envelope documented in
``ken_mcp.utils.polling_envelope``.

Return shape (IMPORTANT - reflects backend reality)
---------------------------------------------------
CSV exports (csv, csv_custom, csv_advanced, csv_clicked) return the
backend's file, which the tool returns as:

    {
      "success": True,
      "data": {
        "fileContent": str,        # the CSV text (UTF-8)
        "fileName": str,           # e.g. "contacts_export_20260101_120000.csv"
        "contentType": "text/csv",
        "size": int,
      },
      # CSV-only debug fields:
      "outreach_id_used": int | None,
      "warning": str (only when outreach_id was omitted),
    }

Multi-segment campaigns return a ZIP archive (one CSV per segment) with
Content-Type ``application/zip``. data then holds ``contentBase64``, the
ZIP's bytes in base64, instead of fileContent. A ZIP over 2 MiB
(2,097,152 bytes) is refused with a validation error: narrow the export
with limit/offset, or download it in the Kenso app. The backend does NOT
return a hosted ``fileUrl`` - callers must persist the file themselves.

Instantly integration returns the gateway's JSON envelope from the
backend, typically
``{"success": True, "data": {...command result...}}`` where the command
result is platform-specific (e.g. exported lead count).

get_fields returns ``{"success": True, "data": {"allFields": [...],
"defaultFields": [...], "fieldDescriptions": {...}}}``.

IMPORTANT - Outreach Status Filtering
-------------------------------------
The ``outreach_id`` parameter filters contacts by which Outreach Status
rows they have. Without it, exports may be empty or include contacts
that haven't completed the expected workflow steps. NOTE: Outreach Status
IDs (the values used here) are NOT the same as AI Workflow IDs in
CLAUDE.md (1=Qualification, 2=Personalization, etc.). See the
``Outreach Status IDs`` section below for the values this parameter
accepts.

Export Types
------------
csv:
    Streamed CSV download via POST /api/v1/export/csv. Multi-segment
    campaigns return a ZIP archive. Backend type ``CsvExportOptions``
    accepts: campaignId, qualified, includeEmails, includeCompany,
    outreachId, limit, offset.
    Example: export_type="csv", campaign_id=123, outreach_id=12

csv_custom:
    POST /api/v1/export/csv/custom with field selection. Backend type
    ``CustomCsvExportOptions`` extends CsvExportOptions with
    ``selectedFields`` (a List<string> of snake_case ExportableFields).
    Example: export_type="csv_custom", campaign_id=123,
             selected_fields=["first_name", "last_name", "email", "company_name"]

csv_advanced:
    POST /api/v1/export/csv/advanced. Includes click_events JSON +
    total_clicks columns. Backend type ``AdvancedCsvExportOptions``
    accepts: campaignId, includeEmails, includeCompany,
    includeClickEvents, includeTotalClicks, selectedFields, limit,
    offset. **It does NOT accept qualified, outreachId, or
    campaignSegmentId** - passing those raises KenValidationError so
    callers don't get silently-ignored filters.
    Example: export_type="csv_advanced", campaign_id=123,
             include_click_events=True, include_total_clicks=True

csv_clicked:
    POST /api/v1/export/csv/clicked. Only contacts who clicked at least
    once. Always includes click_events and total_clicks columns. Backend
    type ``ClickedCsvExportOptions`` accepts: campaignId, includeEmails,
    includeCompany, selectedFields, limit, offset. **It does NOT accept
    qualified, outreachId, or campaignSegmentId** - same rejection
    behavior as csv_advanced.
    Example: export_type="csv_clicked", campaign_id=123

instantly (Kenso staff only):
    POST /api/v1/export/instantly/{campaignId}. No body, no query
    params. Returns gateway JSON envelope. It pushes into Kenso's own
    Instantly account, so the route is staff only: a workspace caller
    is refused with a 403 before any call. Use a CSV export_type
    instead.
    Example: export_type="instantly", campaign_id=123

get_fields:
    GET /api/v1/export/csv/fields. Returns the canonical
    ``allFields`` / ``defaultFields`` lists. Use this BEFORE composing
    ``selected_fields`` to avoid stale field names.

Available Fields (snake_case - this is the backend wire format)
---------------------------------------------------------------
Source: Ken.Scraping.Domain/Common/CustomCsvExportOptions.cs::ExportableFields

Identity & contact:
  contact_id, full_name, first_name, last_name, email, email_validity,
  email_provider, title, headline, location, summary, linkedin_url,
  profile_urn

Qualification & history:
  qualified, qualification.response, last_job_title,
  last_job_description, employment_type, employment_location,
  education, skills

Geography & seniority:
  city, state, country, seniority_level, function

Company:
  company_name, company_domain, company_linkedin_url,
  company_industry, company_size, company_location,
  company_description, company_specialities, company_website,
  company_founded_year, company_type, headquarters_city,
  headquarters_state, headquarters_country

AI personalization (mapped from prompts with toOutput=True in order):
  personalization_1, personalization_2, personalization_3

Campaign / segments / clicks:
  segment_name, tracking_links, click_data, total_clicks

NOTE: ``audience_name`` is obsolete - use ``segment_name`` instead.
Tracking link short URLs are surfaced through dynamic ``tracking_link_*``
columns at runtime (one column per redirect link); request the
``tracking_links`` umbrella field to opt in.

Outreach Status IDs (numeric, NOT the AI Workflow IDs from CLAUDE.md)
--------------------------------------------------------------------
Data Sources:
  1 = LinkedIn Sales Navigator (initial scraping)
  2 = LinkedIn Profile (detailed profile scraping)
  10 = Apollo

Email Enrichment:
  3 = Icypeas
  4 = LeadMagic Business Email
  5 = LeadMagic Personal Email
  17 = Enrow
  18 = Kitt
  19 = Prospeo
  28 = Findymail

Email Verification:
  7 = Bulk Email Checker
  8 = Instantly Email Verification

AI workflow pre-processing (queued):
  14 = AI Pre-Qualification (queued for qualification)
  21 = AI Pre-Personalization (queued for personalization)
  22 = AI Pre-Rewriting (queued for rewriting)
  25 = AI Pre-Segmentation (queued for segmentation)

AI workflow completed:
  11 = AI Qualification (completed)
  12 = AI Personalization (completed) - typical for personalized exports
  13 = AI Rewriting (completed) - typical for rewritten exports
  26 = AI Segmentation (completed)

Integration:
  9 = Uploaded to Instantly

These IDs are Outreach Status IDs (the per-contact step ledger). The AI
Workflow IDs in CLAUDE.md (1-5) reference the *workflow definition*, not
the contact-step status, and the two ID spaces are intentionally
distinct.

Parameters
----------
client : KenAPIClient
    Injected per-request API client.
export_type : str
    Export variant - see Export Types above.
campaign_id : int, optional
    Required for every export_type except ``get_fields``.
include_emails : bool, default=True
    Forwarded as ``includeEmails`` to csv, csv_custom, csv_advanced,
    csv_clicked. Ignored elsewhere.
include_phones : bool, optional (DEPRECATED, no-op)
    Retained only for backward compatibility with older callers. The
    backend ``CsvExportOptions`` family has no IncludePhones property
    and no phone column in the export, so any value here is silently
    dropped. New callers should omit this argument.
include_company : bool, default=True
    Forwarded as ``includeCompany`` to csv, csv_custom, csv_advanced,
    csv_clicked. Ignored elsewhere.
outreach_id : int, optional
    Outreach Status ID (see above). Forwarded only to ``csv`` and
    ``csv_custom`` because the underlying ``CsvExportOptions`` is the
    only options class that exposes it. Passing it with csv_advanced
    or csv_clicked raises KenValidationError.
qualified : bool, optional
    ``CsvExportOptions.Qualified`` filter. Forwarded only to ``csv`` and
    ``csv_custom``. Passing it with csv_advanced or csv_clicked raises
    KenValidationError because those backend option classes have no
    Qualified property.
limit : int, optional
    Forwarded for csv, csv_custom, csv_advanced, csv_clicked.
    Validated against [1, 100000] when provided.
offset : int, optional
    Forwarded for csv, csv_custom, csv_advanced, csv_clicked.
    Validated as ``>= 0`` when provided.
selected_fields : list[str], optional
    Snake_case ExportableFields names mapped to the backend
    ``selectedFields`` payload key. REQUIRED for csv_custom. Optional
    for csv_advanced and csv_clicked. Ignored for csv (the basic export
    uses the default field set) and for instantly. NOTE: this is purely
    a CSV column selector - it has no relation to a campaign/contact
    custom-field entity (none exists in the backend).
include_click_events, include_total_clicks : bool, default=True
    csv_advanced only. Toggle the ``click_events`` and ``total_clicks``
    columns.

Examples
--------
Export personalized contacts to CSV:
    >>> await export_contacts(
    ...     export_type="csv",
    ...     campaign_id=123,
    ...     outreach_id=12,           # AI Personalization complete
    ...     include_emails=True,
    ...     include_company=True,
    ... )

Export only qualified contacts:
    >>> await export_contacts(
    ...     export_type="csv",
    ...     campaign_id=123,
    ...     outreach_id=11,           # AI Qualification complete
    ...     qualified=True,
    ... )

Export a custom column selection:
    >>> await export_contacts(
    ...     export_type="csv_custom",
    ...     campaign_id=123,
    ...     selected_fields=[
    ...         "first_name", "last_name", "email",
    ...         "company_name", "title", "personalization_1",
    ...     ],
    ... )

Get available fields BEFORE building selected_fields:
    >>> await export_contacts(export_type="get_fields")

Raises
------
KenValidationError
    Local validation: missing campaign_id, unsupported parameter
    combinations (e.g. qualified/outreach_id with csv_advanced/csv_clicked),
    or out-of-range limit/offset.
KenNotFoundError
    Backend returned 404 - the campaign id does not exist (or has been
    deleted). The endpoint surfaces "Campaign not found" in this case.
KenAuthError
    Backend returned 403 - the campaign exists but is not owned by the
    authenticated client (cross-tenant access is rejected server-side).
    Also raised locally (403, no call) for export_type="instantly" from
    a caller that is not Kenso staff.
KenAPIError
    Other 4xx/5xx responses from the gateway, including upstream
    Instantly failures for the integration export type.