# Find an email address

Source: https://docs.rocketverifier.com/api/finder
Endpoint: `POST https://api.rocketverifier.com/v1/finder` (OAuth scope `verify:single`)

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

cURL:

```bash
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"}'
```

Node.js:

```js
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);
```

Python:

```python
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"])
```

Response 200:

```json
{
  "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`](https://docs.rocketverifier.com/api/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**

| Field | Type | Description |
| --- | --- | --- |
| `domain` | string | The company domain, such as `northwind.io`. A URL or an address also works: `https://www.northwind.io/about` becomes `northwind.io`. required; up to 253 characters |
| `first_name` | string | First name. Send `first_name` or `full_name`. up to 100 characters |
| `last_name` | string | Last name. Improves the match on most domains. up to 100 characters |
| `full_name` | string | Full name, split into first and last name when `first_name` is not sent. up to 200 characters |

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.

| Field | Type | Description |
| --- | --- | --- |
| `email` | string or null | The most likely address. Null for `not_found` and `domain_no_mail`. |
| `confidence` | integer | How likely `email` is the person's working mailbox. 0 to 100 |
| `status` | enum | `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. required; one of `found`, `catch_all`, `unverified`, `not_found`, `domain_no_mail` |
| `domain` | string | The normalized domain that was searched. required |
| `pattern` | string 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_status` | string or null | The `sub_status` of the deciding check. |
| `checked` | integer | Candidate addresses verified. |
| `alternatives` | array of objects | Up to three other likely addresses on a catch-all domain. |
| `alternatives.email` | string |  |
| `alternatives.confidence` | integer | 0 to 100 |
| `credits_charged` | integer | 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.

| `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](https://docs.rocketverifier.com/rate-limits):

| 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:

```bash
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](https://docs.rocketverifier.com/sandbox).

## 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](https://docs.rocketverifier.com/api#handle-errors).

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