Misar IO Docs

Lead Finder API

REST endpoints for discovering, searching, verifying, scoring, and managing leads — all under api.misar.io/reach.

Base URL

https://api.misar.io/reach

All endpoints require a Bearer token:

Authorization: Bearer msr_your_key_here

POST /api/lead-finder/discover

Discovers companies matching the given criteria using the Hunter.io Discover endpoint, then optionally fetches contact emails for each discovered company.

This endpoint is synchronous and returns immediately with results (unlike /search, which is async).

Request body

querystring

Free-text search query describing the target companies (max 500 characters). Example: "Series A fintech startups in Southeast Asia".

industrystring[]

Array of industry filters (max 10 items, 100 characters each). Example: ["SaaS", "Fintech"].

locationstring[]

Array of location filters (max 10 items, 100 characters each). Example: ["India", "Singapore"].

headcount_minnumber

Minimum employee headcount filter (positive integer).

headcount_maxnumber

Maximum employee headcount filter (positive integer).

technologystring[]

Technologies the company uses (max 10 items). Example: ["React", "AWS"].

fetch_emailsbooleandefault: false

When true, fetches contact emails for up to the first 5 discovered companies (up to 10 total leads). Consumes additional API credits.

limitnumberdefault: 20

Maximum number of companies to return (1–100).

Response

{
  "companies": [
    {
      "name": "Acme Corp",
      "domain": "acmecorp.io",
      "industry": "SaaS",
      "headcount": 42
    }
  ],
  "leads": [
    {
      "name": "Jane Doe",
      "email": "[email protected]",
      "company": "Acme Corp",
      "role": "CTO",
      "domain": "acmecorp.io"
    }
  ]
}

leads is empty when fetch_emails is false.

Example

curl -X POST https://api.misar.io/reach/api/lead-finder/discover \
  -H "Authorization: Bearer msr_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "industry": ["SaaS"],
    "location": ["India"],
    "headcount_min": 10,
    "headcount_max": 100,
    "fetch_emails": true,
    "limit": 10
  }'

POST /api/lead-finder/search

Creates an asynchronous lead search job using a natural-language query. Returns a jobId immediately (HTTP 202). Poll GET /api/lead-finder/jobs/:jobId for status and results.

Credits

  • 1 credit per search (deducted from wallet)
  • Free plan: 25 searches per month before credits are required

Request body

querystringrequired

Natural-language description of target leads (2–200 characters, trimmed). Example: "CTOs at B2B SaaS startups with 10-50 employees in India".

useAIbooleandefault: false

Enable AI-powered lead enrichment during processing.

filtersobject

Optional structured filters applied alongside the query.

filters.locationstring

Target geography (max 100 characters). Example: "India".

filters.rolestring

Target job title or function (max 100 characters). Example: "CTO".

filters.industrystring

Target industry (max 100 characters). Example: "B2B SaaS".

filters.companySizestring

Company size range (max 50 characters). Example: "10-50".

Response

{ "jobId": "550e8400-e29b-41d4-a716-446655440000" }

HTTP status 202 Accepted.

Credit exhaustion (429)

{
  "error": "Free-plan monthly search limit reached (25/mo). Upgrade or top up credits to keep searching.",
  "balance": 0,
  "freeRemaining": 0,
  "upgrade": true
}

Example

curl -X POST https://api.misar.io/reach/api/lead-finder/search \
  -H "Authorization: Bearer msr_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Founders at fintech startups in Southeast Asia",
    "filters": { "location": "Southeast Asia", "industry": "Fintech" },
    "useAI": true
  }'

GET /api/lead-finder/jobs/:jobId

Returns the status and metadata for a lead search job. Poll this endpoint until status is "completed" or "failed".

Path parameters

jobIdstringrequired

UUID of the search job returned by POST /api/lead-finder/search.

Response

{
  "job": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "query": "Founders at fintech startups in Southeast Asia",
    "filters": { "location": "Southeast Asia" },
    "result_count": 42,
    "created_at": "2026-05-21T10:00:00Z"
  }
}

status values: "pending" | "running" | "completed" | "failed"

GET /api/lead-finder/leads

Returns saved leads for the authenticated user, optionally filtered by job or search term.

Query parameters

pagenumberdefault: 1

Page number (positive integer).

limitnumberdefault: 20

Results per page (1–100).

job_idstring

Filter by a specific search job UUID.

searchstring

Free-text filter on name, email, or company (max 100 characters). Case-insensitive.

Response

{
  "leads": [
    {
      "id": "uuid",
      "name": "Priya Sharma",
      "email": "[email protected]",
      "role": "CTO",
      "company": "Acme Corp",
      "linkedin_url": "https://linkedin.com/in/priyasharma",
      "location": "Bangalore, India",
      "source": "hunter",
      "enriched": true,
      "score": 87,
      "score_reason": "Senior technical decision-maker at a growth-stage company in target market.",
      "verify_status": "valid",
      "ai_message": "Hi Priya, ...",
      "created_at": "2026-05-21T10:00:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 20
}

POST /api/lead-finder/verify

Verifies email deliverability for one or a batch of emails (max 20 per request) using Hunter.io. Updates verify_status and verify_score on matching lead_finder_results rows.

Credits

1 verification credit per email.

Request body (single)

{
  "email": "[email protected]",
  "leadId": "optional-uuid"
}

Request body (batch)

{
  "emails": ["[email protected]", "[email protected]"],
  "leadIds": ["optional-uuid-1", "optional-uuid-2"]
}
emailstring

Single email to verify. Use either email or emails — not both.

emailsstring[]

Batch of emails to verify (1–20 items). Each must be a valid email address.

leadIdstring

Optional UUID of the lead record to update with the verification result.

leadIdsstring[]

Optional UUIDs matching the emails array for batch record updates.

Response

{
  "results": [
    { "email": "[email protected]", "status": "valid", "score": 98, "pending": false },
    { "email": "[email protected]",  "status": "risky", "score": 54, "pending": false }
  ],
  "verified": 2
}
results[].statusstring

Email status from Hunter.io: "valid" | "risky" | "invalid" | "unknown". null when still pending.

results[].scorenumber

Deliverability confidence score (0–100). null when pending.

results[].pendingboolean

true when Hunter.io responded with 202 (still verifying asynchronously). Re-call after a delay.

verifiednumber

Count of emails that returned a non-pending result.

Example

curl -X POST https://api.misar.io/reach/api/lead-finder/verify \
  -H "Authorization: Bearer msr_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["[email protected]", "[email protected]"]}'

POST /api/lead-finder/score

AI-scores leads in the background. Accepts either a jobId (scores all unscored results for that job) or an array of leadIds (selective scoring or rescoring). Returns immediately with the count of leads queued.

Credits

1 AI credit per lead scored.

Request body (by job)

{ "jobId": "550e8400-e29b-41d4-a716-446655440000" }

Request body (by lead IDs)

{
  "leadIds": ["uuid-1", "uuid-2", "uuid-3"]
}
jobIdstring

UUID of a completed search job. Scores all unscored results (max 200). Mutually exclusive with leadIds.

leadIdsstring[]

Array of lead UUIDs to score or rescore (1–200). Mutually exclusive with jobId.

Response

{
  "scored": 42,
  "status": "scoring_started"
}

Scoring runs asynchronously in the background. Fetch updated score and score_reason fields from GET /api/lead-finder/leads after a few seconds.

GET /api/lead-finder/lists

Returns all Hunter.io lead lists associated with your account.

Response

{
  "lists": [
    { "id": 12345, "name": "India CTOs — May 2026", "leads_count": 87 }
  ]
}

POST /api/lead-finder/lists

Creates a new Hunter.io lead list.

Request body

namestringrequired

List name (1–200 characters, trimmed).

Response

{
  "list": { "id": 12346, "name": "SEA Founders — Q2 2026" }
}

HTTP status 201 Created.

Example

curl -X POST https://api.misar.io/reach/api/lead-finder/lists \
  -H "Authorization: Bearer msr_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "SEA Founders — Q2 2026"}'

On this page

Base URLPOST /api/lead-finder/discoverRequest bodyResponseExamplePOST /api/lead-finder/searchCreditsRequest bodyResponseCredit exhaustion (429)ExampleGET /api/lead-finder/jobs/:jobIdPath parametersResponseGET /api/lead-finder/leadsQuery parametersResponsePOST /api/lead-finder/verifyCreditsRequest body (single)Request body (batch)ResponseExamplePOST /api/lead-finder/scoreCreditsRequest body (by job)Request body (by lead IDs)ResponseGET /api/lead-finder/listsResponsePOST /api/lead-finder/listsRequest bodyResponseExample