Lead Generation API Documentation

Overview & Quick Map

The Lead Generation API powers three ways to find a business email, plus reveal, save, list, and delete. Every request authenticates with an API key in the URL path and every POST body is application/json.

Tools 1 and 2 share a single endpoint — the mode is chosen automatically by which fields you send. Tool 3 is asynchronous: you submit a job and poll for the result.

#	Tool	Method(s)	Sync?	Cost
1	Prompt Search — describe the leads you want	POST /leads/search	Sync	5 cr / search
2	LinkedIn Finder — name + company → email	POST /leads/search	Sync	5 cr / search
3	Find by URL — LinkedIn profile URL → email	POST /leads/linkedin-url → poll GET	Async	Free to submit; 5 cr if no match
—	Reveal contact (unmask email/phone)	POST /leads/reveal	Sync	10 cr (first time)
—	Save a lead	POST /leads/save	Sync	Free
—	List saved leads	GET /leads/saved	Sync	Free
—	Delete saved lead	DELETE /leads/saved/{id}	Sync	Free

All responses are JSON. Successful searches return masked contact details plus a token you exchange for the real value via Reveal Contact. Keep the demo experience masked and drive sign-up for the full reveal.

Authentication

Every endpoint takes the API key as the last (or a middle) path segment — no headers, no OAuth. The key identifies the account whose credits are charged.

Endpoint

POST https://client.myemailverifier.com/leads/search/YOUR_API_KEY

An invalid or unknown key returns 401 { "error": "INVALID_API_KEY" }.
The key identifies the account whose credits are charged for each billable call.

Demo key for the public website

For the marketing site's live demo, use the shared, referer-locked demo key:

Demo key

RA48VACZWV0VGA66

Rules for the demo key (enforced server-side)

Only usable from myemailverifier.com (referer-locked — works from www. and any sub-path).
3 searches per visitor IP per day on the URL finder submit endpoint. Polling does not count.
After 3 uses → 429 { "error": "DEMO_LIMIT_REACHED" } — show a “Sign up free to keep searching” CTA.

Never expose a real customer key in browser JavaScript. For anything beyond the demo, proxy calls through your own backend so the key stays server-side. The demo key is safe to use client-side because it is referer-locked and rate-limited.

Credit Costs

You are charged in credits per billable action. Browsing masked results is free — you only spend credits on a search or a reveal.

Action	Credits	Notes
Prompt / LinkedIn search	5	Per search, regardless of result count
Find by URL — submit	0	Free to start; pay on reveal
Find by URL — no match	5	Only when a lookup confirms no address exists
Reveal contact (first time)	10	Per unique contact (email + phone together)
Reveal contact (repeat, within 24h)	0	Free re-reveal of the same token
Save / List / Delete	0	Always free

Reveal tokens expire 24 hours after the search that produced them.

Tool 1 — Prompt Search

Describe the leads you want in plain English and get back a list of matching contacts with masked email and phone.

POST /leads/search/{apikey}

Request body

JSON

{ "prompt": "CTO at fintech companies in Mumbai" }

Field	Type	Required	Notes
`prompt`	string	Yes	5–500 chars. e.g. “HR managers at SaaS startups in London”

cURL

bash

curl -X POST "https://client.myemailverifier.com/leads/search/YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "CTO at fintech companies in Mumbai"}'

Response 200

JSON

{
  "status": true,
  "total": 3,
  "cached": false,
  "sources": ["professional network", "database"],
  "credits_remaining": 4995,
  "data": [
    {
      "company": "PayFast India",
      "website": "payfast.in",
      "source_url": "https://www.linkedin.com/in/example",
      "snippet": "...contextual excerpt from the result...",
      "guessed": false,
      "masked_email": "r*****@payfast.in",
      "email_token": "eyJ0eXAiOi...",
      "masked_phone": "+91 98****3210",
      "phone_token": "eyJ0eXAiOi..."
    }
  ],
  "error": null
}

Display note: masked_email / masked_phone are safe to show. Use the tokens with Reveal Contact to get the full values. Do not surface the raw per-lead source field on public pages — treat the top-level sources array as the user-facing provenance instead. The email_token / phone_token values are internal — use them for reveal only, never display them.

Tool 2 — LinkedIn Finder

Find a specific person by name and company. This is the same endpoint as Prompt Search — sending company plus a name switches it to LinkedIn mode automatically.

POST /leads/search/{apikey}

Request body

JSON

{
  "first_name": "Priya",
  "last_name":  "Mehta",
  "company":    "Infosys",
  "designation":"Data Engineer",
  "location":   "Bangalore",
  "domain":     "infosys.com"
}

Field	Type	Required	Notes
`company`	string	Yes	Company name
`first_name`	string	One of	Send at least one of first / last name
`last_name`	string	One of	Send at least one of first / last name
`designation`	string	—	Job title — improves accuracy
`location`	string	—	City / country — improves accuracy
`domain`	string	—	Company email domain — improves accuracy the most

cURL

bash

curl -X POST "https://client.myemailverifier.com/leads/search/YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Priya","last_name":"Mehta","company":"Infosys","domain":"infosys.com"}'

The response has the same shape as Prompt Search — a data[] array of masked contacts with reveal tokens.

Tool 3 — Find Email from LinkedIn URL Async

Give only a LinkedIn profile URL. Because resolution takes a few seconds, this is a two-step flow: submit → poll.

Step 1 — Submit

POST /leads/linkedin-url/{apikey}

JSON request

{ "linkedin_url": "https://www.linkedin.com/in/username" }

Field	Type	Required	Notes
`linkedin_url`	string	Yes	Public profile URL. Company / school pages are rejected with `422 INVALID_URL`.

Response 202

JSON

{
  "status": true,
  "job_id": 4821,
  "job_status": "processing",
  "poll_url": "https://client.myemailverifier.com/leads/linkedin-url/YOUR_API_KEY/4821",
  "message": "Lookup started. Poll poll_url every ~3s until job_status is \"done\" or \"failed\"."
}

Step 2 — Poll (every ~3 seconds)

GET /leads/linkedin-url/{apikey}/{job_id}

While running

JSON

{ "status": true, "job_id": 4821, "job_status": "processing", "progress": 55 }

Use progress (0–100) to drive a progress bar.

When finished — outcome: "verified"

JSON

{
  "status": true,
  "job_id": 4821,
  "job_status": "done",
  "progress": 100,
  "outcome": "verified",
  "identity": {
    "name": "Marc Benioff",
    "headline": "Chair & CEO",
    "company": "Salesforce.com",
    "location": "San Francisco, California, United States",
    "profile_url": "https://www.linkedin.com/in/username"
  },
  "total": 1,
  "data": [
    {
      "company": "Salesforce.com",
      "linkedin_url": "https://www.linkedin.com/in/username",
      "verification_status": "valid",
      "masked_email": "m***********@salesforce.com",
      "email_token": "eyJ0eXAiOi...",
      "email_format": "firstname.lastname",
      "alternates": [
        { "masked_email": "m*******@salesforce.com", "email_token": "eyJ...", "format": "first-initial + lastname" },
        { "masked_email": "m***@salesforce.com",     "email_token": "eyJ...", "format": "firstname only" }
      ]
    }
  ]
}

When no address can be confirmed — outcome: "not_found"

JSON

{
  "status": true,
  "job_status": "done",
  "outcome": "not_found",
  "identity": { "name": "Jane Doe", "company": "Acme Inc", "location": "London, UK" },
  "total": 0,
  "data": [],
  "message": "We found this person but could not confirm an email address for them."
}

When it errored — job_status: "failed"

JSON

{ "status": true, "job_status": "failed", "progress": 100, "message": "Lookup failed. Please try again." }

`outcome` values

Value	Meaning
`verified`	A deliverable address was confirmed — see `data[0]`.
`catch_all`	The company accepts all mail, so the exact inbox can't be confirmed by a standard check. `verification_status` will be `catch_all`. Offer the Deep Catch-All Check.
`not_found`	No address could be confirmed for this person.

Alternates

Several formats can all be deliverable for one person. The most likely is the primary (masked_email / email_token); the rest are in alternates[], each with a plain-language format label (e.g. “first-initial + lastname”) so the user can pick the one matching their company's convention. Each alternate has its own email_token and is revealed the same way.

Want to see this flow in action? Try the LinkedIn email finder demo — it uses the referer-locked demo key and keeps results masked.

Reveal Contact

Turn an email_token (or phone_token) into the real value. 10 credits the first time per contact; free to re-reveal the same token within 24h.

POST /leads/reveal/{apikey}

JSON request

{ "email_token": "eyJ0eXAiOi...", "phone_token": "eyJ0eXAiOi..." }

Both fields optional, but send at least one. Works for a primary token or any alternate token.

Response 200

JSON

{
  "status": true,
  "email": "[email protected]",
  "phone": "+91 9876543210",
  "already_revealed": false,
  "credits_remaining": 4985
}

already_revealed: true → no credits were charged (repeat reveal).
null for a field means no token was sent for it.

The public demo should not call reveal — keep the demo to masked results and drive sign-up for the full reveal. Reveal spends 10 credits and returns the real address.

Save / List / Delete All free

Bookmark contacts to a saved list, read them back, and remove them. None of these calls consume credits.

Save

POST /leads/save/{apikey}

JSON request

{ "email": "[email protected]", "name": "Marc Benioff", "company": "Salesforce",
  "title": "CEO", "phone": "...", "linkedin_url": "...", "notes": "..." }

email required; everything else optional.

JSON response

{ "status": true, "lead_id": 91, "message": "Lead saved successfully." }

List

GET /leads/saved/{apikey}

JSON response

{
  "status": true,
  "total": 2,
  "data": [
    { "lead_id": 91, "name": "Marc Benioff", "email": "[email protected]",
      "phone": null, "company": "Salesforce", "title": "CEO",
      "linkedin_url": "https://www.linkedin.com/in/username", "notes": null,
      "saved_at": "2026-07-21T09:20:00+00:00" }
  ]
}

Delete

DELETE /leads/saved/{apikey}/{lead_id}

JSON response

{ "status": true, "message": "Lead removed from saved list." }

Error Codes

All error bodies follow the shape { "status": false, "error": "CODE", "message": "...", "http_code": NNN }.

HTTP	`error`	Meaning
400	—	API key missing from the URL
401	`INVALID_API_KEY`	Key wrong or inactive
402	`INSUFFICIENT_CREDITS`	Not enough credits (`credits_needed` + `credits_balance` included)
403	`UNAUTHORIZED_REFERER`	Demo key used from outside myemailverifier.com
404	`JOB_NOT_FOUND` / `NOT_FOUND`	Unknown job id / lead id for this key
422	`INVALID_URL`	LinkedIn URL missing or not a profile URL
422	`INVALID_TOKEN` / `MISSING_TOKEN`	Reveal token bad / expired, or none provided
429	`DEMO_LIMIT_REACHED`	Demo key used its 3 daily searches for this IP
429	—	Burst rate limit (throttle) — slow down
500	`SERVICE_ERROR`	Search backend error (no credits charged)

Rate Limits

Limits are per API key unless noted. Polling is generous so you can drive a live progress bar comfortably.

Endpoint	Limit
POST /leads/search	10 / min per key
POST /leads/linkedin-url (submit)	10 / min per key + demo key: 3 / day / IP
GET /leads/linkedin-url/.../{job_id} (poll)	120 / min (polling is fine)
POST /leads/reveal	60 / min
save / saved / delete	30 / min

Field Reference

Which response fields are safe to display, and which are internal. Follow this table when rendering results on any public-facing page.

Field	Where	Show it?
`masked_email`, `masked_phone`	all searches	Yes
`email_token`, `phone_token`	all searches	Internal — use for reveal only, never display
`email_format`, `alternates[].format`	URL finder	Yes — helps users pick
`identity.{name,headline,company,location}`	URL finder	Yes
`verification_status` (`valid` / `catch_all`)	URL finder	Yes (as a badge)
`sources` (top-level array)	prompt / LinkedIn	Yes (provenance)
`source` (per-lead)	prompt / LinkedIn	Internal — do not display
`progress`	URL finder poll	Yes — drive the progress bar

Keep public demos masked, proxy real keys server-side, and use outcome language only (“verified”, “catch-all”) when describing results. Never display the internal source field or the reveal tokens.

Ready to build? Create an account to get your own API key, or explore the Lead Generation feature page and the LinkedIn email finder.

Lead Generation API Documentation

Overview & Quick Map

Authentication

Demo key for the public website

Rules for the demo key (enforced server-side)

Credit Costs

Tool 1 — Prompt Search

Request body

cURL

Response 200

Tool 2 — LinkedIn Finder

Request body

cURL

Tool 3 — Find Email from LinkedIn URL Async

Step 1 — Submit

Response 202

Step 2 — Poll (every ~3 seconds)

While running

When finished — outcome: "verified"

When no address can be confirmed — outcome: "not_found"

When it errored — job_status: "failed"

outcome values

Alternates

Reveal Contact

Response 200

Save / List / Delete All free

Save

List

Delete

Error Codes

Rate Limits

Field Reference

`outcome` values