Kenso

Add leads from your app

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.

Ken-Version: 2026-11-02
Markdown

Before you start

  • REST: export KENSO_API_KEY=<your key> and export KENSO_WORKSPACE_ID=<your workspace id> (see Authentication and 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).
  • MCP: connect https://mcp.ken.so/mcp (setup). 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 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
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
CAMPAIGN_ID=$(kenso campaigns list --status active --q "Website signups" --limit 1 | jq -r '.id')
MCP: campaigns
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 Send the person as one row. A row needs email, firstName, lastName, and companyName or companyDomain. customVariables fill {signup_plan} in your emails.

REST
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": "[email protected]",
      "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
cat > body.json <<'JSON'
{
  "contacts": [
    {
      "email": "[email protected]",
      "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
contacts({
  "operation": "create",
  "campaign_id": 812,
  "contacts": [
    {
      "email": "[email protected]",
      "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} 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
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
kenso contacts get --contact-id "$CONTACT_ID"
MCP: contacts
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.
  • 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 and guides