Skip to content
RocketVerifierDOCS
POSThttps://api.rocketverifier.com/v1/finder

Find an email address

In short

Send a first name, last name and company domain to POST /v1/finder. RocketVerifier ranks the likely address patterns, verifies the candidates live and returns the best address with a 0 to 100 confidence and the pattern it follows. You pay 1 credit per candidate check with a definite answer, at most 4 per search, and unknown checks are free.

OAuth scope verify:single

curl -X POST https://api.rocketverifier.com/v1/finder \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"first_name": "Maya", "last_name": "Patel", "domain": "northwind.io"}'
Response 200
{
  "email": "maya.patel@northwind.io",
  "confidence": 94,
  "status": "found",
  "domain": "northwind.io",
  "pattern": "first.last",
  "sub_status": "none",
  "checked": 1,
  "alternatives": [],
  "credits_charged": 1
}

The finder turns a name and a company into a verified address. It uses each domain's own naming convention when RocketVerifier has learned it, then confirms the address with the same live verification as POST /v1/verify.

Request#

Send a JSON body with a name and a domain. Authenticate with an API key, or with an OAuth token that has the verify:single scope.

Body

  • domainstringrequiredup to 253 characters

    The company domain, such as northwind.io. A URL or an address also works: https://www.northwind.io/about becomes northwind.io.

  • first_namestringup to 100 characters

    First name. Send first_name or full_name.

  • last_namestringup to 100 characters

    Last name. Improves the match on most domains.

  • full_namestringup to 200 characters

    Full name, split into first and last name when first_name is not sent.

Names are normalized before the search: accents are removed and only letters are kept, so José becomes jose and O'Brien becomes obrien. With full_name and no first_name, the first word is the first name and the last word is the last name.

Response#

A 200 response means the search finished. Branch on status; email and confidence carry the answer.

  • emailstring or null

    The most likely address. Null for not_found and domain_no_mail.

  • confidenceinteger0 to 100

    How likely email is the person's working mailbox.

  • statusenumrequired

    found: the mail server confirmed the mailbox. catch_all: the domain accepts every address, so email is the best ranked pattern (confidence up to 75) with alternatives. unverified: the server would not give a definite answer, so email is the best guess (confidence up to 35). not_found: every candidate was rejected. domain_no_mail: the domain takes no mail.

    foundcatch_allunverifiednot_founddomain_no_mail
  • domainstringrequired

    The normalized domain that was searched.

  • patternstring or null

    The naming pattern of email: first.last, flast, first, firstlast, f.last, first_last, firstl, last.first, first-last, lastf, first.l or last.

  • sub_statusstring or null

    The sub_status of the deciding check.

  • checkedinteger

    Candidate addresses verified.

  • alternativesarray of objects

    Up to three other likely addresses on a catch-all domain.

    › Show 2 child fields
  • Credits charged, 1 per candidate check with a definite answer.

How the finder works#

The finder checks the most likely addresses in order and stops as soon as it has an answer, so a search that confirms its first candidate costs 1 credit.

  1. Rank the candidates. The name is expanded into 12 common company patterns, such as first.last (maya.patel), flast (mpatel), first (maya) and firstlast (mayapatel), ordered by how often companies use them. Patterns that need a last name are skipped without one. When RocketVerifier has learned this domain's own pattern, that pattern goes first.
  2. Verify in order. Up to 4 candidates are verified live. A rejected mailbox moves on to the next candidate.
  3. Stop early. The search stops at the first confirmed mailbox, at a catch-all domain (more probes prove nothing there), at a domain that takes no mail, or at a server that will not answer.
statusWhat it meansWhat to do
foundThe mail server confirmed the mailbox. confidence is the verification score.Use the address.
catch_allThe domain accepts every address. email is the best ranked pattern, with up to three alternatives. Confidence is at most 75.Use it for engaged outreach, or confirm the address another way first.
unverifiedThe server blocked, greylisted or timed out. email is the best guess. Confidence is at most 35.Try again later.
not_foundEvery candidate was rejected.No address to use.
domain_no_mailThe domain has no mail route, does not accept mail, failed DNS or is disposable. sub_status says which.Check the domain.

Credits#

  • 1 credit per candidate check with a definite answer, the same price as the check through POST /v1/verify.
  • At most 4 checks per search, and never more checks than your balance covers.
  • Free: checks that return unknown, addresses on your own suppression list, and sandbox searches.

credits_charged in the response says what the search cost. The balance must hold at least 1 credit to start a search.

Limits#

The finder has its own limits on top of your account rate limit:

LimitValue
Searches per minute, per account20
Candidate checks per minute, per account40
Time per search25 seconds

When the check budget runs out partway through a search, the finder returns what it knows as unverified. When it runs out before the first check, the call returns 429 rate_limited.

Test with the sandbox#

With an rv_test_ sandbox key, search the domain sandbox.rocketverifier.com. The finder returns the top ranked pattern as found with confidence 95, checks nothing live and charges nothing.

cURL
curl -X POST https://api.rocketverifier.com/v1/finder \
  -H "Authorization: Bearer $ROCKETVERIFIER_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"first_name": "Maya", "last_name": "Patel", "domain": "sandbox.rocketverifier.com"}'

Sandbox keys cannot search other domains, and live keys cannot search the sandbox domain. Both return 403 sandbox_key_restricted. More in sandbox and testing.

Errors#

Statuserror.codeWhen it happens
400invalid_domaindomain is not a domain name such as northwind.io.
400invalid_nameThe first name has no letters.
401unauthorized, api_key_expiredThe key is missing, invalid, revoked or expired.
402insufficient_creditsThe balance ran out while charging the search.
402api_key_spend_cap_reachedThis key hit its monthly spend cap.
403insufficient_creditsThe balance is zero.
403sandbox_key_restrictedA sandbox key searched a real domain, or a live key searched the sandbox domain.
403insufficient_scopeThe OAuth token lacks verify:single.
422validation_errordomain is missing, or neither first_name nor full_name was sent.
429rate_limitedMore than 20 searches or 40 candidate checks in a minute.
500finder_failedThe search could not be completed. Retry it.

Every error uses the standard error shape.

Frequently asked questions

How much does a search cost?

1 credit for each candidate address that got a definite answer, at most 4 per search. A search that confirms its first candidate costs 1 credit, and checks that come back unknown are free.

What does a catch_all status mean?

The domain accepts mail for every address, so no mail server can confirm one mailbox. The finder returns the best ranked pattern with a confidence of up to 75 and up to three alternatives.

Do I need the last name?

Only first_name (or full_name) is required, but a last name unlocks the most common company patterns such as first.last and flast, so send it whenever you have it.

Can I test the finder for free?

Yes. With an rv_test_ sandbox key and the domain sandbox.rocketverifier.com, the finder returns the top pattern as found with confidence 95 and charges nothing.

Updated 11 November 2026Suggest an edit