Skip to Content

Kenso API

The Kenso API is the API the Kenso app runs on. Build and launch campaigns, manage contacts, read and answer replies, connect inboxes and domains, search people and companies, and get events as webhooks. Every public endpoint is below, with a curl request and an example response.

551 endpoints135 resourcesKen-Version: 2026-11-02
Markdown

Quick start

Create an API key

In the Kenso app, open Settings > Integrations > API keys and create a key. It is shown once, so copy it then. No account? Start a 14-day free trial. The API is on every plan, the trial included.

Keep it in an environment variable

Run export KENSO_API_KEY=<your key>. Every example on these pages reads it.

Check the key

Run the first request below, GET /v1/me. A 200 with your email means the key works.

Set your workspace id

Run the second request below, GET /v1/workspaces?limit=1, and keep the id it returns: export KENSO_WORKSPACE_ID=<id>. Every example sends it as X-Ken-Workspace-Id.

GET /v1/me
curl "https://api.ken.so/v1/me" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02"
Response 200, shortened
{
  "success": true,
  "data": {
    "id": 4127,
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Doe",
    "workspaces": [ { "id": 812, "name": "Acme", "role": "admin" } ]
  }
}
GET /v1/workspaces
curl "https://api.ken.so/v1/workspaces?limit=1" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02"
Response 200, shortened
{
  "success": true,
  "data": [ { "id": 812, "name": "Acme", "isActive": true } ],
  "pagination": { "hasMore": false }
}

Guides

Read these once before you build.

Recipes

The four jobs people come for, one path each, with the REST call, the kenso command and the MCP call side by side.

API reference

Every public endpoint, grouped by what it works on.

Campaigns

Create, launch and pause campaigns, write their sequences, segment the audience and set their languages, markets and compliance.

Campaigns

Create and update campaigns, launch, pause, resume, archive and duplicate them, assign their inboxes and LinkedIn accounts, and run scoring and enrichment.

36 endpoints

Email sequences

A campaign's email sequence: read, replace or delete it, preview it for one contact and send a test.

5 endpoints

LinkedIn sequences

A campaign's LinkedIn sequence and its saved versions.

6 endpoints

Segment email sequences

The email sequence of one segment, with preview, test sends and saved versions.

9 endpoints

Segment LinkedIn sequences

The LinkedIn sequence of one segment and its saved versions.

6 endpoints

Sequence variables

The catalog of variables you can use in sequence copy, with a campaign's custom variables.

1 endpoint

Sequences with conditions

A sequence with conditions sends each contact down a yes or a no path: whether they opened, clicked, replied, booked a meeting or engaged on LinkedIn within a number of days, or what their data holds. A campaign has at most one, saved as a tree per segment. Saving compiles it to the campaign's workflow as a draft; launching the campaign publishes the workflow and starts its leads, and launch refuses a tree that cannot send (the launch operation names the reason).

2 endpoints

Sequence import

Sequence imports read a sequence written in another tool (Origami, lemlist, Instantly, La Growth Machine or anything else) into proposed Kenso steps. Nothing is saved: review the steps, then save them with the email and LinkedIn sequence routes.

1 endpoint

Segments

Split a campaign's audience into segments, preview their filters, switch them on or off and restore saved versions.

16 endpoints

Lead lists

The import lists of a campaign.

3 endpoints

Share links

Share campaigns and results with your clients.

8 endpoints

Client approvals

Items your clients approve before they go out.

4 endpoints

Sending capacity

Sending capacity is how many emails your workspace's inboxes can send in a day, and how much of that your campaigns already use. Read the forecast before you launch a campaign or add contacts, to check there is room for the extra volume. The forecast covers UTC today and the next two days.

1 endpoint

Auto-pauses

Inboxes, domains and campaigns Kenso paused on its own, and why.

1 endpoint

Campaign languages

A campaign can send each contact its email and LinkedIn steps in the contact's own language, called the outreach language. Read a campaign's language settings, the languages it can turn on, and how many contacts have each outreach language. Change the settings with PATCH /v1/campaigns/{campaignId}, and write the translated steps with the campaign localizations calls.

1 endpoint

Localized steps

A localization is one email or LinkedIn step of a campaign, written in one of the languages the campaign turns on. Kenso writes localizations in the background and checks each one. When the campaign's languageMode is auto, Kenso sends each contact the approved localization of their language. Ask Kenso to write the localizations, poll the list until they are written, then approve, regenerate or edit each one.

5 endpoints

Text translation

Translate plain text into one language, for example a reply so a member can read it. The translation keeps line breaks, names, links, numbers and {placeholders}. Each call counts against a per-workspace limit, and a translation Kenso makes anew costs credits.

1 endpoint

Market packs

Market packs: the language facts Kenso writes each locale with, and the cold email notes of the countries it covers.

2 endpoints

Country compliance

Some countries restrict cold email to business contacts, such as Germany or Spain. When a campaign has contacts in one of them, a member acknowledges that country's cold email rules once before the campaign launches. Read the countries a campaign needs acknowledged, then acknowledge them. Until every listed country is acknowledged, launching the campaign answers 409 acknowledgement_required.

2 endpoints

Campaign images

The current images of a campaign's leads, and one image with a fresh preview link.

2 endpoints

Copy and personalization

Variables, prompts and their versions, voices and voice notes, message templates, and grades and lints for email copy.

Custom variables

A campaign's custom contact fields and whether AI may read them.

4 endpoints

AI prompts

Prompts for AI columns and personalization: create, edit, delete and test them.

6 endpoints

Prompt versions

The saved prompt versions of a segment, and restoring one.

3 endpoints

Image variables

The image tokens of a campaign's sequence, each one shared image or one image per lead: create, edit, estimate, test and regenerate them.

9 endpoints

Copy grades

Grade email or LinkedIn copy before you send it.

1 endpoint

Copy checks

Email copy lints check an email step's copy against Kenso's rules for cold email: length, links, tokens, the opening line and spam words. The check runs in code without an AI model, so the same copy always gets the same result. Nothing is saved, and calls do not count toward any limit.

1 endpoint

Voices

Voices are the speakers Kenso can use for LinkedIn AI voice notes: Deepgram voices, ElevenLabs stock voices and voices the workspace imports from its own ElevenLabs account. A voice note step names its voice by provider and voiceId. Importing a voice needs the workspace's ElevenLabs API key in Settings, Integrations. Every call answers 503 voice_notes_unavailable while voice notes are not available.

4 endpoints

Voice notes

Voice notes are the LinkedIn audio messages Kenso records for a contact from a voice note step. Touches, thread messages and account activity show each one as a voiceNote object with its status, and with an audioUrl while its audio is stored. Play the audio with this section's call.

1 endpoint

Voice note previews

Voice note previews let you hear a LinkedIn voice note step before you save it. Kenso writes and speaks the note for up to 3 of the campaign's contacts and returns each one with a link to its audio. Previews are free and count toward a daily limit for the workspace.

1 endpoint

Message templates

WhatsApp message templates, behind the whatsapp flag (404 while off). Writes need workspace_settings.

5 endpoints

Contacts and companies

Import, export and update contacts and companies, tag them, keep blocklists and read company data.

Contacts

List, search, read, update and remove contacts, add them to campaigns and change many in one call.

13 endpoints

Contact imports

Start a contact import and follow it as a job.

3 endpoints

Contact exports

Export contacts as a file and download it.

2 endpoints

Tags

Tag definitions, and assigning them to records one at a time or in bulk.

9 endpoints

Blocklist

Emails and domains Kenso never contacts: add, import from CSV, annotate and remove.

7 endpoints

Blocklist rules

Rules that block contacts by pattern.

5 endpoints

Contact fields

The contact fields available for columns, CSV export and CSV import.

1 endpoint

Companies

The companies in your workspace.

2 endpoints

Company data

Company data is what Kenso knows about a company, looked up by its website domain: its brand (name, description and logo), the technologies seen on its website, and its funding. The data is the same for every workspace and costs no credits. Each answer that finds data, and each request for branding, counts one row toward the workspace's searchBrowseRows quota, the same quota Kenso Search lookups use. The branding kind (logo, colors and fonts read from the company's live website) is opt-in and costs credits.

1 endpoint

Contact behavior

What Kenso learned about the person behind a contact from how they answered outreach: tags such as cold_responder or prefers_linkedin, and the counts behind them. Use them to pick a channel, a send window or whether to follow up. Kenso rebuilds the signals nightly. With the behavior_signals_network feature, you also get anonymous signals from outreach by other Kenso workspaces.

1 endpoint

CRM

Accounts

An account is a company you sell to: the record its people, deals, meeting notes and activity hang on. Kenso matches accounts by domain, so one company is one account. List accounts with domain to find one, and create one from its domains: a domain another account owns answers 409 conflict with that account's id. Update, merge and delete accounts, read an account's website, LinkedIn and careers links, and add the account's people to a campaign. A field a person sets is pinned, so Kenso's own updates leave it as it is.

9 endpoints

People

Send people into Kenso from your own source.

10 endpoints

Person behavior

A person is one real human in your workspace, the same record across your campaigns and your accounts. A person carries their owner, lead status, score, phone numbers and a record of where they came from. List people, look one up by email or LinkedIn URL, or search them by account, role, lead status and tags. Create, update, merge and delete people, and upload or remove a person's photo. Put a person on an account through the account's stakeholders. Use intake to send Kenso people from your own sources, such as a web form, a workflow or your CRM: Kenso matches each one to an existing person or creates them, places them on their company's account and assigns an owner.

1 endpoint

Account domains

An account's domains are the company's website and email domains. Kenso matches people, emails and imports to the account by them, and one domain belongs to one account. Add a domain to an account, or remove one by its id; both answer with the account.

2 endpoints

Stakeholders

A stakeholder is a person's place on an account: their role in the buying committee, their priority and how well you cover them. List an account's stakeholders, put a person on an account (an existing person by id, or a new one), and update or remove a stakeholder. Removing a stakeholder keeps the person.

4 endpoints

Meeting notes

Meeting notes are call notes or a transcript you keep on an account, with each attendee linked to a person on it. Add a note for a meeting that happened, list an account's notes (each with a short excerpt), read one note in full and delete one. A note also shows on the account's meetings. A note on a private meeting shows only to the meeting's owner and workspace admins.

4 endpoints

Inbox

Read and answer reply threads, keep drafts, attachments and reply templates, and connect the inboxes and accounts replies come from.

Prospecting data

Search people and companies, funding rounds and job postings, save searches and lists, find emails, look up social profiles and send signals.

People and company search

Search Kenso's people and company index, look up profiles, read facets and filters, and import people into a campaign.

20 endpoints

Saved searches

Save a search and run it again later.

7 endpoints

Saved lists

Saved lists are reusable lists of people or companies that a workspace builds from Search, saved searches, campaigns, other lists and CSV uploads. Create and copy a list, add sources that fill it in the background and refresh them, and read or remove its members, or search members across every list at once. Share a list read-only with another workspace by email invite and revoke the grant later, or submit it to the Kenso library, where every workspace can read and copy the lists Kenso approves. A member never carries an email address or a phone number, only how many the list holds. A list the workspace cannot read answers 404 not_found, and a private list is visible only to the member who owns it.

18 endpoints

Saved list members

Saved lists are reusable lists of people or companies that a workspace builds from Search, saved searches, campaigns, other lists and CSV uploads. Create and copy a list, add sources that fill it in the background and refresh them, and read or remove its members, or search members across every list at once. Share a list read-only with another workspace by email invite and revoke the grant later, or submit it to the Kenso library, where every workspace can read and copy the lists Kenso approves. A member never carries an email address or a phone number, only how many the list holds. A list the workspace cannot read answers 404 not_found, and a private list is visible only to the member who owns it.

1 endpoint

Saved list invites

A saved-list invite is the link Kenso emails when a workspace shares one of its saved lists with an email address. Any signed-in person who holds the token can read what the invite shares, even before they have a workspace. Accepting the invite adds the list, read-only, to the workspace you call in, and only the invited email address can accept it.

2 endpoints

Email finder

An email find looks up one person's work email from their name and company, in any country. Kenso checks its own email database first, then outside email providers, and verifies each address before it keeps one. A find costs 1 credit when Kenso's own provider access finds a valid email. It costs nothing when it finds none, or when the workspace's own provider key finds the email. A find runs in the background: start it with POST /v1/email-finds and poll GET /v1/email-finds/{emailFindId}.

2 endpoints

Funding rounds

Search companies by their funding rounds and export the results.

5 endpoints

Job postings

Search job postings, read one with its history and export the results.

5 endpoints

Job post search

Find the companies and people behind job postings and import them.

4 endpoints

LinkedIn job search

LinkedIn job search on request: the caller's own LinkedIn seat first (free), Kenso's data provider without one (charged in credits per delivered row), and ken-jobs merged in either way. 404 unless the workspace has linkedin_job_search on. Reads need Search view, as job postings; a search needs Search edit, as an email find, because it can spend credits. Never a Client seat.

2 endpoints

LinkedIn jobs

One LinkedIn job's detail through the caller's own LinkedIn seat. 404 unless the workspace has linkedin_job_search on. Same access as job postings, and never a Client seat.

1 endpoint

Web scraping

Scrape, map, crawl and search the web, and extract structured data from pages.

6 endpoints

Social data lookups

Social data: records from social links (lookups), searches on a platform, a name or link to its profiles (resolutions), and the records stored for a contact, account or person. Each record read on Kenso's key costs 0.15 credits; on the workspace's own key, and for stored records, it is free. 404 unless the workspace has social_data on. Reads need Search view and the POSTs Search edit, as web scraping, because they can spend credits. Never a Client seat.

2 endpoints

Social data searches

Social data: records from social links (lookups), searches on a platform, a name or link to its profiles (resolutions), and the records stored for a contact, account or person. Each record read on Kenso's key costs 0.15 credits; on the workspace's own key, and for stored records, it is free. 404 unless the workspace has social_data on. Reads need Search view and the POSTs Search edit, as web scraping, because they can spend credits. Never a Client seat.

2 endpoints

Social profile resolution

Social data: records from social links (lookups), searches on a platform, a name or link to its profiles (resolutions), and the records stored for a contact, account or person. Each record read on Kenso's key costs 0.15 credits; on the workspace's own key, and for stored records, it is free. 404 unless the workspace has social_data on. Reads need Search view and the POSTs Search edit, as web scraping, because they can spend credits. Never a Client seat.

1 endpoint

Social data records

Social data: records from social links (lookups), searches on a platform, a name or link to its profiles (resolutions), and the records stored for a contact, account or person. Each record read on Kenso's key costs 0.15 credits; on the workspace's own key, and for stored records, it is free. 404 unless the workspace has social_data on. Reads need Search view and the POSTs Search edit, as web scraping, because they can spend credits. Never a Client seat.

1 endpoint

Signals

Queue signals for the current workspace.

1 endpoint

AI

Run AI over a campaign's contacts, review held lines and set what Ken and your own agents may do on their own.

AI runs

Queue AI runs over a campaign's contacts, check eligibility and reset flows or chosen contacts.

5 endpoints

AI lines

AI lines are the personalized lines Ken writes for one contact, one for each AI variable in the campaign's emails. Read the lines a contact's next email will use, correct one by hand, or have Ken write them all again. An edit or a new line applies to the steps that have not been sent yet, and a client approval page that shows the contact gets it too.

3 endpoints

AI line holds

Contacts the AI line check held because their personalization lines failed it: list them and approve one to send its lines as they are.

2 endpoints

Autonomous replies

How Ken answers replies on its own.

2 endpoints

Agent work settings

Decide who runs each kind of AI work that can wait: Kenso's AI (kenso_ai, the default) or your own coding agent (my_agent), which picks the work up with kenso work run.

2 endpoints

Agent permissions

Ken's agent permissions decide, per action, whether Ken asks a person first (asks_first) or acts on its own (runs_on_its_own) for the workspace. The actions, in page order, are send_email, send_linkedin, research_accounts, scan_signals, build_assets, run_crm_workflows and book_meetings. runs_on_its_own removes one thing, the per-item approval: every other guard (suppression, limits, sending windows, client approvals) still applies. These modes decide what Ken does unattended; they do not limit what a caller does with its own role. Behind the agent_permissions feature, and never open to a Client seat.

2 endpoints

Agent work

The agent work queue: the work a workspace gave its own coding agent in the agent work settings, handed out through claims. An agent reads what waits, claims a batch of one kind, writes the answers on its own AI plan and submits them; Kenso checks the format and stores each accepted answer where its own AI would have. Work is built when it is claimed, and a claim holds its items until it expires, is released or every item is answered. Behind the agent_work feature, and never open to a Client seat. Each claim, answer and release needs the access the route that writes the same thing by hand declares: Campaigns edit for the campaign kinds, Meetings edit for meeting_brief, Accounts edit for call_brief and Workflows edit for workflow_prompt.

4 endpoints

Agent sandbox connections

The agent CLIs connected in the caller's own Kenso sandbox. Connecting runs the CLI's own login in the box; the login stays on the box's disk and Kenso never reads or keeps it. A box belongs to one person across workspaces, so every route is the caller's own. Behind the agent_work and agent_sandboxes features, never open to a Client seat, and never to an API key held to a permission template (the agent in a box holds one). The login routes are the app's (internal); list and disconnect are public.

2 endpoints

Agent sandbox runs

Hosted agent sandbox runs: the caller's own Kenso sandbox runs their connected coding agent until the agent work queue in scope is empty, on the caller's own AI plan, and Kenso charges credits per started minute of box time. A run is always the caller's own. Behind the agent_work and agent_sandboxes features, never open to a Client seat, and never to an API key held to a permission template (the agent in a box holds one).

4 endpoints

Agent sandbox automatic runs

Automatic Kenso sandbox runs: Kenso starts an opted-in person's sandbox when the workspace's work for its own agent has waited long enough, one sandbox at a time per workspace, the person whose sandbox ran longest ago first, within the workspace's monthly cap. Each person opts in per workspace; the cap and the wait are the workspace's. Behind the agent_work and agent_sandboxes features, never open to a Client seat or a scoped API key.

3 endpoints

AI feedback

Thumbs up or down on Ken's output: one rating per person per output, with reason chips and an optional note that can earn the workspace credits. Served only when Ken-Version: 1.1, and dark behind the ai_feedback workspace flag (404 while it is off). Any workspace member, Client seats included (they rate and never earn).

5 endpoints

Deliverability

Domains and their health, placement tests, delivery settings, tracking links and your sending infrastructure.

Domains

Your sending domains: settings, health, tracking DNS and nameserver checks.

10 endpoints

Domain health checks

Start a health check of one or more domains and follow it as a job.

1 endpoint

Placement tests

Placement tests show where a campaign's email lands: the inbox, a promotions tab, spam, or nowhere. Kenso sends the campaign's first email from your inboxes to seed mailboxes at Gmail, Google Workspace, Outlook and Microsoft 365, then records where each copy arrived. Start a test, poll it until it completes, then read the results by provider, sending inbox and seed. Kenso also tests your sending domains every week, and a campaign's list includes those weekly tests for the domains it sends from. Where GET /v1/placement-tests/availability answers enabled: true, the workspace's tests run on the Kenso seed network.

4 endpoints

Delivery settings

The workspace's delivery settings: today the placement auto-pause switch. Served only with Ken-Version: 1.1, behind the placement_native feature flag (404 when off). Reading needs Delivery view, changing needs Delivery edit, so workspace admins and Delivery editors can turn it on.

2 endpoints

Tracking links

The tracked links of a campaign's emails.

5 endpoints

Outbound domain pages

The outbound site is a one-page website Kenso builds from your company website and serves on your sending domains, so a prospect who opens one of those domains sees a real page instead of a redirect. Use these operations to edit the details the page shows, rebuild it, and restore an earlier version. A domain shows the page only when its website choice is page (websiteMode on PATCH /v1/domains/{domainId}). A rebuild runs in the background, and the rebuilds you start count against a limit per day and per 30 days.

7 endpoints

Infrastructure findings

Infra findings are problems Kenso finds in a workspace's inboxes and domains, such as a disconnected inbox, a domain about to expire or a deleted mailbox that is still billed. Kenso checks every 6 hours, opens a finding for each new problem and resolves it once a later check no longer sees the problem. Use this section to count and list findings and to snooze, ignore or reopen one. A status change hides or shows a finding and changes nothing on the inbox or domain itself.

3 endpoints

Deliverability rules

Kenso's deliverability rules a client may see: no open pixel, one click-tracking host per sending domain, format by the recipient's mail provider, and the SMTP inbox limits. Canonical (Ken-Version: 1.1), workspace from X-Ken-Workspace-Id, exposure public. The rules come from one static source (DeliverabilityRules), and a workspace sees the ones in force for it: only open_pixel until the others are.

1 endpoint

Meetings and calls

Meeting types, booking links, bookings and the built-in dialer.

Integrations

Webhooks, the event feed, inbound webhooks, CRM connections and sync, and triggers.

Reporting

Campaign analytics, and the long-running jobs behind imports, exports and checks.

Workspace and account

The caller, your workspaces and members, permissions and access requests, credits, brands and CLI logins.

Your account

The caller your API key or token acts as.

1 endpoint

Workspaces

The workspaces your key can reach: list, read and update them.

3 endpoints

Sandboxes

A sandbox is a workspace of your own, one per member, where sends, domain orders and credit charges are simulated and webhooks still fire. Only its owner can read or change it: another member's sandbox answers not_found. Call these routes with your own sign-in or a live API key; a test key works inside its sandbox and is refused here.

6 endpoints

Members

Workspace members and their permissions.

1 endpoint

Permission templates

Reusable sets of member permissions.

2 endpoints

Access requests

Requests for access to a workspace.

3 endpoints

Credits

Your credit balance.

1 endpoint

Credit estimates

Estimate what a campaign, a build, infrastructure or new accounts will cost in credits. Nothing is charged.

1 endpoint

Credit ledger

Every credit added and spent.

1 endpoint

Credit rate card

What each action costs in credits.

1 endpoint

Credit savings

Credits pay for work in Kenso, such as finding emails, AI qualification and personalization, campaign builds, and Kenso inboxes, domains and LinkedIn accounts. Every amount in this section is in millicredits: 1 credit is 1,000 millicredits and costs $0.02. Read the balance and estimate a job before you start it, then read the ledger to see where the credits went. A white-label client workspace shares its parent workspace's balance.

1 endpoint

Credit savings rows

Credits pay for work in Kenso, such as finding emails, AI qualification and personalization, campaign builds, and Kenso inboxes, domains and LinkedIn accounts. Every amount in this section is in millicredits: 1 credit is 1,000 millicredits and costs $0.02. Read the balance and estimate a job before you start it, then read the ledger to see where the credits went. A white-label client workspace shares its parent workspace's balance.

1 endpoint

Credit spend

What the workspace spent per category in a period.

1 endpoint

White-label brands

The white-label brand of a verified custom host.

1 endpoint

CLI login

The Kenso CLI's browser login: start a login, then poll it until it hands the CLI an API key.

2 endpoints

Bug reports

A bug report sends a problem straight to the Kenso team. Your app, your support chat or an AI agent files one with the user's own description, optional diagnostics and up to 10 files. Each person can file 20 reports a day and each workspace 50.

2 endpoints

More ways to build

On this page