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

1. Submit a search job — provide a query and filters (role, location, company size, etc.)
2. Poll job status — the search runs asynchronously; poll until status is done
3. Fetch results — retrieve enriched lead records
4. 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.

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://api.misar.io/mail/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://api.misar.io/mail/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://api.misar.io/mail/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":       "[email protected]",
      "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://api.misar.io/mail/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://api.misar.io/mail/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
}