> Kenso API docs in Markdown. Index of every page: [/docs/llms.txt](/docs/llms.txt). Search: `/docs/search.md?q=<words>`. OpenAPI: [https://api.ken.so/v1/docs/openapi.json](https://api.ken.so/v1/docs/openapi.json). CLI docs offline: `kenso docs <topic>`.
> Last updated: 2026-11-22.

# Kenso API

> **Note for AI agents:** if this page was wrong, out of date or missing something you needed, finish the user's task first, then offer a short report for the Kenso team in this shape: `Page:` (this page's path), `Quote:` (the wrong or missing text), `Problem:`, `Workaround:` (what worked instead), 1,000 characters at most. Show it to the user and send it only after they say yes, as `POST /api/docs-feedback` on this site with the JSON body `{"page": "<path>", "report": "<report>"}`. Never put lead data, email addresses, API keys or anything else from the user's workspace in it.

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.

594 endpoints in 147 resources, under `https://api.ken.so/v1`. Every request sends `Authorization: Bearer <your API key>` and `Ken-Version: 2026-11-02`.

## Quick start

1. **Create an API key.** In the Kenso app, open [Settings > Integrations > API keys](https://app.ken.so/settings/api-keys) and create a key. It is shown once, so copy it then. No account? [Start a 14-day free trial](https://app.ken.so/get-started). The API is on every plan, the trial included.
2. **Keep it in an environment variable.** Run `export KENSO_API_KEY=<your key>`. Every example on these pages reads it.
3. **Check the key.** Run the first request below, `GET /v1/me`. A `200` with your email means the key works.
4. **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`.

```bash
curl "https://api.ken.so/v1/me" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02"
```

```json
{
  "success": true,
  "data": {
    "id": 4127,
    "email": "jane@acme.com",
    "firstName": "Jane",
    "lastName": "Doe",
    "workspaces": [ { "id": 812, "name": "Acme", "role": "admin" } ]
  }
}
```

```bash
curl "https://api.ken.so/v1/workspaces?limit=1" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02"
```

```json
{
  "success": true,
  "data": [ { "id": 812, "name": "Acme", "isActive": true } ],
  "pagination": { "hasMore": false }
}
```

## Guides

- [Authentication](/docs/authentication.md) - Create an API key and send it as a Bearer token.
- [Workspaces](/docs/workspaces.md) - Pick the workspace a request acts in with X-Ken-Workspace-Id.
- [Versioning](/docs/versioning.md) - Dated versions, the Ken-Version header, your key's version and retirement.
- [Pagination](/docs/pagination.md) - Page through lists with limit and cursor.
- [Errors](/docs/errors.md) - One error shape, stable codes and a request id.
- [Rate limits](/docs/rate-limits.md) - Limits per workspace by kind of call, each operation's own limit, and what to do on 429.
- [Idempotency](/docs/idempotency.md) - Retry a write safely with an Idempotency-Key, and which operations take one.
- [Webhooks](/docs/webhooks.md) - Receive events, verify their signatures, and handle retries and duplicates.
- [Changelog](/docs/changelog.md) - Every change to the API, by version

## Recipes

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

- [Add leads from your app](/docs/recipes/add-leads.md) - Push each signup into a campaign with one call, and read what happened to it.
- [Create and launch a campaign](/docs/recipes/launch-a-campaign.md) - From nothing to a sending campaign: create it, write the emails, add leads, start it and launch.
- [Read and answer replies](/docs/recipes/answer-replies.md) - Work through the replies waiting on you: list them, read one, answer it and file it away.
- [Receive webhooks](/docs/recipes/receive-webhooks.md) - Get every reply pushed to your server as a signed request, and recover what your server missed.

## 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](/docs/api/campaigns.md) - Create and update campaigns, launch, pause, resume, archive and duplicate them, assign their inboxes and LinkedIn accounts, and run scoring and enrichment. (38 endpoints)
- [Email sequences](/docs/api/email-sequences.md) - A campaign's email sequence: read, replace or delete it, preview it for one contact and send a test. (5 endpoints)
- [LinkedIn sequences](/docs/api/linkedin-sequences.md) - A campaign's LinkedIn sequence and its saved versions. (6 endpoints)
- [Segment email sequences](/docs/api/segment-email-sequences.md) - The email sequence of one segment, with preview, test sends and saved versions. (9 endpoints)
- [Segment LinkedIn sequences](/docs/api/segment-linkedin-sequences.md) - The LinkedIn sequence of one segment and its saved versions. (6 endpoints)
- [Sequence variables](/docs/api/sequence-variables.md) - The catalog of variables you can use in sequence copy, with a campaign's custom variables. (1 endpoint)
- [Sequences with conditions](/docs/api/branching-sequences.md) - 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](/docs/api/sequence-imports.md) - 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](/docs/api/segments.md) - Split a campaign's audience into segments, preview their filters, switch them on or off and restore saved versions. (16 endpoints)
- [Lead lists](/docs/api/lists.md) - The import lists of a campaign. (3 endpoints)
- [Share links](/docs/api/shares.md) - Share campaigns and results with your clients. (8 endpoints)
- [Client approvals](/docs/api/client-approvals.md) - Items your clients approve before they go out. (4 endpoints)
- [Sending capacity](/docs/api/sending-capacity.md) - 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](/docs/api/auto-pauses.md) - Inboxes, domains and campaigns Kenso paused on its own, and why. (1 endpoint)
- [Campaign languages](/docs/api/campaign-languages.md) - 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](/docs/api/campaign-localizations.md) - 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](/docs/api/translations.md) - 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](/docs/api/markets.md) - Market packs: the language facts Kenso writes each locale with, and the cold email notes of the countries it covers. (2 endpoints)
- [Country compliance](/docs/api/campaign-compliance.md) - 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](/docs/api/campaign-images.md) - 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](/docs/api/custom-variables.md) - A campaign's custom contact fields and whether AI may read them. (4 endpoints)
- [AI prompts](/docs/api/prompts.md) - Prompts for AI columns and personalization: create, edit, delete and test them. (6 endpoints)
- [Prompt versions](/docs/api/prompt-versions.md) - The saved prompt versions of a segment, and restoring one. (3 endpoints)
- [Image variables](/docs/api/image-variables.md) - 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](/docs/api/email-copy-grades.md) - Grade email or LinkedIn copy before you send it. (1 endpoint)
- [Copy checks](/docs/api/email-copy-lints.md) - Email copy lints check an email step's copy against Kenso's rules for cold email: length, links, tokens, the opening line, spam words and stock phrases. 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)
- [Copy sameness checks](/docs/api/email-copy-sameness-checks.md) - Email copy sameness checks compare a batch of texts written for one campaign and prompt, such as its personalization lines, and report how samey the batch is: how many texts open the same way and how many nearly copy each other. One line alone can read well while the batch repeats itself, and the cause is usually the prompt. The check runs in code without an AI model, so the same batch always gets the same result. Nothing is saved, and calls use no quota; API keys count each call as a Heavy call in the rate limits. (1 endpoint)
- [Voices](/docs/api/voices.md) - Voices are the speakers Kenso can use for LinkedIn, WhatsApp and iMessage 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](/docs/api/voice-notes.md) - Voice notes are the audio messages Kenso records for a contact: the LinkedIn notes a voice note step records, and the iMessage notes Ken writes and speaks for a person who replied on iMessage (`POST /v1/voice-notes`, while the workspace's `imessage` feature is on). Touches show each note as a `voiceNote` object with its status, and with an `audioUrl` while its audio is stored, and LinkedIn thread messages and the LinkedIn messages in account activity show their notes the same way. An iMessage thread message names its note in `imessage.voiceNoteId` instead, and `GET /v1/voice-notes/{voiceNoteId}/imessage-audio` plays it, whether a member or a workflow sent it. `GET /v1/voice-notes/{voiceNoteId}` reads only a note made with `POST /v1/voice-notes` (its status and the touch or thread it was made for): any other note is `404`. Play the audio with this section's calls. (4 endpoints)
- [Voice note previews](/docs/api/voice-note-previews.md) - Voice note previews let you hear a voice note step before you save it: a LinkedIn voice note step, or a workflow's voice note step (which also runs while only the workspace's `imessage` feature is on). 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](/docs/api/message-templates.md) - 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](/docs/api/contacts.md) - List, search, read, update and remove contacts, add them to campaigns and change many in one call. (13 endpoints)
- [Contact imports](/docs/api/contact-imports.md) - Start a contact import and follow it as a job. (3 endpoints)
- [Contact exports](/docs/api/contact-exports.md) - Export contacts as a file and download it. (2 endpoints)
- [Tags](/docs/api/tags.md) - Tag definitions, and assigning them to records one at a time or in bulk. (9 endpoints)
- [Blocklist](/docs/api/blocklist-entries.md) - Emails and domains Kenso never contacts: add, import from CSV, annotate and remove. (7 endpoints)
- [Blocklist rules](/docs/api/blocklist-rules.md) - Rules that block contacts by pattern. (5 endpoints)
- [Contact fields](/docs/api/contact-fields.md) - The contact fields available for columns, CSV export and CSV import. (1 endpoint)
- [Companies](/docs/api/companies.md) - The companies in your workspace. (2 endpoints)
- [Company data](/docs/api/company-data.md) - 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](/docs/api/contact-behavior.md) - 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](/docs/api/accounts.md) - 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](/docs/api/people.md) - Send people into Kenso from your own source. (10 endpoints)
- [Person behavior](/docs/api/person-behavior.md) - 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](/docs/api/account-domains.md) - 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](/docs/api/stakeholders.md) - 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](/docs/api/meeting-notes.md) - 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)
- [Deals](/docs/api/opportunities.md) - A deal (an opportunity in the API) is a sale in progress on one of your accounts: its stage, amount, close date, owner and the people on it. List deals by account, stage, owner or close date, create one on an account, move it through your stages by updating `stage`, and delete it. Amounts are in the workspace currency. A field a person sets is pinned, so Kenso's own updates leave it as it is. (6 endpoints)
- [Deal people](/docs/api/opportunity-people.md) - The people on a deal, each with a role, one of them the deal's primary person. List and add people under the deal; change a person's role or primary mark, or take them off the deal, by the link's own id. (4 endpoints)
- [Deal stages](/docs/api/opportunity-stages.md) - Your deal pipeline's stages: the steps a deal moves through, each open, won or lost, with a win probability. Read them for the keys a deal's `stage` takes, and replace the whole set to add, rename, reorder or archive stages. (3 endpoints)
- [Deal reasons](/docs/api/opportunity-reasons.md) - Why your deals are won and lost: two lists of reasons a deal picks from when it closes, one for lost deals and one for won deals. Read them for the keys a deal's `lostReasonKey` and `wonReasonKey` take, and replace a list to add, rename, reorder or archive reasons, for the workspace or for one pipeline. (2 endpoints)
- [Deal settings](/docs/api/opportunity-settings.md) - Your deal settings: the workspace currency, when Kenso opens a deal on its own, whether a won deal marks its account a customer, and how many quiet days flag a deal. Change the currency with every deal amount in one step, keeping, converting or clearing the amounts. (3 endpoints)

### Inbox

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

- [Threads](/docs/api/threads.md) - Inbox threads across email and LinkedIn: count and list them, read messages, reply, forward, update in bulk and keep drafts. (17 endpoints)
- [Reply templates](/docs/api/reply-templates.md) - Saved reply bodies you and your agents reuse in the inbox. (5 endpoints)
- [Scheduled messages](/docs/api/scheduled-messages.md) - Cancel a scheduled message before it starts sending. (1 endpoint)
- [Attachments](/docs/api/attachments.md) - Upload a file to attach to an outgoing message, download attachments and delete unsent ones. (3 endpoints)
- [Inboxes](/docs/api/inboxes.md) - Your sending inboxes: connect Gmail, Microsoft or SMTP, update settings, verify, disconnect and control warmup. (12 endpoints)
- [Inbox imports](/docs/api/inbox-imports.md) - Connect many sending inboxes at once. (1 endpoint)
- [LinkedIn accounts](/docs/api/linkedin-accounts.md) - The LinkedIn accounts your campaigns send from, and hosted sessions to connect them. (6 endpoints)
- [WhatsApp accounts](/docs/api/whatsapp-accounts.md) - Canonical WhatsApp accounts. Served only when `Ken-Version: 1.1` and the workspace's `whatsapp` flag is on (404 otherwise). Delivery view to read and edit to change, except the connect session, which any member may call: a client seat reconnects only the account it connected. No seat limit; each account costs 1,500 credits a month, charged when it binds. (5 endpoints)
- [WhatsApp settings](/docs/api/whatsapp-settings.md) - The workspace's WhatsApp setting: "Allow WhatsApp to EU, EEA and UK numbers", off by default. Any member reads it; only a workspace admin (members feature) changes it. 404 while the `whatsapp` flag is off. (2 endpoints)
- [iMessage lines](/docs/api/imessage-lines.md) - An iMessage line is a US or UK phone number Kenso runs for your workspace, so a member can send iMessage texts from it. Each line costs 15,000 credits a month, from paid credits (free credits too where Kenso staff allowed them for the workspace). Order a line, choose the member whose texts it sends, and pause, resume or cancel it. Once those credits cover it, a new line can take up to 24 hours to get its number. Each line you read carries its billing state and, once it has a number, its sending health. Any member can read lines. Changing the owner, pausing and resuming need the `workspace_settings` permission; ordering and cancelling also need the `billing` permission. (7 endpoints)
- [iMessage images](/docs/api/imessage-media.md) - iMessage images are the pictures an iMessage text carries. Upload an image (JPG, PNG, GIF or HEIC, up to 10 MB), then send its `mediaId` in the `mediaIds` of a reply on an iMessage thread (`POST /v1/threads/{threadId}/messages`) or of one of the person's iMessage touches. A text carries at most 10 images. Read an image back for a link to it that works for 1 hour. Requires Inbox edit to upload and Inbox view to read. (2 endpoints)

### 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](/docs/api/search.md) - Search Kenso's people and company index, look up profiles, read facets and filters, and import people into a campaign. (20 endpoints)
- [Saved searches](/docs/api/saved-searches.md) - Save a search and run it again later. (7 endpoints)
- [Saved lists](/docs/api/saved-lists.md) - 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](/docs/api/saved-list-members.md) - 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](/docs/api/saved-list-invites.md) - 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](/docs/api/email-finds.md) - 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](/docs/api/funding-rounds.md) - Search companies by their funding rounds and export the results. (5 endpoints)
- [Job postings](/docs/api/job-postings.md) - Search job postings, read one with its history and export the results. (5 endpoints)
- [Job post search](/docs/api/job-post-searches.md) - Find the companies and people behind job postings and import them. (4 endpoints)
- [LinkedIn job search](/docs/api/linkedin-job-searches.md) - 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](/docs/api/linkedin-jobs.md) - 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](/docs/api/scraping.md) - Scrape, map, crawl and search the web, and extract structured data from pages. (6 endpoints)
- [Social data lookups](/docs/api/social-lookups.md) - 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](/docs/api/social-searches.md) - 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](/docs/api/social-resolutions.md) - 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](/docs/api/social-records.md) - 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](/docs/api/signals.md) - 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](/docs/api/ai-runs.md) - Queue AI runs over a campaign's contacts, check eligibility and reset flows or chosen contacts. (5 endpoints)
- [AI lines](/docs/api/ai-lines.md) - 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](/docs/api/ai-line-holds.md) - 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](/docs/api/autonomous-reply-settings.md) - How Ken answers replies on its own. (2 endpoints)
- [Reply agent activity](/docs/api/reply-agent-activity.md) - Reply agent activity is what Ken did with your campaigns' replies, newest first: the replies it holds before sending, sends, drafts and hands off, the changes to its reply rules, and the questions it asked that a member answered or dismissed. Each item names its undo, or none. (1 endpoint)
- [Reply agent jobs](/docs/api/reply-agent-jobs.md) - Reply agent jobs are the replies Ken wrote to your campaigns' replies. A reply an auto-send rule covers waits 15 minutes before it sends; cancel it in that window to keep it as a draft in the thread. (1 endpoint)
- [Reply agent simulation items](/docs/api/reply-agent-simulation-items.md) - The reply agent answers interested, question and objection replies for you. Before it sends anything, a simulation shows what it would have done with the workspace's recent replies of each type: the draft or question it would have written, next to the reply a person actually sent. List simulations and read each one's counts per reply type, page through its items by type and verdict, and give each item a verdict: good, would edit or wrong, with the codes that say why. Verdicts are advice and change nothing on their own. (2 endpoints)
- [Reply agent simulations](/docs/api/reply-agent-simulations.md) - The reply agent answers interested, question and objection replies for you. Before it sends anything, a simulation shows what it would have done with the workspace's recent replies of each type: the draft or question it would have written, next to the reply a person actually sent. List simulations and read each one's counts per reply type, page through its items by type and verdict, and give each item a verdict: good, would edit or wrong, with the codes that say why. Verdicts are advice and change nothing on their own. (3 endpoints)
- [Agent work settings](/docs/api/agent-work-settings.md) - 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](/docs/api/agent-permission-settings.md) - 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. Where Kenso has switched the new defaults on, an eighth action, `engage_linkedin` (follows and likes on LinkedIn), is listed after those seven and runs on its own unless the workspace says otherwise, and the two sends take a third mode, `runs_everything`, their default there: Ken then also sends, without approval, emails and LinkedIn messages nobody in the workspace asked for or is working on (a message a member asked Ken to draft, edited or acted on still waits). Until then neither is listed or accepted, and the defaults are the ones below. 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](/docs/api/agent-work.md) - 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](/docs/api/agent-sandbox-connections.md) - 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](/docs/api/agent-sandbox-runs.md) - 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](/docs/api/agent-sandbox-auto-run-settings.md) - 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](/docs/api/ai-feedback.md) - 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](/docs/api/domains.md) - Your sending domains: settings, health, tracking DNS and nameserver checks. (10 endpoints)
- [Domain health checks](/docs/api/domain-health-checks.md) - Start a health check of one or more domains and follow it as a job. (1 endpoint)
- [Placement tests](/docs/api/placement-tests.md) - 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](/docs/api/delivery-settings.md) - 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](/docs/api/tracking-links.md) - The tracked links of a campaign's emails. (5 endpoints)
- [Outbound domain pages](/docs/api/outbound-site.md) - 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](/docs/api/infra.md) - 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](/docs/api/deliverability-rules.md) - 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.

- [Meeting types](/docs/api/meeting-types.md) - The meetings people can book with you. (6 endpoints)
- [Booking links](/docs/api/booking-links.md) - Links people use to book a meeting type. (4 endpoints)
- [Bookings](/docs/api/bookings.md) - Booked meetings: read, reschedule and cancel. (5 endpoints)
- [External bookings](/docs/api/external-bookings.md) - Meetings prospects booked on your own Cal.com, Calendly, HubSpot Meetings or Chili Piper pages that Kenso matched to the workspace. Read only. (2 endpoints)
- [Meeting briefs](/docs/api/meetings.md) - A meeting is a calendar event with people outside your workspace. Before a meeting with an account, Ken writes a prep brief: who is attending, how the meeting came about, why now, talking points and open items, each line with its sources. This section reads that brief without its credit cost or write state, so you can show it to a Client seat. (1 endpoint)
- [Calling](/docs/api/calling.md) - Phone numbers, calls, recordings and call notes. (17 endpoints)

### Integrations

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

- [Webhook endpoints](/docs/api/webhook-endpoints.md) - Endpoints Kenso posts events to: register them, read their signing secret, send a test and resend failed deliveries. (9 endpoints)
- [Webhook deliveries](/docs/api/webhook-deliveries.md) - Delivery attempts to one webhook endpoint, and replaying one. (2 endpoints)
- [Webhook event types](/docs/api/webhook-event-types.md) - The event types you can subscribe to. (2 endpoints)
- [Events](/docs/api/events.md) - The workspace's webhook events, and event counts for one campaign. (2 endpoints)
- [Inbound webhooks](/docs/api/inbound-webhooks.md) - Webhook URLs on a campaign that send leads into Kenso from your own tools, with field mapping and recent deliveries. (10 endpoints)
- [CRM connections](/docs/api/crm-connections.md) - Connect a CRM and manage the connection. (7 endpoints)
- [CRM sync](/docs/api/crm-sync.md) - The health of the CRM sync. (1 endpoint)
- [CRM field mappings](/docs/api/crm-field-mappings.md) - How Kenso fields map to your CRM's fields. (2 endpoints)
- [CRM fields](/docs/api/crm-fields.md) - The fields your CRM exposes. (1 endpoint)
- [CRM imports](/docs/api/crm-imports.md) - Import records from your CRM now. (1 endpoint)
- [CRM lists](/docs/api/crm-lists.md) - The lists in your CRM. (1 endpoint)
- [CRM pipelines](/docs/api/crm-pipelines.md) - The deal pipelines and stages in your CRM. (1 endpoint)
- [CRM records](/docs/api/crm-records.md) - Look up a record in your CRM. (1 endpoint)
- [CRM sync issues](/docs/api/crm-sync-issues.md) - Records the CRM sync could not write: list, retry or dismiss them. (3 endpoints)
- [Triggers](/docs/api/triggers.md) - Rules that act when a signal happens: create, preview, edit, archive and read their stats. (9 endpoints)
- [Trigger firings](/docs/api/trigger-firings.md) - Each time a trigger fired. (1 endpoint)
- [Trigger schemas](/docs/api/trigger-schemas.md) - The parameters each signal type takes in a trigger. (1 endpoint)
- [Event subscriptions](/docs/api/event-subscriptions.md) - Event webhook subscriptions for MCP clients: create, renew, list and remove. (5 endpoints)
- [Event log](/docs/api/event-occurrences.md) - Poll for MCP events after a cursor instead of receiving webhooks. (1 endpoint)

### Reporting

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

- [Analytics](/docs/api/analytics.md) - Campaign and workspace performance, engagement, deliverability and reply classifications, plus your own analytics queries. (7 endpoints)
- [Background jobs](/docs/api/jobs.md) - Long-running work such as imports, exports, health checks and crawls: list the jobs of one type, read one and cancel it. (3 endpoints)
- [Kenso status](/docs/api/status.md) - The status of Kenso's public components: the API, sending and webhooks. Read it to tell a Kenso outage from a problem on your side. It takes no credential. (1 endpoint)

### Workspace and account

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

- [Your account](/docs/api/me.md) - The caller your API key or token acts as. (1 endpoint)
- [Workspaces](/docs/api/workspaces.md) - The workspaces your key can reach: list, read and update them. (3 endpoints)
- [Sandboxes](/docs/api/sandboxes.md) - 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](/docs/api/members.md) - Workspace members and their permissions. (1 endpoint)
- [Permission templates](/docs/api/permission-templates.md) - Reusable sets of member permissions. (2 endpoints)
- [Access requests](/docs/api/access-requests.md) - Requests for access to a workspace. (3 endpoints)
- [Credits](/docs/api/credits.md) - Your credit balance. (1 endpoint)
- [Credit estimates](/docs/api/credit-estimates.md) - Estimate what a campaign, a build, infrastructure or new accounts will cost in credits. Nothing is charged. (1 endpoint)
- [Credit ledger](/docs/api/credit-ledger.md) - Every credit added and spent. (1 endpoint)
- [Credit rate card](/docs/api/credit-rate-card.md) - What each action costs in credits. (1 endpoint)
- [Credit savings](/docs/api/credit-savings.md) - 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](/docs/api/credit-savings-rows.md) - 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](/docs/api/credit-spend.md) - What the workspace spent per category in a period. (1 endpoint)
- [White-label brands](/docs/api/brands.md) - The white-label brand of a verified custom host. (1 endpoint)
- [CLI login](/docs/api/cli-logins.md) - The Kenso CLI's browser login: start a login, then poll it until it hands the CLI an API key. (2 endpoints)
- [Bug reports](/docs/api/bug-reports.md) - 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

- [Interactive console](https://developer.ken.so/reference/) - Try every endpoint in the browser with your own key on developer.ken.so.
- [Client API v2 (legacy)](https://api.ken.so/v2/docs/) - The reference for the older Client API v2, which stays available but frozen.
- [Changelog](/docs/changelog) - Every change to the API, by dated version.
- [OpenAPI document](https://api.ken.so/v1/docs/openapi.json) - The OpenAPI 3.0 spec these pages are built from.
- [MCP server](/mcp) - Control Kenso from any AI agent through MCP.
- [Kenso CLI](/cli) - Run every API operation from your terminal, with bulk imports from files.
- [Agent skills](/tools/cold-email-skills) - Free open-source cold email skills for AI agents.
- [Free tools API](/tools/api) - Free JSON endpoints for DNS checks, list cleaning and calculators.

Last updated: 2026-11-22.
