https://api.rocketverifier.com/v1/finderFind 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"}'const res = await fetch("https://api.rocketverifier.com/v1/finder", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.ROCKETVERIFIER_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ first_name: "Maya", last_name: "Patel", domain: "northwind.io" }),
});
const found = await res.json();
if (found.status === "found") console.log(found.email, found.confidence);import os
import requests
res = requests.post(
"https://api.rocketverifier.com/v1/finder",
headers={"Authorization": f"Bearer {os.environ['ROCKETVERIFIER_API_KEY']}"},
json={"first_name": "Maya", "last_name": "Patel", "domain": "northwind.io"},
timeout=30,
)
found = res.json()
if found["status"] == "found":
print(found["email"], found["confidence"]){
"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
The company domain, such as
northwind.io. A URL or an address also works:https://www.northwind.io/aboutbecomesnorthwind.io.First name. Send
first_nameorfull_name.Last name. Improves the match on most domains.
Full name, split into first and last name when
first_nameis 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_foundanddomain_no_mail. How likely
emailis the person's working mailbox.found: the mail server confirmed the mailbox.catch_all: the domain accepts every address, soemailis the best ranked pattern (confidence up to 75) withalternatives.unverified: the server would not give a definite answer, soemailis 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_mailThe 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.lorlast. - sub_statusstring or null
The
sub_statusof 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
- emailstring
- credits_chargedinteger
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.
- Rank the candidates. The name is expanded into 12 common company patterns, such as
first.last(maya.patel),flast(mpatel),first(maya) andfirstlast(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. - Verify in order. Up to 4 candidates are verified live. A rejected mailbox moves on to the next candidate.
- 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.
status | What it means | What to do |
|---|---|---|
found | The mail server confirmed the mailbox. confidence is the verification score. | Use the address. |
catch_all | The 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. |
unverified | The server blocked, greylisted or timed out. email is the best guess. Confidence is at most 35. | Try again later. |
not_found | Every candidate was rejected. | No address to use. |
domain_no_mail | The 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:
| Limit | Value |
|---|---|
| Searches per minute, per account | 20 |
| Candidate checks per minute, per account | 40 |
| Time per search | 25 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 -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#
| Status | error.code | When it happens |
|---|---|---|
| 400 | invalid_domain | domain is not a domain name such as northwind.io. |
| 400 | invalid_name | The first name has no letters. |
| 401 | unauthorized, api_key_expired | The key is missing, invalid, revoked or expired. |
| 402 | insufficient_credits | The balance ran out while charging the search. |
| 402 | api_key_spend_cap_reached | This key hit its monthly spend cap. |
| 403 | insufficient_credits | The balance is zero. |
| 403 | sandbox_key_restricted | A sandbox key searched a real domain, or a live key searched the sandbox domain. |
| 403 | insufficient_scope | The OAuth token lacks verify:single. |
| 422 | validation_error | domain is missing, or neither first_name nor full_name was sent. |
| 429 | rate_limited | More than 20 searches or 40 candidate checks in a minute. |
| 500 | finder_failed | The 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