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

# Accounts: Update account fields

> **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.

One endpoint of [Accounts](/docs/api/accounts.md). Authentication, workspaces and errors: [/docs.md](/docs.md).

## Update account fields

`PATCH /v1/accounts/{accountId}` - operationId `accounts.update`

| Permission | Rate limit |
| --- | --- |
| Accounts edit | 4,800 requests a minute per API key |

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, sendsFromImessageLineId,
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.
`sendsFromImessageLineId` is the iMessage line the account's texts usually send from: a line of this workspace
that has not ended (ordered, active, paused, cancelling or down) whose owner is a current member. A first text goes
from an active line in the person's country: this line when it is one, else the account owner's line there, else the
workspace's oldest line there; with none there, it goes from this line. A person who already has a thread keeps that
thread's line. The owner of the line a text goes from approves it. Null clears it: a first text with no active line
in the person's country then goes from the account owner's first active line.
`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
the others 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 can't send from it anymore) 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. Only the account owner, a
workspace admin or staff changes a Sends from id: anyone else gets `403 forbidden` with `details[].code` `sends_from_not_allowed` on each such field, and nothing is saved.
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.

Needs the `accounts` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/accounts/PATCH/v1/accounts/%7BaccountId%7D)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `accountId` | path | integer (int64) | yes |  |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The 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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The 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`. |

### Request body

`application/json`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no |  |
| `stage` | string | no | One 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. |
| `networkLabel` | string | no | partner, 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. |
| `ownerMemberId` | integer (int64) | no | A member of this workspace, or null to clear. |
| `fitScore` | integer (int32) | no | 0 to 100. |
| `whyNow` | string | no |  |
| `angle` | string | no |  |
| `cadenceDays` | integer (int32) | no | 1 to 365. Cannot be null. |
| `industry` | string | no |  |
| `fundingRound` | string | no | The latest funding round, such as Series A. 1 to 100 characters. |
| `employeeCount` | integer (int32) | no |  |
| `hqLocation` | string | no | Where the company sits, as free text ("Berlin, Germany"); where filters it with contains. hqCity and hqCountry are the structured, exact-match fields. |
| `revenueRange` | string | no | The 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. |
| `hqCity` | string | no | The HQ city, 1 to 200 characters. |
| `hqCountry` | string | no | The HQ country: an ISO 3166-1 alpha-2 code such as DE, or a country name, stored as the code. |
| `foundedYear` | integer (int32) | no | The year the company was founded, 1000 to 2100. |
| `linkedinUrl` | string | no | The company page, such as https://linkedin.com/company/acme. |
| `kenCompanyId` | integer (int64) | no | The company's Ken id: its id in Ken Search. Null clears it. |
| `sendsFromInboxId` | integer (int64) | no | The 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. |
| `sendsFromLinkedInAccountId` | integer (int64) | no | The 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. |
| `sendsFromWhatsAppAccountId` | integer (int64) | no | The 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. |
| `sendsFromImessageLineId` | integer (int64) | no | The iMessage line this account's texts usually send from: a line of this workspace that has not ended, owned by a current member. A first text goes from an active line in the person's country (this one, else the account owner's, else the oldest), else from this line; a person with a thread keeps its line. The owner of the line a text goes from approves it. Null clears it: the owner's first active line then stands in for this one. |
| `sendsFromFacebookAccountId` | integer (int64) | no | The 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. |
| `customFields` | map of object | no | Custom field values by field key (a record's customFields shows the keys), 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. |
| `overwritePinned` | boolean | no | Change fields a person set. Send true only when the user asked for this change. |
| `sendsFromInstagramAccountId` | integer (int64) | no | The 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. |
| `tierOverride` | integer (int32) | no | 1 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). |
| `isCustomer` | boolean | no | true 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. |
| `accountType` | string | no | prospect, 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. |

### Response 200

`data` is a `Account`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) |  |
| `name` | string |  |
| `mergeSummary` | AccountMergeSummary | Only on the answer of accounts.merge: what the merge changed and moved, or would with `dryRun`. |
| `stage` | string | One 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. A newer build may write a value this list does not have yet; read it as a pipeline stage. |
| `stageGroup` | string | to_sort, pipeline, customers, later, network or archive: the group the stage sits in. Always present; a stage this build does not know reads as pipeline. |
| `networkLabel` | string | partner, investor or personal: what kind of network contact an account at stage network is. Omitted otherwise, and when unset (personal). |
| `stageChangedAt` | string (date-time) |  |
| `ownerMemberId` | integer (int64) |  |
| `fitScore` | integer (int32) |  |
| `whyNow` | string |  |
| `angle` | string |  |
| `cadenceDays` | integer (int32) |  |
| `nextTouchAt` | string (date-time) |  |
| `lastTouchAt` | string (date-time) | The latest of a sent or done touch and the latest outbound email or LinkedIn message to the account's people. Null when there is neither. LinkedIn counts campaign invites, messages and InMails; a LinkedIn message sent from the Inbox does not count. |
| `source` | string |  |
| `primaryDomain` | string |  |
| `domains` | array of AccountDomain |  |
| `industry` | string |  |
| `fundingRound` | string |  |
| `employeeCount` | integer (int32) |  |
| `hqLocation` | string |  |
| `revenueRange` | string | The 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. fieldSources.revenueRange estimate means Ken read it off the headcount. |
| `hqCity` | string |  |
| `hqCountry` | string | ISO 3166-1 alpha-2, upper case. |
| `foundedYear` | integer (int32) |  |
| `linkedinUrl` | string |  |
| `kenCompanyId` | integer (int64) | The company's Ken id: its id in Ken Search. |
| `logoUrl` | string | The LinkedIn company logo from Ken Search for kenCompanyId, an http(s) URL. Omitted when Ken has none; show the primary domain's favicon instead. The URL can stop loading, so fall back on an image error too. |
| `sendsFromInboxId` | integer (int64) | The inbox email touches send from. Omitted means the owner's primary inbox. |
| `sendsFromLinkedInAccountId` | integer (int64) | The LinkedIn account LinkedIn touches send from. Omitted means the one the owner connected. |
| `sendsFromInstagramAccountId` | integer (int64) | The Instagram account Instagram touches send from. Omitted means the one the owner connected. |
| `sendsFromWhatsAppAccountId` | integer (int64) | The WhatsApp account WhatsApp touches send from. Omitted means the one the owner connected. |
| `sendsFromFacebookAccountId` | integer (int64) | The Facebook account Facebook touches send from. Omitted means the owner's lowest-id connected one. |
| `sendsFromImessageLineId` | integer (int64) | The iMessage line this account's texts usually send from. A first text goes from an active line in the person's country: this one, else the account owner's line there, else the workspace's oldest line there; with none there, from this line. A person who already has a thread keeps that thread's line. The owner of the line a text goes from approves it. Omitted means none is set: the account owner's first active line then stands in for this one. |
| `tier` | integer (int32) | 1 to the ladder's tierCount: the tier the account is worked at, tierOverride when a person set one, else autoTier. Always present. A tier past the ladder's tierCount (it was shortened later) reads as its last tier. |
| `autoTier` | integer (int32) | 1 to the ladder's tierCount: the tier Auto puts the account at, the tier the ladder placed it at, else the tier its score falls in on the workspace's ladder (an account not scored yet reads score 0, the last tier). Always present, also while tierOverride is set: it is the tier the account goes back to when tierOverride clears, unless the hand-set tier moved the account to a lane autoTier does not work (a campaign or Watch): Auto then keeps the hand-set tier, so the tier matches where the account is. |
| `tierOverride` | integer (int32) | 1 to 10 when a person set the tier by hand (up to the ladder's tierCount). Omitted for Auto. |
| `tierReason` | AccountTierReason | Why the account sits at its tier; omitted while the feature is off, before a placement, after the tier moved, and under tierOverride. |
| `isCustomer` | boolean | The workspace's customer: its domains are on the blocklist (reason customer), so Ken sends its people nothing. Always present. |
| `customerSince` | string (date-time) | When the account last became a customer. Omitted while it is not one. |
| `customerSource` | string | manual, opportunity_won or crm: what made it a customer. Omitted while it is not one. |
| `accountType` | string | prospect, client, lost, churned, partner, competitor, investor or do_not_contact. It follows the stage: onboarding and client read client; churned, competitor, do_not_contact and lost read that type; network reads partner or investor by its label; any other stage reads prospect, or the type stored before stages carried it. Always present; prospect by default. |
| `customFields` | map of object | The record's custom field values by key (the fields the workspace defined): a string, number or boolean, a list of option keys for a multi_select field, `{amount, currency}` for a currency field. A select field holds its option's key. Empty when none is set. |
| `customFieldMeta` | map of CustomFieldMeta | Who or what last set each custom field, by key. Absent when no value has a record of it. |
| `pinnedFields` | array of string |  |
| `fieldSources` | map of string | Where each field's value came from, by wire name: user or crm (a person set it, pinned), ken_search, research, estimate, agent, api_key, workflow or system. A field with no recorded source is left out. |
| `createdBy` | Actor | Who created or last changed a record. |
| `updatedBy` | Actor | Who created or last changed a record. |
| `createdAt` | string (date-time) |  |
| `updatedAt` | string (date-time) |  |
| `score` | integer (int32) | 0 to 99 from the account's signals of the last 90 days (each kind once, weighted by age) and its engaged people. Null until the account is first scored. |
| `scoredAt` | string (date-time) | When the score was last computed. |
| `signalCount` | integer (int32) | Signals whose event time is in the last 90 days, as of scoredAt. |
| `engagedPeopleCount` | integer (int32) | Distinct live stakeholders who replied, met or viewed an asset in 90 days, or whose coverage is engaged. |
| `latestSignal` | AccountSignalSummary | The signal with the latest event time, any age. Null when the account has none. |
| `recentSignalKinds` | array of string | The distinct kinds of the account's signals whose event time, when it happened else when Ken found it, is in the last 90 days, in this order: funding, hiring, leadership_hire, job_change, headcount_growth, news, public_post, event, tech_change, asset_view, reply, meeting, web_visit. The signal filter's window, but stored kinds, not filter values: the job_change filter value also matches leadership_hire. Read live, so it does not wait for the next score. Omitted when there are none. |
| `openOpportunityCount` | integer (int32) | Live opportunities in an open stage (0 when none). Filled by get, list and search while the opportunities feature is on for the caller; omitted on a write response and when the feature is off. |
| `openPipelineAmount` | number (double) | Sum of the open opportunities' amounts in the workspace currency; omitted when none has an amount. |
| `openOpportunityStage` | string | Stage key of the newest open opportunity; omitted when none is open. |
| `stakeholders` | array of Stakeholder | Only with expand=stakeholders (up to 200; page the rest with stakeholders.list). |
| `committee` | CommitteeSummary | Only with expand=committee on accounts.list: the committee's counts, coverage and latest run. |
| `plan` | AccountPlan | Only on accounts.get. |
| `reengageAfter` | string (date) | The day Ken re-engages a lost account: the day its latest lost opportunity closed, in the planner's time zone, plus 180 days. On an account at stage lost whose deal is lost (list, search, get); omitted otherwise, on a write response and while re-engagement is off. |
| `tagIds` | array of integer (int64) | Ids of the live tags on the account, ascending. Always present; [] when none. |
| `handoff` | AccountHandoff | The latest hand-off to a teammate. Omitted when the account was never handed off. |
| `researchStatus` | string | Latest research run's status: none \| waiting_credits \| queued \| running \| succeeded \| failed (list, search, get). |
| `researchedAt` | string (date-time) | When the latest successful research finished. |
| `research` | AccountResearch | Only with expand=research. |
| `importOnlyAt` | string (date-time) | When the LinkedIn connections import added the account: nobody has worked it yet, so it stays out of All and Ken runs nothing on it. Omitted once someone works it, and for every other account. |
| `connections` | AccountConnections | Only with expand=connections: the teammates' LinkedIn connections at the account. Omitted when none. |
| `whyNotNow` | AccountWhyNotNow | The account's current reason not to reach out now: a stop or a wait. Omitted when there is none, and once it was undone or a wait was released. Read it before any touch: while it is a stop, or a wait whose `until` is ahead, Kenso sends the account nothing but replies and meeting emails. |

### Request

```bash
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."
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "id": 6120,
    "name": "Northwind Labs",
    "stage": "engaged",
    "stageGroup": "pipeline",
    "stageChangedAt": "2026-10-13T16:22:05Z",
    "ownerMemberId": 1093,
    "fitScore": 82,
    "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,
    "nextTouchAt": "2026-10-16T14:00:00Z",
    "lastTouchAt": "2026-10-13T16:22:05Z",
    "source": "api",
    "primaryDomain": "northwind.example.com",
    "domains": [
      {
        "id": 8801,
        "domain": "northwind.example.com",
        "isPrimary": true
      }
    ],
    "industry": "Computer Software",
    "fundingRound": "Series B",
    "employeeCount": 240,
    "hqLocation": "Austin, Texas, United States",
    "kenCompanyId": 3318204,
    "tier": 1,
    "autoTier": 1,
    "isCustomer": false,
    "accountType": "prospect",
    "pinnedFields": [
      "whyNow"
    ],
    "customFields": {
      "renewal_date": "2027-01-31T00:00:00Z"
    },
    "createdBy": {
      "kind": "user",
      "memberId": 1093
    },
    "updatedBy": {
      "kind": "user",
      "memberId": 1093
    },
    "createdAt": "2026-09-23T15:02:11Z",
    "updatedAt": "2026-10-14T09:41:27Z",
    "score": 64,
    "scoredAt": "2026-10-14T09:41:27Z",
    "signalCount": 2,
    "engagedPeopleCount": 1,
    "latestSignal": {
      "id": 4410,
      "kind": "funding",
      "title": "Raised a $40M Series B",
      "occurredAt": "2026-09-18T00:00:00Z",
      "detectedAt": "2026-09-23T15:02:11Z"
    },
    "recentSignalKinds": [
      "funding",
      "hiring"
    ],
    "openOpportunityCount": 1,
    "openPipelineAmount": 48000,
    "openOpportunityStage": "qualified",
    "tagIds": [
      341
    ],
    "researchStatus": "succeeded",
    "researchedAt": "2026-09-23T15:02:11Z"
  }
}
```

## Types

Each named type the tables above use, nested ones included.

### AccountMergeSummary

What a merge changed and moved, on the answer of accounts.merge. With `dryRun` nothing was written: this is what the merge would do.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isDryRun` | boolean | no | True when the call was a dry run: nothing was written. |
| `mergeId` | integer (int64) | no | The id of this merge's log entry, on a merge that was written. |
| `fieldChanges` | array of AccountMergeFieldChange | yes | The kept account's fields the merge changes, each with the value before and the value after. |
| `moved` | AccountMergeMoved | yes | How many records of each kind move to the kept account. |

### AccountDomain

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer (int64) | no |  |
| `domain` | string | yes |  |
| `isPrimary` | boolean | no |  |

### AccountTierReason

Why Ken placed the account at its tier. Who is the tier's "who belongs here" text; Probabilities is keyed by tier number.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `tier` | integer (int32) | no |  |
| `tierName` | string | no |  |
| `who` | string | no |  |
| `confidence` | number (double) | no |  |
| `probabilities` | map of number (double) | no |  |
| `facts` | AccountTierReasonFacts | yes |  |
| `next` | AccountTierReasonNext | no |  |
| `placedAt` | string (date-time) | no |  |

### CustomFieldMeta

Who or what last set a custom field's value on a record, and when.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `source` | string | yes | `user` (a member, in the app), `crm` (your CRM), `agent` (Ken or another agent), `api_key`, `workflow` or `system`. A `user` or `crm` value is pinned: the field is listed in `pinnedFields` as `custom.<key>`. |
| `at` | string (date-time) | no | When the value was set. |
| `memberId` | integer (int64) | no | The member who set it, or who the agent or key acted for. Absent when no member did. |

### Actor

Who created or last changed a record.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | string | yes | Who made the change: `user` (a member in the app), `agent` (Ken or another AI agent), `api_key`, `workflow` or `system` (Kenso itself). |
| `memberId` | integer (int64) | no | The id of the member behind the change. Omitted when no member is. |

### AccountSignalSummary

An account's latest signal, embedded in the account.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer (int64) | no |  |
| `kind` | string | yes | funding, hiring, leadership_hire, job_change, headcount_growth, news, public_post, event, tech_change, asset_view, reply, meeting, web_visit. |
| `title` | string | yes |  |
| `occurredAt` | string (date-time) | no | When it happened, when the source says. |
| `detectedAt` | string (date-time) | no |  |

### Stakeholder

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer (int64) | no |  |
| `accountId` | integer (int64) | no |  |
| `personId` | integer (int64) | no |  |
| `role` | string | yes |  |
| `priority` | integer (int32) | no |  |
| `coverage` | string | yes |  |
| `note` | string | no |  |
| `reportsToStakeholderId` | integer (int64) | no | The stakeholder on the same account this person reports to. |
| `kenNote` | string | no | Ken's longer note for the person rail. |
| `source` | string | yes |  |
| `pinnedFields` | array of string | yes |  |
| `person` | PersonSummary | no | A short view of a person, as an account's stakeholder carries it. |
| `createdBy` | Actor | yes | Who created or last changed a record. |
| `updatedBy` | Actor | yes | Who created or last changed a record. |
| `createdAt` | string (date-time) | no |  |
| `updatedAt` | string (date-time) | no |  |
| `warmPath` | WarmPath | no | The strongest warm path to this person through the team's LinkedIn network on the stakeholder reads. Omitted when there is none or the workspace's `linkedin_network` feature is off. |

### CommitteeSummary

The account's buying committee in brief: its stakeholders, open seats, coverage by role and Ken's latest mapping run.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `stakeholderCount` | integer (int32) | no | Live stakeholders. |
| `openSeatCount` | integer (int32) | no | Live open seats. |
| `coverage` | CommitteeCoverage | yes | Covered stakeholders out of stakeholders plus open seats. |
| `roles` | array of CommitteeRoleCount | yes | One entry per role with a live stakeholder or open seat, in the order champion, economic_buyer, approver, evaluator, user, executive_sponsor, blocker, unknown. [] when the committee is empty. |
| `run` | CommitteeRun | no | Ken's latest run mapping this account's buying committee. Omitted when Ken has never mapped it. |

### AccountPlan

The account's 90-day touch plan. Status is none when the account was never planned.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `accountId` | integer (int64) | no | The account the plan is for. |
| `status` | string | yes | none (no plan yet), active, paused or ended. |
| `startedAt` | string (date-time) | no | When the plan started. |
| `endsAt` | string (date-time) | no | When the plan's window ends. |
| `pausedAt` | string (date-time) | no | When the plan was paused. Set while paused. |
| `pauseReason` | string | no | Why the plan is paused: reply (the account replied) or owner (the account owner paused it). Set while paused. |
| `pausedByMessageId` | string | no | The reply that paused the plan, when `pauseReason` is reply. |
| `resumedAt` | string (date-time) | no | When the plan last resumed after a pause. |
| `endedAt` | string (date-time) | no | When the plan ended. |
| `endReason` | string | no | Why the plan ended: completed, owner (the account owner ended it), meeting_booked or stage_changed. |
| `stepCount` | integer (int32) | no | The plan's steps, not counting deleted or skipped ones. |
| `openStepCount` | integer (int32) | no | Steps not sent yet: planned, drafted, awaiting approval, approved or failed. |
| `thin` | boolean | no | True when an active or paused plan has fewer steps than the minimum its plan calls for, usually because Kenso knows too few people at the account: map more people to fill it. |
| `nextStepAt` | string (date-time) | no | When the earliest open step is due. |

### AccountHandoff

An account's latest hand-off: who it went to, how, by whom and when.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `toMemberId` | integer (int64) | no |  |
| `toName` | string | yes |  |
| `channel` | string | yes | email, slack or crm_task. |
| `crmProvider` | string | no | crm_task only: the CRM that holds the task. |
| `byMemberId` | integer (int64) | no |  |
| `handedOffAt` | string (date-time) | no |  |

### AccountResearch

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer (int64) | no | The id of the dossier shown (the latest succeeded run), which the AI feedback control rates as `account_research:{id}`. Absent when none finished. |
| `status` | string | yes |  |
| `trigger` | string | no |  |
| `errorCode` | string | no |  |
| `researchedAt` | string (date-time) | no |  |
| `isStale` | boolean | no |  |
| `whyNow` | ResearchClaim | no |  |
| `angle` | string | no |  |
| `fitScore` | integer (int32) | no |  |
| `tagline` | ResearchClaim | no |  |
| `description` | ResearchClaim | no |  |
| `facts` | ResearchFacts | no |  |
| `links` | ResearchLinks | no |  |
| `pains` | array of ResearchPain | no |  |
| `stack` | array of ResearchClaim | no |  |
| `signals` | array of ResearchClaim | no |  |
| `sources` | array of ResearchSourceClaim | no |  |
| `whyNowStatus` | string | no | `no_sourced_trigger` when the run found no dated why-now within 120 days. |
| `company` | ResearchCompany | no | The company block, from Ken's own records (no model call): Ken Search, the linked contacts_company row (enrichment) and the job postings index. |
| `stackItems` | array of ResearchStackItem | no | The merged, sourced stack. stack stays for older readers. |
| `pricing` | ResearchPricing | no |  |
| `salesMotion` | ResearchSalesMotion | no |  |
| `acv` | ResearchAcv | no | Their ACV, an estimate of what one customer pays the company a year, derived only from cited published pricing, with its basis. |
| `customers` | array of ResearchClaim | no |  |
| `competitors` | array of ResearchClaim | no |  |
| `answers` | array of ResearchAnswer | no |  |
| `appliedPrompt` | ResearchAppliedPrompt | no | The Knowledge › Prompts research prompt that shaped the dossier shown. |

### AccountConnections

An account's LinkedIn connections, with expand=connections.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `count` | integer (int32) | no | Distinct people at the account who are a teammate's LinkedIn connection. |
| `people` | array of AccountConnectionPerson | yes | The first few of them. |
| `connectedVia` | array of ConnectedVia | yes | The seats those connections come from, by seat id. |

### AccountWhyNotNow

An account's why-not-now: the reason, what it does and its source. A member sets and clears it on the account in Kenso, or Ken does.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reason` | string | yes | outside_limits, company_gone or competitor (a stop); open_deal, asked_later, recent_no, crisis, being_acquired or just_bought (a wait); person_left or wrong_person (switch person, set on one stakeholder and never shown here). |
| `outcome` | string | yes | stop (the account moved to not_a_fit or competitor until a person undoes it) or wait (the stage stays and Kenso holds the account to its release date, `until`). |
| `text` | string | yes | The sentence people read: the reason's label, then the note or source text it was set with. |
| `sourceUrl` | string | no | The source the reason came from, an http(s) URL. Omitted for a reason from a reply. |
| `sourceDate` | string (date) | no | The source's own date. Omitted when the reason came from a reply without one. |
| `replyId` | string | no | The msg_ id of the reply the reason came from. Omitted otherwise. |
| `until` | string (date-time) | no | A wait's release date: Kenso holds the account until then and resumes its plan after. Omitted for a stop. |
| `setBy` | string | yes | ken (a Kenso job), agent (an agent or an API key) or user (a member). |
| `setAt` | string (date-time) | no |  |

### AccountMergeFieldChange

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `field` | string | yes | The field's API name, such as `ownerMemberId` or `industry`. |
| `from` | object | no | The kept account's value before the merge. Absent when it was empty. |
| `to` | object | no | The value the merge sets: the merged-away account's. |

### AccountMergeMoved

How many records of each kind move to the kept account.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `domainCount` | integer (int32) | no |  |
| `personCount` | integer (int32) | no | People who move to the kept account. |
| `combinedPersonCount` | integer (int32) | no | People who were on both accounts and become one place on the kept account. |
| `touchCount` | integer (int32) | no | Touches that moved, sent and skipped ones included. |
| `skippedTouchCount` | integer (int32) | no | Of `touchCount`, the open touches the merge marked skipped as they moved: the kept account already had an open touch for the person, or the person stays removed there. |
| `opportunityCount` | integer (int32) | no | Deals (opportunities). |
| `meetingCount` | integer (int32) | no |  |
| `tagCount` | integer (int32) | no |  |
| `signalCount` | integer (int32) | no |  |
| `studioPageCount` | integer (int32) | no |  |
| `timelineEventCount` | integer (int32) | no |  |

### AccountTierReasonFacts

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fitScore` | integer (int32) | no |  |
| `industry` | string | no |  |
| `employees` | integer (int32) | no |  |
| `fundingRound` | string | no |  |
| `signalScore` | integer (int32) | no |  |
| `engagedPeople` | integer (int32) | no |  |
| `topSignals` | array of string | no |  |

### AccountTierReasonNext

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `tier` | integer (int32) | no |  |
| `who` | string | no |  |

### PersonSummary

A short view of a person, as an account's stakeholder carries it.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer (int64) | no | The person's id. |
| `fullName` | string | no | The person's full name. Omitted when unknown. |
| `title` | string | no | The person's job title. Omitted when unknown. |
| `email` | string | no | The person's email, in lower case. Omitted when Kenso has none. |
| `linkedinUrl` | string | no | The person's LinkedIn profile, as https://linkedin.com/in/{slug}. Omitted when Kenso has none. |
| `kenPersonId` | integer (int64) | no | The person's id in Kenso Search. Omitted when Kenso has not matched them there. |
| `ownerMemberId` | integer (int64) | no | The id of the member who owns the person. Omitted when nobody owns them. |
| `leadStatus` | string | no | The person's lead status: `new`, `working`, `qualified`, `disqualified` or `nurture`. Omitted when the person is not a lead. |
| `leadStatusAt` | string (date-time) | no | When the lead status last changed, in UTC. Omitted when the person has no lead status. |
| `score` | integer (int32) | no | How well the person fits, from 0 to 100. Read-only. Omitted until Kenso scores the person. |
| `phones` | array of PersonPhone | no | Every phone number the person has, in stored order. An entry with `invalidAt` is a known wrong number. |
| `phone` | string | no | The first number in `phones` without `invalidAt`. Omitted when there is none. |
| `firstSource` | PersonSource | no | Where the person first came from. Omitted when Kenso has no record of it. |
| `latestSource` | PersonSource | no | Where the person most recently came from. Omitted when Kenso has no record of it. |
| `headline` | string | no | The person's LinkedIn headline. Omitted when unknown. |
| `photoUrl` | string | no | The URL of the person's photo, a file Kenso stores and serves. Omitted when there is no photo. |
| `photoSource` | string | no | Where the photo came from: `upload` for an uploaded photo, `linkedin` for their LinkedIn photo. Omitted when there is no photo. |
| `emailFind` | PersonEmailFindSummary | no | The newest search for the person's email. Omitted when nobody asked Kenso to find it. |

### WarmPath

One warm path to a stakeholder: how someone on the team can reach them.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | string | yes | past_colleague, connection, connection_colleague or shared_company. |
| `strength` | integer (int32) | no | 90 past_colleague, 80 connection, 60 connection_colleague, 40 shared_company; half at a school. |
| `summary` | string | yes | One line, e.g. "Worked with Jordan at Segment (2019 to 2021)". |
| `linkedinAccountId` | integer (int64) | no | The team's LinkedIn account (seat) the path goes through. |
| `linkedinConnectionId` | integer (int64) | no | The seat's connection the path goes through (connection and connection_colleague). |
| `companyName` | string | no | Where the two worked; omitted for connection. |
| `startDate` | string | no | YYYY-MM-DD: the overlap's start, or for shared_company the seat owner's tenure. Omitted for connection. |
| `endDate` | string | no | YYYY-MM-DD; an ongoing overlap ends today. |

### CommitteeCoverage

"3 of 5 mapped": covered stakeholders out of live stakeholders plus live open seats.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `covered` | integer (int32) | no | Live stakeholders with coverage engaged or planned. |
| `total` | integer (int32) | no | Live stakeholders plus live open seats. |

### CommitteeRoleCount

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `role` | string | yes | champion, economic_buyer, approver, evaluator, user, executive_sponsor, blocker or unknown (stakeholders only). |
| `stakeholderCount` | integer (int32) | no |  |
| `openSeatCount` | integer (int32) | no |  |

### CommitteeRun

One run of Ken's committee mapping.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer (int64) | no |  |
| `accountId` | integer (int64) | no |  |
| `trigger` | string | yes | account_created, ask_ken or api. |
| `instruction` | string | no | The user's steer. |
| `status` | string | yes | finding, queued, running, paused, succeeded or failed. |
| `pausedReason` | string | no | Why the run is paused: credits when the workspace is out of credits, member_limit when the person the run counts against (who started it, else the account owner) reached their monthly credit limit. Null when not paused. |
| `counts` | CommitteeRunCounts | yes |  |
| `costCredits` | integer (int32) | no | Whole credits the run's model call cost, rounded half away from zero. Email finds are charged on each find. |
| `error` | string | no | Short and user-safe, when the run failed. |
| `createdAt` | string (date-time) | no |  |
| `startedAt` | string (date-time) | no |  |
| `completedAt` | string (date-time) | no |  |

### ResearchClaim

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `text` | string | yes |  |
| `sourceUrls` | array of string | yes |  |
| `date` | string | no |  |
| `origin` | string | no | Where the claim came from: ken_search, enrichment, website, news, search, jobs, model or social. Set on the claims of the newer brief fields; absent on older ones. |

### ResearchFacts

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `headquarters` | ResearchFact | no |  |
| `founded` | ResearchFact | no |  |
| `employees` | ResearchFact | no |  |
| `funding` | ResearchFact | no |  |
| `revenue` | ResearchFact | no |  |
| `stock` | ResearchFact | no |  |

### ResearchLinks

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `website` | string | yes |  |
| `linkedin` | string | no |  |
| `careers` | string | no |  |
| `ticker` | string | no |  |

### ResearchPain

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `text` | string | yes |  |
| `evidence` | string | no |  |
| `sourceUrls` | array of string | yes |  |
| `date` | string | no |  |

### ResearchSourceClaim

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `text` | string | yes |  |
| `sourceUrls` | array of string | yes |  |
| `date` | string | no |  |
| `kind` | string | yes |  |

### ResearchCompany

The company block, from Ken's own records (no model call): Ken Search, the linked contacts_company row (enrichment) and the job postings index.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `employees` | ResearchValue | no | One company value with its origin (a ResearchOrigin). |
| `sizeBand` | ResearchValue | no | One company value with its origin (a ResearchOrigin). |
| `industry` | ResearchValue | no | One company value with its origin (a ResearchOrigin). |
| `headquarters` | ResearchValue | no | One company value with its origin (a ResearchOrigin). |
| `founded` | ResearchValue | no | One company value with its origin (a ResearchOrigin). |
| `revenueRange` | ResearchValue | no | One company value with its origin (a ResearchOrigin). |
| `funding` | ResearchValue | no | One company value with its origin (a ResearchOrigin). |
| `openRoles` | ResearchValue | no | One company value with its origin (a ResearchOrigin). |
| `hiring` | array of ResearchClaim | no |  |
| `leadershipChanges` | array of ResearchClaim | no |  |

### ResearchStackItem

One tool in the merged stack (Ken Search, enrichment and the model's cited stack, deduped by name).

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes |  |
| `category` | string | no |  |
| `origin` | string | yes |  |
| `sourceUrls` | array of string | no |  |

### ResearchPricing

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | ResearchClaim | no |  |
| `pricePoints` | array of ResearchClaim | no |  |

### ResearchSalesMotion

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | string | yes | One of all. |
| `evidence` | string | no |  |
| `sourceUrls` | array of string | no |  |

### ResearchAcv

Their ACV, an estimate of what one customer pays the company a year, derived only from cited published pricing, with its basis.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `low` | number (double) | no |  |
| `high` | number (double) | no |  |
| `currency` | string | yes |  |
| `basis` | string | yes |  |
| `sourceUrls` | array of string | no |  |

### ResearchAnswer

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `question` | string | yes |  |
| `answer` | string | yes |  |
| `sourceUrls` | array of string | no |  |

### ResearchAppliedPrompt

The Knowledge › Prompts research prompt that shaped a run.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer (int64) | no |  |
| `name` | string | no |  |

### AccountConnectionPerson

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `personId` | integer (int64) | no |  |
| `fullName` | string | no |  |

### ConnectedVia

A teammate's LinkedIn account that has a person as a connection.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `linkedinAccountId` | integer (int64) | no | The id of the connected LinkedIn account in Kenso. |
| `displayName` | string | no | The name on that LinkedIn account. Omitted when unknown. |
| `memberId` | integer (int64) | no | The id of the member who connected that LinkedIn account to Kenso. Omitted when Kenso did not record it. |

### PersonPhone

One of a person's phone numbers.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `number` | string | yes | The number as a plus sign and 8 to 15 digits, starting with the country code, such as +15551234567. |
| `kind` | string | yes | The kind of number: `mobile`, `work` or `other`. |
| `source` | string | yes | Who added the number: a person source such as `manual`, `api`, `crm` or `form`, or the name of the service that found it. |
| `addedAt` | string (date-time) | no | When the number was added, in UTC. |
| `invalidAt` | string (date-time) | no | When the number was marked as a wrong number, in UTC. Omitted for a number not known to be wrong. |
| `whatsapp` | string | no | on, off or unknown: whether this number is on WhatsApp, from a check in the last 30 days. Only on the people get, list and search reads with the whatsapp feature on; omitted otherwise. |
| `whatsappCheckedAt` | string (date-time) | no | When that check ran. Omitted when whatsapp is unknown or omitted. |
| `whatsappOptOutAt` | string (date-time) | no | When WhatsApp to this number stopped: the person's stop or the number's, whichever came first. Kenso never sends WhatsApp to it. Omitted when neither is set or whatsapp is omitted. phoneOptOutAt blocks WhatsApp too. |

### PersonSource

Where a person came from, and when.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `source` | string | yes | The source: `manual`, `api`, `workflow`, `search`, `research`, `promoted`, `campaign`, `booking`, `crm`, `form`, `webhook`, `import`, `visitor`, `inbound_email` or `linkedin`. |
| `detail` | string | no | More about the source, such as the form or list name an intake sent, or the import or webhook name. Omitted when there is none. |
| `at` | string (date-time) | no | When the person came from this source, in UTC. Omitted when unknown. |

### PersonEmailFindSummary

The newest search for a person's email.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer (int64) | no | The email find's id. |
| `status` | string | yes | Where the find stands: `queued`, `running`, `paused` (waiting for credits), `found`, `not_found` or `failed`. |
| `completedAt` | string (date-time) | no | When the find finished, in UTC. Omitted while it is not finished. |
| `fromKenPool` | boolean | no | True when Kenso's own email database found the email at no charge. Omitted otherwise. |

### CommitteeRunCounts

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `candidatesSeen` | integer (int32) | no |  |
| `peopleAdded` | integer (int32) | no |  |
| `peopleUpdated` | integer (int32) | no |  |
| `seatsOpened` | integer (int32) | no |  |
| `emailsQueued` | integer (int32) | no |  |

### ResearchFact

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | string | yes |  |
| `sub` | string | no |  |
| `sourceUrls` | array of string | yes |  |

### ResearchValue

One company value with its origin (a ResearchOrigin).

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | string | yes |  |
| `sub` | string | no |  |
| `origin` | string | yes |  |
| `sourceUrls` | array of string | no |  |
