Email finder
An email find looks up one person's work email from their name and company, in any country. Kenso checks its own email database first, then outside email providers, and verifies each address before it keeps one. A find costs 1 credit when Kenso's own provider access finds a valid email. It costs nothing when it finds none, or when the workspace's own provider key finds the email. A find runs in the background: start it with POST /v1/email-finds and poll GET /v1/email-finds/{emailFindId}.
Headers
The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Ken-Version | header | string, one of: 2026-11-02, 1.1 | optional | 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 date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy. |
X-Ken-Workspace-Id | header | integer (int64) | optional | 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. |
Find a person's email
/v1/email-findsemail-finds.create- Permission
- Search edit
- Credits
- 1 credit per valid email (
email_found) - Rate limit
- 30 requests a minute and 500 a day per workspace (Free plan: 3 a minute and 50 a day)
email_finder feature on your workspace. Until it is on, calls answer 404.Start a lookup of one person's work email from their name and company. The call returns at once and the find runs in the background.
Send a name, as fullName or as firstName and lastName, and at least one of companyDomain and linkedinUrl. companyDomain is the company's website domain, such as acme.fr. companyName is optional. With only linkedinUrl, Kenso uses the domain of the person's current company in Search. When Search does not know that company, the find ends not_found at no charge.
The call answers 202 with the find in status queued and a Location header. Most finds end within a minute: poll GET /v1/email-finds/{emailFindId}.
Kenso saves the person in the workspace, outside any account. A repeat find for the same name at the same domain reuses that person, also when it adds linkedinUrl, so it makes no duplicate. When that person already has the email, the find comes back found at no charge, with verification unverified. When a find for the same person is still running, the call returns that find instead of starting another. Calls sent at the same moment are not merged, so send one call per person and poll it.
A workspace can start 30 finds a minute and 500 a day. Refused calls and calls that return a running find do not count.
Errors:
400 validation_failed: the name is missing, neithercompanyDomainnorlinkedinUrlis sent, orcompanyDomainis a free mail, social or link host (detail codeinvalid_domain).402 plan_limit_reached: the workspace is out of credits, and nothing runs.error.refusalhas the details.403 permission_denied: you work only your own accounts, and a found person sits on no account. Ask a workspace admin.409 conflict: a find for this person at another company is still running (detail codeactive_find). Try again once it ends.429 quota_exceeded: the workspace started 30 finds this minute or 500 today. Wait for the time inRetry-After.
Requires Search edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
fullName | string | optional | The person's full name. Send it, or firstName and lastName. |
firstName | string | optional | The person's first name, sent with lastName instead of fullName. |
lastName | string | optional | The person's last name, sent with firstName instead of fullName. |
companyDomain | string | optional | The company's website domain, such as acme.fr. Optional when you send linkedinUrl. |
companyName | string | optional | The company's name. Optional. |
linkedinUrl | string | optional | The person's LinkedIn profile URL, the strongest match signal. Optional when you send companyDomain. |
curl -X POST "https://api.ken.so/v1/email-finds" \
-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 '{
"fullName": "Jane Doe",
"firstName": "Jane",
"lastName": "Doe",
"companyDomain": "acme.fr",
"companyName": "Acme",
"linkedinUrl": "https://example.com"
}'Response 202
data is a EmailFind.
Show the 12 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get an email find
/v1/email-finds/{emailFindId}email-finds.get- Permission
- Search view
- Rate limit
- 12,000 requests a minute per API key
email_finder feature on your workspace. Until it is on, calls answer 404.Get one email find and its result. Poll it after POST /v1/email-finds until the find ends.
status is queued, running or paused while the find works. A paused find waits for credits: pausedReason is credits when the workspace ran out, or member_limit when you reached your monthly credit limit. The find then ends found, not_found or failed. On not_found or failed, error says why, and you can start a failed find again.
A found find carries email, provider (where Kenso found it) and verification: its status (safe, verified or unverified) and verifiedBy. costCredits is what the find charged.
Errors:
403 permission_denied: you work only your own accounts, and a found person sits on no account.404 not_found: no find has this id in this workspace.
Requires Search view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
emailFindId | path | integer (int64) | required | The find's id, from POST /v1/email-finds. |
curl -X GET "https://api.ken.so/v1/email-finds/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a EmailFind.
Show the 12 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
More in Prospecting data:People and company searchSaved searchesSaved listsSaved list membersSaved list invitesFunding roundsJob postingsJob post searchLinkedIn job searchLinkedIn jobsWeb scrapingSocial data lookupsSocial data searchesSocial profile resolutionSocial data recordsSignalsAll resources