> 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: Create up to 100 accounts in one call

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

## Create up to 100 accounts in one call

`POST /v1/accounts/bulk-create` - operationId `accounts.bulk-create`

| Permission | Credits | Rate limit |
| --- | --- | --- |
| Accounts edit | 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`) | 240 requests a minute per API key |

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

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/POST/v1/accounts/bulk-create)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `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 |
| --- | --- | --- | --- |
| `items` | array of CreateAccountBody | yes | 1 to 100 accounts. Each item is a POST /v1/accounts body. Required. |

### Response 200

`data` is a `BulkCreateAccountsResult`.

| Field | Type | Description |
| --- | --- | --- |
| `created` | integer (int32) | Items with status created. |
| `skipped` | integer (int32) | Items with status domain_taken: the company is already an account. |
| `failed` | integer (int32) | Items with status invalid or failed. |
| `results` | array of BulkCreateAccountItemResult |  |

### Request

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

### Example response

```json
{
  "success": true,
  "data": {
    "created": 1,
    "skipped": 1,
    "failed": 0,
    "results": [
      {
        "status": "created",
        "accountId": 6120,
        "account": {
          "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"
        },
        "research": "queued"
      },
      {
        "status": "domain_taken",
        "accountId": 5977,
        "domain": "contoso.example.com",
        "error": "Account 5977 already owns contoso.example.com. GET /v1/accounts/5977 instead of creating it, or add your other domains there."
      }
    ]
  }
}
```

## Types

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

### CreateAccountBody

| 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. |
| `domains` | array of string | yes | 1 to 20 domains, website URLs or work emails. The first is primary. Required. |
| `source` | string | no | manual, csv, search, promoted, workflow or api. Defaults to manual for a person and api otherwise. |

### BulkCreateAccountItemResult

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | yes | `created`, `domain_taken`, `invalid` or `failed`. |
| `accountId` | integer (int64) | no | created: the new account. domain_taken: the account that already owns `domain`; use it. |
| `account` | Account | no | created only. |
| `research` | string | no | created only: `queued`, or `waiting_credits` when the workspace is short. Absent when research is off. |
| `domain` | string | no | domain_taken: the domain another account owns. |
| `field` | string | no | invalid: the item field of the first error, such as `domains[0]`. |
| `code` | string | no | invalid: the error code, such as `generic_email_domain`. |
| `error` | string | no | Every status except created: what went wrong and what to do. |

### Account

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer (int64) | no |  |
| `name` | string | yes |  |
| `mergeSummary` | AccountMergeSummary | no | Only on the answer of accounts.merge: what the merge changed and moved, or would with `dryRun`. |
| `stage` | string | yes | 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 | yes | 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 | no | 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) | no |  |
| `ownerMemberId` | integer (int64) | no |  |
| `fitScore` | integer (int32) | no |  |
| `whyNow` | string | no |  |
| `angle` | string | no |  |
| `cadenceDays` | integer (int32) | no |  |
| `nextTouchAt` | string (date-time) | no |  |
| `lastTouchAt` | string (date-time) | no | 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 | yes |  |
| `primaryDomain` | string | no |  |
| `domains` | array of AccountDomain | yes |  |
| `industry` | string | no |  |
| `fundingRound` | string | no |  |
| `employeeCount` | integer (int32) | no |  |
| `hqLocation` | string | no |  |
| `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. fieldSources.revenueRange estimate means Ken read it off the headcount. |
| `hqCity` | string | no |  |
| `hqCountry` | string | no | ISO 3166-1 alpha-2, upper case. |
| `foundedYear` | integer (int32) | no |  |
| `linkedinUrl` | string | no |  |
| `kenCompanyId` | integer (int64) | no | The company's Ken id: its id in Ken Search. |
| `logoUrl` | string | no | 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) | no | The inbox email touches send from. Omitted means the owner's primary inbox. |
| `sendsFromLinkedInAccountId` | integer (int64) | no | The LinkedIn account LinkedIn touches send from. Omitted means the one the owner connected. |
| `sendsFromInstagramAccountId` | integer (int64) | no | The Instagram account Instagram touches send from. Omitted means the one the owner connected. |
| `sendsFromWhatsAppAccountId` | integer (int64) | no | The WhatsApp account WhatsApp touches send from. Omitted means the one the owner connected. |
| `sendsFromFacebookAccountId` | integer (int64) | no | The Facebook account Facebook touches send from. Omitted means the owner's lowest-id connected one. |
| `sendsFromImessageLineId` | integer (int64) | no | 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) | no | 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) | no | 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) | no | 1 to 10 when a person set the tier by hand (up to the ladder's tierCount). Omitted for Auto. |
| `tierReason` | AccountTierReason | no | 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 | no | The workspace's customer: its domains are on the blocklist (reason customer), so Ken sends its people nothing. Always present. |
| `customerSince` | string (date-time) | no | When the account last became a customer. Omitted while it is not one. |
| `customerSource` | string | no | manual, opportunity_won or crm: what made it a customer. Omitted while it is not one. |
| `accountType` | string | no | 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 | no | 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 | no | Who or what last set each custom field, by key. Absent when no value has a record of it. |
| `pinnedFields` | array of string | yes |  |
| `fieldSources` | map of string | no | 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 | 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 |  |
| `score` | integer (int32) | no | 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) | no | When the score was last computed. |
| `signalCount` | integer (int32) | no | Signals whose event time is in the last 90 days, as of scoredAt. |
| `engagedPeopleCount` | integer (int32) | no | Distinct live stakeholders who replied, met or viewed an asset in 90 days, or whose coverage is engaged. |
| `latestSignal` | AccountSignalSummary | no | The signal with the latest event time, any age. Null when the account has none. |
| `recentSignalKinds` | array of string | no | 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) | no | 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) | no | Sum of the open opportunities' amounts in the workspace currency; omitted when none has an amount. |
| `openOpportunityStage` | string | no | Stage key of the newest open opportunity; omitted when none is open. |
| `stakeholders` | array of Stakeholder | no | Only with expand=stakeholders (up to 200; page the rest with stakeholders.list). |
| `committee` | CommitteeSummary | no | Only with expand=committee on accounts.list: the committee's counts, coverage and latest run. |
| `plan` | AccountPlan | no | Only on accounts.get. |
| `reengageAfter` | string (date) | no | 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) | no | Ids of the live tags on the account, ascending. Always present; [] when none. |
| `handoff` | AccountHandoff | no | The latest hand-off to a teammate. Omitted when the account was never handed off. |
| `researchStatus` | string | no | Latest research run's status: none \| waiting_credits \| queued \| running \| succeeded \| failed (list, search, get). |
| `researchedAt` | string (date-time) | no | When the latest successful research finished. |
| `research` | AccountResearch | no | Only with expand=research. |
| `importOnlyAt` | string (date-time) | no | 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 | no | Only with expand=connections: the teammates' LinkedIn connections at the account. Omitted when none. |
| `whyNotNow` | AccountWhyNotNow | no | 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. |

### 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 |  |
