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

# Contacts: Update a contact

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

## Update a contact

`PATCH /v1/contacts/{contactId}` - operationId `contacts.update`

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

Changes the fields you send and returns the updated contact. A field you leave out stays as it is, and null
clears a text field. A field the body does not define is refused.

`outreachLanguage` sets the language Ken writes to the contact in, as a locale such as `fr-FR` or
`es-MX` or a language code such as `de`. Kenso locks a language you set, so no import,
enrichment or reply changes it. Null clears the language and unlocks it.

`customVariables` is an object of string or null values. A string sets that key, null or an empty string
removes it, and keys you leave out stay. A key new to the campaign is added to the campaign's custom
variables. The object itself cannot be null.

`customImageUrl` is the contact's own image, shown in emails as `{{custom_image}}`: a public https
URL of at most 2,048 characters. Kenso downloads and hosts the image. `customVideo` is the
contact's own video, shown as `{{custom_video}}`: a Loom, YouTube, Vimeo, Wistia, Vidyard,
Sendspark or HeyGen share link or embed code, at most 20,480 characters, on a contact in a campaign.
An empty string or null clears either one.

Errors:

- `400 validation_failed`: the body is not a JSON object, a field is unknown or invalid,
`isQualified` or `doNotContact` is null, the email is already another contact's or is
one of the contact's personal addresses, or the workspace does not have campaign images or
campaign videos. The error names the field.
- `404 not_found`: no contact with this id in the workspace, or the contact is deleted.
- `409 video_in_use`: a sent or queued email step uses the contact's current video, so it cannot change.
The old video stays.

Requires Campaigns edit.

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `contactId` | path | integer (int64) | yes | The contact id. |
| `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`, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `firstName` | string | no | First name. Null clears it. |
| `lastName` | string | no | Last name. Null clears it. |
| `title` | string | no | Job title. Null clears it. |
| `linkedInUrl` | string | no | LinkedIn profile URL. Null clears it. |
| `location` | string | no | Location. Null clears it. |
| `email` | string | no | The contact's email address. It must be valid, not another contact's address and not one of the contact's personal addresses. Null removes it. |
| `isQualified` | boolean | no | True or false to mark the contact qualified or not. Null is refused. |
| `doNotContact` | boolean | no | True to mark the contact do-not-contact, so Kenso sends it nothing, or false to clear that. Null is refused. |
| `outreachLanguage` | string | no | The language Ken writes to the contact in: a locale such as `fr-FR` or `es-MX`, or a language code such as `de`. Kenso locks it, so no import, enrichment or reply changes it. Null clears and unlocks it. |
| `customVariables` | map of string | no | Values to merge into the contact's custom variables, by key. A string sets the key, and null or an empty string removes it. Keys you leave out stay. The object itself cannot be null. |
| `customImageUrl` | string | no | The contact's own image, shown in emails as `{{custom_image}}`: a public https URL of at most 2,048 characters, which Kenso downloads and hosts. An empty string or null clears it. Needs campaign images on the workspace. |
| `customVideo` | string | no | The contact's own video, shown in emails as `{{custom_video}}`: a Loom, YouTube, Vimeo, Wistia, Vidyard, Sendspark or HeyGen share link or embed code, at most 20,480 characters. An empty string or null clears it. Needs campaign videos on the workspace and a contact in a campaign. While a sent or queued step uses the current video, it cannot change. |

### Response 200

`data` is a `Contact`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) | The contact id. |
| `campaignId` | integer (int64) | The campaign the contact is in. Null when the contact is in no campaign. |
| `segmentId` | integer (int64) | The campaign segment the contact is in. |
| `campaignListId` | integer (int64) | The import list that added the contact to its campaign. Each import makes one list. Pass it as `listId` to export the contacts of that import. |
| `companyId` | integer (int64) | The id of the contact's company record. |
| `companyName` | string | Company name. |
| `companyEmailName` | string | The company name as Ken writes it in emails: a short form without taglines, trademark signs or text in brackets. |
| `firstName` | string | First name. |
| `lastName` | string | Last name. |
| `email` | string | The contact's first email address. The address `emailValidity` describes can be a later one. |
| `linkedInUrl` | string | LinkedIn profile URL. |
| `profileUrn` | string | The LinkedIn member id of the profile, such as a Sales Navigator id, when Kenso knows it. |
| `isOpenLink` | boolean | True when the LinkedIn profile is an Open Profile, which any LinkedIn member can message without a connection. Null when unknown. |
| `jsonGeoLocation` | string | The LinkedIn profile's location details as a JSON string. |
| `title` | string | Job title. |
| `isQualified` | boolean | True when the contact is qualified for its campaign. |
| `doNotContact` | boolean | True when the contact is marked do-not-contact. Kenso sends nothing to a do-not-contact contact. |
| `sequenceStoppedAt` | string (date-time) | When the contact's sequence in its campaign stopped, in UTC. Do-not-contact does not set it. Omitted while the sequence runs. |
| `sequenceStopReason` | string | Why the sequence stopped: `paused` (a member paused the contact), `account_play` (the contact matched an active account play after a step), `promoted` (the contact's company was promoted to Accounts), or a reason from a campaign imported from another tool (`migration_finished`, `migration_paused`, `migration_pending`). New reasons can appear. Omitted while the sequence runs. |
| `isDecisionMaker` | boolean | True when Kenso's data marks the person as a decision maker. |
| `qualityScore` | integer (int32) | The contact's lead quality score in its campaign. Null until Kenso scores the contact. |
| `qualityReasoning` | string | Ken's explanation of `qualityScore`. Null without a score. |
| `leadQualityScoreId` | integer (int64) | The id of the lead quality score behind `qualityReasoning`; absent with no reasoning. |
| `profileImage` | string | URL of the person's profile photo. Null when Kenso has no real photo. |
| `qualificationResponse` | string | Ken's latest AI qualification answer for the contact. |
| `qualificationResponseId` | integer (int64) | The id of the qualification answer behind `qualificationResponse`; absent with no answer. |
| `segmentationReasoning` | string | Ken's latest explanation of why the contact is in its segment. |
| `experiencesJson` | string | The person's work history as a JSON string. |
| `customVariables` | map of string | The contact's custom variable values by key, for the keys the campaign defines. Keys without a value are left out. Null when there are none. |
| `emailsSent` | integer (int32) | Emails sent to the contact. The six email counts are omitted until the contact has email stats. |
| `clicks` | integer (int32) | Clicks on links in emails to the contact. |
| `replies` | integer (int32) | Email replies from the contact. |
| `unsubscribes` | integer (int32) | Campaigns the contact unsubscribed from, 0 or 1 for a contact in one campaign. |
| `bounces` | integer (int32) | Emails to the contact that bounced. |
| `positiveReplies` | integer (int32) | Campaigns where the contact sent an interested reply, 0 or 1 for a contact in one campaign. |
| `connectionRequestsSent` | integer (int32) | LinkedIn connection requests sent to the contact and confirmed. The four LinkedIn counts are omitted when the contact has no LinkedIn steps and no confirmed LinkedIn send. |
| `connectionsAccepted` | integer (int32) | 1 when the contact accepted the campaign's LinkedIn connection request, else 0. |
| `linkedInMessagesSent` | integer (int32) | LinkedIn messages and InMails sent to the contact and confirmed. |
| `linkedInReplies` | integer (int32) | 1 when the contact replied on LinkedIn in the campaign, else 0. |
| `headline` | string | LinkedIn headline. |
| `location` | string | Location as the profile writes it. |
| `city` | string | City. |
| `state` | string | State or region. |
| `country` | string | Country name. |
| `countryIso2` | string | Two-letter ISO 3166 country code, such as `DE`. |
| `companyLogo` | string | URL of the company logo. Null when Kenso has no real logo. |
| `emailEnrichmentProviders` | array of string | The email finder that found the contact's first email address, as a list of slugs, such as `ken` for Kenso's own email database. Null when the address did not come from a finder. |
| `linkedInUrlNameMismatch` | boolean | True when the LinkedIn URL looks like someone else's: its name part does not match the contact's first and last name, or it is not a personal profile URL. |
| `segmentName` | string | Name of the contact's segment. |
| `missingRequiredVariableKeys` | array of string | The variables the campaign requires for sending that the contact has no value for: custom variable keys, and image or video variables that are not ready. Null when none are missing. |
| `linkedInSendBlockedReason` | string | Why the contact's LinkedIn sequence is held: `missing_required_variables: <names>` names the `{{name}}` tokens in a LinkedIn step's message or InMail subject that nothing fills, so Kenso stopped the sequence at that step instead of sending them as written. Fix the step's text or give the token a fallback. Null when nothing is held. |
| `emailValidity` | string, one of: unknown, invalid, risky, verified, safe, catch_all, verification_error | The verdict of the contact's first email address that is Safe or Verified: `safe` or `verified`. Null when no address of the contact is Safe or Verified. |
| `emailFromKenPool` | boolean | True when the address `emailValidity` describes came free from Kenso's own email database. Omitted without a Safe or Verified email. |
| `companyDomain` | string | Company website domain. |
| `companySize` | string | Employee count range, such as `51-200`. |
| `companyType` | string | Company type. |
| `companyIndustry` | string | Industry. |
| `companyLocation` | string | Company location. |
| `companyTechnologies` | string | Technologies the company uses, as one text value. |
| `companyLinkedInUrl` | string | Company LinkedIn page URL. |
| `companyLinkedInIdent` | string | The company's LinkedIn identifier. |
| `companyEmployeeCount` | integer (int32) | Number of employees. |
| `companySpecialities` | string | The company's specialities, as one text value. |
| `companyDescription` | string | Company description. |
| `companyCrunchBaseUrl` | string | Company Crunchbase URL. |
| `companyJsonLocation` | string | The company's location details as a JSON string. |
| `companyFoundedYear` | integer (int32) | Year the company was founded. |
| `headquartersCity` | string | City of the company headquarters. |
| `headquartersState` | string | State or region of the company headquarters. |
| `headquartersCountry` | string | Country of the company headquarters. |
| `seniorityLevel` | string | Seniority level. |
| `function` | string | Job function, such as sales or engineering. |
| `yearsOfExperience` | number (float) | Years of work experience. |
| `languages` | string | Languages the person lists, as one text value. |
| `outreachLanguage` | string | The locale Ken writes to the contact in, such as `fr-FR`, or a two-letter language code such as `de`. Omitted until Ken picks one. `PATCH` sets it by hand and locks it. |
| `outreachFormality` | string, one of: formal, informal | The register Ken writes to the contact in: `formal` or `informal`. Omitted when the language's default applies. |
| `outreachLanguageSource` | string, one of: manual, reply, declared, country, hq, default | Where the outreach language came from: `manual` (a member set it), `reply` (the language the contact replied in), `declared` (a language the contact lists), `country` (the contact's country), `hq` (the company headquarters' country) or `default` (the campaign's language). |
| `outreachLanguageConfidence` | number (float) | How sure Ken is of the outreach language, from 0 to 1. A language a member set is 1, and the campaign's default language is 0. |
| `outreachLanguageLocked` | boolean | True when a member set the language. No import, enrichment or reply replaces it. |
| `phoneNumber` | string | The contact's first phone number. |
| `phoneNumberValidity` | string, one of: unknown, invalid, risky, verified, valid | How sure Kenso is that `phoneNumber` works. Omitted without a phone number. |
| `phoneCountryAssumed` | boolean | True when Kenso added the country code itself: a number stored without one was read as a US number (+1). Treat it as unverified. |
| `lastJobTitle` | string | Title of the most recent job in the work history. |
| `lastJobDescription` | string | Description of the most recent job in the work history. |
| `employmentType` | string | Employment type of the current job, such as full-time. |
| `employmentLocation` | string | Location of the current job. |
| `summary` | string | The profile summary. |
| `skills` | string | Skills, as one text value. |
| `education` | string | Education, as one text value. |
| `personalizationLineIds` | map of integer (int64) | The id of the AI line behind each personalization field, keyed like those fields (`personalization1` to `personalization20`). Rate a line with AI feedback as `ai_line:{id}`. Absent when the contact has no lines. |
| `createdAt` | string (date-time) | When Kenso created the contact, in UTC. |
| `updatedAt` | string (date-time) | When the contact last changed, in UTC. |
| `accountPlay` | ContactAccountPlay | The contact's account play status in its campaign. Omitted when no account play holds, stops or counts the contact, and for a caller without Accounts view. |
| `securityGateway` | ContactSecurityGateway | The email security gateway in front of the contact's first Safe or Verified email, the address Kenso sends to. Omitted when the workspace does not have security gateways. |
| `mailboxProvider` | ContactMailboxProvider | The host of that email's mailbox, such as Google Workspace. Omitted when the workspace does not have security gateways. |
| `customVideo` | ContactCustomVideo | The contact's own video, shown in emails as `{{custom_video}}`. Null when the contact has none or the workspace does not have campaign videos. Set it with `customVideo` on `PATCH /v1/contacts/{contactId}`. |

### Request

```bash
curl -X PATCH "https://api.ken.so/v1/contacts/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 '{
  "title": "SVP of Engineering",
  "location": "Austin, Texas, United States",
  "isQualified": true,
  "doNotContact": false,
  "outreachLanguage": "en-US",
  "customVariables": {
    "open_roles": "15 engineering roles"
  }
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "id": 90125,
    "campaignId": 4821,
    "segmentId": 1207,
    "campaignListId": 3305,
    "companyId": 22841,
    "companyName": "Northwind Labs",
    "companyEmailName": "Northwind",
    "firstName": "Amanda",
    "lastName": "Chen",
    "email": "amanda.chen@northwind.example.com",
    "linkedInUrl": "https://www.linkedin.com/in/amanda-chen-northwind",
    "title": "VP of Engineering",
    "isQualified": true,
    "doNotContact": false,
    "isDecisionMaker": true,
    "qualityScore": 86,
    "qualityReasoning": "Leads a 40-person engineering team at a 120-person B2B SaaS company that is hiring engineers.",
    "segmentationReasoning": "VP of Engineering, which matches the Engineering leaders segment.",
    "customVariables": {
      "open_roles": "12 engineering roles"
    },
    "emailsSent": 2,
    "clicks": 0,
    "replies": 1,
    "unsubscribes": 0,
    "bounces": 0,
    "positiveReplies": 1,
    "headline": "VP of Engineering at Northwind Labs",
    "location": "Austin, Texas, United States",
    "city": "Austin",
    "state": "Texas",
    "country": "United States",
    "countryIso2": "US",
    "companyLogo": "https://cdn.example.com/companies/22841/logo.png",
    "linkedInUrlNameMismatch": false,
    "segmentName": "Engineering leaders",
    "emailValidity": "safe",
    "emailFromKenPool": false,
    "companyDomain": "northwind.example.com",
    "companySize": "51-200",
    "companyIndustry": "Software Development",
    "companyLocation": "Austin, Texas, United States",
    "companyEmployeeCount": 120,
    "companyDescription": "Northwind Labs builds developer onboarding software for engineering teams.",
    "companyFoundedYear": 2017,
    "headquartersCity": "Austin",
    "headquartersState": "Texas",
    "headquartersCountry": "United States",
    "seniorityLevel": "VP",
    "function": "Engineering",
    "yearsOfExperience": 14,
    "outreachLanguage": "en-US",
    "outreachLanguageSource": "country",
    "outreachLanguageConfidence": 0.8,
    "outreachLanguageLocked": false,
    "phoneCountryAssumed": false,
    "createdAt": "2026-09-23T15:02:11Z",
    "updatedAt": "2026-10-13T16:22:05Z"
  }
}
```

## Types

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

### ContactAccountPlay

How an account play affects the contact in its campaign.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | no | What the account play does to the contact. `skipped`: held before the campaign's first step, because the contact's company is in an active account play. A contact that already got a step stops at its next send. `stopped`: the sequence stopped for good. `would_skip`: protection only counts the match, and sending does not change. |
| `accountId` | integer (int64) | no | The account whose play matches now. Omitted on a stopped contact whose account left the active stages. For a caller who works only their own accounts, this field, `accountName` and `accountStage` are omitted when the caller does not own the account. |
| `accountName` | string | no | The account name. |
| `accountStage` | string | no | The account's stage: `warming`, `engaged`, `meeting_booked` or `in_deal`. |

### ContactSecurityGateway

The email security gateway that filters mail to a contact's address.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | no | Detection result. `detected`: a gateway was found, and `slug` and `name` say which. `none`: no gateway was found, or the contact has no email or a free email address. `pending`: the domain is not checked yet. |
| `slug` | string | no | Short id of the gateway, such as `proofpoint`. Returned only when `status` is `detected`. |
| `name` | string | no | Display name of the gateway. Returned only when `status` is `detected`. |

### ContactMailboxProvider

The host of a contact's mailbox, such as Google Workspace or Microsoft 365.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | no | Detection result. `detected`: the host was found, and `slug` and `name` say which. `unknown`: the domain was checked and no known host matched, or the contact has no email. `pending`: the domain is not checked yet. |
| `slug` | string | no | Short id of the host, such as `google_workspace`. Returned only when `status` is `detected`. |
| `name` | string | no | Display name of the host. Returned only when `status` is `detected`. |

### ContactCustomVideo

The contact's own video, the one emails show as `{{custom_video}}`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | no | The video's state: `pending` while Kenso prepares the thumbnail, `ready` when emails can show the video, or `failed`. |
| `provider` | string | no | The video host: `loom`, `youtube`, `vimeo`, `wistia`, `vidyard`, `sendspark` or `heygen`. |
| `source` | string | no | How the video was set: `import` (a contact import), `api` (this API) or `mcp` (Ken or another AI assistant), or, for a generated video, the service that made it: `sendspark`, `heygen` or `vidyard`. New values can appear. |
| `watchUrl` | string | no | The link where the video plays. |
| `previewUrl` | string | no | A thumbnail image URL for showing the video in your own app. It works for a short time only. Null until the thumbnail is ready. |
| `previewExpiresAt` | string (date-time) | no | When `previewUrl` stops working, in UTC. Read the contact again for a new one. |
| `error` | ContactCustomVideoError | no | Why the video failed. Null unless `status` is `failed`. |

### ContactCustomVideoError

Why the contact's video failed.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | no | A stable error code. |
| `detail` | string | no | A readable explanation. |
