Migrations migrations
Import a workspace from Instantly, Smartlead, EmailBison, Salesforge, lemlist or Apollo (preview: Reply.io, Salesloft, Outreach): connect a key, discover, start a run, read the report.
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through migrations_read and changes through migrations_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: runs-cancel, runs-connect-smtp, connections-create, runs-create, connections-create-connect-session, connections-delete, connections-discover, connections-discovery, connections-get, runs-get, runs-items, connections-list, runs-list, vendors-list, connections-update-key
runs-cancel
Write. POST https://api.ken.so/v1/migration-runs/{runId}/cancel
Path: runId
Cancel a queued or running discovery or import.
POST /api/v1/migration-runs/{runId}/cancel. Needs the migrations flag and a workspace Admin. Sends Ken-Version 1.1.
Returns the run: canceled when no worker had picked it up, else cancel_requested until the worker stops at
its next page. What was already imported stays. Calling it again on a cancel_requested run is safe.
Staff can still cancel while the migrations flag is off; turning the flag off also stops a running run.
409 invalid_state detail run_finished when the run already ended. 404 not_found for a run outside the workspace.
runs-connect-smtp
Write. POST https://api.ken.so/v1/migration-runs/{runId}/smtp-credentials
Path: runId
Body (json): rows array, targetClientId integer
Connect an import's SMTP inboxes in Kenso with their SMTP and IMAP logins, at most 25 rows per call.
POST /api/v1/migration-runs/{runId}/smtp-credentials (JSON). Needs the migrations flag and a workspace Admin.
Sends Ken-Version 1.1. For SMTP inboxes the other tool cannot hand over: each row is a live SMTP and IMAP
login. rows: 1 to 25 objects with keys
email, smtp_host, smtp_port, smtp_password, imap_host, imap_port (required),
smtp_username (optional, defaults to the email), imap_username and imap_password (optional, default to the
SMTP ones).
Passwords are sent exactly as given. At most 25 rows per call (the backend refuses more with too_many_rows).
Rows run one at a time, each a live SMTP and IMAP login of a few seconds, so send a larger list in sequential
batches of 25. No row starts after 60 s of the call: the rows not tried by then come back connected: false with
reasonCode timed_out (the call still succeeds); nothing was done for them, so send just those rows again. Sending
the same rows again is safe: an inbox that is already connected comes back connected: true. target_client_id picks the workspace when the run imports into several; an agent may only
connect into this workspace (403 forbidden detail target_not_admin otherwise). Also needs Delivery at Edit in
this workspace and the target (403 forbidden detail permission_denied). A row connects only an inbox this run
carried over into the target: any other email comes back connected: false with reasonCode inbox_rejected. Without target_client_id, a run
that creates a workspace which does not exist yet is 409 invalid_state detail workspace_not_created.
Returns {results: [{email, connected, inboxId, reasonCode, message}]}, one per row in request order.
reasonCode: inbox_rejected, smtp_probe_failed, inbox_member_owned (a member's own mailbox: only that
member can connect it), or timed_out (not tried within the call's 60 s budget: send it again). message is safe to show and never holds a password. 409 invalid_state detail
not_an_import for a discovery run; 404 not_found for a run outside the workspace.
connections-create
Write. POST https://api.ken.so/v1/migration-connections
Body (json): apiKey string, displayName string, instanceUrl string, vendor string
Connect another outbound tool with its API key so its data can be imported.
POST /api/v1/migration-connections. Needs the migrations flag and a workspace Admin. Sends Ken-Version 1.1.
vendor: instantly, smartlead, emailbison, salesforge, lemlist, apollo (demo is staff only; its test key is demo-ok),
or a preview vendor: replyio, salesloft, outreach. apollo also needs its own migrations_apollo flag, and
the preview vendors need migrations_preview_vendors: while it is off, 400 validation_failed detail vendor_unavailable.
outreach has no API key: a person connects it through migrations(operation="connections-create-connect-session").
instance_url is required for emailbison (https). Kenso checks the key with one vendor call and stores it encrypted;
the key is never returned (keySuffix is its last four characters). 400 validation_failed with detail key_rejected,
plan_required, scope_required or instance_unreachable when the vendor refuses; 503 when it does not answer.
Returns {id, vendor, displayName, instanceUrl, keySuffix, status, discoveredAt, lastVerifiedAt, firstRunAt,
lastRunAt, createdAt, createdByUserId}. Next: migrations(operation="connections-discover", connection_id=id).
runs-create
Write. POST https://api.ken.so/v1/migration-runs
Body (json): accounts array, connectionId integer, cutoverAt date-time, historyFromDate string
Start an import run from a discovered connection into this workspace.
POST /api/v1/migration-runs. Needs the migrations flag and a workspace Admin. Sends Ken-Version 1.1.
accounts: one object per source account to import, with keys
source_account_id (required, an account id from connections-discovery),
target_client_id (optional; defaults to this workspace, the only target an agent may write into),
campaign_ids (optional list of that account's campaign ids; omit or null for every non-archived campaign,
[] for none),
include_blocklist, include_inboxes, include_leads, include_history (optional booleans, default true).
include_inboxes also needs Delivery at Edit in the account's target: without it the run is 403 forbidden detail
permission_denied on accounts[i].includeInboxes; set include_inboxes false to import the rest. Kenso adds an
inbox it does not have only after its login works: one the source tool hands no working login for stays
skipped with reasonCode inbox_login_required until migrations(operation="runs-connect-smtp", ...) or a
Google or Microsoft connect adds it, and a later run puts it on its campaigns.
history_from_date: yyyy-MM-dd, not in the future; messages before it are not imported.
cutover_at: optional instant the other tool stops sending, ISO-8601 with Z or an offset
(2026-11-01T09:00:00Z); a value without one is refused.
An agent cannot create a new workspace (a person does that in the app) and cannot import into another
workspace: 403 forbidden detail target_not_admin. Answers 202 with a job {id, type: migration, status,
progress, resource {type: migration_run, id}}; follow it with migrations(operation="runs-get", run_id=id).
409 invalid_state detail run_already_active, not_discovered, vendor_unavailable (apollo while migrations_apollo
is off, a preview vendor while migrations_preview_vendors is off), or the connection status (key_rejected,
key_expired; connections-update-key replaces the key).
400 validation_failed detail unknown_account, unknown_campaign or duplicate on accounts[i].
connections-create-connect-session
Write. POST https://api.ken.so/v1/migration-connections/connect-sessions
Body (json): connectionId integer, vendor string
Get the consent link that connects Outreach (OAuth, no API key) so its data can be imported.
POST /api/v1/migration-connections/connect-sessions. Needs the migrations flag and a workspace Admin. Sends
Ken-Version 1.1. vendor: outreach (the only vendor that connects with OAuth). connection_id reconnects that
Outreach connection (its key is replaced, its runs stay); leave it out to add a new one. Writes nothing.
Returns {vendor, authorizationUrl, expiresAt}: give authorizationUrl to the person, who opens it in a browser
signed in to Kenso as themselves, before expiresAt (10 minutes). Outreach sends them back to Kenso, which finishes
the connect as that person; an agent cannot finish it. Then list connections with
migrations(operation="connections-list"). 400 validation_failed detail vendor_unavailable while Outreach is not
available to the workspace, 403 detail member_required for a key that names no person, 404 for a connection_id
that is not an Outreach connection of the workspace, 409 invalid_state detail run_already_active.
connections-delete
Write. DELETE https://api.ken.so/v1/migration-connections/{connectionId}
Path: connectionId
Delete a connection and its stored API key.
DELETE /api/v1/migration-connections/{connectionId}. Needs the migrations flag and a workspace Admin.
Sends Ken-Version 1.1. Deletes the stored key, then the connection; answers 204 with no body. Its runs stop
showing on the migration routes. 409 invalid_state detail run_already_active while a discovery or import
runs on it (cancel the run first). 404 not_found for a connection outside the workspace.
connections-discover
Write. POST https://api.ken.so/v1/migration-connections/{connectionId}/discover
Path: connectionId
Start a discovery: read the other tool's accounts, campaigns and counts in the background.
POST /api/v1/migration-connections/{connectionId}/discover. Needs the migrations flag and a workspace Admin.
Sends Ken-Version 1.1. Answers 202 with a job {id, type: migration, status, progress, resource
{type: migration_run, id}}; poll migrations(operation="runs-get", run_id=id) or jobs, then read the result with
migrations(operation="connections-discovery"). 409 invalid_state detail run_already_active while another
discovery or import runs on the connection, the connection status (key_rejected, key_expired) when the key
no longer works (replace it with migrations(operation="connections-update-key")), or vendor_unavailable while
the vendor's own flag is off (apollo: migrations_apollo; replyio, salesloft, outreach:
migrations_preview_vendors). 404 not_found for a connection outside the workspace
(and a demo connection for non-staff).
connections-discovery
Read. GET https://api.ken.so/v1/migration-connections/{connectionId}/discovery
Path: connectionId
Read the last discovery of a connection: the other tool's accounts and campaigns.
GET /api/v1/migration-connections/{connectionId}/discovery. Needs the migrations flag and a workspace Admin.
Sends Ken-Version 1.1. Returns the stored discovery document: the source accounts with their ids, names,
campaigns (ids, names, status) and counts. An account whose listing failed carries error (a code such as
scope_required) and may show no campaigns; one with more campaigns than discovery lists has
campaignsTruncated true and only its first 2000. Tell the user before importing such an account. Use those
account and campaign ids in migrations(operation="runs-create"). 404 not_found when the connection is outside
the workspace or has not been discovered yet.
connections-get
Read. GET https://api.ken.so/v1/migration-connections/{connectionId}
Path: connectionId
Read one connection to another outbound tool.
GET /api/v1/migration-connections/{connectionId}. Needs the migrations flag and a workspace Admin.
Sends Ken-Version 1.1. Same fields as connections-list. 404 not_found for a connection outside the workspace.
runs-get
Read. GET https://api.ken.so/v1/migration-runs/{runId}
Path: runId
Read one run with its progress, per-account status and the to-do counts.
GET /api/v1/migration-runs/{runId}. Needs the migrations flag and a workspace Admin. Sends Ken-Version 1.1.
Returns id, connectionId, vendor, kind, status (queued, discovering, running, cancel_requested, succeeded,
succeeded_with_errors, failed, canceled), options, counters (accounts {total, done}, entities, currentStage,
currentAccountId, currentCampaignId), waitingUntil (UTC, while the run waits for a vendor limit to reset; it
resumes by itself then, null otherwise), accounts (one per source account: target, include flags, status,
errorMessage) and todo: [{reasonCode, entityType, count}], the skipped and failed items and the notes worth
a look, largest first. Read the items behind a todo row with
migrations(operation="runs-items", run_id=..., reason_code=..., entity_type=...).
Staff can still read a run while the migrations flag is off. 404 not_found for a run outside the workspace.
runs-items
Read. GET https://api.ken.so/v1/migration-runs/{runId}/items
Path: runId
Query: accountId string, cursor string, entityType string, limit integer, reasonCode string, status string
List what a run did with each source record: imported, updated, unchanged, skipped or failed.
GET /api/v1/migration-runs/{runId}/items. Needs the migrations flag and a workspace Admin. Sends Ken-Version 1.1.
status: imported, updated, unchanged, skipped, failed. entity_type: blocklist_entry, inbox, campaign, lead,
message, daily_stat, workspace. account_id: a source account id. reason_code: one code from the run's todo
(for example write_failed), at most 64 characters. limit is 1..200 (default 50); pass
pagination.nextCursor back unchanged as cursor. Oldest first. Each item has id, runId, sourceAccountId,
targetClientId, entityType, sourceId, kenId, kenRef, status, reasonCode, reason, attempts, updatedAt. A lead
row's sourceId is {source campaign id}:{source lead id}, because one lead can sit in several campaigns.
Rows written into a client workspace the caller cannot read are left out. 404 not_found for a run outside the
workspace.
connections-list
Read. GET https://api.ken.so/v1/migration-connections
List the workspace's connections to other outbound tools.
GET /api/v1/migration-connections. Needs the migrations flag and a workspace Admin. Sends Ken-Version 1.1. Returns every connection (no paging): id, vendor, displayName, instanceUrl, keySuffix, status (active, key_rejected, key_expired), discoveredAt, lastVerifiedAt, firstRunAt, lastRunAt, createdAt, createdByUserId. The key itself is never returned.
runs-list
Read. GET https://api.ken.so/v1/migration-runs
Query: connectionId integer, cursor string, limit integer, status string
List discovery and import runs, newest first.
GET /api/v1/migration-runs. Needs the migrations flag and a workspace Admin. Sends Ken-Version 1.1. connection_id narrows to one connection. status: queued, discovering, running, cancel_requested, succeeded, succeeded_with_errors, failed, canceled. limit is 1..200 (default 50); pass pagination.nextCursor back unchanged as cursor. Each run has id, connectionId, vendor, kind (discovery, import), status, startedByKind, options, counters and timestamps; accounts and todo are empty here (read them with runs-get). waitingUntil is set while a working run waits for a vendor limit to reset (a daily cap) and holds no run slot.
vendors-list
Read. GET https://api.ken.so/v1/migration-vendors
List the outbound tools Kenso can import from, with what each one can bring over.
GET /api/v1/migration-vendors. Needs the migrations flag and a workspace Admin. Sends Ken-Version 1.1. Each vendor has vendor (the id connections-create takes), name, needsInstanceUrl, capabilities (for example blocklist, inboxes, campaigns) and keyHelpUrl (where the user finds their API key). A vendor with its own rollout flag (apollo: migrations_apollo; the preview vendors replyio, salesloft and outreach: migrations_preview_vendors) is listed only while that flag is on. outreach is also listed only once Kenso's Outreach app is configured, and it takes no API key: connect it with migrations(operation="connections-create-connect-session").
connections-update-key
Write. PATCH https://api.ken.so/v1/migration-connections/{connectionId}
Path: connectionId
Body (json): apiKey string, instanceUrl string
Replace the stored API key of a connection, for example after the vendor rejected or expired the old one.
PATCH /api/v1/migration-connections/{connectionId}. Needs the migrations flag and a workspace Admin.
Sends Ken-Version 1.1. Kenso checks the new key with the same vendor call as connections-create and answers
with the same refusals (400 validation_failed detail key_rejected, plan_required, scope_required or
instance_unreachable; 503 when the vendor does not answer). It keeps the connection id, so later runs
match the ledger of the earlier ones and skip what was already imported. instance_url applies to
emailbison only; omitted, the stored one is kept. 400 detail account_mismatch when the key belongs to
another vendor account than the connection, when it names no account while the connection recorded one, or
(on instanceUrl) when instance_url points to another emailbison host; add such a key with connections-create
instead. 409 invalid_state
detail run_already_active while a discovery or import runs on it, or discovery_changed when a discovery finished
while the key was checked (send it again). 404 not_found outside the workspace.
The key is never returned. Returns the connection, with status active and the new keySuffix.
An outreach connection has no API key (400 validation_failed detail connect_session_required): reconnect it with
migrations(operation="connections-create-connect-session", vendor="outreach", connection_id=id), which keeps
its id and runs.