CRM connections
Connect a CRM and manage the connection.
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.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
connectionId | path | integer (int64) | required | The CRM connection's id. |
Headers
The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Ken-Version | header | string, one of: 2026-11-02, 1.1 | optional | 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 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-Id | header | integer (int64) | optional | 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. |
List CRM connections
/v1/crm-connectionscrm-connections.list- Permission
- Accounts view
- Rate limit
- 12,000 requests a minute per API key
ingestion feature on your workspace. Until it is on, calls answer 404.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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer (int32) | optional | 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 | optional | The nextCursor of the previous page. Omit it for the first page. |
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
/v1/crm-connectionscrm-connections.create- Permission
- Accounts view and the
integrationspermission - Rate limit
- 30 requests a minute per API key
ingestion feature on your workspace. Until it is on, calls answer 404.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:provideris not a supported CRM,apiKeyorbaseUrlis missing or the CRM refused it,baseUrlis not an https URL, orreturnPathis 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.
| Field | Type | Required | Description |
|---|---|---|---|
provider | string | required | Required. The CRM: hubspot, salesforce, pipedrive, attio, close, highlevel, twenty, dynamics or zoho. |
apiKey | string | optional | Your CRM API key. Required for Close and Twenty, ignored for the other CRMs. Kenso never logs it. |
baseUrl | string | optional | 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 | optional | 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 | optional | 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. |
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
/v1/crm-connections/{connectionId}crm-connections.get- Permission
- Accounts view
- Rate limit
- 12,000 requests a minute per API key
ingestion feature on your workspace. Until it is on, calls answer 404.Returns one CRM connection in any status, disconnected included.
Errors:
404 not_found: the workspace has no connection with this id.
Requires Accounts view.
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
/v1/crm-connections/{connectionId}crm-connections.update- Permission
- Accounts view and the
integrationspermission - Rate limit
- 4,800 requests a minute per API key
ingestion feature on your workspace. Until it is on, calls answer 404.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.detailsnames 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.
| Field | Type | Required | Description |
|---|---|---|---|
settings | UpdateCrmSettingsBody | optional | The sync settings to change. Omitted settings keep their value. |
syncObjects | map of CrmSyncObjectPatch | optional | 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. |
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
/v1/crm-connections/{connectionId}crm-connections.delete- Permission
- Accounts view and the
integrationspermission - Rate limit
- 4,800 requests a minute per API key
ingestion feature on your workspace. Until it is on, calls answer 404.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.
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
HTTP/1.1 204 No ContentFinish an OAuth connection
/v1/crm-connections/oauth/completecrm-connections.complete-oauth- Permission
- Accounts view and the
integrationspermission - Rate limit
- 30 requests a minute per API key
ingestion feature on your workspace. Until it is on, calls answer 404.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:codeis 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.
| Field | Type | Required | Description |
|---|---|---|---|
code | string | optional | The CRM's authorization code. Omit it when error is set. |
state | string | required | Required. The state value exactly as the CRM returned it, in the form {workspaceId}.{token}. |
error | string | optional | The CRM's error value, sent when the member declined consent. Kenso never returns it. |
errorDescription | string | optional | The CRM's error_description value. Kenso never returns it. |
accountsServer | string | optional | 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. |
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
/v1/crm-connections/{connectionId}/previewcrm-connections.preview- Permission
- Accounts view
- Rate limit
- 12,000 requests a minute per API key
ingestion feature on your workspace. Until it is on, calls answer 404.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.
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.
More in Integrations:Webhook endpointsWebhook deliveriesWebhook event typesEventsInbound webhooksCRM syncCRM field mappingsCRM fieldsCRM importsCRM listsCRM pipelinesCRM recordsCRM sync issuesTriggersTrigger firingsTrigger schemasEvent subscriptionsEvent logAll resources