> 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 contacts in bulk

> **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 contacts in bulk

`POST /v1/contacts/bulk-update` - operationId `contacts.bulk-update`

| Permission | Rate limit |
| --- | --- |
| Campaigns edit | 480 requests a minute per API key |

Updates up to 1,000 contacts in one call. Each item is a `contactId` plus any fields `PATCH
/v1/contacts/{contactId}` accepts, with the same rules. Items that change only the contact's own fields
(names, title, LinkedIn URL, location, outreach language, do-not-contact) are written together. The other
items run one at a time in request order. A problem with one item fails only that item.

`results` has one entry per item in request order. Its `status` is `updated`, `not_found`
(no such contact in the workspace), `validation_failed` (a field is invalid), `video_in_use`
(a sent or queued step uses the contact's video) or `failed`. After 5 failed items in a row,
Kenso stops running items one at a time and marks each remaining one `failed` with a message asking you
to retry it. Items written together keep their own result.

Errors:

- `400 validation_failed`: nothing was written, because `items` is empty, holds more than 1,000
entries, holds an entry that is not an object or has no positive `contactId`, or repeats a
`contactId`.

Requires Campaigns edit.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/contacts/POST/v1/contacts/bulk-update)

### 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`, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of BulkUpdateContactItemBody | yes | Required. From 1 to 1,000 items, run in request order. |

### Response 200

`data` is a `ContactBulkUpdateResult`.

| Field | Type | Description |
| --- | --- | --- |
| `updated` | integer (int32) | How many items were updated. |
| `failed` | integer (int32) | How many items were not updated, for any reason. |
| `results` | array of ContactBulkUpdateItemResult | One result per item, in request order. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/contacts/bulk-update" \
  -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": [
    {
      "contactId": 90125,
      "title": "SVP of Engineering",
      "customVariables": {
        "open_roles": "15 engineering roles"
      }
    },
    {
      "contactId": 90131,
      "doNotContact": true
    }
  ]
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "updated": 1,
    "failed": 1,
    "results": [
      {
        "contactId": 90125,
        "status": "updated"
      },
      {
        "contactId": 90131,
        "status": "not_found",
        "error": "No contact with this id in the workspace."
      }
    ]
  }
}
```

## Types

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

### BulkUpdateContactItemBody

One contact to update: its `contactId` plus any field `PATCH /v1/contacts/{contactId}` accepts, with the same rules.

| 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. |
| `contactId` | integer (int64) | yes | Required. The contact to update. Each contact id can appear only once in a request. |

### ContactBulkUpdateItemResult

The outcome of one item of a bulk contact update.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `contactId` | integer (int64) | no | The item's contact id. |
| `status` | string | no | The item's outcome: `updated`, `not_found` (no such contact in the workspace), `validation_failed` (a field is invalid), `video_in_use` (a sent or queued step uses the contact's video, so it cannot change) or `failed` (retry the item). |
| `error` | string | no | A readable explanation when the item was not updated. Null on success. |
