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

# People: Upload or replace a person's photo

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

## Upload or replace a person's photo

`PUT /v1/people/{personId}/photo` - operationId `people.replace-photo`

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

Multipart field `file`: a non-empty PNG, JPEG or WebP under 10 MB, checked by type, extension and content
(else `400` `validation_failed`). Kenso stores it and serves it from `/media`; it shows as
`photoUrl` with `photoSource: upload`, ahead of the person's LinkedIn photo, and replaces an earlier
upload. A merged person is `404` `person_merged`. Returns the person. 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/people/PUT/v1/people/%7BpersonId%7D/photo)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `personId` | 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

`multipart/form-data`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `file` | string (binary) | no |  |

### Response 200

`data` is a `Person`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) | The person's id. |
| `mergeSummary` | PersonMergeSummary | Only on the answer of a people.merge sent with `dryRun`: what the merge would fill and move. |
| `fullName` | string | The person's full name. Omitted when unknown. |
| `firstName` | string | The person's first name. Omitted when unknown. |
| `lastName` | string | The person's last name. Omitted when unknown. |
| `title` | string | The person's job title. Omitted when unknown. |
| `email` | string | The person's email, in lower case. Omitted when Kenso has none. |
| `linkedinUrl` | string | The person's LinkedIn profile, as https://linkedin.com/in/{slug}. Omitted when Kenso has none. |
| `kenPersonId` | integer (int64) | The person's id in Kenso Search. Omitted when Kenso has not matched them there. |
| `ownerMemberId` | integer (int64) | The id of the member who owns the person. Omitted when nobody owns them. |
| `leadStatus` | string | The person's lead status: `new`, `working`, `qualified`, `disqualified` or `nurture`. Omitted when the person is not a lead. |
| `leadStatusAt` | string (date-time) | When the lead status last changed, in UTC. Omitted when the person has no lead status. |
| `relationship` | string | Who the person is to you: `to_sort`, `lead`, `customer`, `network` or `archived`. Until someone sets it, Kenso derives it: `to_sort` for a person the LinkedIn connections import added that nobody has worked yet, `customer` for a person on an account in onboarding, client or churned (or marked a customer), else `lead`. Set it with `people.update`. |
| `relationshipSet` | boolean | True when someone set the relationship; false while Kenso derives it. |
| `engagement` | string | How far outreach to the person has gone, derived by Kenso and read-only: `not_contacted`, `contacted`, `replied`, `meeting`, `bounced` or `unsubscribed`, the first that holds in the order unsubscribed, meeting, replied, bounced, contacted. On `people.get`, `people.list`, `people.search` and the `people.update` answer; omitted elsewhere. |
| `lastTouch` | PersonLastTouch | The latest email, LinkedIn, WhatsApp, Facebook, Instagram or iMessage message with the person, sent or received (an automated reply or a bounce is not one). Unlike an account's `lastTouchAt`, it counts the person's replies, and a logged call does not count. Read-only. Only on `people.search` rows, and omitted there when there is none. |
| `suggestion` | PersonSuggestion | Ken's suggestion for the person's relationship, until someone sets the relationship. Omitted when there is none. |
| `score` | integer (int32) | How well the person fits, from 0 to 100. Kenso adds points for the seniority of their title, a business email domain, their account's tier and the source they came from. Read-only. Omitted until Kenso scores the person. |
| `phones` | array of PersonPhone | Every phone number the person has, in stored order. An entry with `invalidAt` is a known wrong number. |
| `phone` | string | The first number in `phones` without `invalidAt`. Omitted when there is none. |
| `phoneOptOutAt` | string (date-time) | When the person asked not to be called, in UTC. Kenso does not call a person who opted out. Omitted when they have not asked. |
| `whatsappOptOutAt` | string (date-time) | When the person asked not to get WhatsApp messages; Kenso never sends them one. Only on the people get, list and search reads with the whatsapp feature on; omitted otherwise and when they have not. |
| `firstSource` | PersonSource | Where the person first came from. Read-only. Omitted when Kenso has no record of it. |
| `latestSource` | PersonSource | Where the person most recently came from, such as the latest intake that matched them. Read-only. Omitted when Kenso has no record of it. |
| `headline` | string | The person's LinkedIn headline. Omitted when unknown. |
| `location` | string | Where the person is based, such as a city and country. Omitted when unknown. |
| `seniority` | string | The person's seniority from Kenso's LinkedIn data, such as Director or VP. Omitted when unknown. |
| `department` | string | The person's function from Kenso's LinkedIn data, such as Sales or Engineering. Omitted when unknown. |
| `photoUrl` | string | The URL of the person's photo: an uploaded photo, else their LinkedIn photo. Kenso stores and serves the file itself, so this is never a LinkedIn URL. Omitted when there is no photo. |
| `photoSource` | string | Where the photo came from: `upload` for an uploaded photo, `linkedin` for their LinkedIn photo. Omitted when there is no photo. |
| `profileSource` | string | Where Kenso's LinkedIn data for the person came from: `ken_search` (Kenso Search) or `contact` (a campaign contact linked to the person). Omitted until Kenso has filled some of it. |
| `profileEnrichedAt` | string (date-time) | When Kenso last checked its LinkedIn data for the person, in UTC. Omitted until Kenso has filled some of it. |
| `profile` | PersonProfile | The rest of the person's LinkedIn profile that Kenso holds. Only a read of one person includes it, so lists and the intake response leave it out. Omitted until Kenso fills it. |
| `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 | The fields a member or your CRM set, by their names in this object, such as `title` or `email`. Kenso's automatic updates, intake included, leave these fields as they are. Empty when there are none. |
| `createdBy` | Actor | Who created the person. |
| `updatedBy` | Actor | Who last changed the person. |
| `createdAt` | string (date-time) | When the person was created, in UTC. |
| `updatedAt` | string (date-time) | When the person last changed, in UTC. |
| `emailFind` | PersonEmailFindSummary | The newest search for the person's email. Omitted when nobody asked Kenso to find it. The intake response leaves it out. |
| `phoneFind` | PersonPhoneFindSummary | The newest search for the person's phone number. Omitted when nobody asked Kenso to find it. The intake response leaves it out. |
| `accounts` | array of PersonAccount | The live accounts the person is on, highest priority first. Empty when they are on none. A caller who works only their own accounts sees only those. Some list responses leave it out. |
| `tagIds` | array of integer (int64) | The ids of the tags the person carries, in ascending order. A champion carries the workspace's Champion tag. The intake response leaves it out. |
| `connectedVia` | array of ConnectedVia | The teammates' LinkedIn accounts that have the person as a connection. Omitted when none does. The intake response leaves it out. |
| `connectionIcpScore` | integer (int32) | How well the person fits your ideal customer profile, from 0 to 100, as Kenso scored them as a teammate's LinkedIn connection. 70 or more is a fit. When several teammates know them, this is the highest score. Omitted when no connection is scored. The intake response leaves it out. |
| `importOnlyAt` | string (date-time) | When Kenso added the person from a teammate's LinkedIn connections, in UTC. Until someone works the person, they stay out of the main people list and Ken runs nothing on them. Omitted once someone works them, and for people from any other source. |
| `emailDropped` | string | Set only on the person a create call returns: `role_address` when the email sent was a shared mailbox, such as support@ or info@, so Kenso created the person without it. Omitted otherwise. |
| `facebook` | PersonFacebook | The person's Facebook profile, on people.get with the facebook_outreach feature: the confirmed one, else a weak match waiting on "Is this them?". Omitted otherwise. |

### Request

```bash
curl -X PUT "https://api.ken.so/v1/people/812/photo" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -F "file=@./file"
```

### Example response

```json
{
  "success": true,
  "data": {
    "id": 77310,
    "fullName": "Amanda Chen",
    "firstName": "Amanda",
    "lastName": "Chen",
    "title": "VP of Engineering",
    "email": "amanda.chen@northwind.example.com",
    "kenPersonId": 51800231,
    "ownerMemberId": 1093,
    "leadStatus": "working",
    "leadStatusAt": "2026-10-13T16:22:05Z",
    "relationship": "lead",
    "relationshipSet": true,
    "engagement": "replied",
    "score": 78,
    "phones": [
      {
        "number": "+15125550142",
        "kind": "mobile",
        "source": "api",
        "addedAt": "2026-09-23T15:02:11Z"
      }
    ],
    "phone": "+15125550142",
    "firstSource": {
      "source": "api",
      "at": "2026-09-23T15:02:11Z"
    },
    "latestSource": {
      "source": "form",
      "detail": "Demo request",
      "at": "2026-10-13T16:22:05Z"
    },
    "headline": "VP of Engineering at Northwind Labs",
    "location": "Austin, Texas, United States",
    "seniority": "VP",
    "department": "Engineering",
    "pinnedFields": [
      "title"
    ],
    "customFields": {
      "buying_role": "evaluator"
    },
    "createdBy": {
      "kind": "user",
      "memberId": 1093
    },
    "updatedBy": {
      "kind": "user",
      "memberId": 1093
    },
    "createdAt": "2026-09-23T15:02:11Z",
    "updatedAt": "2026-10-14T09:41:27Z",
    "accounts": [
      {
        "accountId": 6120,
        "stakeholderId": 2410,
        "name": "Northwind Labs",
        "primaryDomain": "northwind.example.com",
        "role": "champion",
        "priority": 1,
        "coverage": "engaged"
      }
    ],
    "tagIds": [
      341
    ]
  }
}
```

## Types

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

### PersonMergeSummary

What a people.merge dry run would do: nothing was written. Only on the answer of a merge sent with `dryRun`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isDryRun` | boolean | no | True: the call was a dry run, and nothing was written. |
| `fieldChanges` | array of AccountMergeFieldChange | yes | The kept person's blank fields the merge fills, each with the value before and the value after. |
| `moved` | PersonMergeMoved | yes | How many of the merged person's records of each kind move to the kept person. |

### PersonLastTouch

A person's latest email, LinkedIn, WhatsApp, Facebook, Instagram or iMessage message, sent or received.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `at` | string (date-time) | no | When the message was sent or received, in UTC. |
| `channel` | string | yes | Where it happened: `email`, `linkedin`, `whatsapp`, `facebook`, `instagram` or `imessage`. Read an unknown value as a channel added later. |

### PersonSuggestion

Ken's suggestion for a person's relationship.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `relationship` | string | yes | The relationship Ken suggests: `lead`, `customer`, `network`, `archived` or `unsure`. |
| `kind` | string | no | Why: `icp_fit`, `customer_contact`, `old_teammate`, `classmate`, `personal`, `low_icp` or `unsure`. Omitted when Ken gave none. |
| `reason` | string | no | Ken's one-line reason, at most 200 characters, such as "Worked with you at Bolt, 2021-2023". Omitted when there is none. |
| `suggestedAt` | string (date-time) | no | When Ken made the suggestion, in UTC. Omitted when unknown. |

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

### PersonProfile

A person's LinkedIn profile beyond the fields on the person. Dates are yyyy-MM, or yyyy when only the year is known.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `summary` | string | no | The profile's summary. Omitted when unknown. |
| `industry` | string | no | The industry the profile names. Omitted when unknown. |
| `city` | string | no | The person's city. Omitted when unknown. |
| `state` | string | no | The person's state or region. Omitted when unknown. |
| `country` | string | no | The person's country. Omitted when unknown. |
| `currentCompany` | PersonProfileCompany | no | The person's current company and role, with `startedAt`: when they joined it. Omitted when unknown. |
| `yearsOfExperience` | number (double) | no | Years of work experience in total. Omitted when unknown. |
| `yearsInCurrentRole` | number (double) | no | Years in the current role. Omitted when unknown. |
| `yearsInCurrentCompany` | number (double) | no | Years at the current company. Omitted when unknown. |
| `connectionsCount` | integer (int32) | no | How many LinkedIn connections the person has. Omitted when unknown. |
| `followerCount` | integer (int32) | no | How many LinkedIn followers the person has. Omitted when unknown. |
| `experience` | array of PersonProfileRole | no | The person's roles, current ones first, then newest first. Omitted when unknown. |
| `education` | array of PersonProfileEducation | no | The person's schools. Omitted when unknown. |
| `skills` | array of string | no | The skills on the profile. Omitted when unknown. |
| `languages` | array of string | no | The languages on the profile. Omitted when unknown. |
| `certifications` | array of PersonProfileCertification | no | The certifications on the profile. Omitted when unknown. |

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

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

### PersonPhoneFindSummary

The newest search for a person's phone number.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | yes | Where the find stands: `queued`, `running`, `paused` (waiting for credits), `found`, `not_found` or `failed`. |
| `requestedAt` | string (date-time) | no | When someone asked for the find, in UTC. |
| `reason` | string | no | Why a `failed` iMessage find did not look. `suppressed`: Kenso may not contact the person (for example they are on the blocklist, unsubscribed, marked do not contact, or opted out of phone contact), so the find asked no source and charged nothing. Do not offer to try again while that holds. Omitted otherwise. |

### PersonAccount

An account a person is on, with the person's place there.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `accountId` | integer (int64) | no | The account's id. |
| `stakeholderId` | integer (int64) | no | The id of the person's stakeholder record on this account. |
| `name` | string | yes | The account's name. |
| `primaryDomain` | string | no | The account's primary domain, such as acme.com. Omitted when it has none. |
| `logoUrl` | string | no | The URL of the account's logo. Omitted when Kenso has none. |
| `role` | string | yes | The person's role in the account's buying committee: `champion`, `economic_buyer`, `approver`, `evaluator`, `user`, `executive_sponsor`, `blocker` or `unknown`. |
| `priority` | integer (int32) | no | The person's priority on this account, from 1 (highest) to 3. Omitted when not set. |
| `coverage` | string | no | How outreach covers the person on this account: `engaged`, `planned`, `gap` or `not_targeted`. |

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

### PersonFacebook

The person's Facebook profile on people.get. Status confirmed: the profile Kenso uses. Status candidate: a weak match waiting on "Is this them?". source is found_by_kenso for a profile Kenso found, else user, known or import.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes |  |
| `source` | string | yes |  |
| `confidence` | string | no |  |
| `status` | string | yes |  |

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

### PersonMergeMoved

How many of the merged person's records of each kind move to the kept person.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `accountCount` | integer (int32) | no | Accounts the kept person joins. |
| `combinedAccountCount` | integer (int32) | no | Accounts both people are on, where the two places become one. |
| `opportunityCount` | integer (int32) | no | Deals the merged person is on. |
| `meetingCount` | integer (int32) | no |  |
| `taskCount` | integer (int32) | no |  |
| `noteCount` | integer (int32) | no |  |
| `timelineEventCount` | integer (int32) | no | Captured email threads and meetings on the merged person's timeline. |

### PersonProfileCompany

A company on a person's LinkedIn profile, with the person's role there.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | The company's name. Omitted when unknown. |
| `domain` | string | no | The company's domain, such as acme.com. Omitted when unknown. |
| `linkedinUrl` | string | no | The company's LinkedIn page. Omitted when unknown. |
| `kenCompanyId` | integer (int64) | no | The company's id in Kenso Search. Omitted when unknown. |
| `title` | string | no | The person's title at the company. Omitted when unknown. |
| `startedAt` | string | no | When the person started at the company: yyyy-MM, or yyyy when only the year is known. Omitted when unknown. |

### PersonProfileRole

One role on a person's LinkedIn profile.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | string | no | The title of the role. Omitted when unknown. |
| `companyName` | string | no | The company of the role. Omitted when unknown. |
| `location` | string | no | Where the role was based. Omitted when unknown. |
| `startedAt` | string | no | When the role started: yyyy-MM, or yyyy when only the year is known. Omitted when unknown. |
| `endedAt` | string | no | When the role ended: yyyy-MM, or yyyy when only the year is known. Omitted while the role is current. |
| `isCurrent` | boolean | no | True when the person still holds the role. Omitted when unknown. |
| `description` | string | no | The description of the role on the profile. Omitted when there is none. |

### PersonProfileEducation

One school on a person's LinkedIn profile.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `school` | string | no | The school's name. Omitted when unknown. |
| `degree` | string | no | The degree. Omitted when unknown. |
| `fieldOfStudy` | string | no | The field of study. Omitted when unknown. |
| `startedAt` | string | no | When the person started there: yyyy-MM, or yyyy when only the year is known. Omitted when unknown. |
| `endedAt` | string | no | When the person finished there: yyyy-MM, or yyyy when only the year is known. Omitted when unknown. |

### PersonProfileCertification

One certification on a person's LinkedIn profile.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | The certification's name. Omitted when unknown. |
| `issuer` | string | no | Who issued it. Omitted when unknown. |
