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

# Stakeholders: Add a person to an account as a stakeholder

> **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 [Stakeholders](/docs/api/stakeholders.md). Authentication, workspaces and errors: [/docs.md](/docs.md).

## Add a person to an account as a stakeholder

`POST /v1/accounts/{accountId}/stakeholders` - operationId `stakeholders.create`

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

Send `personId` (an existing person) or `person` (found by email, then LinkedIn URL,
then kenPersonId, else created; a match only fills its blank fields), plus `role`
(champion, economic_buyer, approver, evaluator, user, executive_sponsor, blocker, unknown),
`priority` (1-3), `coverage` (engaged, planned, gap, not_targeted), `note`,
`kenNote` (up to 1,000 characters), `reportsToStakeholderId` (a stakeholder on the same
account, no cycles) and `fillsSeatId` (an open seat on this account, closed in the same write).
Conflicts: `already_stakeholder`; `previously_removed` when a person removed them and the
caller is not a person (resend with `force: true` only when the user asked). 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/stakeholders/POST/v1/accounts/%7BaccountId%7D/stakeholders)

### 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 |
| --- | --- | --- | --- |
| `role` | string | no | champion, economic_buyer, approver, evaluator, user, executive_sponsor, blocker or unknown. |
| `priority` | integer (int32) | no | 1 (highest) to 3. |
| `coverage` | string | no | engaged, planned, gap or not_targeted. |
| `note` | string | no | The short line on the chart node, such as "Warm path - ex-Segment". |
| `reportsToStakeholderId` | integer (int64) | no | A live stakeholder on the same account this person reports to. No cycles. Null clears. |
| `kenNote` | string | no | Ken's longer note for the person rail, up to 1,000 characters. |
| `personId` | integer (int64) | no | An existing person. Send this or person, not both. |
| `person` | PersonInputBody | no | Find or create the person. Send this or personId, not both. |
| `source` | string | no | manual, csv, search, promoted, workflow, api or research. |
| `force` | boolean | no | Re-add a person a human removed from this account. Only when the user asked. |
| `fillsSeatId` | integer (int64) | no | An open seat on this account the new stakeholder fills. The seat closes in the same write. |

### Response 201

`data` is a `Stakeholder`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) |  |
| `accountId` | integer (int64) |  |
| `personId` | integer (int64) |  |
| `role` | string |  |
| `priority` | integer (int32) |  |
| `coverage` | string |  |
| `note` | string |  |
| `reportsToStakeholderId` | integer (int64) | The stakeholder on the same account this person reports to. |
| `kenNote` | string | Ken's longer note for the person rail. |
| `source` | string |  |
| `pinnedFields` | array of string |  |
| `person` | PersonSummary | A short view of a person, as an account's stakeholder carries it. |
| `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) |  |
| `warmPath` | WarmPath | 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. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/accounts/812/stakeholders" \
  -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 '{
  "role": "economic_buyer",
  "priority": 1,
  "coverage": "planned",
  "person": {
    "fullName": "Jordan Reyes",
    "title": "Chief Financial Officer",
    "email": "jordan.reyes@northwind.example.com"
  },
  "source": "api"
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "id": 2410,
    "accountId": 6120,
    "personId": 77310,
    "role": "champion",
    "priority": 1,
    "coverage": "engaged",
    "note": "Warm path - worked with Alex at Fabrikam",
    "kenNote": "Replied to the second email and asked for a demo. Runs the SDR team of six.",
    "source": "search",
    "pinnedFields": [
      "role"
    ],
    "person": {
      "id": 77310,
      "fullName": "Amanda Chen",
      "title": "VP of Engineering",
      "email": "amanda.chen@northwind.example.com",
      "ownerMemberId": 1093
    },
    "createdBy": {
      "kind": "user",
      "memberId": 1093
    },
    "updatedBy": {
      "kind": "user",
      "memberId": 1093
    },
    "createdAt": "2026-09-23T15:02:11Z",
    "updatedAt": "2026-10-14T09:41:27Z",
    "warmPath": {
      "kind": "past_colleague",
      "strength": 90,
      "summary": "Worked with Amanda at Fabrikam (2019 to 2021)",
      "linkedinAccountId": 7702,
      "companyName": "Fabrikam",
      "startDate": "2019-03-01",
      "endDate": "2021-06-30"
    }
  }
}
```

## Types

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

### PersonInputBody

Matched by email, then LinkedIn URL, then Ken person id; created when none match.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fullName` | string | no |  |
| `firstName` | string | no |  |
| `lastName` | string | no |  |
| `title` | string | no |  |
| `email` | string | no |  |
| `linkedinUrl` | string | no | A profile, such as https://linkedin.com/in/jane-doe. |
| `kenPersonId` | integer (int64) | no | The person's Ken id: their id in Ken Search. Null clears it. |

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

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

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

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