ZeroBounce Logo

Docs

Language Icon
  • Sign In
  • Sign Up Free

Languages

ZeroBounce ImageGetting Started
ZeroBounce ImageEmail List Validation
ZeroBounce ImageA.I. Email Scoring
ZeroBounce ImageEmail Finder
ZeroBounce ImageDomain Search
ZeroBounce ImageActivity Data
ZeroBounce ImageMulti-file upload
ZeroBounce ImageIntegrations
ZeroBounce ImageUsage Reports
ZeroBounce ImageYour ZeroBounce Account
ZeroBounce ImageEmail Validation API
ZeroBounce ImageEmail Finder API
ZeroBounce ImageBulk Email Finder API
ZeroBounce ImageDomain Search API
ZeroBounce ImageA.I. Scoring API
ZeroBounce ImageActivity Data API
ZeroBounce ImageList Evaluator API
ZeroBounce ImageApi Dashboard
ZeroBounce ImageAPI Wrappers
ZeroBounce ImageAPI Migration
ZeroBounce ImageFAQ
ZeroBounce ImageSecuring Your Account
ZeroBounce ImageAbout ZeroBounce
ZeroBounce ImageDeliverability Tools
ZeroBounce ImageStatus Page
  • Email Validation Homepage
  • Separator
  • Docs
  • Separator
  • Email Finder API (V2)
Docs

Email Finder API (V2)

Email Finder API allows you to search for new business email addresses using our proprietary technologies.

The Email Finder API uses a person’s first and last name and a domain or company name to test a variety of patterns and combinations in real time until it identifies a valid business email. It does not use or process customer data at any point to aid in this search.

Privacy and Security Note – Email Finder API searches are performed in real time and do not use stored or processed customer data. Customer privacy and security are and will always remain our top priority.

How to use the Email Finder API

Before you begin, ensure that your account has enough credits or subscription queries. A successful Email Finder API search will consume one (1) subscription query or 20 credits.

We deduct zero credits or queries if a response is undetermined.

To use the Email Finder API, use the following URL, method, and parameters. Be sure to review the successful response example below and the response details to ensure your API configuration works correctly.

API DEFAULT URL https://api.zerobounce.net/v2/guessformat

API U.S.A. URL*: https://api-us.zerobounce.net/v2/guessformat

API EU URL: https://api-eu.zerobounce.net/v2/guessformat

Method: GET

*This endpoint uses servers located within the United States. By utilizing this endpoint, you acknowledge and consent to your data being processed on servers in the United States.

  • Parameter
    Required
    Description
  • api_key
    Yes
    Your API Key, found in your account.
  • domain
    Yes
    The email domain for which to find the email format.
  • company_name
    Yes
    The company name for which to find the email format.
  • first_name
    No
    The first name of the person whose email format is being searched. [optional]
  • middle_name
    No
    The middle name of the person whose email format is being searched. [optional]
  • last_name
    No
    The last name of the person whose email format is being searched. [optional]

Note: Either the “domain” or the “company_name” must be entered.

Successful Response

Response Details

  • Properties
    Description
  • email
    The resulting email address identified by the API.
  • email_confidence
    The level of confidence we have that the email exists. Possible values: HIGH, MEDIUM, LOW.
  • domain
    The provided domain name.
  • company_name
    The company associated with the domain.
  • did_you_mean
    e.g. a suggestion in case case a firstname is used in the lastname field
  • failure_reason
    A reason for the unknown result. Possible values can be found in the "Possible reasons for unknown status" section below.

Possible failure reasons for unknown status

  • Properties
    Description
  • FREE_DOMAIN_ERROR
    Cannot find pattern for free domains
  • DOMAIN_SYNTAX_ERROR
    Domain syntax error
  • COMPANY_DOMAIN_ERROR
    Either the domain or the company name must be entered
  • COMPANY_DOMAIN_NOT_FOUND
    There is no domain assigned for this company name
  • UNEXPECTED_ERROR_OCCURRED_DURING_VALIDATION
    Unexpected error occurred during validation
  • DOMAIN_DOES_NOT_ACCEPT_MAIL
    Domain does not accept mail
  • NO_DATA_FOR_THIS_DOMAIN
    No data for this domain
  • NO_DATA_FOR_THIS_COMPANY
    No data for this company

Other potential error messages

You can resolve this error by ensuring that there is at least one (1) subscription query or 20 ZeroBounce credits in your account balance before making your next API call. Additionally, ensure that the API key is valid.

Email Finder API confidence levels

For each email address format that the Email Finder API generates, we assign a corresponding confidence level to indicate the probability that the address is actively in use on the respective email domain.

The confidence levels are listed below:

  • LOW - unlikely to be in use; high-risk
  • MEDIUM - medium level of confidence; the format may be in use
  • HIGH - highest level of confidence, format likely in use based on validation results

The Email Finder API lets you reliably identify business email addresses for your potential leads or business contacts.

If you need further assistance configuring the Email Finder API or need help to understand your results, the ZeroBounce customer support team is available 24/7.

Bulk Email Finderⓘ API Documentation

Email search engine - Send file

The email-finder/sendfile API allows you to send a file for bulk email finderⓘ. This guide will provide everything you need to know on how to find email addresses in bulk via API.

There is no restriction on the file size, number of emails, or number of files you can submit using this endpoint.

Each search will consume 20 credits if a valid email format is returned. If you are a monthly subscriber, the API call will consume 1 Email Finderⓘ query if a valid format is returned. As long as you have the available queries via subscription or the credits in your account to cover the number of searches submitted in the file, your file will be accepted.

To avoid API interruptions, consider activating AutoPay in your ZeroBounce account settings to ensure you never run out of credits.

POST /EMAIL-FINDER/SENDFILE

API URL: https://bulkapi.zerobounce.net/email-finder/sendfile

The content type of the body should be multipart/form-data.

Link parameters

  • Parameter
    Description
  • file
    The CSV or TXT file. Byte array content for the submitted file. The content header is of type "text/csv"
  • api_key
    Your API key, which is located in your account. (Required)
  • domain_column
    The domain column index in the file. The index starts from 1 (required).
  • first_name_column
    The column index for the first name column. (It is mandatory that one of the columns, either the first name or the full name column, be filled in)
  • last_name_column
    The column index for the last name column. (Optional)
  • middle_name_column
    The column index for the middle name column. (Optional)
  • full_name_column
    The column index for the full name column. (It is mandatory that one of the columns, either the first name or the full name column, be filled in)
  • has_header_row
    If the first row of the submitted file is a header row; true or false (optional)

END POINT ANSWER

Successful Response

Error Response

Do you need help submitting your file to the bulk email search engine? Tell us what you need: our team is available at any time to assist you.

Bulk Email Finderⓘ API Documentation

Email search engine - Archive status

The email finderⓘ's filestatus API returns the file processing status for the file that was sent using the email finderⓘ's sendfile API.

GET /EMAIL-FINDER/FILESTATUS

API URL: https://bulkapi.zerobounce.net/email-finder/filestatus

Link parameters

  • Parameter
    Description
  • api_key
    Your API key, which is located in your account. (Required)
  • file_id
    The file ID returned when calling the sendfile API.

If you want to call the API from your browser to test it, replace the API KEY parameter with your unique API key (found in your ZeroBounce account settings) and the FILE ID parameter with the returned file ID from sendfile API:

https://bulkapi.zerobounce.net/email-finder/filestatus?api_key=[replacewithyours]&file_id=[replacewithyours]

ENDPOINT RESPONSE

Successful Response

Error Response

For each email address it verifies, the email finderⓘ API consumes 1 query (if you have an active ZeroBounce One subscription ). If you have credits or use Pay-As-You-Go, Email Finderⓘ will consume 20 credits per successful result. If you use the API regularly, take measures to ensure your account is replenished periodically with credits to avoid interruptions.

Need help determining the status of your email finderⓘ API files? Please reach out to our Customer Support team. We are available around the clock to answer any questions and assist you.

Bulk Email Finderⓘ API Documentation

Email Finderⓘ - Get File

The email finderⓘ getfile API allows you to get the email finderⓘ results for the file you submitted using email finderⓘ sendfile API.

GET /EMAIL-FINDER/GETFILE

API URL: https://bulkapi.zerobounce.net/email-finder/getfile

Link parameters

  • Parameter
    Description
  • api_key
    Your API Key, found in your account. (Required)
  • file_id
    The returned file ID when calling sendfile API.

If you want to call the API from your browser to test it, all you have to do is to replace the API KEY parameter with your API key (found in your ZeroBounce account settings ) and the FILE ID with the returned file ID from sendfile API:

https://bulkapi.zerobounce.net/email-finder/getfile?api_key=replacewithyours&file_id=[replacewithyours]

ENDPOINT RESPONSE

Successful Response

The email finderⓘ getfile API returns the email finderⓘ results file. The returned content type is "application/octet-stream". You can get the file name from response.Content.Headers.ContentDisposition.FileName. If you are calling the API directly from the browser, you can either save or open the results file from the browser.

Error Response

Need help getting your email finderⓘ API results? Our team is here to lend a hand. Reach out to us anytime. We offer 24/7 customer support.

Bulk Email Finderⓘ API Documentation

Email Finderⓘ - Delete File

The email finderⓘ deletefile API allows you to delete the file that you submitted using the email finderⓘ sendfile API. Please note that the file can be deleted only when its status is Complete.

GET /EMAIL-FINDER/GETFILE

API URL: https://bulkapi.zerobounce.net/email-finder/deletefile

Link parameters

  • Parameter
    Description
  • api_key
    Your API Key, found in your account. (Required)
  • file_id
    The returned file ID when calling sendfile API.

ENDPOINT RESPONSE

Below you can find examples of both successful and errors responses.

Successful Response

Error Response

If you need help deleting your email finderⓘ API file, let us know. Our team is here 24/7 to answer any questions and make things easier for you.