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

# CRM connections: Update a CRM connection

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

## Update a CRM connection

`PATCH /v1/crm-connections/{connectionId}` - operationId `crm-connections.update`

| Permission | Rate limit |
| --- | --- |
| Accounts view and the `integrations` permission | 4,800 requests a minute per API key |

Changes the connection's sync settings and turns sync on or off for each object. Send only the fields to change:
omitted fields keep their value. `stageMap`, `listSources` and `inboundPeople.filters` replace the
whole map or list.

Turning an object on in `syncObjects` needs a finished first import and CRM writes turned on for the
workspace. When contact sync turns on, Kenso starts creating CRM records for every contact that already meets
`createRecordsWhen`.
A new `pipelineExternalId` must exist in the CRM. When you pick a new pipeline without a `stageMap`,
Kenso maps its stages to your opportunity stages. `stageMap` values must be opportunity stage keys that are
not archived.

Errors:

- `400 validation_failed`: a value is out of range, the pipeline or a stage does not exist in the CRM, a campaign is not in the workspace, or the CRM cannot sync the object. `error.details` names each field.
- `402 plan_required`: the connection is paused for the plan, and the change turns sync on or picks a pipeline.
- `404 not_found`: the workspace has no connection with this id.
- `409 import_pending`: the first import has not finished yet.
- `409 crm_sync_disabled`: writing to the CRM is not on for this workspace yet.
- `409 needs_reconnect`: the CRM refused Kenso's access. Reconnect the CRM first.
- `409 invalid_state`: the connection is disconnected.
- `503 crm_unavailable`: the CRM cannot be reached to check the pipeline. Try again later.

Requires Accounts view and the `integrations` permission.

Needs the `ingestion` 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/crm-connections/PATCH/v1/crm-connections/%7BconnectionId%7D)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `connectionId` | path | integer (int64) | yes | The CRM connection's 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`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `settings` | UpdateCrmSettingsBody | no | The sync settings to change. Omitted settings keep their value. |
| `syncObjects` | map of CrmSyncObjectPatch | no | The objects to turn on or off, keyed by `company`, `contact`, `deal`, `activity`, `suppression` or `list`. Omitted objects keep their switch. An object the CRM does not support cannot be turned on. |

### Response 200

`data` is a `CrmConnection`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) | The connection's id. |
| `provider` | string | The CRM: `hubspot`, `salesforce`, `pipedrive`, `attio`, `close`, `highlevel`, `twenty`, `dynamics` or `zoho`. |
| `status` | string | The connection state: `connected`, `needs_reconnect` (the CRM refused Kenso's access, so connect it again), `paused` (sync is stopped, see `pausedReason`) or `disconnected`. |
| `pausedReason` | string | Why sync is paused: `plan` when the workspace's plan no longer includes CRM sync. Omitted unless the status is `paused`. |
| `externalAccountName` | string | The CRM account's name, such as the HubSpot portal or Salesforce organization. Omitted when the CRM gives none. |
| `instanceUrl` | string | The CRM instance's base URL, for a CRM that has one per customer. Omitted otherwise. |
| `connectedAsEmail` | string | The email of the CRM user Kenso connected as. Kenso reads and writes with that user's access. |
| `connectedAt` | string (date-time) | When the CRM was connected, in UTC. |
| `disconnectedAt` | string (date-time) | When the CRM was disconnected, in UTC. Omitted while it is connected. |
| `lastImportStartedAt` | string (date-time) | When the latest import from the CRM started, in UTC. Omitted before the first import. |
| `lastImportCompletedAt` | string (date-time) | When the latest import from the CRM finished, in UTC. Omitted until the first import finishes. |
| `lastInboundAt` | string (date-time) | When Kenso last applied a change read from the CRM, in UTC. |
| `lastOutboundAt` | string (date-time) | When Kenso last finished a write to the CRM, in UTC. |
| `lastError` | string | The latest connection error, such as why the CRM needs a reconnect. Never a copy of the CRM's response. |
| `lastErrorAt` | string (date-time) | When `lastError` happened, in UTC. |
| `syncObjects` | map of CrmSyncObject | The sync switch of each object, always with the six keys `company`, `contact`, `deal`, `activity`, `suppression` and `list`. |
| `settings` | CrmSettings | How Kenso syncs with this CRM. |
| `capabilities` | array of string | What this CRM supports: `companies`, `contacts`, `deals`, `owners`, `activity_write`, `activity_read`, `lists`, `opt_out_write`, `ken_fields`, `webhooks`, `tasks`, `email_activity` and `lifecycles`. A sync object or setting the CRM does not support is refused. |

### Request

```bash
curl -X PATCH "https://api.ken.so/v1/crm-connections/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 '{
  "settings": {
    "createRecordsWhen": "never",
    "salesforcePersonMode": "lead_or_contact",
    "emailLogging": "subject_and_body",
    "pipelineExternalId": "string",
    "stageMap": {
      "key": "string"
    },
    "importDaily": true,
    "skipOpenOpportunities": true,
    "blockCustomers": true,
    "pauseOnRepActivityDays": 1,
    "staticListPerCampaign": true,
    "listSources": [
      {
        "listExternalId": "string",
        "campaignId": 812,
        "keepInSync": true
      }
    ],
    "inboundPeople": {
      "enabled": true,
      "filters": [
        {
          "field": "hs_lead_status",
          "op": "equals",
          "value": "string"
        }
      ],
      "leadStatus": "new",
      "defaultOwnerMemberId": 812
    }
  },
  "syncObjects": {
    "key": {
      "enabled": true
    }
  }
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "id": 812,
    "provider": "hubspot",
    "status": "string",
    "pausedReason": "string",
    "externalAccountName": "string",
    "instanceUrl": "https://example.com",
    "connectedAsEmail": "jane@example.com",
    "connectedAt": "2026-09-23T15:02:11Z",
    "disconnectedAt": "2026-09-23T15:02:11Z",
    "lastImportStartedAt": "2026-09-23T15:02:11Z",
    "lastImportCompletedAt": "2026-09-23T15:02:11Z",
    "lastInboundAt": "2026-09-23T15:02:11Z",
    "lastOutboundAt": "2026-09-23T15:02:11Z",
    "lastError": "string",
    "lastErrorAt": "2026-09-23T15:02:11Z",
    "syncObjects": {
      "key": {
        "enabled": true,
        "enabledAt": "2026-09-23T15:02:11Z"
      }
    },
    "settings": {
      "createRecordsWhen": "interested",
      "salesforcePersonMode": "lead_or_contact",
      "emailLogging": "subject_and_body",
      "pipelineExternalId": "string",
      "stageMap": {
        "key": "string"
      },
      "importDaily": true,
      "skipOpenOpportunities": true,
      "blockCustomers": true,
      "pauseOnRepActivityDays": 1,
      "staticListPerCampaign": true,
      "listSources": [
        {
          "listExternalId": "string",
          "campaignId": 812,
          "keepInSync": true
        }
      ],
      "inboundPeople": {
        "enabled": true,
        "filters": [
          {
            "field": "hs_lead_status",
            "op": "equals",
            "value": "string"
          }
        ],
        "leadStatus": "new",
        "defaultOwnerMemberId": 812,
        "enabledAt": "2026-09-23T15:02:11Z"
      }
    },
    "capabilities": [
      "string"
    ]
  }
}
```

## Types

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

### UpdateCrmSettingsBody

The sync settings to change. Omitted settings keep their value.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `createRecordsWhen` | string | no | When Kenso creates a CRM record for a campaign contact: `never`, `first_send`, `first_reply` or `interested`. HubSpot refuses `first_send`. |
| `salesforcePersonMode` | string | no | Salesforce only. The record Kenso writes for a person: `lead_or_contact`, `lead` or `contact`. |
| `emailLogging` | string | no | What Kenso logs on the CRM for each email: `subject_and_body` or `subject_only`. |
| `pipelineExternalId` | string | no | The CRM deal pipeline Kenso writes deals to, from `GET /v1/crm-connections/{connectionId}/pipelines`. An empty string clears the pipeline and the stage map. A new pipeline sent without a `stageMap` gets a default map. |
| `stageMap` | map of string | no | Replaces the whole stage map: each CRM stage id of the pipeline to a Kenso opportunity stage key that is not archived. A non-empty map needs a pipeline. |
| `importDaily` | boolean | no | When true, each night Kenso adds a Kenso account for every new company in the company lists among `listSources`. |
| `skipOpenOpportunities` | boolean | no | When true, Kenso holds sends to a contact whose CRM contact or company has an open deal. |
| `blockCustomers` | boolean | no | When true and suppression sync is on, Kenso blocks the domains of every company the CRM marks as a customer. |
| `pauseOnRepActivityDays` | integer (int32) | no | Days Kenso holds sends to a contact after a rep worked that contact in the CRM, from 0 to 365. 0 turns the hold off. |
| `staticListPerCampaign` | boolean | no | When true, Kenso keeps one static CRM list per campaign. Needs a CRM with the `lists` capability. |
| `listSources` | array of CrmListSourceBody | no | Replaces the whole list of CRM lists that feed campaigns, at most 50. A non-empty list needs a CRM with the `lists` capability. An empty list removes every source. |
| `inboundPeople` | UpdateCrmInboundPeopleBody | no | Whether new CRM contacts become people in Kenso, and which ones. Omitted fields keep their value. |

### CrmSyncObjectPatch

The switch for one sync object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | boolean | yes | Required. True to sync the object, false to stop. |

### CrmListSourceBody

A CRM list whose members Kenso adds to a campaign.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `listExternalId` | string | yes | Required. The CRM list's id, from `GET /v1/crm-connections/{connectionId}/lists`. |
| `campaignId` | integer (int64) | yes | Required. The campaign in this workspace that the list's members join. |
| `keepInSync` | boolean | no | True (the default) to keep reading the list and add new members as they join. False for a one-time import. Kenso never removes a contact that left the list. |

### UpdateCrmInboundPeopleBody

The changes to how new CRM contacts become people. Omitted fields keep their value.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | boolean | no | True to turn it on, false to turn it off. Turning it on needs a CRM with the `contacts` capability. |
| `filters` | array of CrmInboundPeopleFilterBody | no | Replaces the whole list of filters, at most 10. A new CRM contact must pass all of them. An empty list removes every filter. |
| `leadStatus` | string | no | The lead status Kenso sets on a new person that has none: `new`, `working`, `qualified`, `disqualified` or `nurture`. |
| `defaultOwnerMemberId` | integer (int64) | no | The member who owns a new person when the CRM contact's owner matches no member. Send null to clear it. |

### CrmInboundPeopleFilterBody

One filter a new CRM contact must pass to become a person.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `field` | string | yes | Required. The CRM field's API name as the CRM shows it, such as `hs_lead_status` in HubSpot or `LeadSource` in Salesforce. At most 255 characters. |
| `op` | string | yes | Required. How the field is compared: `equals`, `contains`, `in` or `not_empty`. |
| `value` | string | no | The value to compare, ignoring case, at most 1,000 characters. Required except for `not_empty`. For `in`, a comma-separated list. |

### CrmSyncObject

The sync switch of one CRM object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | boolean | no | True when Kenso syncs this object. |
| `enabledAt` | string (date-time) | no | When sync of this object was last turned on, in UTC. Omitted while it is off. |

### CrmSettings

How Kenso syncs with a CRM.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `createRecordsWhen` | string | no | When Kenso creates a CRM record for a campaign contact: `never`, `first_send`, `first_reply` or `interested` (the default). HubSpot reads `first_send` as `first_reply`. |
| `salesforcePersonMode` | string | no | Salesforce only. The record Kenso writes for a person: `lead_or_contact` (the default), `lead` or `contact`. |
| `emailLogging` | string | no | What Kenso logs on the CRM for each email: `subject_and_body` (the default) or `subject_only`. |
| `pipelineExternalId` | string | no | The CRM deal pipeline Kenso writes deals to. Omitted when none is picked. |
| `stageMap` | map of string | no | Maps each CRM stage id of the pipeline to a Kenso opportunity stage key. |
| `importDaily` | boolean | no | When true (the default), each night Kenso adds a Kenso account for every new company in the company lists among `listSources`. Needs company sync on. |
| `skipOpenOpportunities` | boolean | no | When true (the default), Kenso holds sends to a contact whose CRM contact or company has an open deal, and checks again each day. |
| `blockCustomers` | boolean | no | When true (the default) and suppression sync is on, Kenso blocks the domains of every company the CRM marks as a customer. |
| `pauseOnRepActivityDays` | integer (int32) | no | Days Kenso holds sends to a contact after a rep worked that contact in the CRM, from 0 to 365. The default is 14. 0 turns the hold off. |
| `staticListPerCampaign` | boolean | no | When true, Kenso keeps one static CRM list per campaign with the campaign's contacts. False by default. |
| `listSources` | array of CrmListSource | no | CRM lists whose members Kenso adds to a campaign. Empty when none. |
| `inboundPeople` | CrmInboundPeople | no | Whether new CRM contacts become people in Kenso, and which ones. |

### CrmListSource

A CRM list whose members Kenso adds to a campaign.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `listExternalId` | string | no | The CRM list's id, from `GET /v1/crm-connections/{connectionId}/lists`. |
| `campaignId` | integer (int64) | no | The campaign the list's members join. |
| `keepInSync` | boolean | no | True when Kenso keeps reading the list and adds new members as they join. False for a one-time import. Kenso never removes a contact that left the list. |

### CrmInboundPeople

Whether new CRM contacts become people in Kenso. While it is on, each contact the CRM creates that passes every filter becomes a person.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | boolean | no | True when new CRM contacts become people. |
| `filters` | array of CrmInboundPeopleFilter | no | Filters a new CRM contact must all pass. Empty lets every new contact through. |
| `leadStatus` | string | no | The lead status Kenso sets on a new person that has none: `new` (the default), `working`, `qualified`, `disqualified` or `nurture`. |
| `defaultOwnerMemberId` | integer (int64) | no | The member who owns a new person when the CRM contact's owner matches no member. Omitted when none is set. |
| `enabledAt` | string (date-time) | no | When this was turned on, in UTC. Contacts the CRM created earlier never become people. Omitted while it is off. |

### CrmInboundPeopleFilter

One filter a new CRM contact must pass to become a person.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `field` | string | no | The CRM field's API name, such as `hs_lead_status` or `lifecyclestage` in HubSpot, or `LeadSource` in Salesforce. A field the record lacks reads as blank, so a field only Salesforce Leads have leaves every Salesforce Contact out. |
| `op` | string | no | How the field is compared: `equals`, `contains`, `in` or `not_empty`. |
| `value` | string | no | The value to compare, ignoring case. For `in`, a comma-separated list. Omitted for `not_empty`. |
