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

All endpoints are served from the MisarReach base URL and require a Bearer token.

Base URL: https://api.misar.io/reach — pass Authorization: Bearer msr_your_key_here on every request.

Discover leads

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). leads is empty when fetch_emails is false.

Request body

querystringbody

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

industrystring[]body

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

locationstring[]body

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

headcount_minnumberbody

Minimum employee headcount filter (positive integer).

headcount_maxnumberbody

Maximum employee headcount filter (positive integer).

technologystring[]body

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

fetch_emailsbooleanbodydefault: false

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

limitnumberbodydefault: 20

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

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
  }'

{
  "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"
    }
  ]
}

Start a search job

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

querystringbodyrequired

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

useAIbooleanbodydefault: false

Enable AI-powered lead enrichment during processing.

filtersobjectbody

Optional structured filters applied alongside the query.

filters.locationstringbody

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

filters.rolestringbody

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

filters.industrystringbody

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

filters.companySizestringbody

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

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
  }'

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

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

Get a search job

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". status values: "pending" | "running" | "completed" | "failed".

Path parameters

jobIdstringpathrequired

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

{
  "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"
  }
}

List leads

GET/api/lead-finder/leads

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

Query parameters

pagenumberquerydefault: 1

Page number (positive integer).

limitnumberquerydefault: 20

Results per page (1–100).

job_idstringquery

Filter by a specific search job UUID.

searchstringquery

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

{
  "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
}

Verify emails

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

emailstringbody

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

emailsstring[]body

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

leadIdstringbody

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

leadIdsstring[]body

Optional UUIDs matching the emails array for batch record updates.

Response fields

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.

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

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

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]"]}'

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

Score leads

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. Scoring runs asynchronously in the background — fetch updated score and score_reason fields from GET /api/lead-finder/leads after a few seconds.

Credits: 1 AI credit per lead scored.

Request body

jobIdstringbody

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

leadIdsstring[]body

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

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

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

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

List lead lists

GET/api/lead-finder/lists

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

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

Create a lead list

POST/api/lead-finder/lists

Creates a new Hunter.io lead list. Returns HTTP 201 Created.

Request body

namestringbodyrequired

List name (1–200 characters, trimmed).

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"}'

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

Lead Finder API

Discover leads

Start a search job

Get a search job

List leads

Verify emails

Score leads

List lead lists

Create a lead list