> Kenso API docs in Markdown. Index of every page: [/docs/llms.txt](/docs/llms.txt). Search: `/docs/search.md?q=<words>`. OpenAPI: [/docs/api/contacts/openapi.json](/docs/api/contacts/openapi.json). CLI docs offline: `kenso docs <topic>`.
> Last updated: 2026-11-22.

# Contacts: List contacts

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

## List contacts

`GET /v1/contacts` - operationId `contacts.list`

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

Returns the workspace's contacts, ordered by id. Deleted contacts are left out. The query parameters narrow
the list to one campaign, segment or company, an email address, a person (`personId`: their contact in each
campaign they are in), a name search, a qualified or do-not-contact state, or a creation time range.

`sort=createdAt` lists by each contact's `createdAt`, oldest first, and `sort=-createdAt` newest
first. Keep the same `sort` while you page: a cursor from another order is refused.

Each contact on a page counts against the workspace's daily allowance of API read rows. Past it, the call
returns `429 quota_exceeded` with a `Retry-After` header. To filter on more than one
campaign, on contact fields or on another sort order, use `POST /v1/contacts/search`.

A contact has about 95 properties. `fields` names the ones you read, for example
`fields=id,email,companyName`, and each contact then holds only those: the page is smaller and faster.
Without `fields` every property is returned.

Errors:

- `400 validation_failed`: `limit` is not between 1 and 1,000, `sort` is not `createdAt` or
`-createdAt`, `cursor` is not valid or comes from another `sort`, `createdBefore` is
not later than `createdAfter`, or `fields` names something that is not a top-level contact property.
- `429 quota_exceeded`: the workspace used up its API read rows for the day.

Requires Campaigns view.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/contacts/GET/v1/contacts)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `campaignId` | query | integer (int64) | no | Only contacts in this campaign. |
| `companyId` | query | integer (int64) | no | Only contacts at this company, matched on the contact's `companyId`. |
| `segmentId` | query | integer (int64) | no | Only contacts in this campaign segment. |
| `email` | query | string | no | Only contacts that have this email address. The match is exact and ignores case. |
| `personId` | query | integer (int64) | no | Only the contacts of this person, one per campaign they are in. |
| `q` | query | string | no | Free-text search on the first name, last name, full name and email addresses. It matches any part of a value and ignores case. |
| `isQualified` | query | boolean | no | True keeps only qualified contacts, false only unqualified ones. Omitted keeps both. |
| `doNotContact` | query | boolean | no | True keeps only do-not-contact contacts, false only the others. Omitted keeps both. |
| `createdAfter` | query | string (date-time) | no | Only contacts created at or after this time, in UTC. |
| `createdBefore` | query | string (date-time) | no | Only contacts created before this time, in UTC. Must be later than `createdAfter`. |
| `sort` | query | string | no | The order, by each contact's `createdAt`: `createdAt` lists oldest first and `-createdAt` newest first. Omitted keeps the id order. Keep the same `sort` while you page. |
| `limit` | query | integer (int32) | no | Contacts per page, from 1 to 1000. Default 50. |
| `cursor` | query | string | no | The `nextCursor` of the previous page. Omitted starts at the first page. |
| `fields` | query | string | no | The contact properties to return, as a comma-separated list of top-level names, for example `id,email,companyName`. Each contact then holds only those. Omitted returns every property. |
| `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 `Contact`. Each item has these fields. The response also carries `pagination`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) | The contact id. |
| `campaignId` | integer (int64) | The campaign the contact is in. Null when the contact is in no campaign. |
| `segmentId` | integer (int64) | The campaign segment the contact is in. |
| `campaignListId` | integer (int64) | The import list that added the contact to its campaign. Each import makes one list. Pass it as `listId` to export the contacts of that import. |
| `companyId` | integer (int64) | The id of the contact's company record. |
| `companyName` | string | Company name. |
| `companyEmailName` | string | The company name as Ken writes it in emails: a short form without taglines, trademark signs or text in brackets. |
| `firstName` | string | First name. |
| `lastName` | string | Last name. |
| `email` | string | The contact's first email address. The address `emailValidity` describes can be a later one. |
| `linkedInUrl` | string | LinkedIn profile URL. |
| `profileUrn` | string | The LinkedIn member id of the profile, such as a Sales Navigator id, when Kenso knows it. |
| `isOpenLink` | boolean | True when the LinkedIn profile is an Open Profile, which any LinkedIn member can message without a connection. Null when unknown. |
| `jsonGeoLocation` | string | The LinkedIn profile's location details as a JSON string. |
| `title` | string | Job title. |
| `isQualified` | boolean | True when the contact is qualified for its campaign. |
| `doNotContact` | boolean | True when the contact is marked do-not-contact. Kenso sends nothing to a do-not-contact contact. |
| `sequenceStoppedAt` | string (date-time) | When the contact's sequence in its campaign stopped, in UTC. Do-not-contact does not set it. Omitted while the sequence runs. |
| `sequenceStopReason` | string | Why the sequence stopped: `paused` (a member paused the contact), `account_play` (the contact matched an active account play after a step), `promoted` (the contact's company was promoted to Accounts), or a reason from a campaign imported from another tool (`migration_finished`, `migration_paused`, `migration_pending`). New reasons can appear. Omitted while the sequence runs. |
| `isDecisionMaker` | boolean | True when Kenso's data marks the person as a decision maker. |
| `qualityScore` | integer (int32) | The contact's lead quality score in its campaign. Null until Kenso scores the contact. |
| `qualityReasoning` | string | Ken's explanation of `qualityScore`. Null without a score. |
| `leadQualityScoreId` | integer (int64) | The id of the lead quality score behind `qualityReasoning`; absent with no reasoning. |
| `profileImage` | string | URL of the person's profile photo. Null when Kenso has no real photo. |
| `qualificationResponse` | string | Ken's latest AI qualification answer for the contact. |
| `qualificationResponseId` | integer (int64) | The id of the qualification answer behind `qualificationResponse`; absent with no answer. |
| `segmentationReasoning` | string | Ken's latest explanation of why the contact is in its segment. |
| `experiencesJson` | string | The person's work history as a JSON string. |
| `customVariables` | map of string | The contact's custom variable values by key, for the keys the campaign defines. Keys without a value are left out. Null when there are none. |
| `emailsSent` | integer (int32) | Emails sent to the contact. The six email counts are omitted until the contact has email stats. |
| `clicks` | integer (int32) | Clicks on links in emails to the contact. |
| `replies` | integer (int32) | Email replies from the contact. |
| `unsubscribes` | integer (int32) | Campaigns the contact unsubscribed from, 0 or 1 for a contact in one campaign. |
| `bounces` | integer (int32) | Emails to the contact that bounced. |
| `positiveReplies` | integer (int32) | Campaigns where the contact sent an interested reply, 0 or 1 for a contact in one campaign. |
| `connectionRequestsSent` | integer (int32) | LinkedIn connection requests sent to the contact and confirmed. The four LinkedIn counts are omitted when the contact has no LinkedIn steps and no confirmed LinkedIn send. |
| `connectionsAccepted` | integer (int32) | 1 when the contact accepted the campaign's LinkedIn connection request, else 0. |
| `linkedInMessagesSent` | integer (int32) | LinkedIn messages and InMails sent to the contact and confirmed. |
| `linkedInReplies` | integer (int32) | 1 when the contact replied on LinkedIn in the campaign, else 0. |
| `headline` | string | LinkedIn headline. |
| `location` | string | Location as the profile writes it. |
| `city` | string | City. |
| `state` | string | State or region. |
| `country` | string | Country name. |
| `countryIso2` | string | Two-letter ISO 3166 country code, such as `DE`. |
| `companyLogo` | string | URL of the company logo. Null when Kenso has no real logo. |
| `emailEnrichmentProviders` | array of string | The email finder that found the contact's first email address, as a list of slugs, such as `ken` for Kenso's own email database. Null when the address did not come from a finder. |
| `linkedInUrlNameMismatch` | boolean | True when the LinkedIn URL looks like someone else's: its name part does not match the contact's first and last name, or it is not a personal profile URL. |
| `segmentName` | string | Name of the contact's segment. |
| `missingRequiredVariableKeys` | array of string | The variables the campaign requires for sending that the contact has no value for: custom variable keys, and image or video variables that are not ready. Null when none are missing. |
| `linkedInSendBlockedReason` | string | Why the contact's LinkedIn sequence is held: `missing_required_variables: <names>` names the `{{name}}` tokens in a LinkedIn step's message or InMail subject that nothing fills, so Kenso stopped the sequence at that step instead of sending them as written. Fix the step's text or give the token a fallback. Null when nothing is held. |
| `emailValidity` | string, one of: unknown, invalid, risky, verified, safe, catch_all, verification_error | The verdict of the contact's first email address that is Safe or Verified: `safe` or `verified`. Null when no address of the contact is Safe or Verified. |
| `emailFromKenPool` | boolean | True when the address `emailValidity` describes came free from Kenso's own email database. Omitted without a Safe or Verified email. |
| `companyDomain` | string | Company website domain. |
| `companySize` | string | Employee count range, such as `51-200`. |
| `companyType` | string | Company type. |
| `companyIndustry` | string | Industry. |
| `companyLocation` | string | Company location. |
| `companyTechnologies` | string | Technologies the company uses, as one text value. |
| `companyLinkedInUrl` | string | Company LinkedIn page URL. |
| `companyLinkedInIdent` | string | The company's LinkedIn identifier. |
| `companyEmployeeCount` | integer (int32) | Number of employees. |
| `companySpecialities` | string | The company's specialities, as one text value. |
| `companyDescription` | string | Company description. |
| `companyCrunchBaseUrl` | string | Company Crunchbase URL. |
| `companyJsonLocation` | string | The company's location details as a JSON string. |
| `companyFoundedYear` | integer (int32) | Year the company was founded. |
| `headquartersCity` | string | City of the company headquarters. |
| `headquartersState` | string | State or region of the company headquarters. |
| `headquartersCountry` | string | Country of the company headquarters. |
| `seniorityLevel` | string | Seniority level. |
| `function` | string | Job function, such as sales or engineering. |
| `yearsOfExperience` | number (float) | Years of work experience. |
| `languages` | string | Languages the person lists, as one text value. |
| `outreachLanguage` | string | The locale Ken writes to the contact in, such as `fr-FR`, or a two-letter language code such as `de`. Omitted until Ken picks one. `PATCH` sets it by hand and locks it. |
| `outreachFormality` | string, one of: formal, informal | The register Ken writes to the contact in: `formal` or `informal`. Omitted when the language's default applies. |
| `outreachLanguageSource` | string, one of: manual, reply, declared, country, hq, default | Where the outreach language came from: `manual` (a member set it), `reply` (the language the contact replied in), `declared` (a language the contact lists), `country` (the contact's country), `hq` (the company headquarters' country) or `default` (the campaign's language). |
| `outreachLanguageConfidence` | number (float) | How sure Ken is of the outreach language, from 0 to 1. A language a member set is 1, and the campaign's default language is 0. |
| `outreachLanguageLocked` | boolean | True when a member set the language. No import, enrichment or reply replaces it. |
| `phoneNumber` | string | The contact's first phone number. |
| `phoneNumberValidity` | string, one of: unknown, invalid, risky, verified, valid | How sure Kenso is that `phoneNumber` works. Omitted without a phone number. |
| `phoneCountryAssumed` | boolean | True when Kenso added the country code itself: a number stored without one was read as a US number (+1). Treat it as unverified. |
| `lastJobTitle` | string | Title of the most recent job in the work history. |
| `lastJobDescription` | string | Description of the most recent job in the work history. |
| `employmentType` | string | Employment type of the current job, such as full-time. |
| `employmentLocation` | string | Location of the current job. |
| `summary` | string | The profile summary. |
| `skills` | string | Skills, as one text value. |
| `education` | string | Education, as one text value. |
| `personalizationLineIds` | map of integer (int64) | The id of the AI line behind each personalization field, keyed like those fields (`personalization1` to `personalization20`). Rate a line with AI feedback as `ai_line:{id}`. Absent when the contact has no lines. |
| `createdAt` | string (date-time) | When Kenso created the contact, in UTC. |
| `updatedAt` | string (date-time) | When the contact last changed, in UTC. |
| `accountPlay` | ContactAccountPlay | The contact's account play status in its campaign. Omitted when no account play holds, stops or counts the contact, and for a caller without Accounts view. |
| `securityGateway` | ContactSecurityGateway | The email security gateway in front of the contact's first Safe or Verified email, the address Kenso sends to. Omitted when the workspace does not have security gateways. |
| `mailboxProvider` | ContactMailboxProvider | The host of that email's mailbox, such as Google Workspace. Omitted when the workspace does not have security gateways. |
| `customVideo` | ContactCustomVideo | The contact's own video, shown in emails as `{{custom_video}}`. Null when the contact has none or the workspace does not have campaign videos. Set it with `customVideo` on `PATCH /v1/contacts/{contactId}`. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/contacts?limit=50" \
  -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": 90125,
      "campaignId": 4821,
      "segmentId": 1207,
      "campaignListId": 3305,
      "companyId": 22841,
      "companyName": "Northwind Labs",
      "companyEmailName": "Northwind",
      "firstName": "Amanda",
      "lastName": "Chen",
      "email": "amanda.chen@northwind.example.com",
      "linkedInUrl": "https://www.linkedin.com/in/amanda-chen-northwind",
      "title": "VP of Engineering",
      "isQualified": true,
      "doNotContact": false,
      "isDecisionMaker": true,
      "qualityScore": 86,
      "qualityReasoning": "Leads a 40-person engineering team at a 120-person B2B SaaS company that is hiring engineers.",
      "segmentationReasoning": "VP of Engineering, which matches the Engineering leaders segment.",
      "customVariables": {
        "open_roles": "12 engineering roles"
      },
      "emailsSent": 2,
      "clicks": 0,
      "replies": 1,
      "unsubscribes": 0,
      "bounces": 0,
      "positiveReplies": 1,
      "headline": "VP of Engineering at Northwind Labs",
      "location": "Austin, Texas, United States",
      "city": "Austin",
      "state": "Texas",
      "country": "United States",
      "countryIso2": "US",
      "companyLogo": "https://cdn.example.com/companies/22841/logo.png",
      "linkedInUrlNameMismatch": false,
      "segmentName": "Engineering leaders",
      "emailValidity": "safe",
      "emailFromKenPool": false,
      "companyDomain": "northwind.example.com",
      "companySize": "51-200",
      "companyIndustry": "Software Development",
      "companyLocation": "Austin, Texas, United States",
      "companyEmployeeCount": 120,
      "companyDescription": "Northwind Labs builds developer onboarding software for engineering teams.",
      "companyFoundedYear": 2017,
      "headquartersCity": "Austin",
      "headquartersState": "Texas",
      "headquartersCountry": "United States",
      "seniorityLevel": "VP",
      "function": "Engineering",
      "yearsOfExperience": 14,
      "outreachLanguage": "en-US",
      "outreachLanguageSource": "country",
      "outreachLanguageConfidence": 0.8,
      "outreachLanguageLocked": false,
      "phoneCountryAssumed": false,
      "createdAt": "2026-09-23T15:02:11Z",
      "updatedAt": "2026-10-13T16:22:05Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6ODE1fQ",
    "hasMore": true,
    "total": 1,
    "totalCount": 1,
    "isTotalCapped": true
  }
}
```

## Types

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

### ContactAccountPlay

How an account play affects the contact in its campaign.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | no | What the account play does to the contact. `skipped`: held before the campaign's first step, because the contact's company is in an active account play. A contact that already got a step stops at its next send. `stopped`: the sequence stopped for good. `would_skip`: protection only counts the match, and sending does not change. |
| `accountId` | integer (int64) | no | The account whose play matches now. Omitted on a stopped contact whose account left the active stages. For a caller who works only their own accounts, this field, `accountName` and `accountStage` are omitted when the caller does not own the account. |
| `accountName` | string | no | The account name. |
| `accountStage` | string | no | The account's stage: `warming`, `engaged`, `meeting_booked` or `in_deal`. |

### ContactSecurityGateway

The email security gateway that filters mail to a contact's address.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | no | Detection result. `detected`: a gateway was found, and `slug` and `name` say which. `none`: no gateway was found, or the contact has no email or a free email address. `pending`: the domain is not checked yet. |
| `slug` | string | no | Short id of the gateway, such as `proofpoint`. Returned only when `status` is `detected`. |
| `name` | string | no | Display name of the gateway. Returned only when `status` is `detected`. |

### ContactMailboxProvider

The host of a contact's mailbox, such as Google Workspace or Microsoft 365.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | no | Detection result. `detected`: the host was found, and `slug` and `name` say which. `unknown`: the domain was checked and no known host matched, or the contact has no email. `pending`: the domain is not checked yet. |
| `slug` | string | no | Short id of the host, such as `google_workspace`. Returned only when `status` is `detected`. |
| `name` | string | no | Display name of the host. Returned only when `status` is `detected`. |

### ContactCustomVideo

The contact's own video, the one emails show as `{{custom_video}}`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | no | The video's state: `pending` while Kenso prepares the thumbnail, `ready` when emails can show the video, or `failed`. |
| `provider` | string | no | The video host: `loom`, `youtube`, `vimeo`, `wistia`, `vidyard`, `sendspark` or `heygen`. |
| `source` | string | no | How the video was set: `import` (a contact import), `api` (this API) or `mcp` (Ken or another AI assistant), or, for a generated video, the service that made it: `sendspark`, `heygen` or `vidyard`. New values can appear. |
| `watchUrl` | string | no | The link where the video plays. |
| `previewUrl` | string | no | A thumbnail image URL for showing the video in your own app. It works for a short time only. Null until the thumbnail is ready. |
| `previewExpiresAt` | string (date-time) | no | When `previewUrl` stops working, in UTC. Read the contact again for a new one. |
| `error` | ContactCustomVideoError | no | Why the video failed. Null unless `status` is `failed`. |

### ContactCustomVideoError

Why the contact's video failed.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | no | A stable error code. |
| `detail` | string | no | A readable explanation. |
