> 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: Scan an import file

> **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).

## Scan an import file

`POST /v1/contact-imports/scans` - operationId `contact-imports.scan`

| Permission | Rate limit |
| --- | --- |
| Campaigns view and the `import` permission | 30 requests a minute, 600 an hour and 5,000 a day per workspace (Free plan: 3 a minute, 60 an hour and 500 a day) |

Suggests the contact field for each column of an import file, from its header row and a few sample rows. Send
`keys` as well to run the list check: it reads every row and reports the rows the import skips anyway and the
risky rows you can drop. Call it before you import a CSV file, a Google Sheet or an Airtable table with
`POST /v1/contact-imports`, or before you upload a file to a saved list.

The body needs `source` (`csv`, `google_sheets` or `airtable`), `headers` (from 1 to 200
column names, each at most 500 characters) and up to 200 `sampleRows` (each cell at most 2,000 characters).
`target` says where the rows go:

- `campaign` (the default) needs `campaignId`.
- `people` suggests only the fields a people import stores and runs no list check.
- `saved_list` needs `savedListId` for an existing list or `savedListKind` for a list you have not
created yet, never both. It also needs Search view and the `saved_lists` feature on the workspace.

The list check runs for `campaign` and `saved_list` when you send `keys`: the key columns of every
row, one list per column, all of the same length from 1 to 25,000. `keys.rowCount` is the file's row count and
must be at least that length. For a larger file, send its first 25,000 rows and the full row count. The check then
says `truncated`. A scan that sends `keys` skips the AI suggestions. To get both, scan once without
`keys` to map the columns, then again with `keys` filled from the mapped columns. Example body:
`{ "source": "csv", "campaignId": 42, "headers": ["Full Name", "Work contact"], "sampleRows": [["Ada Lovelace",
"ada@example.com"]], "keys": { "rowCount": 1, "fullName": ["Ada Lovelace"], "email": ["ada@example.com"] } }`.

Pass the answer on to the import. Each column's `csvColumn`, `targetField` and `customVariableName`
are the fields of a `columnMappings` entry of `POST /v1/contact-imports`. For a campaign, send the keys of
the checks you keep on in the import's `fixes` form field (a JSON array), send
`includeRecentlyContacted=true` to keep the rows in `contacted`, and send `cleanup` with the value of
`cleanupApplied`. The import applies none of them unless you send them. For a saved list, send `fixes` and
`cleanup` the same way to `POST /v1/saved-lists/{savedListId}/uploads`.

The scan stores nothing and charges nothing. The list check reads only data Kenso already has and runs no paid
lookup. Each call counts against the workspace's `contactImportScans` quota: 30 a minute, 600 an hour and
5,000 a day.

Errors:

- `400 validation_failed`: a body field breaks a rule above. The error names the field.
- `403 permission_denied`: `target` is `saved_list` and the caller lacks Search view.
- `404 not_found`: the campaign is not in the workspace, the saved list is not one of the workspace's own lists
(a list shared from elsewhere, a library list or another member's private list), or `target` is
`saved_list` while the `saved_lists` feature is off.
- `429 quota_exceeded`: the workspace used up its scans for now. Wait for the `Retry-After` seconds.

Requires Campaigns view and the `import` permission.

Needs the `csv_import_check` 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/scans)

### 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 |
| --- | --- | --- | --- |
| `source` | string | yes | Where the file comes from: `csv`, `google_sheets` or `airtable`. Required. |
| `target` | string | no | Where the rows go: `campaign`, `people` (workspace people, only the fields a people import stores) or `saved_list`. Omitted means `campaign`. |
| `campaignId` | integer (int64) | no | The campaign the file goes into. Required when `target` is `campaign`. |
| `savedListId` | integer (int64) | no | The saved list the file goes into, when `target` is `saved_list`. It must be one of the workspace's own lists that the caller can see. Send this or `savedListKind`, not both. |
| `savedListKind` | string | no | The kind of a saved list you have not created yet: `people` or `companies`. Send it instead of `savedListId` when `target` is `saved_list`. Kenso reads the rows as a new list of that kind would. |
| `headers` | array of string | no | The file's header row: from 1 to 200 column names, each at most 500 characters. |
| `sampleRows` | array of array of string | no | Up to 200 data rows, each a list of cells in header order. Each cell is at most 2,000 characters. Kenso reads a missing cell at the end of a short row as blank and ignores cells past the last header. |
| `keys` | ContactImportScanKeys | no | The key columns of every row, for the list check. Kenso runs the check when `target` is `campaign` or `saved_list`. Sending it skips the AI suggestions. |

### Response 200

`data` is a `ContactImportScan`.

| Field | Type | Description |
| --- | --- | --- |
| `columns` | array of ContactImportScanColumn | One suggestion per header, in header order. |
| `listKind` | string | What a row of the file stands for. `company` when no column maps to `email`, `profile_url`, `first_name`, `last_name` or `full_name` and at least one maps to `company_name`, `company_domain` or `company_linkedin_url`. Otherwise `people`. |
| `check` | ContactImportListCheck | The list check of every row, against the campaign or the saved list. Null when the scan sent no `keys` or `target` is `people`. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/contact-imports/scans" \
  -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 '{
  "source": "csv",
  "target": "string",
  "campaignId": 812,
  "savedListId": 812,
  "savedListKind": "people",
  "headers": [
    "string"
  ],
  "sampleRows": [
    [
      "string"
    ]
  ],
  "keys": {
    "rowCount": 1,
    "cleanup": true,
    "email": [
      "jane@example.com"
    ],
    "profileUrl": [
      "https://example.com"
    ],
    "companyDomain": [
      "example.com"
    ],
    "companyName": [
      "Acme"
    ],
    "companyLinkedinUrl": [
      "https://example.com"
    ],
    "firstName": [
      "Jane"
    ],
    "lastName": [
      "Doe"
    ],
    "fullName": [
      "Jane Doe"
    ],
    "title": [
      "string"
    ],
    "emailValidity": [
      "string"
    ],
    "otherEmails": [
      [
        "jane@example.com"
      ]
    ],
    "otherEmailValidity": [
      [
        "string"
      ]
    ]
  }
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "columns": [
      {
        "index": 1,
        "csvColumn": "string",
        "targetField": "email",
        "customVariableName": "string",
        "confidence": "string",
        "reason": "string",
        "samples": [
          "string"
        ],
        "cleanup": "string"
      }
    ],
    "listKind": "string",
    "check": {
      "rows": 1,
      "scannedRows": 1,
      "truncated": true,
      "cleanupApplied": true,
      "always": [
        {
          "key": "string",
          "label": "string",
          "count": 1,
          "samples": [
            {}
          ],
          "rows": [
            1
          ]
        }
      ],
      "contacted": {
        "count": 1,
        "days": 1,
        "skipByDefault": true,
        "samples": [
          {
            "row": 1,
            "value": "string",
            "reason": "string"
          }
        ],
        "rows": [
          1
        ]
      },
      "checks": [
        {
          "key": "string",
          "label": "string",
          "fixLabel": "Drop",
          "count": 1,
          "defaultOn": true,
          "prior": 0.5,
          "note": "string",
          "samples": [
            {}
          ]
        }
      ],
      "rowFlags": [
        [
          1
        ]
      ],
      "noEmailRows": [
        1
      ],
      "baselinePrior": 0.5,
      "bounce": {
        "expected": 0.5,
        "beforeFixes": 0.5,
        "band": "string"
      },
      "willAdd": 1,
      "companyContactedDays": 1,
      "companyCap": 1,
      "domainsChecked": 1,
      "domainsTotal": 1,
      "titleMix": [
        {
          "label": "VP",
          "share": 1
        }
      ],
      "providerMix": [
        {
          "label": "VP",
          "share": 1
        }
      ]
    }
  }
}
```

## Types

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

### ContactImportScanKeys

The key columns of every data row for the list check. Each list holds one column's cells in row order, so index 0 of every list is the first data row. Send a list only for a column you mapped to that field. When `target` is `campaign` or `saved_list`, every list you send has the same length, from 1 to 25,000.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `rowCount` | integer (int32) | no | The number of data rows in the file, at least the length of the lists. A larger number means the lists hold only the first rows of the file, and the check says `truncated`. |
| `cleanup` | boolean | no | Whether Kenso cleans every value first, as the import does with `cleanup=true`. Omitted means true for a campaign and false for a saved list, since a saved list upload cleans only when you send `cleanup=true`. |
| `email` | array of string | no | The cells of the first column mapped to `email`. |
| `profileUrl` | array of string | no | The cells of the column mapped to `profile_url`, the person's LinkedIn URL. |
| `companyDomain` | array of string | no | The cells of the column mapped to `company_domain`. |
| `companyName` | array of string | no | The cells of the column mapped to `company_name`. |
| `companyLinkedinUrl` | array of string | no | The cells of the column mapped to `company_linkedin_url`. |
| `firstName` | array of string | no | The cells of the column mapped to `first_name`. |
| `lastName` | array of string | no | The cells of the column mapped to `last_name`. |
| `fullName` | array of string | no | The cells of the column mapped to `full_name`. |
| `title` | array of string | no | The cells of the column mapped to `title`. |
| `emailValidity` | array of string | no | The cells of the column mapped to `email_validity` for the first email column. For a campaign, a cell that says `invalid` or `undeliverable` marks the row's email invalid, and a catch-all status marks it catch-all. A saved list ignores it. |
| `otherEmails` | array of array of string | no | One list for each further column mapped to `email`, in mapping order, at most 10. The import keeps every valid address of a row, so the blocklist and duplicate checks read them all. |
| `otherEmailValidity` | array of array of string | no | The `email_validity` column mapped right after each list in `otherEmails`, in the same order. Null where that email column has no validity column. It holds no more lists than `otherEmails`. |

### ContactImportScanColumn

The suggested field for one column of the file.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `index` | integer (int32) | no | The column's position in the header row, starting at 0. |
| `csvColumn` | string | yes | The column's header, as sent. |
| `targetField` | string | yes | The suggested contact field key, such as `email`, `full_name` or `profile_url`. It can also be `custom_variable` (import the column as a custom variable) or `skip` (do not import it). Each field is suggested for one column at most, except `email`, `email_validity` and `custom_variable`. With `target` `people`, only `email`, `first_name`, `last_name`, `full_name`, `title`, `company_name`, `company_domain`, `phone_number`, `profile_url` and `skip`. |
| `customVariableName` | string | no | The custom variable's name when `targetField` is `custom_variable`, else null. |
| `confidence` | string | yes | How sure the suggestion is. `high`: the header names the field, or nearly every value is one. `memory`: this workspace mapped the same header to this field before. `check`: likely, so confirm it. `skip`: the column is not imported. |
| `reason` | string | yes | Why Kenso suggests this field, in one short sentence. |
| `samples` | array of string | yes | Up to 3 distinct values from the column's sample rows, blanks left out, each at most 120 characters. |
| `cleanup` | string | no | What the import's cleanup would change in this column's sample values, such as `Cleans 3 of 10 sample values (casing, format)`. Null when nothing changes or Kenso has no cleanup for the field. |

### ContactImportListCheck

The list check: the rows the import skips anyway, the rows recently emailed by another campaign, and the optional fixes for risky rows.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `rows` | integer (int32) | no | The number of data rows in the file, as sent in `keys.rowCount`. |
| `scannedRows` | integer (int32) | no | The number of rows checked: the length of the `keys` lists. |
| `truncated` | boolean | no | True when the file has more rows than were checked, so the counts cover only its first `scannedRows` rows. |
| `cleanupApplied` | boolean | no | True when Kenso cleaned every key value first, as the import does with `cleanup=true`. It follows `keys.cleanup`. |
| `always` | array of ListCheckBucket | yes | The rows the import skips whatever you choose, one bucket per reason, empty buckets included. A row lands in the first bucket it matches, in this order. `failedValidation`: no name, or no company name, domain or company LinkedIn URL. `missingKey`: no usable email and no LinkedIn URL. `blocklist`: on the workspace blocklist. `duplicateInFile`: repeats an earlier row. `duplicateInCampaign`: already in this campaign. `duplicateInOtherCampaign`: already in another campaign. For a saved list the buckets are what its upload does with a row anyway. `missingKey`: the upload rejects the row because it has no LinkedIn URL, no email and no name with a company domain (for a companies list, no company domain or company page). `duplicateInFile` and `duplicateInList`: the row merges into an earlier row's member or into a member already on the list, and its addresses join that member. |
| `contacted` | ListCheckContacted | yes | The rows another campaign emailed within this campaign's recently emailed window. The import skips them unless you send `includeRecentlyContacted=true`. Empty for a saved list. |
| `checks` | array of ListCheckItem | yes | The optional fixes, one per key, in this order. `invalidEmail`: Kenso knows the address is invalid, or the file's validity column says so. `noMx`: the email domain takes no mail. `catchAll`: the domain accepts every address. `personalEmail`: a personal address such as Gmail or Outlook.com. `roleAddress`: a shared address such as info@ or sales@. `companyContacted`: someone else at the company got an email from this workspace within `companyContactedDays`. `companyCap`: the rows after the first `companyCap` at one company. For a saved list the fixes are `blocklist` (an address, its domain or the company domain is on the workspace blocklist), `invalidEmail`, `noMx`, `catchAll`, `personalEmail` and `roleAddress`. A saved list ignores the file's validity column. |
| `rowFlags` | array of array of integer (int32) | yes | One `[rowIndex, mask]` pair for each row with at least one mark, rows in an `always` bucket left out. `rowIndex` counts from 0 into the `keys` lists. The mask adds up these bits: 1 `contacted`, 2 `invalidEmail`, 4 `noMx`, 8 `catchAll`, 16 `roleAddress`, 32 `personalEmail`, 64 `companyContacted`, 128 `companyCap` and 256 `blocklist` (saved list only). |
| `noEmailRows` | array of integer (int32) | yes | The rows outside the `always` buckets that have no usable email, as indexes counting from 0 into the `keys` lists. They send no email, so the bounce estimate leaves them out. |
| `baselinePrior` | number (double) | no | The expected hard bounce rate of a row with an email that no email check marks, from 0 to 1. |
| `bounce` | ListCheckBounce | no | The expected hard bounce rate of the rows added with an email. Null when no row has an email. |
| `willAdd` | integer (int32) | no | The rows the import adds with the default choices: every check whose `defaultOn` is true sent in `fixes`, and the `contacted` rows skipped. For a saved list, the members the list gains. |
| `companyContactedDays` | integer (int32) | no | The window of the `companyContacted` check, in days: the campaign's recently emailed window, else 90. 0 for a saved list. |
| `companyCap` | integer (int32) | no | How many rows per company the `companyCap` fix keeps. 0 for a saved list. |
| `domainsChecked` | integer (int32) | no | How many of the `domainsTotal` email domains Kenso has mailbox data for. |
| `domainsTotal` | integer (int32) | no | The number of distinct email domains among the rows outside the `always` buckets. |
| `titleMix` | array of ListCheckShare | yes | The title mix of the rows outside the `always` buckets. Labels are `C-level or Founder`, `VP`, `Director`, `Head or Manager` and `Other`. Shares are whole percents that add up to 100, and a label with no rows is left out. |
| `providerMix` | array of ListCheckShare | yes | The mailbox provider mix of those rows that have an email. Labels are `Google`, `Microsoft`, `Other` and `Unknown`, with shares as in `titleMix`. |

### ListCheckBucket

The rows the import skips for one reason.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `key` | string | no | The reason's key, as listed under `always`. |
| `label` | string | no | The reason in words, for display, such as `Already in this campaign`. |
| `count` | integer (int32) | no | The number of rows with this reason. |
| `samples` | array of ListCheckSample | no | Up to 3 example rows. |
| `rows` | array of integer (int32) | no | The indexes of every row with this reason, counting from 0 into the `keys` lists. |

### ListCheckContacted

The rows another campaign emailed within this campaign's recently emailed window.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `count` | integer (int32) | no | The number of those rows. |
| `days` | integer (int32) | no | The campaign's recently emailed window, in days. Null when the campaign has none, and then `count` is 0. Null for a saved list. |
| `skipByDefault` | boolean | no | True when the import skips these rows unless you send `includeRecentlyContacted=true`. False for a saved list. |
| `samples` | array of ListCheckSample | no | Up to 3 example rows. |
| `rows` | array of integer (int32) | no | The indexes of those rows, counting from 0 into the `keys` lists. |

### ListCheckItem

One optional fix: the rows a check marks, and whether the fix is on by default.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `key` | string | no | The fix key, as listed under `checks`. Send it in `fixes` to drop these rows. |
| `label` | string | no | The check in words, for display, such as `Catch-all domain`. |
| `fixLabel` | string | no | What the fix does, for display: `Drop`, `Skip` or `Keep 5 each`. |
| `count` | integer (int32) | no | The number of rows the check marks. |
| `defaultOn` | boolean | no | True when the fix is on by default. `invalidEmail` and `noMx` are on by default, as are `blocklist` for a saved list and `personalEmail` for a campaign that skips personal emails. |
| `prior` | number (double) | no | The expected hard bounce rate of the rows this check marks, from 0 to 1. |
| `note` | string | no | One sentence about the check, for display, such as `No MX record on 2 domains.` |
| `samples` | array of ListCheckSample | no | Up to 3 example rows. |

### ListCheckBounce

The expected hard bounce rate of the rows added with an email.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `expected` | number (double) | no | In percent, with the default choices: the fixes whose `defaultOn` is true applied, and the `contacted` rows skipped. |
| `beforeFixes` | number (double) | no | In percent, with no fix applied and the `contacted` rows kept. |
| `band` | string | no | `green` when `expected` is under 2, `amber` from 2 to 5, and `red` over 5. |

### ListCheckShare

One label's share of the rows.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | string | no | The label, such as `VP` or `Google`. |
| `share` | integer (int32) | no | The share, in whole percent. |

### ListCheckSample

One example row of a bucket or a check.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `row` | integer (int32) | no | The row's number in the file, counting data rows from 1, header excluded. For `companyCap`, the company's first row past the cap. |
| `value` | string | no | What identifies the row: its email, else its LinkedIn URL, else its company name or domain. For a saved list row with none of those, the person's name. For `companyCap`, the company. |
| `reason` | string | no | Why the row is here, in a few words, such as `same as row 4` or `acme.com has no MX`. |
