API reference / Find email

Find email

Find the most likely deliverable address for a person at a company domain, one at a time, as a batch, or as a background job. You are charged only when a usable address is returned.

POST/v1/finderFind one email. POST /v1/finder/single (or /v1/finder)POST/v1/finder/batchFind many emails in ONE request (tenant integration). POST /v1/finder/batch Body: { "contacts": [ { "first_name", "last_name", "domain" }, … ] } (max 100). Synchronous, like /v1/verify/batch POST/v1/finder/jobs GET/v1/finder/jobsList the caller's bulk-finder jobs (paginated). GET /v1/finder/jobs POST/v1/finder/singleFind one email. POST /v1/finder/single (or /v1/finder)

POST/v1/finder

Find one email. POST /v1/finder/single (or /v1/finder)

Request body application/json

Field	Type	Required
firstName	string · null	optional
lastName	string · null	optional
domain	string · null	optional

Response 200 · inside data

Field	Type	Description	Example
email	string · null	The found email address, or null when nothing usable was found.	"[email protected]"
status	string · null	Whether an address was returned: `Found` or `Not Found`.	"Found"
quality	string · null	Send-readiness of the found address: `Good`, `Risky`, or `Bad`.	"Good"
result	string · null	`Ok` (verified deliverable), `Catch-all` (the domain accepts it), or `Unknown`.	"Ok"
reason	string · null	Internal reason for the outcome, e.g. `found`, `catch_all`, `not_found`, `unsupported_free_domain`.	"found"
confidence	integer · int32	Confidence in the format for this person on this domain, 0 to 100.	92
provider	string · null	The domain's mailbox provider when detected, e.g. `google`, `microsoft`. Empty otherwise.	"google"
creditsCharged	integer · int32	Credits charged for this call: `10` when an email is returned, `0` on a miss.	10
creditsRemaining	integer · int64	Your remaining credit balance after this call.	48200

Returns 401, 402 with the error envelope { status, error: { code, message } }. Branch on the numeric error.code, never the message.

Request

curl -X POST "https://api.primeverifier.com/v1/finder" \
  -H "X-API-KEY: pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Doe",
    "domain": "acme.com"
  }'

const res = await fetch("https://api.primeverifier.com/v1/finder", {
  method: "POST",
  headers: {
    "X-API-KEY": "pk_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "firstName": "Jane",
    "lastName": "Doe",
    "domain": "acme.com"
  }),
});
const data = await res.json();
console.log(data);

import requests

res = requests.post(
    "https://api.primeverifier.com/v1/finder",
    headers={"X-API-KEY": "pk_live_your_api_key"},
    json={"firstName": "Jane", "lastName": "Doe", "domain": "acme.com"},
)
print(res.json())

using var client = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Post, "https://api.primeverifier.com/v1/finder");
req.Headers.Add("X-API-KEY", "pk_live_your_api_key");
req.Content = new StringContent("{\"firstName\":\"Jane\",\"lastName\":\"Doe\",\"domain\":\"acme.com\"}",
    Encoding.UTF8, "application/json");
var res = await client.SendAsync(req);
Console.WriteLine(await res.Content.ReadAsStringAsync());

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.primeverifier.com/v1/finder"))
    .header("X-API-KEY", "pk_live_your_api_key")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"firstName\":\"Jane\",\"lastName\":\"Doe\",\"domain\":\"acme.com\"}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

$ch = curl_init("https://api.primeverifier.com/v1/finder");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => ["X-API-KEY: pk_live_your_api_key", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => json_encode(["firstName" => "Jane", "lastName" => "Doe", "domain" => "acme.com"]),
]);
$response = curl_exec($ch);
echo $response;

body := strings.NewReader(`{"firstName":"Jane","lastName":"Doe","domain":"acme.com"}`)
req, _ := http.NewRequest("POST", "https://api.primeverifier.com/v1/finder", body)
req.Header.Set("X-API-KEY", "pk_live_your_api_key")
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
out, _ := io.ReadAll(res.Body)
fmt.Println(string(out))

require "net/http"
require "json"

uri = URI("https://api.primeverifier.com/v1/finder")
req = Net::HTTP::Post.new(uri)
req["X-API-KEY"] = "pk_live_your_api_key"
req["Content-Type"] = "application/json"
req.body = { firstName: "Jane", lastName: "Doe", domain: "acme.com" }.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

Response200 OK

{
  "status": "success",
  "data": {
    "email": "[email protected]",
    "status": "Found",
    "quality": "Good",
    "result": "Ok",
    "reason": "found",
    "confidence": 92,
    "provider": "google",
    "creditsCharged": 10,
    "creditsRemaining": 48200
  },
  "error": null
}

Try itPOST /v1/finder

API key *

Request body (JSON)

Runs a real request against api.primeverifier.com. A decisive verification may use 1 credit.

POST/v1/finder/batch

Find many emails in ONE request (tenant integration). POST /v1/finder/batch Body: { "contacts": [ { "first_name", "last_name", "domain" }, … ] } (max 100). Synchronous, like /v1/verify/batch

Request body application/json

Field	Type	Required	Description
contacts	FinderRequest[]	optional

Returns 400, 402 with the error envelope { status, error: { code, message } }. Branch on the numeric error.code, never the message.

Request

curl -X POST "https://api.primeverifier.com/v1/finder/batch" \
  -H "X-API-KEY: pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {
        "firstName": "Jane",
        "lastName": "Doe",
        "domain": "acme.com"
      }
    ]
  }'

const res = await fetch("https://api.primeverifier.com/v1/finder/batch", {
  method: "POST",
  headers: {
    "X-API-KEY": "pk_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "contacts": [
      {
        "firstName": "Jane",
        "lastName": "Doe",
        "domain": "acme.com"
      }
    ]
  }),
});
const data = await res.json();
console.log(data);

import requests

res = requests.post(
    "https://api.primeverifier.com/v1/finder/batch",
    headers={"X-API-KEY": "pk_live_your_api_key"},
    json={"contacts": [{"firstName": "Jane", "lastName": "Doe", "domain": "acme.com"}]},
)
print(res.json())

using var client = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Post, "https://api.primeverifier.com/v1/finder/batch");
req.Headers.Add("X-API-KEY", "pk_live_your_api_key");
req.Content = new StringContent("{\"contacts\":[{\"firstName\":\"Jane\",\"lastName\":\"Doe\",\"domain\":\"acme.com\"}]}",
    Encoding.UTF8, "application/json");
var res = await client.SendAsync(req);
Console.WriteLine(await res.Content.ReadAsStringAsync());

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.primeverifier.com/v1/finder/batch"))
    .header("X-API-KEY", "pk_live_your_api_key")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"contacts\":[{\"firstName\":\"Jane\",\"lastName\":\"Doe\",\"domain\":\"acme.com\"}]}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

$ch = curl_init("https://api.primeverifier.com/v1/finder/batch");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => ["X-API-KEY: pk_live_your_api_key", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => json_encode(["contacts" => [["firstName" => "Jane", "lastName" => "Doe", "domain" => "acme.com"]]]),
]);
$response = curl_exec($ch);
echo $response;

body := strings.NewReader(`{"contacts":[{"firstName":"Jane","lastName":"Doe","domain":"acme.com"}]}`)
req, _ := http.NewRequest("POST", "https://api.primeverifier.com/v1/finder/batch", body)
req.Header.Set("X-API-KEY", "pk_live_your_api_key")
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
out, _ := io.ReadAll(res.Body)
fmt.Println(string(out))

require "net/http"
require "json"

uri = URI("https://api.primeverifier.com/v1/finder/batch")
req = Net::HTTP::Post.new(uri)
req["X-API-KEY"] = "pk_live_your_api_key"
req["Content-Type"] = "application/json"
req.body = { contacts: [{ firstName: "Jane", lastName: "Doe", domain: "acme.com" }] }.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

Response200 OK

{
  "status": "success",
  "data": {},
  "error": null
}

Try itPOST /v1/finder/batch

API key *

Request body (JSON)

Runs a real request against api.primeverifier.com. A decisive verification may use 1 credit.

POST/v1/finder/jobs

Returns 400 with the error envelope { status, error: { code, message } }. Branch on the numeric error.code, never the message.

Request

curl -X POST "https://api.primeverifier.com/v1/finder/jobs" \
  -H "X-API-KEY: pk_live_your_api_key"

const res = await fetch("https://api.primeverifier.com/v1/finder/jobs", {
  method: "POST",
  headers: {
    "X-API-KEY": "pk_live_your_api_key",
  },
});
const data = await res.json();
console.log(data);

import requests

res = requests.post(
    "https://api.primeverifier.com/v1/finder/jobs",
    headers={"X-API-KEY": "pk_live_your_api_key"},
)
print(res.json())

using var client = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Post, "https://api.primeverifier.com/v1/finder/jobs");
req.Headers.Add("X-API-KEY", "pk_live_your_api_key");
var res = await client.SendAsync(req);
Console.WriteLine(await res.Content.ReadAsStringAsync());

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.primeverifier.com/v1/finder/jobs"))
    .header("X-API-KEY", "pk_live_your_api_key")
    .method("POST", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

$ch = curl_init("https://api.primeverifier.com/v1/finder/jobs");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => ["X-API-KEY: pk_live_your_api_key"],
]);
$response = curl_exec($ch);
echo $response;

req, _ := http.NewRequest("POST", "https://api.primeverifier.com/v1/finder/jobs", nil)
req.Header.Set("X-API-KEY", "pk_live_your_api_key")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
out, _ := io.ReadAll(res.Body)
fmt.Println(string(out))

require "net/http"
require "json"

uri = URI("https://api.primeverifier.com/v1/finder/jobs")
req = Net::HTTP::Post.new(uri)
req["X-API-KEY"] = "pk_live_your_api_key"
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

Try itPOST /v1/finder/jobs

API key *

Runs a real request against api.primeverifier.com. A decisive verification may use 1 credit.

GET/v1/finder/jobs

List the caller's bulk-finder jobs (paginated). GET /v1/finder/jobs

Parameters

Name	In	Type	Required	Description
page	query	integer · int32	optional
pageSize	query	integer · int32	optional

Request

curl -X GET "https://api.primeverifier.com/v1/finder/jobs?page=string&pageSize=string" \
  -H "X-API-KEY: pk_live_your_api_key"

const res = await fetch("https://api.primeverifier.com/v1/finder/jobs?page=string&pageSize=string", {
  method: "GET",
  headers: {
    "X-API-KEY": "pk_live_your_api_key",
  },
});
const data = await res.json();
console.log(data);

import requests

res = requests.get(
    "https://api.primeverifier.com/v1/finder/jobs?page=string&pageSize=string",
    headers={"X-API-KEY": "pk_live_your_api_key"},
)
print(res.json())

using var client = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Get, "https://api.primeverifier.com/v1/finder/jobs?page=string&pageSize=string");
req.Headers.Add("X-API-KEY", "pk_live_your_api_key");
var res = await client.SendAsync(req);
Console.WriteLine(await res.Content.ReadAsStringAsync());

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.primeverifier.com/v1/finder/jobs?page=string&pageSize=string"))
    .header("X-API-KEY", "pk_live_your_api_key")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

$ch = curl_init("https://api.primeverifier.com/v1/finder/jobs?page=string&pageSize=string");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => ["X-API-KEY: pk_live_your_api_key"],
]);
$response = curl_exec($ch);
echo $response;

req, _ := http.NewRequest("GET", "https://api.primeverifier.com/v1/finder/jobs?page=string&pageSize=string", nil)
req.Header.Set("X-API-KEY", "pk_live_your_api_key")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
out, _ := io.ReadAll(res.Body)
fmt.Println(string(out))

require "net/http"
require "json"

uri = URI("https://api.primeverifier.com/v1/finder/jobs?page=string&pageSize=string")
req = Net::HTTP::Get.new(uri)
req["X-API-KEY"] = "pk_live_your_api_key"
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

Response200 OK

{
  "status": "success",
  "data": {},
  "error": null
}

Try itGET /v1/finder/jobs

API key *

page (query)

pageSize (query)

POST/v1/finder/single

Find one email. POST /v1/finder/single (or /v1/finder)

Request body application/json

Field	Type	Required
firstName	string · null	optional
lastName	string · null	optional
domain	string · null	optional

Response 200 · inside data

Field	Type	Description	Example
email	string · null	The found email address, or null when nothing usable was found.	"[email protected]"
status	string · null	Whether an address was returned: `Found` or `Not Found`.	"Found"
quality	string · null	Send-readiness of the found address: `Good`, `Risky`, or `Bad`.	"Good"
result	string · null	`Ok` (verified deliverable), `Catch-all` (the domain accepts it), or `Unknown`.	"Ok"
reason	string · null	Internal reason for the outcome, e.g. `found`, `catch_all`, `not_found`, `unsupported_free_domain`.	"found"
confidence	integer · int32	Confidence in the format for this person on this domain, 0 to 100.	92
provider	string · null	The domain's mailbox provider when detected, e.g. `google`, `microsoft`. Empty otherwise.	"google"
creditsCharged	integer · int32	Credits charged for this call: `10` when an email is returned, `0` on a miss.	10
creditsRemaining	integer · int64	Your remaining credit balance after this call.	48200

Returns 401, 402 with the error envelope { status, error: { code, message } }. Branch on the numeric error.code, never the message.

Request

curl -X POST "https://api.primeverifier.com/v1/finder/single" \
  -H "X-API-KEY: pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Doe",
    "domain": "acme.com"
  }'

const res = await fetch("https://api.primeverifier.com/v1/finder/single", {
  method: "POST",
  headers: {
    "X-API-KEY": "pk_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "firstName": "Jane",
    "lastName": "Doe",
    "domain": "acme.com"
  }),
});
const data = await res.json();
console.log(data);

import requests

res = requests.post(
    "https://api.primeverifier.com/v1/finder/single",
    headers={"X-API-KEY": "pk_live_your_api_key"},
    json={"firstName": "Jane", "lastName": "Doe", "domain": "acme.com"},
)
print(res.json())

using var client = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Post, "https://api.primeverifier.com/v1/finder/single");
req.Headers.Add("X-API-KEY", "pk_live_your_api_key");
req.Content = new StringContent("{\"firstName\":\"Jane\",\"lastName\":\"Doe\",\"domain\":\"acme.com\"}",
    Encoding.UTF8, "application/json");
var res = await client.SendAsync(req);
Console.WriteLine(await res.Content.ReadAsStringAsync());

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.primeverifier.com/v1/finder/single"))
    .header("X-API-KEY", "pk_live_your_api_key")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"firstName\":\"Jane\",\"lastName\":\"Doe\",\"domain\":\"acme.com\"}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

$ch = curl_init("https://api.primeverifier.com/v1/finder/single");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => ["X-API-KEY: pk_live_your_api_key", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => json_encode(["firstName" => "Jane", "lastName" => "Doe", "domain" => "acme.com"]),
]);
$response = curl_exec($ch);
echo $response;

body := strings.NewReader(`{"firstName":"Jane","lastName":"Doe","domain":"acme.com"}`)
req, _ := http.NewRequest("POST", "https://api.primeverifier.com/v1/finder/single", body)
req.Header.Set("X-API-KEY", "pk_live_your_api_key")
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
out, _ := io.ReadAll(res.Body)
fmt.Println(string(out))

require "net/http"
require "json"

uri = URI("https://api.primeverifier.com/v1/finder/single")
req = Net::HTTP::Post.new(uri)
req["X-API-KEY"] = "pk_live_your_api_key"
req["Content-Type"] = "application/json"
req.body = { firstName: "Jane", lastName: "Doe", domain: "acme.com" }.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

Response200 OK

{
  "status": "success",
  "data": {
    "email": "[email protected]",
    "status": "Found",
    "quality": "Good",
    "result": "Ok",
    "reason": "found",
    "confidence": 92,
    "provider": "google",
    "creditsCharged": 10,
    "creditsRemaining": 48200
  },
  "error": null
}

Try itPOST /v1/finder/single

API key *

Request body (JSON)

Runs a real request against api.primeverifier.com. A decisive verification may use 1 credit.