> 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-records/openapi.json](/docs/api/crm-records/openapi.json). CLI docs offline: `kenso docs <topic>`.
> Last updated: 2026-11-22.

# CRM records: Look up CRM records

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

## Look up CRM records

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

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

Finds what Kenso holds for a CRM record and the Kenso record it is linked to. Use it to check how a contact or
company matched between Kenso and the CRM.

Send exactly one of `email`, `domain` or `externalId`. `externalId` also needs
`objectType`. The call returns at most 20 records. It reads only the records Kenso imported from this
connection's CRM account and makes no call to the CRM. It also answers for a disconnected connection.

Errors:

- `400 validation_failed`: none or more than one of `email`, `domain` and `externalId` was sent, the email or domain is not valid, or `objectType` is missing or unknown.
- `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-sync/GET/v1/crm-connections/%7BconnectionId%7D/records)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `connectionId` | path | integer (int64) | yes | The CRM connection's id. |
| `email` | query | string | no | Find records with this email address. Send exactly one of `email`, `domain` and `externalId`. |
| `domain` | query | string | no | Find records at this company domain, such as `acme.com`. |
| `externalId` | query | string | no | Find the record with this id in the CRM. Needs `objectType`. |
| `objectType` | query | string | no | The record type for `externalId`: `company`, `contact`, `deal`, `owner`, `activity` or `list`. Required with `externalId` and ignored otherwise. |
| `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 `CrmRecord`. Each item has these fields. The response also carries `pagination`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) | Kenso's id for this CRM record. |
| `objectType` | string | The CRM object: `company`, `contact`, `deal`, `owner`, `activity` or `list`. |
| `externalId` | string | The record's id in the CRM. |
| `externalSubtype` | string | The CRM's own kind of record when one object covers several, such as `lead` for a lead in a CRM that keeps leads apart from contacts. Omitted otherwise. |
| `externalUrl` | string | A link that opens the record in the CRM. Omitted when the CRM gives none. |
| `email` | string | The record's email, for a contact or owner. |
| `domain` | string | The record's domain, for a company. |
| `displayName` | string | The record's name as the CRM shows it. |
| `ownerExternalId` | string | The id of the CRM user who owns the record. |
| `lifecycle` | string | The record's lifecycle stage: `lead`, `prospect`, `opportunity`, `customer`, `churned` or `other`. Omitted when the CRM gives none. |
| `isOptedOut` | boolean | True when the CRM marks the contact as opted out of email. |
| `isCustomer` | boolean | True when the CRM marks the company as a customer. |
| `hasOpenDeal` | boolean | True when the record has an open deal in the CRM. |
| `lastRepActivityAt` | string (date-time) | When a rep last worked the record in the CRM, in UTC. |
| `crmUpdatedAt` | string (date-time) | When the record last changed in the CRM, in UTC. |
| `lastSyncedAt` | string (date-time) | When Kenso last synced the record, in UTC. |
| `crmDeletedAt` | string (date-time) | When the record was deleted or merged away in the CRM, in UTC. Kenso never deletes the linked Kenso record. |
| `mergedIntoExternalId` | string | The CRM id of the record this one was merged into. Omitted unless it was merged. |
| `snapshot` | map of string | The values of mapped CRM fields as Kenso last read them, keyed by the CRM field's API name. |
| `linked` | CrmLinkedEntity | The Kenso record or member the CRM record is linked to. Omitted when it is not linked. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/crm-connections/812/records" \
  -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,
      "objectType": "company",
      "externalId": "string",
      "externalSubtype": "lead",
      "externalUrl": "https://example.com",
      "email": "jane@example.com",
      "domain": "example.com",
      "displayName": "string",
      "ownerExternalId": "string",
      "lifecycle": "lead",
      "isOptedOut": true,
      "isCustomer": true,
      "hasOpenDeal": true,
      "lastRepActivityAt": "2026-09-23T15:02:11Z",
      "crmUpdatedAt": "2026-09-23T15:02:11Z",
      "lastSyncedAt": "2026-09-23T15:02:11Z",
      "crmDeletedAt": "2026-09-23T15:02:11Z",
      "mergedIntoExternalId": "string",
      "snapshot": {
        "key": "string"
      },
      "linked": {
        "entityType": "string",
        "entityId": 812,
        "entityKey": "string",
        "entityRef": "account:1042"
      }
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6ODE1fQ",
    "hasMore": true,
    "total": 1,
    "totalCount": 1,
    "isTotalCapped": true
  }
}
```

## Types

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

### CrmLinkedEntity

The Kenso record or member a CRM record is linked to.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `entityType` | string | no | What it is linked to: `account`, `person`, `contact_email` (a campaign contact with no person), `company_domain` (a company with no account), `opportunity`, `member`, `activity_event` or `campaign`. |
| `entityId` | integer (int64) | no | The linked record's id. Omitted for `contact_email` and `company_domain`. |
| `entityKey` | string | no | The key of a link with no id: the email for `contact_email`, the domain for `company_domain`. |
| `entityRef` | string | no | A reference such as `account:1042`, for the record types the sync writes. Omitted for the others. |
