Skip to main content

Lead Search

Search the lead database using filters and pagination.

Endpoint​

POST /api/public/search

Authentication​

Use an API key header as described in the Authentication guide.

Request body​

Pagination​

  • _page (default 1)
  • _per_page (default 25)
  • max_results (default 500, max 100000)

Output flags​

  • _include_raw (default true) — include a raw object with original fields
  • include_emails (default true)
  • include_phones (default false)
  • email_status (default all) — all | verified | likely

Filters​

All filter fields and allowed values are listed in Filters.

Response fields​

  • count: number of rows returned in this page
  • preview_count: same as count
  • preview_data: array of lead records
  • page, per_page, total_pages, total_count, has_more, next_page
  • search_id: currently null
  • counting: currently false

Errors​

  • 401 — Missing or invalid API key
  • 402 — Not enough API credits
  • 502 — Lead service error (upstream VPS)
  • 500 — Server error

Examples​

Request​

curl -X POST https://dievio.com/api/public/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "_per_page": 25,
    "_page": 1,
    "max_results": 500,
    "_include_raw": true,
    "job_titles": ["Founder", "CEO"],
    "job_title_seniority": ["owner", "cxo"],
    "person_location_country": ["United States"],
    "include_emails": true,
    "include_phones": true
  }'

Response​

{
  "success": true,
  "count": 25,
  "total_count": 500,
  "preview_count": 25,
  "preview_data": [
    {
      "first_name": "Jane",
      "last_name": "Doe",
      "full_name": "Jane Doe",
      "email_status": "found",
      "phone_status": "not_found",
      "job_title": "CEO",
      "company": "Acme Inc",
      "city": "San Francisco",
      "state": "California",
      "country": "United States",
      "work_email": "jane@acme.com",
      "personal_emails": ["jane@gmail.com"],
      "mobile_phone": null,
      "linkedin_url": "https://www.linkedin.com/in/janedoe",
      "linkedin_status": "found",
      "facebook_status": "not_found",
      "twitter_status": "found"
    }
  ],
  "message": "Search completed.",
  "page": 1,
  "per_page": 25,
  "total_pages": 20,
  "has_more": true,
  "next_page": 2,
  "search_id": null,
  "counting": false,
  "max_results": 500
}

Notes​

  • Credits are deducted for the number of leads returned.
  • If your credit balance is low, the API may return fewer results than requested.
  • total_count is capped by max_results. If a page is full, total_count is reported as max_results; if a page is shorter, it is computed as (page - 1) * per_page + returned_rows.
  • search_id is currently null and counting is false for this endpoint.