Skip to Content
Integrations

CRM connections

Connect a CRM and manage the connection.

Integrations7 endpointsKen-Version: 2026-11-02AuthenticationWorkspacesErrors
MarkdownOpenAPI

Path parameters

The endpoints whose path names one of these take it as described here. An endpoint's own table lists a path parameter only when it describes it differently.

NameInTypeRequiredDescription
connectionIdpathinteger (int64)requiredThe CRM connection's id.

Headers

The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.

NameInTypeRequiredDescription
Ken-Versionheaderstring, one of: 2026-11-02, 1.1optionalThe 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 date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy.
X-Ken-Workspace-Idheaderinteger (int64)optionalThe 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.

List CRM connections

GET/v1/crm-connectionscrm-connections.list
Permission
Accounts view
Rate limit
12,000 requests a minute per API key
Needs the ingestion feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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.

Parameters

NameInTypeRequiredDescription
limitqueryinteger (int32)optionalItems 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.
cursorquerystringoptionalThe nextCursor of the previous page. Omit it for the first page.
Request
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"

Response 200

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

Show the 18 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Connect a CRM

POST/v1/crm-connectionscrm-connections.create
Permission
Accounts view and the integrations permission
Rate limit
30 requests a minute per API key
Needs the ingestion feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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.

Request body

application/json, optional.

FieldTypeRequiredDescription
providerstringrequiredRequired. The CRM: hubspot, salesforce, pipedrive, attio, close, highlevel, twenty, dynamics or zoho.
apiKeystringoptionalYour CRM API key. Required for Close and Twenty, ignored for the other CRMs. Kenso never logs it.
baseUrlstringoptionalAn 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.
returnPathstringoptionalAn 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.
installSourcestringoptionalWhere 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.
Request
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"
}'

Response 201

Also answers 200. data is a CrmConnection.

Show the 18 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Get a CRM connection

GET/v1/crm-connections/{connectionId}crm-connections.get
Permission
Accounts view
Rate limit
12,000 requests a minute per API key
Needs the ingestion feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Returns one CRM connection in any status, disconnected included.

Errors:

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

Requires Accounts view.

Request
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"

Response 200

data is a CrmConnection.

Show the 18 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Update a CRM connection

PATCH/v1/crm-connections/{connectionId}crm-connections.update
Permission
Accounts view and the integrations permission
Rate limit
4,800 requests a minute per API key
Needs the ingestion feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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.

Request body

application/json, optional.

FieldTypeRequiredDescription
settingsUpdateCrmSettingsBodyoptionalThe sync settings to change. Omitted settings keep their value.
syncObjectsmap of CrmSyncObjectPatchoptionalThe 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.
Request
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
    }
  }
}'

Response 200

data is a CrmConnection.

Show the 18 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Disconnect a CRM

DELETE/v1/crm-connections/{connectionId}crm-connections.delete
Permission
Accounts view and the integrations permission
Rate limit
4,800 requests a minute per API key
Needs the ingestion feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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.

Request
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"

Response 204

Response 204
HTTP/1.1 204 No Content

Finish an OAuth connection

POST/v1/crm-connections/oauth/completecrm-connections.complete-oauth
Permission
Accounts view and the integrations permission
Rate limit
30 requests a minute per API key
Needs the ingestion feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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.

Request body

application/json, optional.

FieldTypeRequiredDescription
codestringoptionalThe CRM's authorization code. Omit it when error is set.
statestringrequiredRequired. The state value exactly as the CRM returned it, in the form {workspaceId}.{token}.
errorstringoptionalThe CRM's error value, sent when the member declined consent. Kenso never returns it.
errorDescriptionstringoptionalThe CRM's error_description value. Kenso never returns it.
accountsServerstringoptionalZoho 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.
Request
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"
}'

Response 200

data is a CrmOAuthCompletion.

Show the 3 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Preview a CRM sync

GET/v1/crm-connections/{connectionId}/previewcrm-connections.preview
Permission
Accounts view
Rate limit
12,000 requests a minute per API key
Needs the ingestion feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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.

Request
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"

Response 200

data is a CrmPreview.

Show the 6 response fields and an example

The fields and an example are also on this endpoint's Markdown page.


On this page