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.
Before you start
- REST:
export KENSO_API_KEY=<your key>andexport KENSO_WORKSPACE_ID=<your workspace id>(see Authentication and Workspaces). The examples read ids withjq. kenso:npm i -g kenso,printf '%s' "$KENSO_API_KEY" | kenso auth login --with-key, thenkenso workspace use <your workspace id>. A command prints the response'sdatawithout 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 asclient_idand 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/intakesaves a person to your CRM accounts, not to a campaign, so nothing is emailed. It also needs thelead_intakefeature.POST /v1/contact-importsis a background job for files and other sources: it answers202with a job to poll and counts instead of row results, and a second import into the same campaign answers409while 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.
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')
CAMPAIGN_ID=$(kenso campaigns list --status active --q "Website signups" --limit 1 | jq -r '.id')
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.
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')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')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.
createdid is the new contact.updatedcustomVariables merged. Same id.skippedduplicate, already_contactedid.failedblocklistedfailedexcluded, invalid_email, validationfailedlimit_reached3. 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.
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 contacts get --contact-id "$CONTACT_ID"
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
updatedwith the same id. The call takes noIdempotency-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.csvbatch and resume a CSV for you.