Lead Finder
Find, enrich, and import verified leads with AI-powered search and Hunter.io integration
Lead Finder
Lead Finder searches the web for prospects that match your criteria, verifies email addresses, enriches contact data, and optionally generates a personalized outreach message — all in one pipeline.
Auth scope: Session cookie (dashboard UI) or API key with leads scope.
How It Works
- Submit a search job — provide a query and filters (role, location, company size, etc.)
- Poll job status — the search runs asynchronously; poll until
statusisdone - Fetch results — retrieve enriched lead records
- Import to Contacts — promote results to the contacts table for use in campaigns
Each result consumed counts against your monthly Lead Credits quota.
Credit System
Lead Finder uses a credit-based quota enforced by the check_lead_credit / consume_lead_credit RPCs in the database.
| Plan | Lead Searches / mo | Lead Results / mo | Overage Rate |
|---|---|---|---|
| Free | 3 | 25 | Not available |
| Pro | 25 | 500 | $0.05 / result |
| Max | 100 | 5,000 | $0.05 / result |
| Enterprise | Unlimited | Unlimited | — |
Credits are only counted against active subscriptions. Trialing or past-due accounts follow Free plan limits.
Overage billing for Lead Results only applies when Allow Overage is enabled in Settings → Billing. When disabled, the API returns 429 once the monthly quota is reached.
Endpoints
| Method | Path | Description |
|---|---|---|
POST | /api/v1/leads/search | Start a new lead search job |
GET | /api/v1/leads/jobs/:id | Poll a job's status and progress |
GET | /api/v1/leads/jobs | List your recent search jobs |
GET | /api/v1/leads/results/:job_id | Fetch results for a completed job |
POST | /api/v1/leads/import | Import lead results into Contacts |
GET | /api/v1/leads/credits | Check remaining Lead Credits |
POST /api/v1/leads/search
Start an async lead search. Returns a job_id — poll GET /api/v1/leads/jobs/:id for completion.
curl -X POST https://mail.misar.io/api/v1/leads/search \
-H "Authorization: Bearer msk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "SaaS founders in India",
"filters": {
"role": "Founder",
"location": "India",
"company_size": "1-50",
"industry": "SaaS"
},
"limit": 50
}'Request Fields
| Field | Type | Required | Notes |
|---|---|---|---|
query | string | ✓ | Natural-language search description |
filters.role | string | — | Job title or role keyword |
filters.location | string | — | City, country, or region |
filters.company_size | string | — | e.g. "1-50", "51-200", "201-1000" |
filters.industry | string | — | Industry vertical |
limit | integer | — | Max results to return (default: 25, max: 500) |
Response
{
"success": true,
"job_id": "a1b2c3d4-...",
"status": "pending",
"created_at": "2026-04-13T10:00:00Z"
}GET /api/v1/leads/jobs/:id
Poll job status. When status is done, fetch results with GET /api/v1/leads/results/:job_id.
curl https://mail.misar.io/api/v1/leads/jobs/a1b2c3d4-... \
-H "Authorization: Bearer msk_YOUR_API_KEY"Response
{
"success": true,
"job": {
"id": "a1b2c3d4-...",
"query": "SaaS founders in India",
"filters": { "role": "Founder", "location": "India" },
"status": "done",
"total_found": 42,
"created_at": "2026-04-13T10:00:00Z",
"completed_at": "2026-04-13T10:00:18Z"
}
}Job Status Values
| Status | Meaning |
|---|---|
pending | Queued, not yet started |
running | Search in progress |
done | Completed — results available |
failed | Error — check error field |
GET /api/v1/leads/results/:job_id
Fetch enriched lead records for a completed job.
curl "https://mail.misar.io/api/v1/leads/results/a1b2c3d4-...?page=1&per_page=25" \
-H "Authorization: Bearer msk_YOUR_API_KEY"Query Parameters
| Param | Default | Notes |
|---|---|---|
page | 1 | Page number |
per_page | 25 | Results per page (max 100) |
enriched_only | false | Return only enriched records |
Response
{
"success": true,
"results": [
{
"id": "r1a2b3c4-...",
"name": "Priya Sharma",
"email": "priya@example.io",
"linkedin_url":"https://linkedin.com/in/priyasharma",
"company": "Acme SaaS",
"role": "Founder & CEO",
"location": "Bengaluru, India",
"source": "hunter",
"enriched": true,
"ai_message": "Hi Priya, I saw Acme SaaS is growing fast — we help founders like you..."
}
],
"pagination": {
"page": 1,
"per_page": 25,
"total": 42,
"total_pages": 2
}
}ai_message is a cached AI-generated outreach opener. Available when the lead has been enriched.
POST /api/v1/leads/import
Import selected lead results into your Contacts table.
curl -X POST https://mail.misar.io/api/v1/leads/import \
-H "Authorization: Bearer msk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"result_ids": ["r1a2b3c4-...", "r2b3c4d5-..."],
"list_id": "optional-contact-list-uuid"
}'Request Fields
| Field | Type | Required | Notes |
|---|---|---|---|
result_ids | string[] | ✓ | Lead result IDs to import |
list_id | string | — | Target contact list UUID |
Response
{
"success": true,
"imported": 2,
"skipped": 0,
"message": "2 leads imported to contacts"
}Duplicate emails are silently skipped (skipped count reflects this).
GET /api/v1/leads/credits
Check your remaining Lead Credits for the current billing period.
curl https://mail.misar.io/api/v1/leads/credits \
-H "Authorization: Bearer msk_YOUR_API_KEY"Response
{
"success": true,
"plan": "pro",
"billing_period": {
"start": "2026-04-01T00:00:00Z",
"end": "2026-04-30T23:59:59Z"
},
"searches": {
"used": 12,
"limit": 25,
"remaining": 13
},
"results": {
"used": 340,
"limit": 500,
"remaining": 160,
"overage_rate":"$0.05 / result"
},
"overage_enabled": false
}