Integrations integrations
Every integration Kenso shows (CRMs, mailboxes, LinkedIn, enrichment, AI clients): whether it is live, your connection and its on/off options. Connect and disconnect with each integration's own tool. Also Google Ads and Meta Ads audiences synced from a campaign's leads (ad-audiences-*, ad-connections-*), and recruiting ATS connections, job imports and candidate pushes (ats-*).
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through integrations_read and changes through integrations_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: ats-jobs-bulk-import, ad-audiences-create, ats-pushes-create, ad-audiences-delete, get, provider-key-savings-get, contact-exports-google-sheet, ad-audiences-list, ad-connections-list, airtable-bases-list, airtable-records-list, airtable-tables-list, ats-connections-list, ats-jobs-list, list, ad-connections-list-ad-accounts, google-sheets-preview, ats-connections-test, ad-audiences-update, update
ats-jobs-bulk-import
Write. Early access: needs recruiting on for the workspace. POST https://api.ken.so/v1/ats/connections/{atsConnectionId}/jobs/bulk-import
Path: atsConnectionId
Body (json): jobIds array
Import 1 to 25 ATS jobs as Kenso roles, each linked to its job. A job already linked returns its role unchanged.
POST /api/v1/ats/connections/{atsConnectionId}/jobs/bulk-import.
Staff, or a workspace with the recruiting flag. Sends Ken-Version 1.1. Requires campaigns edit.
job_ids: ids from integrations(operation="ats-jobs-list"); duplicates are sent once.
Returns data {succeeded [{jobId, roleId, created}], failed [{jobId, error {code,
message}}]}. One job's failure never stops the others. created false: a role was
already linked to that job and nothing changed. Work with the roles in the roles tool.
ad-audiences-create
Write. Early access: needs ad_audiences on for the workspace. POST https://api.ken.so/v1/ad-audiences
Body (json): adConnectionId integer, audienceKind string, campaignId integer, enhancedMatching boolean, firstPartyAttested boolean, holdoutPercent integer, name string, sourceType string, tier integer
Create an ad audience from a campaign's leads, or an account tier's committees or companies, on an ad platform. Returns 201, pending. The next sync uploads hashed emails to the ad account (unsubscribed, blocklisted, bounced and, by default, EU, UK and Swiss contacts left out). Google Ads needs first_party_attested, confirmed by the user.
POST /api/v1/ad-audiences.
Staff, or a workspace with the ad_audiences flag. Sends Ken-Version 1.1. Requires the integrations
permission (workspace admins).
ad_connection_id: a connected connection with an ad account picked (see
integrations(operation="ad-connections-list")).
source_type: campaign (default) or account_tier.
campaign_id: required for campaign, a campaign of the workspace.
tier: required for account_tier, 1 to the workspace's tier count (5 by default). The members
are the committee contacts (people on the account's buying committee who have a contact
row) of the accounts the workspace works at that tier while their stage is researching,
warming, engaged or nurture. An account that books a meeting, is paused, lost or not a
fit, or moves to another tier leaves on the next sync. A tier with no accounts syncs nobody.
name: at most 200 characters, default "Ken - {campaign name}", or for a tier "Ken - {tier name}"
when the workspace named its tiers, else "Ken - Tier {n} accounts".
first_party_attested: required true on a Google Ads connection, which accepts only
contacts the workspace collected first-party (its own customers, sign-ups or inbound
leads). Send true only when the user explicitly confirms the campaign's contacts are
first-party; never on your own. Without it Google Ads answers 400 first_party_required
(offer Meta or LinkedIn instead). Meta and LinkedIn do not need it.
holdout_percent: 0 to 50, default 10. That share of the contacts, picked at random by
address and the same on every sync and in every audience, never goes to the platform, so ad-audiences-lift can
compare their reply rates with the synced contacts'. 0 uploads everyone and shows no lift.
enhanced_matching: default false. true also uploads the hashed personal emails (up to 3 per
contact) and, on Meta, phone numbers that Kenso's licensed people dataset holds for the
contacts, so the platform matches more of them. Meta and LinkedIn campaign audiences only:
400 validation_failed on Google Ads or an account tier. Nothing extra goes up until Kenso turns
the feature on for the platform and the workspace.
audience_kind: contact (default) or company: the tier's accounts as a LinkedIn company list
(name, domain, company page; no personal data). Needs LinkedIn Ads and account_tier, else 400
company_audience_unsupported. Blocklisted domains stay out. Holdout by account, 0 by default; no lift.
The audience starts pending: no call goes to the platform now. The sync job creates it
in the ad account and uploads the members on its next pass (every 6 hours), then keeps
it in step with the source: new contacts go in, unsubscribed or bounced ones come out.
Nothing is created or added until an admin attests the platform's terms on the
connection (syncBlockedReason terms_not_attested, see crm(operation="ad-connections-update")).
409 reconnect_required (reconnect in the Kenso app), 409 account_required (pick the ad
account in the Kenso app), 409 audience_exists (the campaign or tier already has an
audience on this connection). Returns data, the audience (see list).
ats-pushes-create
Write. Early access: needs recruiting on for the workspace. POST https://api.ken.so/v1/ats/pushes
Body (json): candidateId integer
Send one role candidate to the role's ATS now, with the whole conversation attached as a note.
POST /api/v1/ats/pushes.
Staff, or a workspace with the recruiting flag. Sends Ken-Version 1.1. Requires campaigns edit.
candidate_id: a role candidate id (from the roles tool). Ken finds the person in the ATS
by email, else LinkedIn URL, or creates them with source "Ken", then creates their
application on the role's ATS job. Returns data {candidateId, atsCandidateId,
atsApplicationId, pushedAt}. 409 ats_not_linked (the role has no ATS job: import or
link one first), 409 reconnect_required, 409 ats_rejected (the ATS refused, for example
a person with neither email nor LinkedIn URL), 409 ats_push_in_progress (another push of
this candidate is running: try again in a minute), 503 provider_unavailable.
ad-audiences-delete
Write. Early access: needs ad_audiences on for the workspace. DELETE https://api.ken.so/v1/ad-audiences/{adAudienceId}
Path: adAudienceId
Delete an ad audience. Kenso stops syncing it at once; the response says whether the ad account's copy goes too. Cannot be undone; create a new audience to sync the campaign again.
DELETE /api/v1/ad-audiences/{adAudienceId}.
Staff, or a workspace with the ad_audiences flag. Sends Ken-Version 1.1. Requires
the integrations permission.
Returns data {id, status (deleted), deletesPlatformAudience, message}.
deletesPlatformAudience is true when the next sync pass deletes the audience in the ad
account too (it was created there and the connection is still connected); otherwise it
stays in the ad account and message says so.
get
Read. GET https://api.ken.so/v1/integrations/{integrationKey}
Path: integrationKey
Get one integration: whether it is live, your connection and its option switches.
GET /api/v1/integrations/{integrationKey}. Internal. Sends Ken-Version
1.1 and X-Ken-Workspace-Id. Needs the integrations_catalog feature (404
when off). Any workspace member.
integration_key: a catalog key from integrations(operation="list"), such
as gmail, hubspot or api-keys (case-insensitive). An unknown key is 404.
Returns one entry with the fields described under list.
provider-key-savings-get
Read. GET https://api.ken.so/v1/provider-keys/savings
What the workspace's own keys did this billing month: emails each email-finder key found (and the credits that saved), and the calls, tokens and estimated cost each AI key ran.
GET /api/v1/provider-keys/savings. Internal. Sends Ken-Version 1.1 and
X-Ken-Workspace-Id. Needs the integrations feature (Admin). Read only;
it returns no key material.
Counts, per live email finder (prospeo, findymail, leadmagic), the emails
the workspace's own key found, one per contact, in the current billing
month (since signup on the Free plan). Each would have cost 1 credit
($0.02) on Kenso's keys. Read from the provider call log: an email counts
when the provider returned it, whether or not it later verified.
AI keys (DEV-5284): per AI provider (anthropic, openai, openrouter,
vercel, typesafe, xai, deepseek), the calls the workspace's own key ran in the same
period, failed ones included, their input and output tokens, and their
estimated cost in USD at list prices. The provider bills the workspace
directly, so the cost is an estimate, never a bill and never Kenso credits.
Read from Kenso's AI call ledger, which starts on 2026-10-23.
Response: period (billing_month, or since_signup on Free), from
(inclusive), to (exclusive), providers: one entry per finder that found
at least one email, in catalogue order, with provider (as on the
provider key list), emailsFoundCount, millicredits, amount {amount (USD
cents), currency}. Empty when no workspace key found anything.
ai: one entry per AI provider whose key ran at least one call, in
catalogue order, with provider, calls, inputTokens, outputTokens,
cacheReadTokens, cacheWriteTokens and estimatedCostUsd (omitted when no
call could be priced). Tokens are as the provider reported them:
OpenAI-style providers count cache reads inside inputTokens, Anthropic
reports them only in cacheReadTokens. Empty when no AI key ran anything;
ai itself is omitted when Kenso's AI call ledger could not be read (the
email savings still return), which means unavailable, not no usage.
display (added by this tool): one line per provider, e.g.
"prospeo key: 412 emails found, saved 412 credits ($8.24)" and
"anthropic key: 1,204 AI calls, 3,200,000 input and 410,000 output
tokens, about $4.12".
Errors:
- 503: BYOK is off for the workspace (Byok:Enabled false or not
allowlisted). The tool returns a generic try-again-later error.
- 400 workspace_required: pass client_id.
- 404 not_found: the caller is not a member of that workspace.
contact-exports-google-sheet
Write. POST https://api.ken.so/v1/contact-exports/{exportId}/google-sheet
Path: exportId
Write a contact export 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/contact-exports/{exportId}/google-sheet. Internal. Sends Ken-Version 1.1.
Writes the rows contacts(operation="content") would download to a new
spreadsheet named "Kenso export - <campaign name or Contacts> - <yyyy-MM-dd>",
with the caller's own Kenso Workspace Google connection. Cells are text,
never formulas, and a cell that starts like a formula keeps a leading
apostrophe, as in the CSV download (numbers and phone numbers such as
+15551234567 do not). data holds spreadsheetId, spreadsheetUrl and
rowCount. Requires export access and the google_sheets feature (404 while
it is off). A campaign export that is one file per segment is 409
invalid_state: export one segment at a time. Google refusing to create or
write the sheet in the member's Drive is 409 invalid_state too. No Google
connection is 409 reconnect_required; Google failing or rate-limiting is
503 provider_unavailable. Counts against the same export row limits as the
download.
ad-audiences-list
Read. Early access: needs ad_audiences on for the workspace. GET https://api.ken.so/v1/ad-audiences
List the workspace's ad audiences (campaign, workflow or account-tier sources synced to the ad platforms), newest first. Shows each audience's status, member count, matched size against the platform's minimum ("too small to run ads yet"), last sync and last error.
GET /api/v1/ad-audiences.
Staff, or a workspace with the ad_audiences flag. Sends Ken-Version 1.1. Requires accounts view.
404 while the ad_audiences flag is off.
Returns data [{id, adConnectionId, provider, sourceType, audienceKind, campaignId, workflowId,
tier, name, status, memberCount, lastSyncedAt, externalAudienceId, lastError, lastErrorAt,
firstPartyAttestedAt, regionExcludedCount, syncBlockedReason, holdoutPercent, createdAt,
matchedSize, matchedSizeAt, platformMinimum, tooSmall, enhancedMatching, matchedMemberCount}].
sourceType: campaign (a campaign's leads, campaignId set), workflow (the leads a workflow's
ads.add_to_audience step added, workflowId set) or account_tier (a tier's buying
committees, tier set); the other ids are left out. audienceKind: contact or company (a
LinkedIn company list; its counts are companies). holdoutPercent: the share of the
source's contacts (0 to 50, 10 by default) the sync keeps out of the audience at random, so
their reply rates show the ads' lift (see crm(operation="ad-audiences-lift")). status: pending
(not created on the platform yet), active, paused, error (stopped after repeated failures,
Meta's Custom Audience terms are not accepted, or Meta flagged the audience for sensitive
information: lastError says what to do). Deleted audiences are left out.
syncBlockedReason: null, terms_not_attested (an admin has not confirmed the platform's terms
on the connection, see crm(operation="ad-connections-update")) or first_party_not_attested
(a Google Ads audience nobody confirmed as first-party). While it is set the sync adds
nobody; removals still run. regionExcludedCount: contacts in the EU, UK or Switzerland left
out on the last pass. They are left out unless the platform's includeEuUkChContacts
integration option is on (integrations(operation="update")); contacts in the EU, UK and
Switzerland need a legal basis such as consent before you upload them, so turn it on only
if the workspace has one. A contact with no known country is uploaded.
memberCount is the hashed emails Kenso uploaded (companies, for a company audience);
matchedSize is how many people the platform matched (Meta's lower bound, Google's largest
network estimate, LinkedIn's audience size once the segment is ready), read on each
sync pass after the one that created the audience and omitted until the platform
reports one. It is 0 when Meta marks the audience too small without a count, and a
platform's 0 counts only 48 hours after Kenso first uploaded to the audience (matching takes
that long).
platformMinimum is the smallest matched size the platform runs ads to (LinkedIn 300,
Meta 100, Google 100).
tooSmall true means matchedSize is below it: say "too small to run ads yet" (add more
contacts to its source). tooSmall is false while matchedSize is unknown.
enhancedMatching: true when the sync also uploads the hashed personal emails (and on Meta,
phone numbers) Kenso's licensed people dataset holds for the contacts, in workspaces Kenso has
turned that on for. matchedMemberCount, present only then, is how many of memberCount are
those matched hashes.
ad-connections-list
Read. Early access: needs ad_audiences on for the workspace. GET https://api.ken.so/v1/ad-connections
List the workspace's Google Ads and Meta Ads connections, one entry per platform. Shows whether each is connected, its ad account and whether Kenso's app for it is set up.
GET /api/v1/ad-connections. Staff, or a workspace with the ad_audiences flag. Sends Ken-Version 1.1. Requires accounts view. 404 while the ad_audiences flag is off. Returns data, one entry per provider (google_ads, meta_ads, linkedin_ads): id (absent when not connected), provider, available (false when Kenso's app for the platform is not set up), status (connected, needs_reconnect or not_connected), externalAccountId, externalAccountName, loginAccountId (the Google manager account, when access goes through one), connectedAsEmail, connectedAt, tokenExpiresAt, lastError, lastErrorAt, termsAttestedAt and termsAttestedByUserId (when and by whom a workspace admin confirmed the platform's terms; null until then, and the sync adds nobody without it). A connection with no externalAccountId needs its ad account picked in the Kenso app before it can hold audiences. Connecting, picking the account and disconnecting happen in the Kenso app under Integrations; there is no tool for them. Record the terms attestation with crm(operation="ad-connections-update").
airtable-bases-list
Read. GET https://api.ken.so/v1/airtable/bases
List the Airtable bases the workspace's Airtable token can read. Each base has id (app...), name and permissionLevel.
GET /api/v1/airtable/bases. Internal. Sends Ken-Version 1.1. Reads with the workspace's own Airtable personal access token, saved in the Kenso app (Settings > Integrations > Airtable). data lists every base the token reaches: id, name and permissionLevel (none, read, comment, edit, create or interfaceOnly). One page: pagination.hasMore is always false. No saved token, or one Airtable refused, is 409 not_connected. A token without the schema.bases:read scope is 409 scope_required. Airtable failing or rate-limiting the token is 503 provider_unavailable. Needs the airtable feature (404 while it is off).
airtable-records-list
Read. GET https://api.ken.so/v1/airtable/bases/{baseId}/tables/{tableId}/records
Path: baseId, tableId
Query: cursor string, limit integer, view string
List one page of an Airtable table's records, every cell as text. Each record is {id, fields}; fields maps field name to cell text. Page with cursor.
GET /api/v1/airtable/bases/{baseId}/tables/{tableId}/records. Internal.
Sends Ken-Version 1.1.
table_id is a table id (tbl...) or name; view (a view id or name) reads in
that view's order and filter. limit is 1 to 100 (default 100). Pass
pagination.nextCursor as cursor, with the same view, for the next page; a
cursor from another table or view, or one Airtable no longer knows, is 400
validation_failed on cursor: read again from the first page. Cells come back
as the text Airtable shows (dates in UTC, en-us); empty cells are left out.
To import the rows as campaign contacts, call
contacts(operation="contact-imports-create") with source airtable instead:
it reads every page itself, up to 10,000 records. For an Accounts import,
create the accounts from these records with accounts bulk-create, 100 per
call.
A token without data.records:read or access to the base is 409
scope_required; no saved token is 409 not_connected; an unknown view is 400
validation_failed on view. Needs the airtable feature (404 while it is off).
airtable-tables-list
Read. GET https://api.ken.so/v1/airtable/bases/{baseId}/tables
Path: baseId
List the tables of an Airtable base, with their fields and views. base_id is the app... id from integrations(operation="airtable-bases-list").
GET /api/v1/airtable/bases/{baseId}/tables. Internal. Sends Ken-Version 1.1.
data lists every table of base_id: id (tbl...), name, primaryFieldId,
fields (id, name, Airtable type such as singleLineText or email) and views
(id, name). One page: pagination.hasMore is always false.
A malformed base_id is 400 validation_failed. A base the token cannot
reach, or a token without schema.bases:read, is 409 scope_required (Airtable
does not tell the two apart). No saved token is 409 not_connected. Needs the
airtable feature (404 while it is off).
ats-connections-list
Read. Early access: needs recruiting on for the workspace. GET https://api.ken.so/v1/ats/connections
List the workspace's ATS connections (Bullhorn, Ashby, Greenhouse, Lever). Shows whether each is connected, its ATS account and its push, pull and dedupe settings.
GET /api/v1/ats/connections.
Staff, or a workspace with the recruiting flag. Sends Ken-Version 1.1. Requires campaigns and accounts view.
404 while the recruiting flag is off. An ATS whose own flag is off is left out.
Returns data [{id, provider (bullhorn, ashby, greenhouse, lever), authKind (oauth or
api_key), status (connected or needs_reconnect), externalAccountName, connectedAsEmail,
connectedAt, disconnectedAt, lastPullAt, lastError, lastErrorAt, settings {pushStages
(interested and/or screen_booked: the stages that send a candidate to the ATS on their
own), pullEnabled (ATS stage changes come back to Kenso), dedupeEnabled (Kenso asks the ATS
about each contact: an email waits for the answer, up to 6 hours, and a person already in
process for the role is held and their sequence stopped; LinkedIn steps are not held while
an answer is pending), stageMap (ATS stage id or name to a Kenso stage)}}]. needs_reconnect:
reconnect in the Kenso app under Settings > Integrations. Connecting, settings and
disconnecting happen there; there is no tool for them.
ats-jobs-list
Read. Early access: needs recruiting on for the workspace. GET https://api.ken.so/v1/ats/connections/{atsConnectionId}/jobs
Path: atsConnectionId
Query: cursor string, limit integer
List the open jobs of a connected ATS, read live, with the Kenso role already linked to each. Use it to pick jobs to import as Kenso roles.
GET /api/v1/ats/connections/{atsConnectionId}/jobs.
Staff, or a workspace with the recruiting flag. Sends Ken-Version 1.1. Requires campaigns and accounts view.
limit: 1 to 100 (default 25). cursor: pagination.nextCursor of the previous page.
Returns data [{id, title, status, location, department, url, updatedAt, roleId (the Kenso
role linked to this job, or null)}] and pagination {nextCursor, hasMore}.
409 reconnect_required, 503 provider_unavailable.
list
Read. GET https://api.ken.so/v1/integrations
List every integration in the workspace with whether it is live, your connection and its option switches.
GET /api/v1/integrations. Internal. Sends Ken-Version 1.1 and
X-Ken-Workspace-Id. Needs the integrations_catalog feature on the
workspace (404 when it is off). Any workspace member.
Returns the whole catalog in display order (about 100 entries); it is not
paginated (pagination.hasMore is false). Each entry:
- key: stable id such as gmail, outlook, gcal, hubspot, linkedin,
prospeo, slack, api-keys, webhooks.
- name, category (crm, email, linkedin, enrich, signals, meetings,
messaging, automation, models, ai, developer, ads, calling, files,
verify, voice). verify holds the email verifiers that run on the
workspace's own key (zerobounce, neverbounce); voice holds the voice
note providers on the workspace's own key (deepgram, elevenlabs). The
enrich finders on the workspace's own key include apollo, datagma,
snovio, zoominfo, blitz, cognism and fullenrich.
firecrawl (enrich) is the workspace's own Firecrawl key: Kenso's web
scraping, crawls and searches for the workspace run on it and are not
charged. It has no switches. The key is saved in the Kenso app, never
through this server.
LinkedIn is in enrich. Sales Navigator is detected on the LinkedIn
seat (see products), not a separate connection.
- scope: member (your own connection, such as your mailbox or LinkedIn
seat) or workspace (shared by everyone).
- availability: live, or coming_soon when Kenso has no backend for it in
this workspace yet.
- status: connected, not_connected, needs_reconnect, or unknown when
Kenso could not read that integration's store. Always not_connected while
coming_soon.
- connectedAs: the connected account (mailbox email, LinkedIn name), when
known. connectedAt: when it was connected, when known.
- options: {key, value, defaultValue} switches, empty unless live. Change
them with integrations(operation="update"). gmail and outlook also
carry trackOpens when you have a mailbox there (the one connectedAs
names): your own mailbox's Track opens option, off by default. Open
tracking is unavailable: Kenso adds no open-tracking pixel to replies or
1:1 Accounts email, and turning it on is refused.
- products (linkedin only): {premium, salesNavigator, recruiter,
checkedAt}, the plan Kenso detected on the seat in connectedAs (read
daily from the account, never a separate connect). Omitted until the
seat is first checked, which means plain LinkedIn.
To connect or disconnect an integration use its own tool (inboxes,
linkedin, api_keys, webhooks); this catalog only reports the state.
The visitor-ID cards rb2b, vector, snitcher and warmly (signals) are the
website's provider, one at a time: website(operation="update",
changes={"provider": "rb2b"}) connects one and returns the webhook URL to
paste in it, and provider none disconnects it. The connected one reads
connected, or needs_reconnect while its webhook is paused.
ad-connections-list-ad-accounts
Read. Early access: needs ad_audiences on for the workspace. GET https://api.ken.so/v1/ad-connections/{adConnectionId}/ad-accounts
Path: adConnectionId
List the ad accounts an ad connection reaches, read live from Google or Meta. Use it to see which account the connection could sync to.
GET /api/v1/ad-connections/{adConnectionId}/ad-accounts.
Staff, or a workspace with the ad_audiences flag. Sends Ken-Version 1.1.
Requires accounts view. Another workspace's id is not_found.
Returns data [{id, name, loginAccountId, isManager}]. Google ids are customer ids
without dashes; a client account reached through a manager carries that manager as
loginAccountId; a manager account itself cannot hold audiences. Meta ids are act_<id>.
409 reconnect_required when the token cannot be used (reconnect in the Kenso app),
503 provider_unavailable when the platform is not reachable.
google-sheets-preview
Read. GET https://api.ken.so/v1/google-sheets/{spreadsheetId}/preview
Path: spreadsheetId
Query: sheet string
Preview a Google Sheet before importing it as contacts. Returns the header row, the first 20 rows, the tab titles and the column mappings.
GET /api/v1/google-sheets/{spreadsheetId}/preview. Internal. Sends Ken-Version 1.1.
Reads one tab (sheet, a tab title; omitted reads the first tab) of
spreadsheet_id (an id or a Google Sheets URL) with the caller's own Kenso
Workspace Google connection. data holds spreadsheetId, title, sheet,
sheets (every tab title), headers, rows (up to 20) and suggestedMappings:
the suggested column mappings (with csv_import_check on, from the headers
and rows, skipped columns left out; else the header aliases), to pass as column_mappings to
contacts(operation="contact-imports-create") with source google_sheets. Kenso reaches only
sheets it created and sheets the member picked for Kenso with Google Picker:
any other sheet is 409 sheet_not_shared. No Google connection is 409
reconnect_required; Google failing or rate-limiting is 503
provider_unavailable. Needs the google_sheets feature (404 while it is off).
ats-connections-test
Write. Early access: needs recruiting on for the workspace. POST https://api.ken.so/v1/ats/connections/{atsConnectionId}/test
Path: atsConnectionId
Check that an ATS connection still works by calling the ATS with Kenso's stored credentials.
POST /api/v1/ats/connections/{atsConnectionId}/test.
Staff, or a workspace with the recruiting flag. Sends Ken-Version 1.1. Requires the
integrations permission (workspace admins).
Returns data, the refreshed connection. 409 reconnect_required when the ATS refused the
key or token (the connection is now needs_reconnect: reconnect in the Kenso app), 503
provider_unavailable when the ATS is not reachable.
ad-audiences-update
Write. Early access: needs ad_audiences on for the workspace. PATCH https://api.ken.so/v1/ad-audiences/{adAudienceId}
Path: adAudienceId
Body (json): enhancedMatching boolean, firstPartyAttested boolean, holdoutPercent integer, name string, status string
Pause, resume, rename, attest first-party, change the holdout or turn enhanced matching on or off. Absent fields stay. active also resumes an audience in error once its cause is fixed.
PATCH /api/v1/ad-audiences/{adAudienceId}.
Staff, or a workspace with the ad_audiences flag. Sends Ken-Version 1.1. Requires the
integrations permission. Send at least one field.
status: active or paused. paused stops adding members (Kenso still removes contacts who
unsubscribe, bounce or leave the campaign); active resumes it, an audience in error
included. name: 1 to 200
characters; it changes in Kenso only, the platform keeps the name it was created with.
first_party_attested: true records that the user explicitly confirmed the campaign's
contacts are first-party (send it only on that confirmation); a Google Ads audience
cannot withdraw it (400 first_party_required), other platforms clear it with false.
holdout_percent: 0 to 50. On the next sync, contacts newly held out leave the platform
audience and contacts no longer held out join it. A change restarts the lift window
(ad-audiences-lift startedAt), so change it only when you start over.
enhanced_matching: true adds the contacts' matched personal emails (and on Meta, phones) on
the next sync, once Kenso has turned the feature on for the workspace (400 on Google Ads or an
account tier); false removes them on the next sync.
Returns data, the audience (see list).
update
Write. PATCH https://api.ken.so/v1/integrations/{integrationKey}
Path: integrationKey
Body (json): options object
Change an integration's option switches. Only the options you send change; each is true or false.
PATCH /api/v1/integrations/{integrationKey}. Internal. Sends Ken-Version
1.1 and X-Ken-Workspace-Id. Needs the integrations_catalog feature (404
when off).
options: at least one {optionKey: true|false}, using the keys the
integration lists (for example gmail and outlook: addSignature,
trackOpens; linkedin: sendConnectionNotes, readInMailReplies; prospeo:
useInEmailWaterfall). An option the integration does not
have, or a non-boolean value, is 400 validation_failed with field
options.{key}.
trackOpens (gmail and outlook only) is the Track opens option of your own
mailbox, the one connectedAs names, off by default. Open tracking is
unavailable: Kenso adds no open-tracking pixel to replies or 1:1 Accounts
email, so trackOpens true is 400 validation_failed with details code
open_tracking_unavailable (field options.trackOpens) and nothing is
written; false is accepted. With no mailbox connected there, or when it was
reconnected by someone else while saving, it is 409 invalid_state and
nothing is written. When Kenso could not read your mailboxes (status
unknown) it is 503 service_unavailable and nothing is written; retry. The
whole body is checked before any write; trackOpens is written first, then
the other options.
A member-scoped integration's options (gmail, outlook, linkedin, ...) are
the caller's own, so any member may change them. A workspace-scoped
integration's options apply to everyone and need the Integrations
permission (403 permission_denied without it). A coming_soon integration
is 409 invalid_state. Returns the integration with its new options.