Skip to Content
Prospecting data

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

Prospecting data2 endpointsKen-Version: 2026-11-02AuthenticationWorkspacesErrors
MarkdownOpenAPI

Headers

The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.

NameInTypeRequiredDescription
Ken-Versionheaderstring, one of: 2026-11-02, 1.1optionalThe 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-Idheaderinteger (int64)optionalThe 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

POST/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)
Needs the email_finder feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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, neither companyDomain nor linkedinUrl is sent, or companyDomain is a free mail, social or link host (detail code invalid_domain).
  • 402 plan_limit_reached: the workspace is out of credits, and nothing runs. error.refusal has 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 code active_find). Try again once it ends.
  • 429 quota_exceeded: the workspace started 30 finds this minute or 500 today. Wait for the time in Retry-After.

Requires Search edit.

Request body

application/json, optional.

FieldTypeRequiredDescription
fullNamestringoptionalThe person's full name. Send it, or firstName and lastName.
firstNamestringoptionalThe person's first name, sent with lastName instead of fullName.
lastNamestringoptionalThe person's last name, sent with firstName instead of fullName.
companyDomainstringoptionalThe company's website domain, such as acme.fr. Optional when you send linkedinUrl.
companyNamestringoptionalThe company's name. Optional.
linkedinUrlstringoptionalThe person's LinkedIn profile URL, the strongest match signal. Optional when you send companyDomain.
Request
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

GET/v1/email-finds/{emailFindId}email-finds.get
Permission
Search view
Rate limit
12,000 requests a minute per API key
Needs the email_finder feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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

NameInTypeRequiredDescription
emailFindIdpathinteger (int64)requiredThe find's id, from POST /v1/email-finds.
Request
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.


On this page