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

# Add leads from your app

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

This call adds a lead to one campaign, or updates it when the email is already there. It never overwrites a field that has a value, never saves a blocklisted address, and never emails a lead while the campaign is a draft.

## Before you start

- REST: `export KENSO_API_KEY=<your key>` and `export KENSO_WORKSPACE_ID=<your workspace id>` (see [Authentication](/docs/authentication) and [Workspaces](/docs/workspaces)). The examples read ids with `jq`.
- `kenso`: `npm i -g kenso`, `printf '%s' "$KENSO_API_KEY" | kenso auth login --with-key`, then `kenso workspace use <your workspace id>`. A command prints the response's `data` without the envelope, and a list prints one JSON row per line ([CLI guide](/cli)).
- MCP: connect `https://mcp.ken.so/mcp` ([setup](/mcp)). Each tool takes the workspace id as `client_id` and returns the same body as the REST call.
- Each step keeps the ids the next steps need in shell variables (`$CAMPAIGN_ID`). The MCP examples show the same ids as numbers.

## The path

Use `POST /v1/campaigns/{campaignId}/contacts` with one row per signup. It is the only call that puts a lead straight into a campaign, answers at once, and returns each row's result with the new contact id.

- `POST /v1/people/intake` saves a person to your CRM accounts, not to a campaign, so nothing is emailed. It also needs the `lead_intake` feature.
- `POST /v1/contact-imports` is a background job for files and other sources: it answers `202` with a job to poll and counts instead of row results, and a second import into the same campaign answers `409` while one runs.
- Inbound webhooks (`POST /v1/campaigns/{campaignId}/inbound-webhooks`) give a form tool a URL to post to without an API key. The lead passes through a staging campaign and you get no contact id back.

## 1. Find the campaign

[`GET /v1/campaigns`](/docs/api/campaigns.md)

Look the id up once and keep it in your config: it is also in the campaign's URL in the app. Here, the active campaign named Website signups.

**REST**

```bash
CAMPAIGN_ID=$(curl -sS -X GET "https://api.ken.so/v1/campaigns?status=active&q=Website%20signups&limit=1" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" | jq -r '.data[0].id')
```

**kenso**

```bash
CAMPAIGN_ID=$(kenso campaigns list --status active --q "Website signups" --limit 1 | jq -r '.id')
```

**MCP** (`campaigns`)

```text
campaigns({
  "operation": "list",
  "status": "active",
  "q": "Website signups",
  "limit": 1,
  "client_id": 4107
})
```

Keeps `data[0].id` as `$CAMPAIGN_ID`.

## 2. Add the lead

[`POST /v1/campaigns/{campaignId}/contacts`](/docs/api/contacts.md)

Send the person as one row. A row needs `email`, `firstName`, `lastName`, and `companyName` or `companyDomain`. `customVariables` fill `{signup_plan}` in your emails.

**REST**

```bash
CONTACT_ID=$(curl -sS -X POST "https://api.ken.so/v1/campaigns/$CAMPAIGN_ID/contacts" \
  -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 '{
  "contacts": [
    {
      "email": "maya.patel@example.com",
      "firstName": "Maya",
      "lastName": "Patel",
      "title": "Head of Growth",
      "companyName": "Example Corp",
      "companyDomain": "example.com",
      "customVariables": {
        "signup_plan": "trial"
      }
    }
  ]
}' | jq -r '.data.results[0].id')
```

**kenso**

```bash
cat > body.json <<'JSON'
{
  "contacts": [
    {
      "email": "maya.patel@example.com",
      "firstName": "Maya",
      "lastName": "Patel",
      "title": "Head of Growth",
      "companyName": "Example Corp",
      "companyDomain": "example.com",
      "customVariables": {
        "signup_plan": "trial"
      }
    }
  ]
}
JSON
CONTACT_ID=$(kenso contacts create --campaign-id "$CAMPAIGN_ID" --data @body.json | jq -r '.results[0].id')
```

**MCP** (`contacts`)

```text
contacts({
  "operation": "create",
  "campaign_id": 812,
  "contacts": [
    {
      "email": "maya.patel@example.com",
      "first_name": "Maya",
      "last_name": "Patel",
      "title": "Head of Growth",
      "company_name": "Example Corp",
      "company_domain": "example.com",
      "custom_variables": {
        "signup_plan": "trial"
      }
    }
  ],
  "client_id": 4107
})
```

Keeps `data.results[0].id` as `$CONTACT_ID`.

The call answers `200` even when the row fails, so read `data.results[0].status`. Only a body with no rows, or more than 1,000, answers `400`, and a campaign outside the workspace answers `404`.

| `status` | `reason` | What happened |
| --- | --- | --- |
| `created` |  | The lead is in the campaign. `id` is the new contact. |
| `updated` |  | The email was already in this campaign: blank fields were filled and `customVariables` merged. Same `id`. |
| `skipped` | `duplicate`, `already_contacted` | The person is in another campaign, or was emailed recently, and your workspace's duplicate setting keeps them out. No `id`. |
| `failed` | `blocklisted` | The address or domain is on the workspace blocklist, which holds unsubscribes, complaints and bounces. Nothing is saved. |
| `failed` | `excluded`, `invalid_email`, `validation` | The campaign excludes the lead's country, the email is not valid, or a required field is missing. |
| `failed` | `limit_reached` | The plan's contact allowance is used up, so the lead was not added. |

## 3. Check the lead

[`GET /v1/contacts/{contactId}`](/docs/api/contacts.md)

`sendable: true` in the result does not mean the lead will be emailed. Read the contact: `isQualified` turns true once the campaign's checks (email verification, AI qualification) pass, and `doNotContact` is true for an unsubscribed lead.

**REST**

```bash
curl -sS -X GET "https://api.ken.so/v1/contacts/$CONTACT_ID" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

**kenso**

```bash
kenso contacts get --contact-id "$CONTACT_ID"
```

**MCP** (`contacts`)

```text
contacts({
  "operation": "get",
  "contact_id": 90412,
  "client_id": 4107
})
```

## Dedupe, blocklist and sending

- Dedupe is by email within the campaign, so a retry is safe: the same email again answers `updated` with the same id. The call takes no `Idempotency-Key`, so send one call at a time for the same new email.
- Across campaigns, your workspace's duplicate setting and the campaign's recently-emailed window decide whether a person already in another campaign is added.
- An active campaign picks a new lead up and runs its checks before the first step sends. A draft keeps the lead until you [launch it](/docs/recipes/launch-a-campaign).
- Your key needs edit access to campaigns.
- For a backfill, send at most 1,000 rows per call, or let `kenso contacts import --campaign 812 --file leads.csv` batch and resume a CSV for you.

## More recipes

- [Create and launch a campaign](/docs/recipes/launch-a-campaign.md)
- [Read and answer replies](/docs/recipes/answer-replies.md)
- [Receive webhooks](/docs/recipes/receive-webhooks.md)
- [API reference](/docs.md)
