Roles roles
The jobs a recruiting workspace hires for, each with a candidate pipeline by stage, and the extra roles a recruiting campaign also hires for. Extract reads a job link into a draft role.
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through roles_read and changes through roles_write. Each takes operation plus that operation's parameters, and your workspace role decides which operations you see.
Each operation with a route calls the Kenso API at https://api.ken.so with Authorization: Bearer <Kenso API key>, Ken-Version: 1.1 and X-Ken-Workspace-Id: <workspace id>. You can call that route directly with the same headers.
Operations: candidates-create, create, delete, candidates-events, candidates-export, extract, candidates-find, campaign-roles-get, get, candidates-list, list, campaign-roles-replace, candidates-update, update
candidates-create
Write. Early access: needs recruiting on for the workspace. POST https://api.ken.so/v1/roles/{roleId}/candidates
Path: roleId
Body (json): campaignId integer, contactId integer, email string, firstName string, lastName string, linkedinUrl string, referredByContactId integer, source string
Add a person to a role's pipeline at stage sourced. Pass contact_id for a contact, or the person's email or linkedin_url to create them.
POST /api/v1/roles/{roleId}/candidates. Staff. Sends Ken-Version 1.1 and X-Ken-Actor:
agent. Requires campaigns edit. Without contact_id the person (first_name, last_name,
email, linkedin_url) becomes a lead of campaign_id, else of the role's first
recruiting campaign; the usual dedupe, blocklist and lead credits apply. email is
required unless that campaign is LinkedIn-only, where linkedin_url is enough. An email or
linkedin_url of someone already a contact elsewhere in the workspace adds that contact.
campaign_id must be a recruiting campaign of this role. referred_by_contact_id names the contact
who referred them and makes source referral; source is manual or referral. Returns
201 with the candidate. Errors: not_found (role_not_found, contact_not_found,
referrer_not_found, campaign_not_found); conflict (already_candidate,
contact_exists, not_recruiting, campaign_not_linked); validation_failed
(campaign_required when the role has no recruiting campaign; email required when
the campaign sends email and no email was sent).
create
Write. Early access: needs recruiting on for the workspace. POST https://api.ken.so/v1/roles
Body (json): ats object, companyDomain string, companyName string, description string, hiringContact string, jobUrl string, location string, mustHaves array, niceToHaves array, pay object, remotePolicy string, seniority string, status string, title string
Create a role: a job the workspace hires for. Status starts open. title is required; fields takes the rest. To fill it from a job link, run extract first.
POST /api/v1/roles. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent. Requires
campaigns edit. title: 1 to 200 characters. fields (all optional): company_name,
company_domain (a domain, website or work email), job_url (an http(s) URL),
description, must_haves and nice_to_haves (lists of up to 20 short lines), pay {min,
max, currency (ISO 4217 such as USD), period (year, month, day, hour)}, location,
remote_policy (onsite, hybrid, remote), seniority (such as Senior), hiring_contact
(who candidates hear from, such as a name and title; up to 200 characters), status
(open, paused, filled, closed), ats {provider (bullhorn, ashby, greenhouse, lever),
job_id, connection_id}. Returns 201 with the role. Errors: validation_failed naming
the field (required, invalid, out_of_range); conflict with detail ats_job_mapped when
another live role maps the same ATS job.
delete
Write. Early access: needs recruiting on for the workspace. DELETE https://api.ken.so/v1/roles/{roleId}
Path: roleId
Delete a role. Its candidates and their history stay; its campaigns keep running.
DELETE /api/v1/roles/{roleId}. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Requires campaigns edit. Soft delete; returns 204. The role leaves list and get; its
candidates and their events stay readable, and a campaign that hires for it keeps
running unchanged. An unknown role or another workspace's is not_found with detail
role_not_found.
candidates-events
Read. Early access: needs recruiting on for the workspace. GET https://api.ken.so/v1/roles/{roleId}/candidates/{candidateId}/events
Path: roleId, candidateId
Read a candidate's stage history, oldest first.
GET /api/v1/roles/{roleId}/candidates/{candidateId}/events. Staff. Sends Ken-Version
1.1 and X-Ken-Actor: agent. Requires the campaigns page. Each event: id, fromStage
(absent on the first), toStage, source, moveKind (automatic, manual, ats),
actorUserId, reason, occurredAt. Errors: not_found with detail candidate_not_found.
candidates-export
Write. Early access: needs recruiting on for the workspace. POST https://api.ken.so/v1/roles/{roleId}/candidates/export
Path: roleId
Body (json): stages array
Export a role's candidates as CSV text, up to 5,000 rows. stages limits it to those stages; absent or [] exports every stage.
POST /api/v1/roles/{roleId}/candidates/export. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Requires the campaigns page and export access (admin or editor).
Returns {format: csv, rowCount, csv}, plus truncated: true when the role has more
than 5,000 candidates and the rest were cut (the Kenso app exports up to 50,000). The
header is candidate_id, contact_id, first_name, last_name, email, linkedin_url,
title, company, location, stage, stage_changed_at, source, campaign_id,
referred_by_contact_id, ats_candidate_id, ats_application_id, created_at. Each export
writes an audit-log entry. Errors: not_found with detail role_not_found;
validation_failed naming stages, or with detail too_many_rows over 50,000 candidates
(pass stages to narrow it).
extract
Write. Early access: needs recruiting on for the workspace. POST https://api.ken.so/v1/roles/extract
Body (json): text string, url string
Read a job link or pasted text into a draft role. Nothing is saved. Send url (a job or application page) or text (the role in the user's words; it wins).
POST /api/v1/roles/extract. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent. Requires campaigns edit. Takes up to a minute. Returns a draft with the create fields it found (title, companyName, companyDomain, jobUrl, description, mustHaves, niceToHaves, pay, location, remotePolicy, seniority), plus missing (the fields the page did not give) and questions (one plain question per missing field, to ask the user). Review the draft with the user, then save it with roles(operation='create'). Errors: validation_failed with detail page_unreadable when Kenso cannot read the page (paste the text instead); 503 extraction_unavailable when the model is down (retry later).
candidates-find
Read. Early access: needs recruiting on for the workspace. GET https://api.ken.so/v1/role-candidates
Query: contactId integer
List the roles a contact is a candidate for, one row per role.
GET /api/v1/role-candidates?contactId=. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent. Requires the campaigns page. Returns the candidates on every role of the workspace, deleted roles included, oldest first, with the fields of roles(operation='candidates-list'); an empty list when the contact is in no pipeline.
campaign-roles-get
Read. Early access: needs recruiting on for the workspace. GET https://api.ken.so/v1/campaigns/{campaignId}/roles
Path: campaignId
Read the roles a campaign hires for: its own role and up to 3 extra roles.
GET /api/v1/campaigns/{campaignId}/roles. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Requires the campaigns page. Returns {primaryRoleId, extraRoleIds}.
A sales campaign has no primaryRoleId and an empty extraRoleIds. Errors: not_found
with detail campaign_not_found.
get
Read. Early access: needs recruiting on for the workspace. GET https://api.ken.so/v1/roles/{roleId}
Path: roleId
Read one role with its campaigns and pipeline counts by stage.
GET /api/v1/roles/{roleId}. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Requires the campaigns page. The role has the fields of roles(operation='list'). An
unknown role, a deleted one or another workspace's is not_found with detail
role_not_found.
candidates-list
Read. Early access: needs recruiting on for the workspace. GET https://api.ken.so/v1/roles/{roleId}/candidates
Path: roleId
Query: cursor string, limit integer, stage string
List a role's candidates with their stage and where they came from. stage filters (comma = OR) by any of the ten pipeline stages.
GET /api/v1/roles/{roleId}/candidates. Staff. Sends Ken-Version 1.1 and X-Ken-Actor:
agent. Requires the campaigns page. Stages: sourced, contacted, replied, interested,
screen_booked, submitted, interviewing, offer, hired, not_a_fit. limit 1 to 100
(default 50); pass pagination.nextCursor back as cursor with the same stage. Each
candidate: id, roleId, contactId, campaignId, stage, stageChangedAt, source (campaign,
manual, referral, ats, import), person {firstName, lastName, title, company,
linkedinUrl, email, location}, ats {candidateId, applicationId, pushedAt},
referredByContactId, studio {views, ctaClicks, formSubmits, lastEventAt}, createdAt.
Empty fields are left out. studio is the person's engagement with their own Studio
pages: human views, CTA clicks and form submits (scanner hits not counted), and the
time of the latest of them. A page nobody has opened yet gives {views: 0, ctaClicks:
0, formSubmits: 0, lastEventAt: null}; studio is left out when the person has no
Studio page. Readable after the role is deleted.
list
Read. Early access: needs recruiting on for the workspace. GET https://api.ken.so/v1/roles
Query: cursor string, limit integer, q string, status string
List the workspace's roles with their campaigns and pipeline counts by stage. status filters (comma = OR): open, paused, filled, closed. q matches the title or company.
GET /api/v1/roles. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent. Requires the
campaigns page. status absent = every status. limit 1 to 100 (default 50); pass
pagination.nextCursor back as cursor with the same filters. Each role: id, title,
companyName, companyDomain, jobUrl, description, mustHaves, niceToHaves, pay {min, max,
currency, period (year, month, day, hour)}, location, remotePolicy (onsite, hybrid,
remote), seniority, hiringContact (who candidates hear from), status, ats {provider,
jobId, connectionId}, campaignIds (the live campaigns that hire for it, as primary or
extra role), stageCounts (all ten stages: sourced, contacted, replied, interested,
screen_booked, submitted, interviewing, offer, hired, not_a_fit), createdAt,
updatedAt. Empty fields are left out.
campaign-roles-replace
Write. Early access: needs recruiting on for the workspace. PUT https://api.ken.so/v1/campaigns/{campaignId}/roles
Path: campaignId
Body (json): extraRoleIds array
Set a recruiting campaign's extra roles, in order. [] removes every extra role.
PUT /api/v1/campaigns/{campaignId}/roles. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Requires campaigns edit. extra_role_ids: up to 3 live role ids,
not the campaign's own role (change that on the campaign). Returns {primaryRoleId,
extraRoleIds}.
Errors: not_found (campaign_not_found, role_not_found); conflict with detail
not_recruiting for a sales campaign; validation_failed (primary_role,
too_many_roles).
candidates-update
Write. Early access: needs recruiting on for the workspace. PATCH https://api.ken.so/v1/roles/{roleId}/candidates/{candidateId}
Path: roleId, candidateId
Body (json): stage string
Move a candidate to a stage by hand. Any stage; the move is recorded in their events.
PATCH /api/v1/roles/{roleId}/candidates/{candidateId}. Staff. Sends Ken-Version 1.1
and X-Ken-Actor: agent. Requires campaigns edit. stage: sourced, contacted, replied,
interested, screen_booked, submitted, interviewing, offer, hired or not_a_fit. A move
by hand skips the automatic rules (it can go back a stage). The same stage changes
nothing. Returns the candidate. Errors: not_found with detail candidate_not_found;
validation_failed naming stage; conflict with detail move_refused.
update
Write. Early access: needs recruiting on for the workspace. PATCH https://api.ken.so/v1/roles/{roleId}
Path: roleId
Body (json): ats object, companyDomain string, companyName string, description string, hiringContact string, jobUrl string, location string, mustHaves array, niceToHaves array, pay object, remotePolicy string, seniority string, status string, title string
Change a role. Send only the fields that change; null clears one. changes takes title and the create fields (pay and ats replace the whole object).
PATCH /api/v1/roles/{roleId}. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Requires campaigns edit. changes keys: title, company_name, company_domain, job_url,
description, must_haves, nice_to_haves, pay {min, max, currency, period}, location,
remote_policy, seniority, hiring_contact, status, ats {provider, job_id,
connection_id}. title and status cannot be null; null or blank hiring_contact clears
it. A campaign that hires for the role gets the new facts in its Role brief
qualification prompt. Returns the role. Errors: not_found with detail role_not_found;
validation_failed naming the field; conflict with detail ats_job_mapped.