Email Finder
Operations for finding email addresses
Find an email
Find and verify the email address of one person from their first name, last name and company. The call is synchronous: the address and its deliverability verdict come back in the response, and there is no job to poll.
Company information: supply company_name or company_domain — at least one is needed, and giving both finds the right address more often.
A person we cannot find an address for is not an error: the response still arrives with prospect.status set to failed, prospect.found_email null, and the reason in prospect.error_message.
Cost: 1 credit when a deliverable email is found, nothing when it is not. Use POST /v1/email-finder/ instead when you have more than a handful of people to look up.
Find an email › Request Body
first_nameFirst name of the person whose email you are looking for.
last_nameLast name of the person whose email you are looking for.
company_nameName of the company the person works at. Supply this or company_domain — the lookup needs at least one of them, and sending both gives the best hit rate.
company_domainWeb domain of the company, without a scheme or path. The most accurate way to identify the company; supply this or company_name.
Find an email › Responses
OK
The person you asked about, with the email and its verdict.
successtrue when the lookup ran, including when it ran and found nothing; false when the lookup itself errored.
job_idReference for this single lookup. There is nothing to poll: the result is already in prospect.
List Email Finder jobs
List the email finder jobs on your account, newest first, with each job's status, progress and prospect results.
Use limit and offset to page through them (25 per page by default). Reading the list is free.
query Parameters
limitoffsetList Email Finder jobs › Responses
OK
idIdentifier of the job, as returned when you created it.
statusJob status: pending, running, complete or failed.
created_atWhen the job was created.
updated_atWhen the job last changed.
One result per prospect submitted, in the order received.
progressPercentage of the job's prospects that have finished, from 0 to 100.
error_messageJob-level failure message. Empty when the job itself did not fail; a single prospect failing is reported on that prospect.
job_typeAlways email_finder for jobs created on this endpoint.
Find emails in bulk
Create a job that finds email addresses for a list of prospects. Each prospect needs a first name, a last name, and a company name or company domain — sending the domain as well improves accuracy.
The lookups run in the background, so the call returns straight away with 202 and a job_id. Poll GET /v1/email-finder/{job_id}/ for progress and results: it answers 202 while the job is still running and 200 once every prospect is done.
Webhook support: include a webhook_url and we POST the finished job to it instead, with the same payload as the retrieve endpoint, so you do not have to poll.
Cost: 1 credit per deliverable email found. Prospects with no email, or an email that fails verification, are not charged. Credits are taken when the job finishes.
Find emails in bulk › Request Body
The people to find emails for. Each entry needs a first and last name plus a company name or domain.
job_nameYour own label for the job, so you can recognize it later. Optional.
webhook_urlOptional HTTPS URL to notify when the job finishes. We send a POST carrying the same payload as GET /v1/email-finder/{job_id}/, so you can skip polling.
Find emails in bulk › Responses
Accepted
job_idIdentifier of the queued job. Use it with GET /v1/email-finder/{job_id}/ to collect the results.
successAlways true; failures come back as an error response.
messageHuman-readable confirmation that the job was queued.
Get Email Finder job results
Retrieve one email finder job by the job_id you got when you created it. This is the polling endpoint for a bulk job.
While the job is queued or running you get 202 with its status and progress percentage. Once every prospect has been processed you get 200 with the full result list, each entry carrying the email found and its deliverability verdict. Polling once every few seconds is plenty.
Reading a job is free — the credits for the emails found were already taken when the job finished.
path Parameters
job_idGet Email Finder job results › Responses
OK
idIdentifier of the job, as returned when you created it.
statusJob status: pending, running, complete or failed.
created_atWhen the job was created.
updated_atWhen the job last changed.
One result per prospect submitted, in the order received.
progressPercentage of the job's prospects that have finished, from 0 to 100.
error_messageJob-level failure message. Empty when the job itself did not fail; a single prospect failing is reported on that prospect.
job_typeAlways email_finder for jobs created on this endpoint.