Opportunities opportunities
Deals on your accounts: stage, amount, close date, owner and the people on each deal with their roles. One pipeline per workspace; stages are configurable.
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through opportunities_read and changes through opportunities_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: settings-change-currency, create, people-create, people-delete, fill-details, get, settings-get, get-stage-history, judge-stage, list, people-list, stages-list, stages-replace, update, people-update, settings-update
settings-change-currency
Write. Early access: needs opportunities on for the workspace. POST https://api.ken.so/v1/opportunity-settings/change-currency
Body (json): amounts string, currency string, dryRun boolean, fromCurrency string, rateDate date
Change the workspace currency and keep, convert or clear every deal amount in one step. Only on the user's explicit request: run dry_run=true first and confirm the counts and rate with them. Needs the workspace_settings permission.
POST /api/v1/opportunity-settings/change-currency. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent. currency: the new code, one of supportedCurrencies in opportunities(operation="settings-get"), such as EUR. amounts: keep (every amount keeps its number, only the currency changes), convert (every amount times today's reference rate, rounded to the new currency's minorUnits: cents for EUR, whole yen for JPY) or clear (every amount removed). dry_run: true answers the same way and writes nothing. rate_date (convert only, YYYY-MM-DD): send the rateDate the dry run answered with, so the change converts at exactly the rate the user confirmed; without it, the latest rate. It must be within the last 7 days. from_currency (optional): send the fromCurrency the dry run answered with; if the workspace currency changed since, the call is 409 currency_changed and nothing runs, so it never converts from a currency the user did not confirm. It changes every live deal with an amount, including amounts a person set (who set each amount, and its pin, stay as they were), and moves the live deals without one to the new currency. Deleted deals keep theirs. Returns data: dryRun, changed, fromCurrency, currency, amounts, opportunityCount (live deals with an amount), amountTotal (in fromCurrency) and settings; with convert also convertedAmountTotal, rate (1 fromCurrency = rate currency), rateDate and rateSource: ecb (the ECB reference rates), or bnm for a change to or from MDL (the National Bank of Moldova's EUR rate, crossed with the other currency's ECB rate of the same day; rateDate is that ECB day). currency equal to the workspace's changes nothing (changed false), unless from_currency names another currency (then 409 currency_changed). Errors: currency or from_currency invalid (not in supportedCurrencies; allowed lists them), currency rate_unavailable (the rate source publishes no rate for it; keep or clear still work), amounts out_of_range (a converted amount would pass 999999999999.99), 409 currency_changed (the currency changed meanwhile), 409 crm_amount_sync (convert and clear are refused while Kenso writes deal amounts to a connected CRM; keep still works), 503 (the rate source did not answer; retry later). A failure changes nothing.
create
Write. Early access: needs opportunities on for the workspace. POST https://api.ken.so/v1/opportunities
Body (json): accountId integer, amount number, closeDate date, currency string, customFields object, dealType string, lostReason string, lostReasonKey string, name string, nextStep string, ownerMemberId integer, primaryPersonId integer, probability integer, stage string, summary string
Open an opportunity (deal) on a target account. Returns 201 with the opportunity. Stages are configurable per workspace: call stages-list for valid keys before setting stage.
POST /api/v1/opportunities. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent. account_id: the target account (accounts tool). Move it later with update's account_id. fields (optional): name (1 to 300 characters; defaults to the account name), stage (a stage key; defaults to the first open stage), amount (0 or more), currency, close_date (YYYY-MM-DD), owner_member_id (a member of this workspace), primary_person_id (a person id, see the accounts tool's people operations; they also join the deal's people), next_step (up to 2,000 characters), summary (where the deal stands, up to 2,000 characters), lost_reason (a free-text note, up to 500), lost_reason_key (only with a lost stage: no_budget = No budget, timing = Timing, competitor = Chose a competitor, went_quiet = Went quiet, not_a_fit = Not a fit, other = Other), deal_type (new_business = New business, expansion = Expansion, renewal = Renewal; omit it and a deal on a customer account is expansion, any other new_business), probability (the deal's own win probability, a whole percent from 0 to 100; omit it to use the stage's), custom_fields (an object). snake_case or camelCase keys. Omit currency: it must equal the workspace currency (currency_mismatch lists it). An unknown stage key fails with out_of_range and the live keys. An agent's values are not pinned, so a person can change them later.
people-create
Write. Early access: needs opportunities on for the workspace. POST https://api.ken.so/v1/opportunities/{opportunityId}/people
Path: opportunityId
Body (json): isPrimary boolean, overwritePinned boolean, personId integer, role string
Put a person on an opportunity with a role. Returns 201 with the opportunity person.
POST /api/v1/opportunities/{opportunityId}/people. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. person_id: any live person in the workspace, on the deal's
account or not (the accounts tool's people operations find them). role: champion,
economic_buyer, approver, evaluator, user, executive_sponsor, blocker or unknown;
omitted, it is their stakeholder role on the account, else unknown. is_primary=true
also makes them the deal's primary person (fails with pinned_by_user when a person
set the primary person: leave it). A person already on the deal fails with
already_on_opportunity.
people-delete
Write. Early access: needs opportunities on for the workspace. DELETE https://api.ken.so/v1/opportunity-people/{opportunityPersonId}
Path: opportunityPersonId
Query: overwritePinned boolean (required)
Take a person off an opportunity. The person stays in the workspace. Only on the user's request.
DELETE /api/v1/opportunity-people/{opportunityPersonId}. Staff. Sends Ken-Version 1.1
and X-Ken-Actor: agent. opportunity_person_id is the id from people-list. Taking off
the primary person clears the deal's primary person. Someone a person put on the deal
or last changed, or a primary person a person set, fails with pinned_by_user: leave
them then. Returns 204 with no body.
fill-details
Write. Early access: needs opportunities on for the workspace. POST https://api.ken.so/v1/opportunities/{opportunityId}/fill-details
Path: opportunityId
Fill an opportunity's details from its context: summary and next step, plus amount, close date and person when stated. Ken never estimates a number and keeps every value a person, an import or a CRM set.
POST /api/v1/opportunities/{opportunityId}/fill-details. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Ken reads the deal's context (account research, emails and LinkedIn
messages with its people, meeting notes, calls, the source campaign, the stage history)
and writes summary (a few sentences on where the deal stands) and next_step, plus amount,
close_date and primary_person_id only when the context states them explicitly. The owner
is never set. A field is written only while it is empty or Ken wrote it last. Returns
the opportunity; summaryGeneratedAt says when Ken wrote the summary.
Errors: rate_limited (this deal was filled in the last 2 minutes; wait Retry-After),
quota_exceeded (the workspace's limit), invalid_state with no_context (the account has
no research, messages, meeting notes or calls yet: nothing to fill from), and
service_unavailable when the model did not answer (retry later).
get
Read. Early access: needs opportunities on for the workspace. GET https://api.ken.so/v1/opportunities/{opportunityId}
Path: opportunityId
Return one opportunity with its account, people, primary person and pinned fields.
GET /api/v1/opportunities/{opportunityId}. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. pinnedFields lists the fields a person set; leave those as
they are. source says who opened it (ken, manual, crm, api, workflow); a deal Ken
opened also carries sourceCampaignId, sourceStepOrder, sourceTouchId or
sourceMeetingId. dealType is new_business, expansion or renewal; a lost deal may carry
lostReasonKey (the picked reason) beside lostReason (the free-text note).
createdBy and updatedBy are {kind, memberId?}. people lists everyone
on the deal, primary first: {id, personId, role, isPrimary, person {id, fullName,
title, email}}; change them with the people-* operations.
settings-get
Read. Early access: needs opportunities on for the workspace. GET https://api.ken.so/v1/opportunity-settings
Read the workspace's opportunity settings: create trigger, currency, mark customer on won, automatic stage moves, quiet threshold, supported currencies.
GET /api/v1/opportunity-settings. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Returns data: createTrigger (meeting_booked, interested or never: when Ken opens an
opportunity on its own), currency (ISO 4217, one per workspace), markCustomerOnWon
(true: a move into a won stage marks the account a customer and blocklists its domains),
autoStageMoves (true by default: Ken moves deals into the stages whose autoMove is on, from
reply and meeting events and its stage judge; false: Ken moves no deal on its own),
quietAfterDays (7 to 60, default 14: the days with no reply, held meeting or connected
call on a deal's account before it goes quiet, DEV-5524; a meeting booked ahead keeps
it from going quiet, DEV-6076)
and supportedCurrencies: every code the workspace currency may be, in picker order, each
{code, name, group, minorUnits}. group is majors, europe, asia_pacific or
americas_middle_east_africa; minorUnits is the decimals an amount shows (0 for JPY, KRW,
ISK, HUF and IDR, else 2). The set is the 30 ECB currencies plus MDL. Read it before
opportunities(operation="settings-update") or
opportunities(operation="settings-change-currency"): any other code is refused.
get-stage-history
Read. Early access: needs opportunities on for the workspace. GET https://api.ken.so/v1/opportunities/{opportunityId}/stage-history
Path: opportunityId
Return a deal's stage history: each stage it entered, when, who moved it and how long it sat there.
GET /api/v1/opportunities/{opportunityId}/stage-history. Staff. Sends Ken-Version 1.1
and X-Ken-Actor: agent. Returns opportunityId, stage (now), stageChangedAt, isComplete
and entries, oldest first. Each entry: kind (created = the stage the deal opened in,
stage_changed, won, lost), stage, stageLabel (its name then), stageCategory (open,
won, lost), fromStage, enteredAt, leftAt, durationSeconds (how long it sat there:
until leftAt, or until now on the entry with isCurrent true), actorKind (user, agent,
api_key, system = Ken, workflow), actorMemberId (the member whose credential made it)
and, on a move Ken's stage judge made, reason. isComplete is false when Kenso has no
record of part of the history (a deal created or moved before Kenso recorded stage
events, or moved by a data fix): say so instead of reading the entries as every move.
A deal with no recorded event returns no entries.
judge-stage
Read. Early access: needs opportunities on for the workspace. POST https://api.ken.so/v1/opportunities/{opportunityId}/judge-stage
Path: opportunityId
Body (json): dryRun boolean, stages array
Preview Ken's stage decision on one opportunity (a dry run): would it move the deal, to which stage, and why. Writes nothing: no move, no event, no saved stage change.
POST /api/v1/opportunities/{opportunityId}/judge-stage with dryRun: true. Staff. Sends
Ken-Version 1.1 and X-Ken-Actor: agent. Ken's stage judge reads the deal's emails and
LinkedIn messages, meeting notes, calls and stage history, and the stage descriptions
(opportunities(operation="stages-list") description), and decides in one model call. It
considers only stages whose autoMove is on: an open stage other than interested,
meeting_booked and meeting_held as it is, one of those three only with a description, and
a won or lost stage only with a description. With the default stages there are none
(skipped, no_candidate_stages, no model call). A real move (a person's run or Ken's sweep,
never this preview) has the effects of any move into that category: into a won stage it
marks the account a customer and blocklists its domains while markCustomerOnWon is on,
and into a lost stage it moves the account to Lost, so the planner stops touching it.
stages (optional): up to 20
{key, autoMove?, description?} that override those stages' switch (true, false, or null
for the default) and description (up to 1000 characters; "" or null clears) for this run
only, to preview a change before a person saves it. Returns data: outcome (would_move,
stayed or skipped), fromStage, stage (the stage it would move to, else fromStage),
matchedStage, reason (names the stage description it matched) and skipReason
(auto_moves_off, closed_deal, pinned, no_candidate_stages, no_context or model_failed).
Errors: quota_exceeded (the workspace's limit; wait Retry-After), validation_failed (an
unknown stage key or a description over 1000 characters).
list
Read. Early access: needs opportunities on for the workspace. GET https://api.ken.so/v1/opportunities
Query: accountId integer, closeDateAfter date, closeDateBefore date, cursor string, limit integer, ownerMemberId integer, q string, sort string, sourceCampaignId integer, stage string, stageCategory string, staleDays integer
List opportunities (deals) in the workspace, each with its account. Filter by account, stage, stage category, owner, source campaign, close date, name text or days without activity.
GET /api/v1/opportunities. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
stage: comma-separated stage keys (OR). Stages are configurable per workspace, so
read the keys with the stages-list operation. stage_category: comma-separated, any of
open, won, lost. close_date_before and close_date_after are YYYY-MM-DD and
inclusive. q matches the opportunity name or the account name (up to 300
characters). stale_days (1 to 3650) returns only open deals with no activity for
that many days, quietest first (sort is ignored); won and lost deals never come
back. sort: -createdAt (default), closeDate, -amount, -stageChangedAt.
limit 1 to 200 (default 50). Pass pagination.nextCursor back unchanged with the
same filters and sort.
Each item: id, accountId, name, stage, stageCategory, stageChangedAt, lastActivityAt
(latest of stageChangedAt, updatedAt and the newest activity on the deal or its
account), amount,
currency, closeDate, ownerMemberId, primaryPersonId, source (ken, manual, crm, api,
workflow), sourceCampaignId, nextStep, lostReason, closedAt, customFields,
pinnedFields, account {id, name, primaryDomain}, primaryPerson, people (everyone on
the deal with their role, primary first), createdAt, updatedAt. Empty fields are omitted.
people-list
Read. Early access: needs opportunities on for the workspace. GET https://api.ken.so/v1/opportunities/{opportunityId}/people
Path: opportunityId
Query: cursor string, limit integer
List the people on an opportunity, each with their role and whether they are the primary person.
GET /api/v1/opportunities/{opportunityId}/people. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Oldest first; limit 1 to 200 (default 50), pass
pagination.nextCursor back unchanged. Each item: id (the opportunity person id the
people-update and people-delete operations take), opportunityId, personId, role
(champion, economic_buyer, approver, evaluator, user, executive_sponsor, blocker,
unknown), isPrimary, person {id, fullName, title, email}, createdAt, updatedAt.
People deleted from the workspace are left out.
stages-list
Read. Early access: needs opportunities on for the workspace. GET https://api.ken.so/v1/opportunity-stages
List the workspace's opportunity stages in pipeline order, with counts and totals. Stages are configurable per workspace: read the keys here before setting stage.
GET /api/v1/opportunity-stages. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent. One pipeline per workspace. Returns data.items: key (what stage takes), label, color (a palette name: gray, blue, violet, teal, green, amber, orange, red or pink; or an upper-case #RRGGBB hex such as #12AB9F; null when unset), category (open, won or lost), position, isSystem, isArchived, opportunityCount, amountTotal, and the weighted pipeline: winProbability (the stage's chance of winning, a whole percent from 0 to 100), defaultWinProbability (what it reads when none is set), isDefaultWinProbability and weightedAmountTotal (the sum of amount x probability / 100 over its deals: on an open stage each deal's own probability else the stage's, on a won or lost stage the stage's). The weighted open pipeline is the sum of weightedAmountTotal over the open stages. autoMove: whether Ken moves deals into the stage on its own (default on for interested, meeting_booked and meeting_held, off for every other stage; nothing moves while opportunities(operation="settings-get") autoStageMoves is off). description (absent when none): what the stage means, for Ken's stage judge; preview a decision with opportunities(operation="judge-stage"). The judge moves a deal into a won or lost stage only when that stage's autoMove is on and it has a description: a move into won marks the account a customer and blocklists its domains while markCustomerOnWon is on, and a move into lost moves the account to Lost, so the planner stops touching it. Only win probabilities can be changed from here (opportunities(operation="stages-replace")); stages, their autoMove and their description cannot: a person changes those in Settings > Pipeline.
stages-replace
Write. Early access: needs opportunities on for the workspace. PUT https://api.ken.so/v1/opportunity-stages
Body (json): stages array
Set the win probability of one or more opportunity stages. Nothing else about the stages changes. Only on the user's explicit request. Needs the workspace_settings permission.
GET then PUT /api/v1/opportunity-stages. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent. win_probabilities maps a stage key (from opportunities(operation="stages-list")) to its win probability: a whole percent from 0 to 100, or null to go back to the stage's default. Defaults: every won stage 100, every lost stage 0, Cold 5, Interested 10, Meeting booked 20, Meeting held 30, Qualified 40, Proposal 60, Nurture 5, any other open stage 10. The tool reads the stages and sends every one back as it is, with only the named stages' probabilities changed, so no stage is added, renamed, reordered, archived or removed, and no autoMove or description changes (they are not sent, which keeps them). The API enforces that for an agent: when the stages sent differ from the stored ones (a person edited them after the read), it refuses with 409 stages_changed and changes nothing, so call it again. An unknown key fails before anything is sent. Returns the stages as stages-list does, with each stage's weightedAmountTotal recomputed.
update
Write. Early access: needs opportunities on for the workspace. PATCH https://api.ken.so/v1/opportunities/{opportunityId}
Path: opportunityId
Body (json): accountId integer, amount number, closeDate date, currency string, customFields object, dealType string, lostReason string, lostReasonKey string, name string, nextStep string, overwritePinned boolean, ownerMemberId integer, primaryPersonId integer, probability integer, stage string, summary string
Update an opportunity: stage, amount, close date, owner and the rest. Null clears a field. A field a person set fails with pinned_by_user: leave it. Call stages-list for valid stage keys.
PATCH /api/v1/opportunities/{opportunityId}. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Absent keys stay unchanged; null clears a field.
changes keys: account_id, name, stage, amount, currency, close_date (YYYY-MM-DD),
owner_member_id, primary_person_id, next_step, summary, lost_reason, lost_reason_key,
deal_type, probability, custom_fields.
account_id moves the deal to another live account in the workspace (it cannot be
null; a merged account fails with account_merged and names the one to use). Both
accounts' stage follows their deals again, and a won deal marks its new account a
customer when the workspace's markCustomerOnWon is on: move one only on the user's
request. primary_person_id also puts that person in the deal's people.
summary is a few sentences on where the deal stands (up to 2,000 characters); the
opportunity returns summaryGeneratedAt only while the summary is the one Ken wrote.
stage is a key from the stages-list operation (configurable per workspace); an unknown
key fails with out_of_range and the live keys. lost_reason is a free-text note on why a
deal was lost. lost_reason_key is the reason picked from a set: no_budget (No budget),
timing (Timing), competitor (Chose a competitor), went_quiet (Went quiet), not_a_fit
(Not a fit) or other (Other). Send it only with a lost stage, or on a deal already in
one (validation_error "lostReasonKey needs a lost stage" otherwise); a move out of the
lost stages clears it, and null clears it. deal_type is new_business (New business),
expansion (Expansion) or renewal (Renewal) and cannot be null. A deal whose stage moves
past Meeting held (qualified, proposal, or a custom open stage after meeting_held) moves
its account to in_deal, unless the account is a customer, nurture, paused, network or
archived.
probability is the deal's own win probability, a whole percent from 0 to 100 (out_of_range
otherwise); null goes back to its stage's. It counts while the deal's stage is open: a won
or lost deal reads its stage's, and a value set while it is won or lost is stored but shows
only once it reopens. The opportunity returns probability (the one in effect),
probabilitySource (stage or deal) and weightedAmount (amount x probability / 100).
custom_fields merges per key: a key set to null is removed, other keys stay.
currency must equal the workspace currency.
pinnedFields on the opportunity lists what a person set; a change to one fails
with pinned_by_user. Leave it, and tell the user if it should change.
people-update
Write. Early access: needs opportunities on for the workspace. PATCH https://api.ken.so/v1/opportunity-people/{opportunityPersonId}
Path: opportunityPersonId
Body (json): isPrimary boolean, overwritePinned boolean, role string
Change a person's role on an opportunity, or whether they are its primary person.
PATCH /api/v1/opportunity-people/{opportunityPersonId}. Staff. Sends Ken-Version 1.1
and X-Ken-Actor: agent. opportunity_person_id is the id from people-list (not the
person id). Send role, is_primary or both. role: champion, economic_buyer, approver,
evaluator, user, executive_sponsor, blocker or unknown. is_primary=true makes them the
primary person (the previous one stays on the deal); false clears the primary person
when it is them. A primary person a person set, or the role of someone a person put on
the deal or last changed, fails with pinned_by_user: leave it.
settings-update
Write. Early access: needs opportunities on for the workspace. PATCH https://api.ken.so/v1/opportunity-settings
Body (json): autoStageMoves boolean, createTrigger string, currency string, markCustomerOnWon boolean, quietAfterDays integer
Change the workspace's opportunity settings. Absent fields stay unchanged. Only on the user's explicit request. Needs the workspace_settings permission.
PATCH /api/v1/opportunity-settings. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Send at least one field; none of them can be cleared.
create_trigger: meeting_booked, interested or never (when Ken opens an opportunity on
its own). currency: a code from supportedCurrencies in
opportunities(operation="settings-get"), such as USD or EUR (any other code is 400
invalid, with allowed listing them); it changes every
live opportunity's currency, and fails with 409 invalid_state (currency_in_use) while
any live opportunity has an amount: then use opportunities(operation="settings-change-currency"),
which keeps, converts or clears those amounts. mark_customer_on_won: true or false (default
true). While true, a move into a won stage marks the opportunity's account a customer
and puts its domains on the blocklist (reason customer), so its people get no more
outbound. auto_stage_moves: true or false (default true). While false, Ken moves no deal
between stages on its own (reply and meeting events, the stage judge); people, the API and
workflows still can, and Ken still opens deals as create_trigger says. An agent can switch
it off but not back on: true while it is off is 403 forbidden (requires_human), because
only a person turns it back on in Settings > Pipeline. quiet_after_days: 7 to 60 (default
14), the days with no reply, held meeting or connected call on a deal's account before the
nightly check flags the open deal as quiet (Today's "{deal} went quiet" row and quietSince
on opportunities; only while the workspace has the deal_quiet flag). A meeting booked
ahead on the account (not cancelled) keeps the deal from going quiet. A new value applies
from the next nightly check: a deal already flagged stays quiet until a reply, held meeting
or connected call lands or a meeting is booked. Out of range is 400 out_of_range. Returns
the settings as opportunity-settings get does.