> 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: List 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.

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

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