Email Finder

Find a person's business email address from their full name and their company's domain. Finding is free: no credits are deducted. The candidates are not verified, so check the one you want to use with Single Verification (1 credit) before you send.

Endpoint

POST /api/v1/finder/person

Request

Headers

Header	Required	Description
Content-Type	Yes	Must be application/json
X-API-Key	Yes	Your live ClearBounce API key (cb_live_). Sandbox keys can't call this endpoint.

Body

{
  "name": "Jane Porter",
  "domain": "northwindtraders.com"
}

Field	Type	Required	Description
name	string	Yes	The person's full name, 1 to 120 characters
domain	string	Yes	The company domain, for example northwindtraders.com

Response

Success Response

{
  "status": "found",
  "email": "jane.porter@northwindtraders.com",
  "confidence": 92,
  "pattern": null,
  "candidates": [
    "jporter@northwindtraders.com",
    "jane@northwindtraders.com"
  ],
  "seen_at_company": [
    "sales@northwindtraders.com",
    "m.chen@northwindtraders.com"
  ]
}

Field	Type	Description
status	string	found when the address was found in published sources. pattern means no published address was found, and email and candidates are guesses based on common address patterns.
email	string or null	The most likely address
confidence	number or null	Confidence in email, from 0 to 100
pattern	string or null	The address pattern the company uses, when it could be detected
candidates	string[]	Other possible addresses, most likely first
seen_at_company	string[]	Addresses already published at this domain, which show how the company formats addresses

A lookup can take up to about a minute for domains that need more sources checked, so allow a long request timeout.

Error Responses

Status	Code	When
400	VALIDATION_ERROR	name or domain is missing or too long
401	UNAUTHORIZED	The API key is missing, invalid or revoked
402	INSUFFICIENT_CREDITS	The account has no credits left. Lookups are free but need a positive balance.
403	SANDBOX_KEY_NOT_ALLOWED	A sandbox (cb_test_) key was used
502 / 503 / 504	FINDER_ERROR / FINDER_UNAVAILABLE / FINDER_TIMEOUT	The finder couldn't complete the lookup. Try again later.

See Errors for the error response format.

Example

curl -X POST https://api.clearbounce.net/api/v1/finder/person \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"name": "Jane Porter", "domain": "northwindtraders.com"}'

Find, then verify

const headers = { 'Content-Type': 'application/json', 'X-API-Key': 'YOUR_API_KEY' };

const found = await fetch('https://api.clearbounce.net/api/v1/finder/person', {
  method: 'POST',
  headers,
  body: JSON.stringify({ name: 'Jane Porter', domain: 'northwindtraders.com' })
}).then(r => r.json());

// Verify candidates one at a time and stop at the first deliverable one (1 credit each)
for (const email of [found.email, ...found.candidates].filter(Boolean)) {
  const { data } = await fetch('https://api.clearbounce.net/api/v1/verify', {
    method: 'POST',
    headers,
    body: JSON.stringify({ email })
  }).then(r => r.json());

  if (data.status === 'deliverable') {
    console.log(`Use ${email}`);
    break;
  }
}