POST /email_finder • Credits: 5 credits per call, charged only when an email is found

The RichAPI Email Finder API finds a person's work email address. Send a first name, a last name, and a company domain, or send a LinkedIn profile URL. The endpoint is POST https://api.richapi.ai/api/v1/email_finder. It returns a JSON response that holds the email address, the provider that found it, and a per-provider execution log. One call costs 5 credits ($0.10), and RichAPI charges those credits only for a call that finds an email.

What Email Finder does

Email Finder solves one problem: you know who a person is, but you do not know the work email address. You send a name plus a company domain, or a LinkedIn profile URL. RichAPI then runs a waterfall across several email data providers. A waterfall tries each provider in a fixed order and stops at the first provider that returns an email. RichAPI pays every provider it tries, but it charges you one flat price for the whole call. The response names the provider that won, and it lists every provider that RichAPI tried.

What is the Email Finder endpoint?

Method: POST
URL: https://api.richapi.ai/api/v1/email_finder
Authentication: x-api-key header
Response: synchronous JSON
Cost: 5 credits per call, charged on a hit only
Success status: 200

How to send an Email Finder request

Copy your API key from the RichAPI dashboard.
Set the x-api-key header to your API key.
Set the Content-Type header to application/json.
Build a request body with one accepted input shape.
For the name shape, send first_name, last_name, and company_domain.
For the LinkedIn shape, send linkedin_url.
Send the request to https://api.richapi.ai/api/v1/email_finder.
Read the success field in the response.
If success is true, read the email from result.email.

CAUTION: A request body that satisfies no input shape returns 400. RichAPI charges no credits for that request.

cURL

curl -X POST https://api.richapi.ai/api/v1/email_finder   
  -H "x-api-key: YOUR_API_KEY"   
  -H "Content-Type: application/json"   
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "company_domain": "acme.com"
  }'

Python

import requests

response = requests.post(
    "https://api.richapi.ai/api/v1/email_finder",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "first_name": "John",
        "last_name": "Doe",
        "company_domain": "acme.com",
    },
    timeout=60,
)
response.raise_for_status()
data = response.json()

if data["success"]:
    print(data["result"]["email"])
else:
    print("No email found. This call was not billed.")

Node.js

const response = await fetch("https://api.richapi.ai/api/v1/email_finder", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    first_name: "John",
    last_name: "Doe",
    company_domain: "acme.com",
  }),
});

const data = await response.json();

if (data.success) {
  console.log(data.result.email);
} else {
  console.log("No email found. This call was not billed.");
}

Which parameters does Email Finder accept?

Every parameter is a string. Every parameter has an empty string as its default. No single parameter is required on its own. The request body must satisfy one accepted input shape.

Parameter	Type	Required	Default	Description
`first_name`	string	Conditional	`""`	The person's first name. Required for the name shape. Example: `John`.
`last_name`	string	Conditional	`""`	The person's last name. Required for the name shape. Example: `Doe`.
`company_domain`	string	Conditional	`""`	The company domain. Required for the name shape. Example: `acme.com`.
`linkedin_url`	string	Conditional	`""`	The person's LinkedIn profile URL. Required for the LinkedIn shape.
`company_name`	string	No	`""`	The company name. It does not replace `company_domain`: a body without `company_domain` or `linkedin_url` returns `400`.

Which input shapes does Email Finder accept?

Shape	Parameters to send	When to use it
Name plus domain	`first_name`, `last_name`, `company_domain`	You know the person's name and the employer's website.
LinkedIn URL	`linkedin_url`	You know only the LinkedIn profile.

RichAPI strips a leading https:// from company_domain. RichAPI also lowercases and trims the domain. If the request body satisfies neither shape, the API returns 400 and names the accepted shapes in the accepted_input_shapes field.

What does Email Finder return?

Email Finder returns 200 for every valid request, both for a hit and for a miss. Read the success field to tell the two apart.

A hit returns this response:

{
  "success": true,
  "result": {
    "email": "[email protected]",
    "email_status": "valid"
  },
  "provider": "provider_a",
  "providers_tried": 1,
  "execution_log": [
    { "provider": "provider_a", "status": "success", "latency_ms": 342 }
  ]
}

A miss returns this response:

{
  "success": false,
  "result": null,
  "provider": null,
  "providers_tried": 2,
  "execution_log": [
    { "provider": "provider_a", "status": "no_data", "latency_ms": 412 },
    { "provider": "provider_b", "status": "no_data", "latency_ms": 688 }
  ],
  "billed": false
}

What does each Email Finder response field mean?

Field	Type	Description
`success`	boolean	`true` when a provider returned an email. `false` when no provider returned an email.
`result`	object or null	The found data. It is `null` when `success` is `false`.
`result.email`	string	The work email address that the successful provider returned.
`result.email_status`	string	The verification status that the successful provider reported for the email.
`provider`	string or null	The brand name of the provider that returned the email, for example `provider_a`. It is `null` on a miss.
`providers_tried`	integer	The number of providers that RichAPI tried for this call.
`execution_log`	array	One entry per provider that RichAPI tried, in the order tried.
`execution_log[].provider`	string	The brand name of that provider.
`execution_log[].status`	string	The outcome for that provider, for example `success`, `no_data`, or `skipped_missing_input`.
`execution_log[].latency_ms`	integer	The time that provider took, in milliseconds.
`billed`	boolean	Present only on a miss. It is always `false`, which confirms that RichAPI charged no credits.
`error`	string	Present only when every provider was unreachable. It explains the refund.

What happens when Email Finder finds no email?

Email Finder returns 200 with "success": false and "billed": false. RichAPI charges 0 credits for that call and releases the credit reservation. Email Finder and Phone Finder are the two places where the general RichAPI rule differs. The general rule is that RichAPI bills every 2xx response. For Email Finder, RichAPI bills a 2xx response only when success is true.

Two different misses exist, and neither one costs a credit.

Outcome	What happened	Response	Credits charged	What to do
Hit	A provider returned an email.	`200`, `success: true`	5	Read `result.email`.
Soft miss	Every provider answered, and none held this person's email.	`200`, `success: false`, `billed: false`	0	Do not send the same request again. Change the input shape, or find the LinkedIn URL first.
Hard miss	Every provider was unreachable, for example a timeout or a `5xx`.	`200`, `success: false`, `billed: false`, plus an `error` field	0	Wait a few minutes, then send the request again.
Invalid input	The request body satisfied no input shape.	`400`	0	Send one of the accepted input shapes.

To tell a soft miss from a hard miss, read the error field. A hard miss carries an error field, and a soft miss does not. A soft miss also shows at least one no_data entry in execution_log.

How does the Email Finder waterfall work?

A waterfall is an ordered list of email data providers. RichAPI sends your input to the first provider in the list. If that provider returns an email, RichAPI stops and returns it. If that provider returns nothing, RichAPI moves to the next provider. RichAPI repeats this until one provider returns an email, or until the list ends.

Three rules follow from that design:

RichAPI charges one flat price of 5 credits, whatever the number of providers tried.
The provider order is fixed. RichAPI selects the providers, and you cannot choose them.
If your input cannot satisfy a provider, RichAPI skips that provider. A LinkedIn-only body skips every name-plus-domain provider.

The providers_tried field and the execution_log array show exactly what happened on your call.

How much does Email Finder cost?

Email Finder costs 5 credits per successful call. One credit costs $0.02 on the 1,000 and 5,000 credit packs, so one successful call costs $0.10 there. Larger packs cost less per credit. A call that finds no email costs 0 credits.

Calls (all successful)	Credits	Cost
1	5	$0.10
100	500	$10.00
1,000	5,000	$100.00
10,000	50,000	$1,000.00

A real list never returns 100% hits. For 1,000 calls at a 60% hit rate, RichAPI bills 600 calls. That is 3,000 credits, or $60.00.

Which errors can Email Finder return?

Status	Meaning	What to do
`400`	The request body satisfied no input shape, or the body was not valid JSON.	Read `accepted_input_shapes` in the response. Send one of those shapes.
`401`	The API key is missing, wrong or revoked.	Send a valid key in the `x-api-key` header.
`403`	`Endpoint not available on your plan`: this API key has no access to this endpoint.	Call `GET /api/v1/my-endpoints` to list the endpoints this key can use. Contact support for access.
`402`	`Insufficient credits`: the organization has too few credits for this call. Or `Monthly spend limit reached`: the team hit its monthly spend limit.	Buy credits in the dashboard, or ask the organization owner to raise the spend limit, then send the request again.
`405`	The request used a method other than `POST`.	Send the request as `POST`.
`429`	Too many requests.	Read the `Retry-After` header. Wait that many seconds, then send the request again.
`500`	The API failed.	Send the request again. If the failure repeats, contact support.

RichAPI charges no credits for any of these errors.

Frequently asked questions

Does Email Finder charge credits when it finds no email?

No. Email Finder charges 5 credits only when the response holds "success": true. A response with "success": false also holds "billed": false, and RichAPI charges 0 credits for it.

Why does Email Finder return status 200 when it finds no email?

Email Finder returns 200 because the request itself was valid and RichAPI served it. The success field, not the HTTP status, reports whether an email was found. Read success in every response.

How accurate is the email that Email Finder returns?

Accuracy depends on the provider that returned the email and on the person's public footprint. The result.email_status field carries the verification status that the provider reported for that address. For an independent check before a send, pass the address to the Email Verifier API.

What is the minimum input for Email Finder?

Email Finder needs one complete input shape. Send first_name, last_name, and company_domain together, or send linkedin_url on its own. A body that holds only a first name returns 400 and costs no credits.

Can I choose which provider Email Finder uses?

No. RichAPI sets the provider order and tries the providers in that fixed order. The response reports the winning provider in the provider field and every attempt in execution_log.

How long does an Email Finder call take?

Email Finder is synchronous, so one HTTP request returns the result. Each provider carries a timeout of 10 to 15 seconds, the whole call has a 25-second budget, and the waterfall stops at the first hit. Set a client timeout of 60 seconds.

Does a repeat lookup for the same person cost credits again?

Yes, unless the call misses. Every successful call costs 5 credits. Cache the result on your side to avoid a repeat charge for the same person.