# Email Finder

`POST https://api.getprospect.com/v2/email/find`

Find the verified business email address of a specific person. Costs 1 email credit per served address the workspace does not already own; 1 enrich rate-limit unit. Inside `data`, provide the person's name (full_name, or first_name + last_name) plus their company (domain preferred, or company name). Not-found and accept-all outcomes are free, and so is the email of a person you have already saved or revealed. A live search can take more than a minute: set the client timeout to at least 95 seconds. A search that times out answers 408 and is never charged; ask again after `Retry-After` seconds, when its result is usually stored. Authenticate with your API key in the x-api-key header.

> **How are credits spent?**
>
> 1 email credit is charged only when a valid email is found. Searches that
> end in `not_found` or `accept_all` are free - the credit is refunded
> automatically.

## Choosing a domain

Pass `domain` directly when you have it - it is searched exactly as given, with no
substitution. A `company` value that is itself domain-shaped (e.g. a website like
`tryaizy.com`) is treated the same way: used as-is, never looked up or swapped for a
different domain. Only a genuine company **name** in `company` (not a domain) is resolved
- the same way [Company Enrich](https://getprospect.com/api-docs/company-enrich.md) resolves one: a companies-v2
lookup by name first, preferring that company's [`email.domain`](https://getprospect.com/api-docs/company-object.md)
over its `website` when they differ, then a search+AI fallback.

So when a [Company object](https://getprospect.com/api-docs/company-object.md) shows an `email.domain` that differs
from `website` (example: website `tryaizy.com`, `email.domain` `aizy.nl`), pass that
`email.domain` value as `domain` yourself - passing the website domain instead searches the
website domain literally and is not automatically resolved to the company's mail domain.

## Mailbox status vs domain status

`status` is the verdict for the one mailbox this call probed; `domain_status` describes the
domain in general (`accept_all` when the domain accepts mail to any address, plus
`disposable`, `invalid`, and `unknown`), independent of what happened to that specific
mailbox. A `status: "valid"` result with `domain_status: "accept_all"` means this exact
mailbox was positively confirmed deliverable even though its domain generally accepts
everything - it is a genuine find, not a downgraded guess.

Email Finder never returns `status: "accept_all"` itself: when the mailbox-level check comes
back accept-all (inconclusive - the server would have accepted almost any address), the
result is treated as unreliable and returned as the standard `not_found` response instead
(with `domain_status: "accept_all"`), and the credit is refunded, as noted above.


## Authentication

Pass your API key in the `x-api-key` header.

## Body parameters

- `data` (object, required): Lookup identifiers. Provide full_name or first_name + last_name, plus domain or company.
  - `full_name` (string, optional): The contact's full name (e.g. "Dmytro Shulha"). Use instead of first_name + last_name.
  - `first_name` (string, optional): The contact's first name (e.g. "Dmytro"). Required if full_name is not provided.
  - `last_name` (string, optional): The contact's last name (e.g. "Shulha"). Required when first_name is provided.
  - `domain` (string, optional): The company domain (e.g. "getprospect.com"). Provides the best results.
  - `company` (string, optional): The company name (e.g. "GetProspect"). Used as a fallback when domain is not provided.

## Example request

```bash
curl --request POST \
  --url https://api.getprospect.com/v2/email/find \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "data": {
    "first_name": "Emily",
    "last_name": "Carter",
    "domain": "intercom.com"
  }
}
'
```

## Response 200

The search ran. A served address has `status: valid`; when nothing could be confirmed `success` is false, `data.status` is `not_found` and `errors[0].name` is `NOT_FOUND` (not charged).

```json
{
  "success": true,
  "data": {
    "email": "emily.carter.sample@intercom.com",
    "status": "valid",
    "account": "emily.carter.sample",
    "domain": "intercom.com",
    "domain_status": "valid",
    "smtp_provider": "google",
    "free_email": false
  },
  "metadata": {
    "timestamp": "2026-07-25T14:07:55.000Z",
    "credits": {
      "email_search": 482,
      "email_verification": 500,
      "reset_at": "2026-08-01T00:00:00.000Z"
    }
  }
}
```

## Response 400

Invalid request (`VALIDATION_ERROR`). A malformed field carries `payload.code` (`wrong_type`, ...) and `payload.field`; a missing name or company, or a domain that is not one, answers without a code.

```json
{
  "success": false,
  "data": null,
  "metadata": {
    "timestamp": "2026-10-08T14:07:55.000Z"
  },
  "errors": [
    {
      "name": "VALIDATION_ERROR",
      "message": "full_name must be a string",
      "payload": {
        "field": "data.full_name",
        "code": "wrong_type",
        "received_value": 42,
        "received_type": "number",
        "constraints": {
          "isString": "full_name must be a string"
        }
      }
    }
  ]
}
```

## Response 401

Missing, unknown or inactive credentials (`UNAUTHORIZED`).

## Response 402

Not enough credits (`PAYMENT_REQUIRED`).

```json
{
  "success": false,
  "data": null,
  "metadata": {
    "timestamp": "2026-10-08T14:07:55.000Z"
  },
  "errors": [
    {
      "name": "PAYMENT_REQUIRED",
      "message": "Workspace has reached its credit limit"
    }
  ]
}
```

## Response 408

The search is still running (`TIMEOUT`). Not charged; ask again after `Retry-After` seconds.

```json
{
  "success": false,
  "data": null,
  "metadata": {
    "timestamp": "2026-10-08T14:07:55.000Z",
    "credits": {
      "email_search": 482,
      "email_verification": 499,
      "reset_at": "2026-11-01T00:00:00.000Z"
    }
  },
  "errors": [
    {
      "name": "TIMEOUT",
      "message": "Email search is taking longer than expected. Please retry your request in a few minutes."
    }
  ]
}
```

## Response 429

Over the `enrich` rate limit (`RATE_LIMIT`); wait `Retry-After` seconds. Sent only where rate limits are enforced.

## Response 500

Unexpected server error.