Skip to Content
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.

CRM9 endpointsKen-Version: 2026-11-02AuthenticationWorkspacesErrors
MarkdownOpenAPI

Path parameters

The endpoints whose path names one of these take it as described here. An endpoint's own table lists a path parameter only when it describes it differently.

NameInTypeRequiredDescription
accountIdpathinteger (int64)required

Headers

The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.

NameInTypeRequiredDescription
Ken-Versionheaderstring, one of: 2026-11-02, 1.1optionalThe API version, a date in YYYY-MM-DD form. 1.1 is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and 404 where the path exists only in this version. A date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy.
X-Ken-Workspace-Idheaderinteger (int64)optionalThe id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers 400 workspace_required. A workspace you are not a member of answers 404 not_found.

List accounts in the current workspace

GET/v1/accountsaccounts.list
Permission
Accounts view
Rate limit
12,000 requests a minute per API key
Needs the accounts feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Filters: stage (comma = OR: new, researching, warming, engaged, meeting_booked, in_deal, onboarding, client, churned, nurture, paused, lost, network, not_a_fit, competitor, do_not_contact), stageGroup (comma = OR: to_sort, pipeline, customers, later, network, archive: to_sort is new, pipeline is researching to in_deal, customers is onboarding, client and churned, later is nurture, paused and lost, network is network, archive is not_a_fit, competitor and do_not_contact), ownerMemberId, domain (any domain, URL or email; normalized), q (name or domain contains), nextTouchBefore, latestSignalAfter (the latest signal's event time is at or after it), tagIds (comma = OR: accounts carrying any of these tags; up to 100 positive ids, anything else is 400 validation_failed), hasOpenOpportunity (true: accounts with an open opportunity, false: accounts without), isCustomer (true: customer accounts, false: the rest), accountType (comma = OR: prospect, client, lost, churned, partner, competitor, investor, do_not_contact; it follows the stage), fitsIcp (true: accounts that fit the ICP, which are the accounts Today surfaces for their signals: none of the account's domains is one of the workspace's own domains (Settings > Company domains and the Primary), its stage is in pipeline or later, and research has not scored its fit below 20 (an account not researched yet fits); false: the accounts that do not). sort: up to 3 comma-separated keys, each field (ascending), -field (descending), field:asc or field:desc, default -createdAt. Fields: createdAt, name, score, tier (ascending is tier 1 first), latestSignalAt, committee (the engaged share), pipelineAmount, nextTouchAt, lastTouchAt; an account with no value for a key comes last in both directions (-score: highest first, never scored last). Today's Heating up is latestSignalAfter=<now - 7 days>&fitsIcp=true&sort=-score&limit=4. Each item embeds its domains, its tagIds and, when it has one, its latestSignal, and carries openOpportunityCount, openPipelineAmount and openOpportunityStage, and, once handed off, its latest handoff. score (0-99), scoredAt, signalCount and engagedPeopleCount are absent until the account is first scored. expand=committee adds each account's committee: stakeholderCount, openSeatCount, coverage (covered stakeholders, and the total of stakeholders and open seats), roles (role, stakeholderCount and openSeatCount per role that has either) and run, Ken's latest run mapping the buying committee (omitted when Ken never mapped the account). Without expand there is no committee. limit: 1-1000, default 50.

ids (comma, 1 to 100 account ids) returns those accounts in one call, each exactly as GET /v1/accounts/{accountId} returns it, in the order sent: expand=stakeholders embeds up to 200 stakeholders each with their person (research is one account's read: use accounts.get). An id that is missing, deleted, another workspace's or outside the caller's account scope is left out; a merged id answers with the account it was merged into, and each account comes back once. Every account is on one page (pagination.hasMore is false). With ids, any other parameter but expand is 400 validation_failed. Requires Accounts view.

Parameters

NameInTypeRequiredDescription
stagequerystringoptionalComma-separated stages, OR: new, researching, warming, engaged, meeting_booked, in_deal, onboarding, client, churned, nurture, paused, lost, network, not_a_fit, competitor, do_not_contact.
stageGroupquerystringoptionalComma-separated stage groups, OR: to_sort (new), pipeline (researching to in_deal), customers (onboarding, client, churned), later (nurture, paused, lost), network (network), archive (not_a_fit, competitor, do_not_contact).
ownerMemberIdqueryinteger (int64)optional
domainquerystringoptionalA domain, website URL or email. Normalized to the registrable domain.
qquerystringoptionalContains, case-insensitive, on the name or any domain.
nextTouchBeforequerystring (date-time)optionalAccounts with an open touch due before this time.
latestSignalAfterquerystring (date-time)optionalAccounts whose latest signal's event time is at or after this time (inclusive).
tagIdsquerystringoptionalComma-separated tag ids, OR: accounts carrying any of them.
hasOpenOpportunityquerybooleanoptionaltrue: accounts with a live open opportunity; false: accounts without one.
isCustomerquerybooleanoptionaltrue: customer accounts; false: accounts that are not customers.
accountTypequerystringoptionalComma-separated account types, OR: prospect, client, lost, churned, partner, competitor, investor, do_not_contact. Matches the type the account reads, which follows its stage.
fitsIcpquerybooleanoptionaltrue: accounts that fit the ICP (none of the workspace's own domains, stage in pipeline or later, research fit unknown or at least 20); false: the accounts that do not.
sortquerystringoptionalUp to 3 comma-separated keys, each field, -field, field:asc or field:desc. Fields: createdAt, name, score, tier, latestSignalAt, committee, pipelineAmount, nextTouchAt, lastTouchAt. Default -createdAt.
expandquerystringoptionalComma-separated: committee (each account's committee summary), connections. With ids: stakeholders.
limitqueryinteger (int32)optional1 to 1000. Default 50.
cursorquerystringoptionalThe nextCursor of the previous page. Omit it for the first page.
idsquerystringoptionalComma-separated account ids, 1 to 100: returns those accounts as accounts.get does, in this order, in one call. Takes no other parameter but expand.
Request
curl -X GET "https://api.ken.so/v1/accounts?limit=50" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"

Response 200

data is a list of Account. Each item has these fields. The response also carries pagination.

Show the 67 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Create an account from its domains

POST/v1/accountsaccounts.create
Permission
Accounts edit
Credits
Varies with the request (account_research); Varies with the request (committee_mapping); 1 credit per valid email (email_found); Varies with the request (web_scrape); Spends credits, price not on the rate card yet (podcast_search); Spends credits, price not on the rate card yet (social_data_record)
Rate limit
4,800 requests a minute per API key
Needs the accounts feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

domains (1 to 20 domains, website URLs or work emails; the first is primary) is required. A domain another account owns is 409 conflict with detail domain_taken and that accountId: use that account instead. With account scope own, an account the caller cannot see is not named (the detail has no accountId), a missing, null or own ownerMemberId makes the caller the owner, and another member's is 403 permission_denied with scope: all. Fields a person sets are pinned. Ken resolves the company from Kenso Search and fills the name (else from the primary domain: acme.com becomes Acme), industry, size, HQ and LinkedIn page without pinning them. When research is on, it starts research, charged in credits for its AI work and for each web page or search Kenso reads for it. skipResearch=true creates the account without research or the committee run, so the create costs no credits; research can be started later in the Kenso app. sendsFromInboxId, sendsFromLinkedInAccountId and sendsFromFacebookAccountId are checked like on PATCH. Requires Accounts edit.

Parameters

NameInTypeRequiredDescription
skipResearchquerybooleanoptionalTrue: do not queue research or the committee run for the new account. Absent or false: queue them as before.

Request body

application/json, optional.

The account to create.

FieldTypeRequiredDescription
namestringoptional
stagestringoptionalOne of the 16 stages: new, researching, warming, engaged, meeting_booked, in_deal, onboarding, client, churned, nurture, paused, lost, network, not_a_fit, competitor or do_not_contact. Onboarding and client make the account a customer (admins only). Cannot be null.
networkLabelstringoptionalpartner, investor or personal: what kind of network contact an account at stage network is. Only with stage network (the stored stage, or stage network in the same body); null clears it, which reads as personal.
ownerMemberIdinteger (int64)optionalA member of this workspace, or null to clear.
fitScoreinteger (int32)optional0 to 100.
whyNowstringoptional
anglestringoptional
cadenceDaysinteger (int32)optional1 to 365. Cannot be null.
industrystringoptional
fundingRoundstringoptionalThe latest funding round, such as Series A. 1 to 100 characters.
employeeCountinteger (int32)optional
hqLocationstringoptionalWhere the company sits, as free text ("Berlin, Germany"). Filters read hqCity and hqCountry.
revenueRangestringoptionalThe annual revenue band in US dollars: under_1m, from_1m_to_10m, from_10m_to_50m, from_50m_to_100m, from_100m_to_1b or from_1b. Null clears it.
hqCitystringoptionalThe HQ city, 1 to 200 characters.
hqCountrystringoptionalThe HQ country: an ISO 3166-1 alpha-2 code such as DE, or a country name, stored as the code.
foundedYearinteger (int32)optionalThe year the company was founded, 1000 to 2100.
linkedinUrlstringoptionalThe company page, such as https://linkedin.com/company/acme.
kenCompanyIdinteger (int64)optionalThe company's Ken id: its id in Ken Search. Null clears it.
sendsFromInboxIdinteger (int64)optionalThe inbox this account's email touches send from: a member's primary inbox (owned, on the workspace's primary domain), or a shared campaign inbox on one of the workspace's cold sending domains. Null clears it, and the account owner's primary inbox sends.
sendsFromLinkedInAccountIdinteger (int64)optionalThe LinkedIn account this account's LinkedIn touches send from. It must have been connected by a member. Null clears it, and the LinkedIn account the owner connected sends.
sendsFromWhatsAppAccountIdinteger (int64)optionalThe WhatsApp account this account's WhatsApp touches send from. It must have been connected by a member. Null clears it, and the WhatsApp account the owner connected sends.
sendsFromFacebookAccountIdinteger (int64)optionalThe Facebook account this account's Facebook touches send from. It must have been connected by a member, and the workspace must have Facebook outreach on. Null clears it, and the lowest-id Facebook account the owner connected sends.
domainsarray of stringrequired1 to 20 domains, website URLs or work emails. The first is primary. Required.
sourcestringoptionalmanual, csv, search, promoted, workflow or api. Defaults to manual for a person and api otherwise.
Request
curl -X POST "https://api.ken.so/v1/accounts" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Northwind Labs",
  "domains": [
    "northwind.example.com"
  ],
  "stage": "new",
  "ownerMemberId": 1093,
  "whyNow": "Raised a $40M Series B in September and is hiring 12 engineers.",
  "angle": "Their outbound team doubled this year: one place to run email and LinkedIn.",
  "cadenceDays": 7,
  "industry": "Computer Software",
  "employeeCount": 240,
  "hqLocation": "Austin, Texas, United States"
}'

Response 201

data is a Account.

Show the 67 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Return one account

GET/v1/accounts/{accountId}accounts.get
Permission
Accounts view
Rate limit
12,000 requests a minute per API key
Needs the accounts feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

expand=stakeholders embeds up to 200 stakeholders with their person. expand=research embeds the research dossier (status, trigger, errorCode, researchedAt, isStale, whyNow, angle, fitScore, tagline, description, facts, links, pains, stack, signals, sources). The status is the latest run's; the dossier fields come from the latest succeeded run, so a refresh in progress still shows the previous dossier. trigger is add, manual, stale, touch, signal, meeting_booked, or agent for research an agent wrote (accounts.write-research). researchStatus (none | waiting_credits | queued | running | succeeded | failed) and researchedAt are on every account in get, list and search. score (0-99 from the signals of the last 90 days and the engaged people), scoredAt, signalCount, engagedPeopleCount and latestSignal (id, kind, title, occurredAt, detectedAt) are absent until the account is first scored. handoff is the latest hand-off to a teammate, omitted when there is none. Requires Accounts view.

Parameters

NameInTypeRequiredDescription
accountIdpathinteger (int64)requiredThe account.
expandquerystringoptionalComma-separated: stakeholders, research.
Request
curl -X GET "https://api.ken.so/v1/accounts/812" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"

Response 200

data is a Account.

Show the 67 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Update account fields

PATCH/v1/accounts/{accountId}accounts.update
Permission
Accounts edit
Rate limit
4,800 requests a minute per API key
Needs the accounts feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Absent fields stay unchanged; null clears.

Fields: name, stage, networkLabel, ownerMemberId (a workspace member), fitScore (0-100), whyNow, angle, cadenceDays (1-365), industry, fundingRound (1-100 characters), employeeCount, hqLocation, linkedinUrl, kenCompanyId (the company's Kenso id), sendsFromInboxId, sendsFromLinkedInAccountId, sendsFromFacebookAccountId. sendsFromInboxId is the inbox email touches send from: a member's primary inbox (owned and on the workspace's primary domain), or a shared campaign inbox on one of the workspace's cold sending domains, whose touches the account owner approves. sendsFromLinkedInAccountId is the LinkedIn account LinkedIn touches send from, connected by a member. sendsFromInstagramAccountId (PATCH only) is the Instagram account Instagram touches send from, one of this workspace's connected by a member. sendsFromFacebookAccountId is the Facebook account Facebook touches send from, connected by a member; it needs Facebook outreach on for the workspace (400 validation_failed with code not_enabled otherwise). Null on any of them means the owner's default. None is pinned, so an agent may change them. A bad id is 400 validation_failed with code not_found, not_owned, not_member (its member left the workspace) or email_domain_mismatch (the inbox is not on the workspace's email domain; the message says what fixes it). Only a changed id is checked, so a form that sends the stored ids back saves. A disconnected sender is accepted; its touches wait until it reconnects. Changing a field a person set is 409 conflict with pinned_by_user unless overwritePinned: true; nothing is applied partially. With account scope own, an account the caller does not own is 404 not_found, and an ownerMemberId other than the caller's own is 403 permission_denied with scope: all. Requires Accounts edit.

tierOverride (1 to the ladder's tierCount; a higher tier is 400 validation_failed) sets the account's tier by hand after the other fields are saved, and routes it to that tier's destination at once where the workspace has tier routing on (account-tiers); null is Auto: the account goes back to its auto tier (the tier the ladder placed it at, else its score's tier) without routing, and the ladder moves it from then on. Both write a tier change to the account's activity, with tier routing on or off. A tier whose move adds the account's people to a campaign, or stops the people the ladder put in one, also requires campaigns edit (403 permission_denied); both are checked before anything is saved. The response's tier is the hand-set tier, else autoTier. When another tier change on the account ran at the same time, the tier is not set and the response is 409 conflict; the other fields are saved. A campaign that refuses the people (the plan's lead limit) also leaves the tier unset, with the other fields saved.

isCustomer (true or false) marks the account a customer or clears it, after the other fields are saved. Only a workspace admin can change it (403 forbidden with code customer_not_allowed, checked before anything is saved); anyone else may send the stored value back, which leaves the flag as it is. true puts every domain of the account on the workspace blocklist with reason customer, so Ken sends its people nothing, and moves the stage to client unless it is onboarding or client already. false on an account at onboarding or client moves it to churned and keeps those rows; false on a customer at any other stage (flagged before stages carried the flag) takes off only those rows, and a domain blocked for another reason stays blocked. The response carries isCustomer, customerSince and customerSource (manual here).

stage is one of the 16 stages accounts.list names. The read's stageGroup is the group it sits in. The Customer flag and accountType follow the stage: onboarding and client make the account a customer (its domains go on the blocklist), and moving a customer off them clears the flag, to churned, lost, competitor or do_not_contact with its domains kept on the blocklist, to any other stage with them taken off. A stage that sets or clears the flag needs a workspace admin (403 forbidden with code customer_not_allowed, checked before anything is saved); a stage and an isCustomer that disagree in one body are 400 validation_failed. networkLabel (partner, investor or personal; null clears it) needs stage network, sent or held (400 validation_failed otherwise), and clears when the account leaves network.

accountType (prospect, client, lost, churned, partner, competitor, investor, do_not_contact; not null) is what the workspace calls the account. It moves the stage, after isCustomer: client to client; churned, competitor, do_not_contact and lost to the stage of that name; partner and investor to network with that label; prospect to researching when the stage reads another type, else nothing moves. With stage in the same body, stage wins and accountType is ignored. client is the customer flag: moving an account to client marks it a customer (its domains go on the blocklist) and moving a client to another type clears it, so either needs a workspace admin (403 forbidden with code customer_not_allowed, checked before anything is saved); the flag turning on or off any other way (a won opportunity to onboarding) moves the stage and so the type. Any other type change is open to anyone with accounts edit. accountType and isCustomer that disagree in one body are 400 validation_failed. Each change shows on the account's timeline. Only client changes sending by itself: any other type blocks the account's domains only while an enabled blocklist rule names it (accountTypes on /v1/blocklist-rules), except that a client moved to lost, churned, competitor or do_not_contact keeps its domains on the blocklist. Sending the type the account already has changes nothing. To stop contacting an account, put its domains on the blocklist.

Request body

application/json, optional.

FieldTypeRequiredDescription
namestringoptional
stagestringoptionalOne of the 16 stages: new, researching, warming, engaged, meeting_booked, in_deal, onboarding, client, churned, nurture, paused, lost, network, not_a_fit, competitor or do_not_contact. Onboarding and client make the account a customer (admins only). Cannot be null.
networkLabelstringoptionalpartner, investor or personal: what kind of network contact an account at stage network is. Only with stage network (the stored stage, or stage network in the same body); null clears it, which reads as personal.
ownerMemberIdinteger (int64)optionalA member of this workspace, or null to clear.
fitScoreinteger (int32)optional0 to 100.
whyNowstringoptional
anglestringoptional
cadenceDaysinteger (int32)optional1 to 365. Cannot be null.
industrystringoptional
fundingRoundstringoptionalThe latest funding round, such as Series A. 1 to 100 characters.
employeeCountinteger (int32)optional
hqLocationstringoptionalWhere the company sits, as free text ("Berlin, Germany"). Filters read hqCity and hqCountry.
revenueRangestringoptionalThe annual revenue band in US dollars: under_1m, from_1m_to_10m, from_10m_to_50m, from_50m_to_100m, from_100m_to_1b or from_1b. Null clears it.
hqCitystringoptionalThe HQ city, 1 to 200 characters.
hqCountrystringoptionalThe HQ country: an ISO 3166-1 alpha-2 code such as DE, or a country name, stored as the code.
foundedYearinteger (int32)optionalThe year the company was founded, 1000 to 2100.
linkedinUrlstringoptionalThe company page, such as https://linkedin.com/company/acme.
kenCompanyIdinteger (int64)optionalThe company's Ken id: its id in Ken Search. Null clears it.
sendsFromInboxIdinteger (int64)optionalThe inbox this account's email touches send from: a member's primary inbox (owned, on the workspace's primary domain), or a shared campaign inbox on one of the workspace's cold sending domains. Null clears it, and the account owner's primary inbox sends.
sendsFromLinkedInAccountIdinteger (int64)optionalThe LinkedIn account this account's LinkedIn touches send from. It must have been connected by a member. Null clears it, and the LinkedIn account the owner connected sends.
sendsFromWhatsAppAccountIdinteger (int64)optionalThe WhatsApp account this account's WhatsApp touches send from. It must have been connected by a member. Null clears it, and the WhatsApp account the owner connected sends.
sendsFromFacebookAccountIdinteger (int64)optionalThe Facebook account this account's Facebook touches send from. It must have been connected by a member, and the workspace must have Facebook outreach on. Null clears it, and the lowest-id Facebook account the owner connected sends.
customFieldsmap of objectoptionalCustom field values by key (the fields of GET /v1/fields), merged per key: send only the keys to change, and a key as null to clear it. Each value is read as its field's type: text and url a string, number a number, boolean true or false, date a date or an ISO 8601 time, select an option's key or label, multi_select a list of them, currency {"amount": 1200.50, "currency": "USD"}, user a member id. A key no field names, an archived field or a value of the wrong type is 400 with details on customFields.<key>. A person's value pins the field as custom.<key>, like the built-in fields. Needs the custom_fields feature.
overwritePinnedbooleanoptionalChange fields a person set. Send true only when the user asked for this change.
sendsFromInstagramAccountIdinteger (int64)optionalThe Instagram account this account's Instagram touches send from: one of this workspace's, connected by a member. Null clears it, and the Instagram account the owner connected sends. The account owner or an admin changes it, as with the other Sends from fields.
tierOverrideinteger (int32)optional1 to the ladder's tierCount (at most 10) sets the account's tier by hand and routes it there at once; null is Auto (the account keeps its tier and the ladder moves it from then on).
isCustomerbooleanoptionaltrue marks the account a customer and puts its domains on the blocklist (reason customer); false clears it and takes off only the rows the flag added. Admins only (403 customer_not_allowed). Cannot be null.
accountTypestringoptionalprospect, client, lost, churned, partner, competitor, investor or do_not_contact. It moves the stage: client to client; churned, competitor, do_not_contact and lost to that stage; partner and investor to network with that label; prospect to researching from a stage that reads another type. client is the customer flag: moving to client sets isCustomer and moving a client away clears it, so either needs an admin (403 customer_not_allowed). Ignored when the body also sends stage. Cannot be null.
Request
curl -X PATCH "https://api.ken.so/v1/accounts/812" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "stage": "meeting_booked",
  "fitScore": 88,
  "whyNow": "Booked a demo after the Series B announcement; the VP of Engineering owns the budget."
}'

Response 200

data is a Account.

Show the 67 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Delete an account

DELETE/v1/accounts/{accountId}accounts.delete
Permission
Accounts edit
Rate limit
4,800 requests a minute per API key
Needs the accounts feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Frees its domains, removes its stakeholders (people stay), skips its open touches and deletes its opportunities. Returns 204. Requires Accounts edit access (owners, admins and editors by default).

Request
curl -X DELETE "https://api.ken.so/v1/accounts/812" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"

Response 204

Response 204
HTTP/1.1 204 No Content

Create up to 100 accounts in one call

POST/v1/accounts/bulk-createaccounts.bulk-create
Permission
Accounts edit
Credits
Varies with the request (account_research); Varies with the request (committee_mapping); 1 credit per valid email (email_found); Varies with the request (web_scrape); Spends credits, price not on the rate card yet (podcast_search); Spends credits, price not on the rate card yet (social_data_record)
Rate limit
240 requests a minute per API key
Needs the accounts feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

items (1 to 100) are each a POST /v1/accounts body. Returns 200 with one result per item in request order: created (with the account and research: queued or waiting_credits), domain_taken (the accountId that already owns domain; counted in skipped), invalid (field, code and error of the item's first problem) or failed (retry that item). The same domain twice in one call (acme.com and www.acme.com) creates once; the repeat is domain_taken. Duplicates are by domain only: acme.com and acme.io are two accounts. Ken resolves each company from Kenso Search and, when research is on, starts research per created account, charged in credits for its AI work and for each web page or search Kenso reads for it; research waits for credits when the balance is short. With account scope own, every created account is the caller's, and an item naming another member's ownerMemberId is invalid with code permission_denied. Requires Accounts edit.

Request body

application/json, optional.

FieldTypeRequiredDescription
itemsarray of CreateAccountBodyrequired1 to 100 accounts. Each item is a POST /v1/accounts body. Required.
Request
curl -X POST "https://api.ken.so/v1/accounts/bulk-create" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "name": "Northwind Labs",
      "domains": [
        "northwind.example.com"
      ],
      "stage": "new",
      "ownerMemberId": 1093,
      "whyNow": "Raised a $40M Series B in September and is hiring 12 engineers.",
      "angle": "Their outbound team doubled this year: one place to run email and LinkedIn.",
      "cadenceDays": 7,
      "industry": "Computer Software",
      "employeeCount": 240,
      "hqLocation": "Austin, Texas, United States"
    },
    {
      "name": "Contoso Analytics",
      "domains": [
        "contoso.example.com"
      ]
    }
  ]
}'

Response 200

data is a BulkCreateAccountsResult.

Show the 4 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Merge an account into another account that is the same company

POST/v1/accounts/{accountId}/mergeaccounts.merge
Permission
Accounts edit
Rate limit
4,800 requests a minute per API key
Needs the accounts feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

The account in the path is merged into intoAccountId, the account to keep, in one step. The kept account keeps every field a person set; otherwise a field a person set on the merged account wins, and a blank field takes the merged value. Domains, stakeholders, touches, research, committee runs and seats, email finds, Studio pages, opportunities, bookings, booking links, meetings, calendar guests, tags and the timeline move to the kept account. A person on both accounts becomes one stakeholder. Unsent touches are skipped (account_merged) when the kept account already has an open touch. Returns the kept account. The merged id then reads as the kept account, and a write to it is 409 conflict with account_merged and mergedIntoId. There is no unmerge. Merging an account into itself is 400 (same_account); a merged account on either side is 409 (account_merged). With account scope own both accounts must be the caller's; another member's is 404. Requires accounts edit, like delete.

Request body

application/json, optional.

FieldTypeRequiredDescription
intoAccountIdinteger (int64)requiredThe account to keep. The account in the path is merged into it. Required.
Request
curl -X POST "https://api.ken.so/v1/accounts/812/merge" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "intoAccountId": 6120
}'

Response 200

data is a Account.

Show the 67 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Add the account's people with no 1:1 touch planned to a campaign

POST/v1/accounts/{accountId}/add-to-campaignaccounts.add-to-campaign
Permission
Accounts edit and Campaigns edit
Rate limit
4,800 requests a minute per API key
Needs the accounts feature on your workspace. Until it is on, calls answer 404. Needs the nurture_air_cover feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Body: campaignId (required: a campaign of this workspace that is not archived or completed) and who: not_yet_contacted (default: people nobody ever sent a 1:1 touch, a member mailbox email or a campaign email) or everyone_mapped. A person joins when they are a stakeholder with an email, targeted and not a blocker. The economic buyer, anyone with a 1:1 touch planned and anyone touched in the last 30 days stay out, and so does anyone another open campaign already holds, so an account's people join one campaign (the first add wins). People are imported like a lead upload (dedup, blocklist, lead credits); the campaign's own sequence sends to them. Returns added, alreadyIn (people the campaign already had) and skipped (people the rules or another campaign held back, or the import left out), and writes "N people with no 1:1 touch added to {campaign}" on the account timeline when it added anyone. Running it again adds nobody twice. An account or campaign not in the workspace is 404 not_found; an archived or completed campaign is 409 invalid_state with campaign_closed. When the plan's lead credits refuse the import before anyone joined, the answer is 402 plan_limit_reached with the refusal. With account scope own, an account the caller does not own is 404. Requires accounts edit and campaigns edit, and the nurture_air_cover feature.

Request body

application/json, optional.

FieldTypeRequiredDescription
campaignIdinteger (int64)requiredThe campaign the people join, a live campaign of this workspace that is not archived or completed. Required.
whostringoptionalnot_yet_contacted (default): people nobody has touched yet. everyone_mapped: every mapped person not touched in 30 days.
Request
curl -X POST "https://api.ken.so/v1/accounts/812/add-to-campaign" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "campaignId": 4821,
  "who": "not_yet_contacted"
}'

Response 200

data is a AccountCampaignPeople.

Show the 6 response fields and an example

The fields and an example are also on this endpoint's Markdown page.


On this page