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

# Contact imports: Preview buyers at a list of companies

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

## Preview buyers at a list of companies

`POST /v1/contact-imports/buyer-previews` - operationId `contact-imports.buyer-preview`

| Permission | Rate limit |
| --- | --- |
| Campaigns edit and the `import` permission | 240 requests a minute per API key |

Finds the people to contact at each company of a list, matched to a campaign's ideal customer profile (ICP). Use
it when a file lists companies instead of people: preview the people, drop the ones you do not want, then add the
rest with `POST /v1/contact-imports`.

The body needs `campaignId` and `companies`: from 1 to 50 companies, each with a `name`, a
`domain` or both, and an optional `key` that the answer echoes back. Send a longer list in parts of 50.
`perCompany` sets how many people to return per company, from 1 to 3 (default 3). Example body:
`{ "campaignId": 812, "companies": [{ "key": "row-2", "name": "Northwind", "domain": "northwind.com" }], "perCompany": 3 }`.

Kenso looks up each company in Kenso Search. A company sent with a domain matches the company that owns the
domain: the one with the same name at that domain, else the one whose website is the domain's home page. A
company that only has a page under the domain (such as `notion.so/acme`) does not own it, and Kenso never
matches by name in its place. A company sent without a domain matches when exactly one company in Kenso Search
has its name.

The ICP is the people filters of the campaign's active segments: titles, seniority levels, functions, decision
makers and exclusions. For each matched company, Kenso lists up to `perCompany` people in the ICP, best
first. When the ICP finds too few, Kenso fills the company from a looser search and marks those people
`weakMatch`. When the campaign has no ICP, Kenso ranks people by seniority. Each person appears once in the
whole answer, even when Kenso Search holds them twice.

Each kept person's `contact` goes unchanged into the `contacts` of a `POST /v1/contact-imports`
call with `source` `search`. Deduplication, the blocklist and lead credits apply there. The preview
stores nothing and charges nothing. It counts the companies times `perCompany` against the workspace's daily
`searchBrowseRows` quota, the same quota Search results use. A company Kenso Search does not answer for in
time comes back `failed`: send it again.

Errors:

- `400 validation_failed`: `campaignId` is missing, `companies` is empty or holds more than 50,
a company has neither a name nor a domain (the error names `companies[i]`), or `perCompany` is less
than 1 or more than 3.
- `404 not_found`: the campaign is not in the workspace.
- `429 quota_exceeded`: the request would pass the workspace's `searchBrowseRows` quota. Wait for the
`Retry-After` seconds.

Requires Campaigns edit and the `import` permission.

Needs the `csv_buyer_preview` 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/contact-imports/POST/v1/contact-imports/buyer-previews)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `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`. |

### Request body

`application/json`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `campaignId` | integer (int64) | yes | The campaign whose ideal customer profile the people are matched to. Required. |
| `companies` | array of BuyerPreviewCompanyInput | no | The companies to search, from 1 to 50. Each needs a `name`, a `domain` or both. |
| `perCompany` | integer (int32) | no | The most people to return per company, from 1 to 3. Omitted means 3. |

### Response 200

`data` is a `BuyerPreview`.

| Field | Type | Description |
| --- | --- | --- |
| `icp` | array of string | The campaign's ideal customer profile (ICP) that the people were matched to, as display labels such as `Decision makers`. Empty when the campaign has no ICP. |
| `companies` | array of BuyerPreviewCompany | One entry per company sent, in the order sent. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/contact-imports/buyer-previews" \
  -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 '{
  "campaignId": 812,
  "companies": [
    {
      "key": "string",
      "name": "string",
      "domain": "northwind.com"
    }
  ],
  "perCompany": 1
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "icp": [
      "string"
    ],
    "companies": [
      {
        "key": "string",
        "input": {
          "name": "string",
          "domain": "example.com"
        },
        "status": "string",
        "unmatchedReason": "string",
        "company": {
          "kenCompanyId": 812,
          "name": "string",
          "domain": "northwind.com",
          "employeeCount": 1,
          "industry": "string"
        },
        "signal": {
          "kind": "hiring",
          "label": "string",
          "at": "2026-09-23T15:02:11Z"
        },
        "people": [
          {
            "kenPersonId": 812,
            "fullName": "Jane Doe",
            "title": "string",
            "seniorityLevel": "string",
            "function": "string",
            "linkedInUrl": "https://example.com",
            "reason": "string",
            "weakMatch": true,
            "contact": {}
          }
        ]
      }
    ]
  }
}
```

## Types

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

### BuyerPreviewCompanyInput

One company to search, as your file has it.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `key` | string | no | Your own label for the company, such as its row in your file. The answer echoes it back. Optional. |
| `name` | string | no | The company name. Kenso uses the first 200 characters. A company needs a name, a domain or both. |
| `domain` | string | no | The company's domain or website, such as `northwind.com`. Kenso reads a URL as its registrable domain, so `https://www.eu.northwind.com/about` reads as `northwind.com`. |

### BuyerPreviewCompany

One company of the list and the people found there.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `key` | string | no | The `key` you sent with the company, else null. |
| `input` | BuyerPreviewInput | no | The name and domain you sent. |
| `status` | string | no | How the lookup went. `matched`: Kenso Search found the company, though `people` can still be empty. `unmatched`: no company in Kenso Search fits, and `unmatchedReason` says why. `failed`: Kenso Search did not answer in time, so send the company again. |
| `unmatchedReason` | string | no | Why the company is `unmatched` or `failed`, such as `acme.com is not in Kenso Search`, `could not match notion.so: no company in Kenso Search has it as its own website` or `no domain, name matches 3 companies`. Null when `matched`. |
| `company` | BuyerPreviewCompanyFacts | no | The company Kenso Search matched. Null unless `status` is `matched`. |
| `signal` | BuyerPreviewSignal | no | The company's latest hiring, funding or leadership change from the last 90 days. Null when there is none. |
| `people` | array of BuyerPreviewPerson | no | The people found, best first, at most `perCompany`. Empty unless `status` is `matched`. A person already listed at an earlier company is not listed again. |

### BuyerPreviewInput

The name and domain of a company, as sent.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | The name you sent, else null. |
| `domain` | string | no | The domain you sent, else null. |

### BuyerPreviewCompanyFacts

The company Kenso Search matched.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kenCompanyId` | integer (int64) | no | The company's id in Kenso Search. |
| `name` | string | no | The company's name in Kenso Search. |
| `domain` | string | no | The company's domain, such as `northwind.com`. Null when unknown. |
| `employeeCount` | integer (int32) | no | The company's number of employees. Null when unknown. |
| `industry` | string | no | The company's industry. Null when unknown. |

### BuyerPreviewSignal

A recent event at the company.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | string | no | The kind of event: `hiring`, `funding` or `leadership_hire`. |
| `label` | string | no | The event in one short line, for display, such as `Series B - $40M - Sep 3`. |
| `at` | string (date-time) | no | When it happened, in UTC. |

### BuyerPreviewPerson

A person found at a company.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kenPersonId` | integer (int64) | no | The person's id in Kenso Search. |
| `fullName` | string | no | The person's full name. |
| `title` | string | no | The person's current job title. Null when unknown. |
| `seniorityLevel` | string | no | The person's seniority level as Kenso Search labels it. Null when unknown. |
| `function` | string | no | The person's job function as Kenso Search labels it. Null when unknown. |
| `linkedInUrl` | string | no | The person's LinkedIn profile URL. Null when unknown. |
| `reason` | string | no | Why Kenso picked this person, in one sentence under 90 characters. |
| `weakMatch` | boolean | no | True when the campaign's ICP found too few people and Kenso loosened the search to fill the company. |
| `contact` | SearchContact | no | The person as a contact for `POST /v1/contact-imports` with `source` `search`. To add the people you keep, send their `contact` objects unchanged in `contacts`. |

### SearchContact

One person to import, with their profile and current company.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `firstName` | string | no | The person's first name. Kenso takes it from `fullName` when it is blank. |
| `lastName` | string | no | The person's last name. Kenso takes it from `fullName` when it is blank. |
| `fullName` | string | no | The person's full name. Kenso splits it when `firstName` or `lastName` is blank. |
| `title` | string | no | The person's current job title. |
| `headline` | string | no | The person's LinkedIn headline. |
| `location` | string | no | Where the person is based, as free text. |
| `linkedInUrl` | string | no | The person's LinkedIn profile URL. |
| `companyName` | string | no | The name of the person's current company. |
| `companyDomain` | string | no | The current company's website domain, such as `example.com`. Kenso reduces a full URL to its domain. |
| `companyLinkedInUrl` | string | no | The current company's LinkedIn page URL. |
| `companyIndustry` | string | no | The current company's industry. |
| `companyEmployeeCount` | integer (int32) | no | The current company's number of employees. |
| `companyDescription` | string | no | A description of the current company. |
| `companyType` | string | no | The current company's type, as text. |
| `companyFoundedYear` | integer (int32) | no | The year the current company was founded. |
| `companyLocation` | string | no | The current company's location, as free text. Omitted, Kenso builds it from the headquarters city, state and country. |
| `companySpecialties` | string | no | The current company's specialties, as one comma-separated string. Kenso also takes a JSON array of strings and joins it with commas. |
| `summary` | string | no | The person's profile summary. |
| `experiencesJson` | string | no | The person's work history, as a JSON array in a string. Kenso stores it as sent. |
| `educationJson` | string | no | The person's education, as a JSON array in a string. Kenso stores it as sent. |
| `certificationsJson` | string | no | The person's certifications, as a JSON array in a string. Kenso stores it as sent. |
| `inferredSkills` | string | no | The person's skills, as one comma-separated string. |
| `languages` | string | no | The languages the person speaks, as one comma-separated string. Kenso also takes a JSON array of strings and joins it with commas. |
| `lastJobDescription` | string | no | The description of the person's current or latest job. |
| `kenCompanyId` | integer (int64) | no | The current company's id in Kenso Search. Kenso uses it to fill in missing company data. |
| `profilePhotoUrl` | string | no | The URL of the person's profile photo. |
| `city` | string | no | The city where the person is based. |
| `state` | string | no | The state or region where the person is based. |
| `country` | string | no | The country where the person is based. Kenso leaves out a person in a country the campaign excludes. |
| `countryIso2` | string | no | The two-letter ISO 3166 code of the person's country, such as `US`. Kenso leaves out a person in a country the campaign excludes. |
| `seniorityLevel` | string | no | The person's seniority, as text. |
| `function` | string | no | The person's job function, as text. |
| `isDecisionMaker` | boolean | no | Whether the person makes buying decisions. Default `false`. |
| `yearsOfExperience` | number (float) | no | The person's total years of work experience. |
| `yearsInCurrentRole` | number (float) | no | The person's years in their current role. |
| `yearsInCurrentCompany` | number (float) | no | The person's years at their current company. |
| `changedJobRecently` | boolean | no | Whether the person changed jobs recently. Default `false`. |
| `jobChangeDate` | string (date-time) | no | When the person changed jobs, as an ISO 8601 date and time. |
| `companyFounded` | integer (int32) | no | The year the current company was founded. Kenso reads it when `companyFoundedYear` is empty. |
| `headquartersCity` | string | no | The city of the current company's headquarters. |
| `headquartersState` | string | no | The state or region of the current company's headquarters. |
| `headquartersCountry` | string | no | The country of the current company's headquarters. |
| `companySize` | string | no | The current company's employee count range, as text. |
| `companyLogoUrl` | string | no | The URL of the current company's logo. |
| `companyFollowers` | integer (int32) | no | The current company's number of followers. |
| `companyTotalFunding` | integer (int64) | no | The current company's total funding amount. |
| `companyLastFundingRoundType` | string | no | The type of the current company's latest funding round, such as `Series A`. |
| `companyLastFundingAmount` | integer (int64) | no | The amount the current company raised in its latest funding round, in US dollars. Kenso keeps it only with `companyLastFundingRoundType`. |
| `currentExperiences` | array of CurrentExperienceImport | no | The person's other current jobs, besides the main one. Kenso also looks at these companies when it searches for the person's email. |
| `searchToken` | string | no | Proof that Kenso Search found this person, set by Kenso on each person a people search, person lookup or buyer preview returns. Send it back unchanged with the person's `linkedInUrl`: a `source` `search` import counts a person in your Free with Kenso savings only with a valid token, so a contact without one, or whose LinkedIn URL you changed, is still imported but not counted. Null on a contact Kenso did not find. |

### CurrentExperienceImport

Another job the person holds now, besides the main one.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `companyId` | integer (int64) | no | Not read by the import. |
| `companyName` | string | no | The company's name. Kenso ignores an entry with neither a name nor a domain. |
| `companyUrl` | string | no | The company's LinkedIn page URL. |
| `companyDomain` | string | no | The company's website domain, such as `example.com`. |
| `companyEmployeeCount` | integer (int32) | no | The company's number of employees. |
| `title` | string | no | The person's job title at this company. |
| `startDate` | string (date-time) | no | When the person started this job, as an ISO 8601 date and time. |
