> 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

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

Connect a CRM and manage the connection.

Integrations. 7 endpoints under `https://api.ken.so`. Every request sends `Authorization: Bearer <your API key>` and `Ken-Version: 2026-11-02`: see [Authentication](/docs/authentication.md), [Workspaces](/docs/workspaces.md) and [Errors](/docs/errors.md). OpenAPI for this resource only: [/docs/api/crm-connections/openapi.json](/docs/api/crm-connections/openapi.json).

- `GET /v1/crm-connections` - List CRM connections (`crm-connections.list`): [/docs/api/crm-connections/list.md](/docs/api/crm-connections/list.md)
- `POST /v1/crm-connections` - Connect a CRM (`crm-connections.create`): [/docs/api/crm-connections/create.md](/docs/api/crm-connections/create.md)
- `GET /v1/crm-connections/{connectionId}` - Get a CRM connection (`crm-connections.get`): [/docs/api/crm-connections/get.md](/docs/api/crm-connections/get.md)
- `PATCH /v1/crm-connections/{connectionId}` - Update a CRM connection (`crm-connections.update`): [/docs/api/crm-connections/update.md](/docs/api/crm-connections/update.md)
- `DELETE /v1/crm-connections/{connectionId}` - Disconnect a CRM (`crm-connections.delete`): [/docs/api/crm-connections/delete.md](/docs/api/crm-connections/delete.md)
- `POST /v1/crm-connections/oauth/complete` - Finish an OAuth connection (`crm-connections.complete-oauth`): [/docs/api/crm-connections/complete-oauth.md](/docs/api/crm-connections/complete-oauth.md)
- `GET /v1/crm-connections/{connectionId}/preview` - Preview a CRM sync (`crm-connections.preview`): [/docs/api/crm-connections/preview.md](/docs/api/crm-connections/preview.md)

## List CRM connections

`GET /v1/crm-connections` - operationId `crm-connections.list`

| Permission | Rate limit |
| --- | --- |
| Accounts view | 12,000 requests a minute per API key |

Returns the workspace's live CRM connection, or an empty list when no CRM is connected. A live connection has
status `connected`, `needs_reconnect` or `paused`. A workspace has at most one, so the list holds
one item at most.

To read a disconnected connection, call `GET /v1/crm-connections/{connectionId}` with its id.

Requires Accounts view.

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/GET/v1/crm-connections)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer (int32) | no | Items per page, from 1 to 200. Omit `limit` and `cursor` to get every item in one response, as before; with only `cursor`, 50 per page. |
| `cursor` | query | string | no | The `nextCursor` of the previous page. Omit it for the first page. |
| `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`. |

### Response 200

`data` is a list of `CrmConnection`. Each item has these fields. The response also carries `pagination`.

| 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 GET "https://api.ken.so/v1/crm-connections?limit=1" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### 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": [
            {}
          ],
          "leadStatus": "new",
          "defaultOwnerMemberId": 812,
          "enabledAt": "2026-09-23T15:02:11Z"
        }
      },
      "capabilities": [
        "string"
      ]
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6ODE1fQ",
    "hasMore": true,
    "total": 1,
    "totalCount": 1,
    "isTotalCapped": true
  }
}
```

## Connect a CRM

`POST /v1/crm-connections` - operationId `crm-connections.create`

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

Starts a connection to the CRM named in `provider`. The call must come from a member: a member's session or
an API key tied to a member.

For an OAuth CRM, Kenso answers 200 with `authorizeUrl`. Send the member's browser there. After consent, the
CRM returns the browser to the Kenso web app, which finishes the connection with
`POST /v1/crm-connections/oauth/complete`. Dynamics 365 also needs `baseUrl`, your organization URL.
For Close or Twenty, send `apiKey`, plus `baseUrl` for a self-hosted Twenty. Kenso checks the key with
the CRM and answers 201 with the connection.
You can connect the CRM the workspace already uses again, for example after a lost token or a missing scope. The
same CRM account keeps its connection.
Any plan can connect. On the Free plan the connection starts with `status` `paused` and
`pausedReason` `plan`: it syncs nothing until the workspace is on a paid plan, then it resumes and runs
its first import.

Errors:

- `400 validation_failed`: `provider` is not a supported CRM, `apiKey` or `baseUrl` is missing or the CRM refused it, `baseUrl` is not an https URL, or `returnPath` is not an app path.
- `403 forbidden`: the API key is not tied to a member.
- `404 not_found`: this CRM is not available to the workspace.
- `409 crm_already_connected`: the workspace is connected to another CRM. Disconnect it first.
- `503 crm_unavailable`: Kenso cannot reach the CRM or start its OAuth flow right now. 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/POST/v1/crm-connections)

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `provider` | string | yes | Required. The CRM: `hubspot`, `salesforce`, `pipedrive`, `attio`, `close`, `highlevel`, `twenty`, `dynamics` or `zoho`. |
| `apiKey` | string | no | Your CRM API key. Required for Close and Twenty, ignored for the other CRMs. Kenso never logs it. |
| `baseUrl` | string | no | An absolute https URL. For a self-hosted Twenty, its base URL. Required for Dynamics 365: your organization URL, such as `https://contoso.crm.dynamics.com`. |
| `returnPath` | string | no | An app path to return the member to after OAuth, starting with a single `/`, without spaces, at most 300 characters. `POST /v1/crm-connections/oauth/complete` returns it. |
| `installSource` | string | no | Where the install started: `app` (the default) or `marketplace`, the Install button of the CRM's app marketplace listing. Kenso records it when the OAuth connect creates the connection. An API-key connect records `app`, and a reconnect keeps the value the connection already has. |

### Response 201

Also answers `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 POST "https://api.ken.so/v1/crm-connections" \
  -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 '{
  "provider": "hubspot",
  "apiKey": "string",
  "baseUrl": "https://contoso.crm.dynamics.com",
  "returnPath": "string",
  "installSource": "app"
}'
```

### 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"
    ]
  }
}
```

## Get a CRM connection

`GET /v1/crm-connections/{connectionId}` - operationId `crm-connections.get`

| Permission | Rate limit |
| --- | --- |
| Accounts view | 12,000 requests a minute per API key |

Returns one CRM connection in any status, `disconnected` included.

Errors:

- `404 not_found`: the workspace has no connection with this id.

Requires Accounts view.

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/GET/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`. |

### 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 GET "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"
```

### 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"
    ]
  }
}
```

## 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"
    ]
  }
}
```

## Disconnect a CRM

`DELETE /v1/crm-connections/{connectionId}` - operationId `crm-connections.delete`

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

Disconnects the CRM. Kenso stops every sync, cancels the changes still queued for or from the CRM, and deletes
its access token. Your Kenso records, the links between Kenso and CRM records, and the data in the CRM stay.

A connection that is already disconnected also answers 204.

Errors:

- `404 not_found`: the workspace has no connection with this id.

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/DELETE/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`. |

### Response 204

### Request

```bash
curl -X DELETE "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"
```

### Example response

```http
HTTP/1.1 204 No Content
```

## Finish an OAuth connection

`POST /v1/crm-connections/oauth/complete` - operationId `crm-connections.complete-oauth`

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

Completes an OAuth connection after the member consents in the CRM. The CRM returns the browser to the Kenso web
app's `/crm/oauth/callback` page, and that page posts what the CRM sent here, signed in as the same member.

Send `state` exactly as the CRM returned it, with `code`, or with `error` when the member declined.
Send `X-Ken-Workspace-Id` set to the part of `state` before the first dot.
Only the member who started the connection, in the same workspace, can finish it, and only within 10 minutes of
the start. Kenso answers any other call with `400 invalid_state` and changes nothing.
The response holds the connection, its `provider` and the `returnPath` sent when the connection started.
On the Free plan the connection is paused for the plan, as `POST /v1/crm-connections` describes.

Errors:

- `400 invalid_state`: the state is missing or expired, or belongs to another member or workspace.
- `400 provider_error`: the member declined consent in the CRM.
- `400 exchange_failed`: `code` is missing, or the CRM did not accept it.
- `409 crm_already_connected`: the workspace connected another CRM in the meantime.
- `409 crm_account_mismatch`: the member authorized a different CRM account than the connection's. Disconnect first to switch accounts.
- `503 provider_unavailable`: the CRM is not available to the workspace, or cannot be reached.

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/POST/v1/crm-connections/oauth/complete)

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | no | The CRM's authorization code. Omit it when `error` is set. |
| `state` | string | yes | Required. The `state` value exactly as the CRM returned it, in the form `{workspaceId}.{token}`. |
| `error` | string | no | The CRM's `error` value, sent when the member declined consent. Kenso never returns it. |
| `errorDescription` | string | no | The CRM's `error_description` value. Kenso never returns it. |
| `accountsServer` | string | no | Zoho CRM only: the callback's `accounts-server` value, which names the Zoho data center that issued the code. Kenso uses it only when it is one of Zoho's accounts servers, and ignores it for every other CRM. |

### Response 200

`data` is a `CrmOAuthCompletion`.

| Field | Type | Description |
| --- | --- | --- |
| `provider` | string | The CRM, such as `hubspot` or `salesforce`. |
| `returnPath` | string | The `returnPath` sent with `POST /v1/crm-connections`. Omitted when none was sent. |
| `connection` | CrmConnection | The CRM connection. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/crm-connections/oauth/complete" \
  -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 '{
  "code": "string",
  "state": "string",
  "error": "string",
  "errorDescription": "string",
  "accountsServer": "string"
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "provider": "hubspot",
    "returnPath": "string",
    "connection": {
      "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": [
            {}
          ],
          "leadStatus": "new",
          "defaultOwnerMemberId": 812,
          "enabledAt": "2026-09-23T15:02:11Z"
        }
      },
      "capabilities": [
        "string"
      ]
    }
  }
}
```

## Preview a CRM sync

`GET /v1/crm-connections/{connectionId}/preview` - operationId `crm-connections.preview`

| Permission | Rate limit |
| --- | --- |
| Accounts view | 12,000 requests a minute per API key |

Shows what turning sync on would do, without writing anything. Call it after the first import and before you turn
on sync objects.

The preview counts the CRM records the import read and the ones it linked to Kenso records. It counts the CRM
records Kenso would create now under `createRecordsWhen`, and the CRM field values Kenso would change on
records that already exist, with samples. It also lists the CRM users who match no workspace member by email.
It reads only data Kenso holds and makes no call to the CRM.

Errors:

- `404 not_found`: the workspace has no connection with this id.
- `409 import_pending`: the first import has not finished yet.
- `409 invalid_state`: the connection is disconnected.

Requires Accounts view.

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-sync/GET/v1/crm-connections/%7BconnectionId%7D/preview)

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

### Response 200

`data` is a `CrmPreview`.

| Field | Type | Description |
| --- | --- | --- |
| `matched` | CrmObjectCounts | CRM records the import linked to a Kenso record, by object. |
| `read` | CrmObjectCounts | CRM records the import read, by object. |
| `wouldCreate` | CrmWouldCreate | CRM records Kenso would create now under the connection's `createRecordsWhen` setting. |
| `fieldUpdates` | CrmFieldUpdates | CRM field values Kenso would change on records that already exist in the CRM. |
| `unmatchedOwners` | array of CrmUnmatchedOwner | CRM users whose email matches no member, at most 50. |
| `importCompletedAt` | string (date-time) | When the import the preview reads finished, in UTC. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/crm-connections/812/preview" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": {
    "matched": {
      "companies": 1,
      "contacts": 1,
      "deals": 1,
      "owners": 1
    },
    "read": {
      "companies": 1,
      "contacts": 1,
      "deals": 1,
      "owners": 1
    },
    "wouldCreate": {
      "contacts": 1,
      "companies": 1,
      "createRecordsWhen": "string",
      "complete": true,
      "excludedLibraryContacts": 1
    },
    "fieldUpdates": {
      "count": 1,
      "recordsChecked": 1,
      "complete": true,
      "samples": [
        {
          "entityRef": "account:1042",
          "objectType": "company",
          "crmField": "string",
          "kenField": "string",
          "from": "string",
          "to": "string"
        }
      ]
    },
    "unmatchedOwners": [
      {
        "externalId": "string",
        "email": "jane@example.com",
        "name": "string"
      }
    ],
    "importCompletedAt": "2026-09-23T15:02:11Z"
  }
}
```

## Types

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

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

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

### CrmConnection

A workspace's connection to one CRM, with its sync settings and the sync switch of each object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer (int64) | no | The connection's id. |
| `provider` | string | no | The CRM: `hubspot`, `salesforce`, `pipedrive`, `attio`, `close`, `highlevel`, `twenty`, `dynamics` or `zoho`. |
| `status` | string | no | 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 | no | Why sync is paused: `plan` when the workspace's plan no longer includes CRM sync. Omitted unless the status is `paused`. |
| `externalAccountName` | string | no | The CRM account's name, such as the HubSpot portal or Salesforce organization. Omitted when the CRM gives none. |
| `instanceUrl` | string | no | The CRM instance's base URL, for a CRM that has one per customer. Omitted otherwise. |
| `connectedAsEmail` | string | no | The email of the CRM user Kenso connected as. Kenso reads and writes with that user's access. |
| `connectedAt` | string (date-time) | no | When the CRM was connected, in UTC. |
| `disconnectedAt` | string (date-time) | no | When the CRM was disconnected, in UTC. Omitted while it is connected. |
| `lastImportStartedAt` | string (date-time) | no | When the latest import from the CRM started, in UTC. Omitted before the first import. |
| `lastImportCompletedAt` | string (date-time) | no | When the latest import from the CRM finished, in UTC. Omitted until the first import finishes. |
| `lastInboundAt` | string (date-time) | no | When Kenso last applied a change read from the CRM, in UTC. |
| `lastOutboundAt` | string (date-time) | no | When Kenso last finished a write to the CRM, in UTC. |
| `lastError` | string | no | The latest connection error, such as why the CRM needs a reconnect. Never a copy of the CRM's response. |
| `lastErrorAt` | string (date-time) | no | When `lastError` happened, in UTC. |
| `syncObjects` | map of CrmSyncObject | no | The sync switch of each object, always with the six keys `company`, `contact`, `deal`, `activity`, `suppression` and `list`. |
| `settings` | CrmSettings | no | How Kenso syncs with this CRM. |
| `capabilities` | array of string | no | 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. |

### CrmObjectCounts

Counts of CRM records by object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `companies` | integer (int32) | no | Companies. |
| `contacts` | integer (int32) | no | Contacts, including leads. |
| `deals` | integer (int32) | no | Deals. |
| `owners` | integer (int32) | no | CRM users. |

### CrmWouldCreate

CRM records Kenso would create now under the connection's `createRecordsWhen` setting.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `contacts` | integer (int32) | no | Contacts Kenso would create. |
| `companies` | integer (int32) | no | Companies Kenso would create. Always 0 for a CRM without the `companies` capability, and for Salesforce unless `salesforcePersonMode` is `contact`. |
| `createRecordsWhen` | string | no | The `createRecordsWhen` setting the counts use. |
| `complete` | boolean | no | True when the counts are exact. False when counting stopped at its cap. |
| `excludedLibraryContacts` | integer (int32) | no | Contacts the rule picked that Kenso leaves out because they came only from a Kenso library list. Kenso never sends library contacts to a CRM in bulk. |

### CrmFieldUpdates

CRM field values Kenso would change on records that already exist in the CRM.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `count` | integer (int32) | no | Field values Kenso would change across the records checked. |
| `recordsChecked` | integer (int32) | no | Linked records checked, at most 300 each for companies, contacts and deals. |
| `complete` | boolean | no | True when every linked record was checked. False when the cap left some out. |
| `samples` | array of CrmFieldUpdateSample | no | Up to 10 of the changes, as examples. |

### CrmUnmatchedOwner

A CRM user whose email matches no member.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `externalId` | string | no | The CRM user's id. |
| `email` | string | no | The CRM user's email. Omitted when the CRM gives none. |
| `name` | string | no | The CRM user's name. Omitted when the CRM gives none. |

### CrmFieldUpdateSample

One CRM field value Kenso would change.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `entityRef` | string | no | The Kenso record, such as `account:1042` or `person:88231`. |
| `objectType` | string | no | The CRM object: `company`, `contact` or `deal`. |
| `crmField` | string | no | The CRM field's API name. |
| `kenField` | string | no | The Kenso field mapped to the CRM field. Omitted when no mapping names it. |
| `from` | string | no | The CRM's current value. Omitted when the CRM holds none. |
| `to` | string | no | The value Kenso would write. Omitted when Kenso would clear the field. |

All resources: [/docs.md](/docs.md).
