Search API

Search API Documentation

Discover and filter leads from our extensive database using AI-powered search and advanced filters.

Endpoint

POST /v1/leads/search

Search for leads using natural language queries or advanced filters. Returns a paginated list of matching websites with contact information.

Authentication

Include your API key in the X-API-Key header with every request.

HTTP Header

X-API-Key: your_api_key_here

Request Parameters

Parameter	Type	Required	Description
limit	integer	Optional	Number of results per page (default: 20, max: 100)
language	string	Optional	Filter by website language (e.g., "en", "fr", "es")
select	array	Optional	Specify which fields to return in the response
wrapped_query	string	Optional	A pre-formatted query string that bypasses AI query generation. Uses the DSL syntax (e.g., `@technology(Shopify)`). See Wrapped Query section below for syntax details.

Wrapped Query (wrapped_query)

What is a Wrapped Query?

The wrapped_query parameter allows you to bypass the AI query generation step and provide a pre-formatted query string directly. This gives you full control over the search criteria and eliminates reliance on AI interpretation of natural language queries.

DSL Syntax Reference

The DSL (Domain Specific Language) uses @ prefixed directives. Each line represents an AND condition. Comma-separated values within parentheses represent OR conditions.

Directive	Syntax	Description
Language	@lang()	ISO 639-1 language code (e.g., en, fr, es)
Technology	@technology()	Named tools/technologies (e.g., Shopify, Mailchimp, Stripe)
Offers	@offers()	What they sell/provide (e.g., crm, marketing, legal_service)
Lacks	@lacks()	What they're missing/need (e.g., crm, analytics, seo_structured_data)
Category Uses	@categories_uses()	Software categories they use (e.g., ecommerce, analytics, crm)
Service Type	@service_type()	Business model (e.g., SaaS, Ecommerce, Agency, Realtor)
Country	@country()	ISO3 country code (e.g., USA, CAN, FRA)
State	@state()	2-letter state code (e.g., CA, NY, TX)
Score	@score()	SEO quality score (1-90). Supports operators: >50, less than 80, >70
Spending	@spends()	Ad spending range. Operators: >10000, 5000-50000
Pages	@pages()	Website page paths (e.g., /pricing/, /careers/)
Flags	@flag	Flags: @not_responsive, @not_secure, @missing_sitemap, @missing_schema, @missing_robot, @missing_heading, @missing_description

AND & OR Operators

AND Operator (Multiple Lines)

Each new line in the wrapped query acts as an AND condition. All conditions must be satisfied.

@lang(en)
@technology(Shopify)
@country(USA)
# Result: English-language Shopify stores in the USA

OR Operator (Comma-Separated)

Comma-separated values within parentheses represent OR conditions. At least one of the values must match.

@technology(Shopify,WooCommerce)
@country(USA,Canada)
# Result: Shopify OR WooCommerce stores in the USA OR Canada

Numeric Operators (Range & Comparison)

Use standard comparison operators for numeric filters like score and spending.

@score(>70)          # Score greater than 70
@score(<50)          # Score less than 50
@spends(>10000)      # Spending greater than $10,000
@spends(5000-50000)  # Spending between $5,000 and $50,000

Negation (Exclusion) Syntax

Prefix any directive with ! to exclude or negate it. This adds a MUST_NOT clause to the query.

Negation Syntax	What it Excludes	Example
!@country()	Exclude countries	`!@country(USA)`
!@state()	Exclude states	`!@state(CA)`
!@city()	Exclude cities	`!@city(San Francisco)`
!@technology()	Exclude technologies	`!@technology(Wix)`
!@offers()	Exclude offers/categories	`!@offers(crm)`
!@lacks()	Exclude lacks conditions	`!@lacks(crm)`
!@region()	Exclude regions	`!@region(Africa)`
!@subregion()	Exclude subregions	`!@subregion(Western Europe)`

Negation works with all @ directives. Simply prefix with !.

Complete DSL Examples

DSL Query Examples

# Basic search: Shopify stores in USA with high quality
@lang(en)
@technology(Shopify)
@country(USA)
@score(>70)

# Law firms in California needing CRM
@lang(en)
@offers(legal_service)
@lacks(crm)
@state(CA)

# SaaS companies using analytics with budget
@lang(en)
@service_type(SaaS)
@categories_uses(analytics)
@spends(>10000)

# French restaurants in NY needing SEO
@lang(en)
@offers(italian restaurant)
@state(NY)
@lacks(crm)
@lacks(seo_structured_data)

# Ecommerce sites NOT in USA, NOT using Wix
@lang(en)
@categories_uses(ecommerce)
!@country(USA)
!@technology(Wix)

# Marketing agencies NOT in specific states
@lang(en)
@offers(marketing)
@service_type(Agency)
!@state(CA)
!@state(NY)
!@state(TX)

Available Filters

Refine your search results with these powerful filters. You can use filters alone (without a query) for precise targeting.

Location Filters

country

Filter by country (e.g., "USA", "Canada")

state

Filter by state/province (e.g., "CA", "NY")

city

Filter by city (e.g., "San Francisco")

Technology & Business Filters

technologies

Array of technologies (e.g., ["Shopify", "Stripe", "React"])

keywords

Array of keywords to search for in website content

categories_uses

Array of software categories. Values: "ecommerce", "crm", "analytics", "marketing", "email_marketing", "cms", "payments", "lead_generation", "cybersecurity", "artificial_intelligence", "hosting_server_environment", "cloud_providers", "advertising", "seo_structured_data", "website_builder", "mobile_app", "education", "healthcare", "real_estate", "financial_services", and more

service_type

String - Business type. Values: "Enterprise", "SaaS", "Ecommerce", "Agency", "Local Business", "Firm", "Consultant", "Publisher", "Marketplace", "Mobile App", "Non-Profit", "Education", "Government", "Manufacturer", "Healthcare", "Hospitality", "Financial Services", "Entertainment", "Gaming"

offers

String - Service offered. Values: "advertising", "email_marketing", "lead_generation", "marketing", "seo_structured_data", "social_media_marketing", "crm", "customer_support", "analytics", "artificial_intelligence", "cybersecurity", "cms", "website_builder", "ecommerce", "payments", "booking_calendar", and more

pages

Array of specific page paths to filter by (e.g., ["/pricing", "/careers"])

Contact & Social Filters

has_phone

Boolean - Only return results with phone numbers

has_facebook

Boolean - Has Facebook profile

has_linkedin

Boolean - Has LinkedIn profile

has_twitter

Boolean - Has Twitter/X profile

has_instagram

Boolean - Has Instagram profile

has_youtube

Boolean - Has YouTube channel

has_tiktok

Boolean - Has TikTok profile

has_pinterest

Boolean - Has Pinterest profile

exclude_generic_emails

Boolean - Exclude generic emails (info@, contact@)

Business Filters

spending

Estimated ad spending range string (e.g., "1000-5000", "1000+")

min_spending

Integer - Minimum estimated ad spending

max_spending

Integer - Maximum estimated ad spending

min_score

Integer - Minimum SEO score (0-100)

max_score

Integer - Maximum SEO score (0-100)

updated_after

RFC3339 timestamp - Only recently crawled sites

Technical & SEO Filters

not_secure

Boolean - Filter for sites without HTTPS

missing_sitemap

Boolean - Filter for sites missing a sitemap

missing_schema

Boolean - Filter for sites missing structured data schema

not_responsive

Boolean - Filter for sites that are not mobile responsive

load_time_ms

Filter by page load time in ms (e.g., "<=2000" for fast sites, ">5000" for slow sites)

seo_score

Filter by SEO score (e.g., ">=80" for high-quality sites, "less than 50" for low-quality sites)

Response Format

Successful requests return a 200 OK status with the following JSON structure:

JSON Response

{
  "result_id": "550e8400-e29b-41d4-a716-446655440000",
  "total_results": 1247,
  "size": 20,
  "results": [
    {
      "domain": "example-ai.com",
      "title": "Example AI - Machine Learning Solutions",
      "emails": ["[email protected]", "[email protected]"],
      "phones": ["+1-415-555-0123"],
      "technologies": ["React", "Stripe", "AWS"],
      "country": "USA",
      "state": "CA",
      "city": "San Francisco",
      "crawled_at": "2024-07-20T14:30:00Z"
    }
  ],
  "filters": {
    "technologies": ["React", "Stripe"],
    "country": "USA",
    "state": "CA",
    "has_phone": true
  },
  "next": "/v1/leads/search/eyJzZWFyY2hfaWQiOiI1NTBlODQwMC...",
  "previous": null
}

Available Select Fields

When using the select parameter, you can choose from the following fields:

Field	Description
domain	The website domain
business_name	The business name
title	The page title
description	The page description
emails	Array of email addresses found
phones	Array of phone numbers found
language	The website language
spending	Estimated spending range
country	The country location
state	The state/region location
city	The city location
technologies	Array of technologies used
links	Array of page links found
score	SEO score
social_links	Object containing social media links
crawled_at	When the website was last crawled (always included)
favicon	The website favicon URL

The crawled_at field is always included automatically when using the select parameter.

Examples

AI Search with Filters

Combine natural language queries with filters for precise targeting.

Request Body

{
  "query": "AI startups in California",
  "limit": 20,
  "language": "en",
  "technologies": ["React", "Stripe"],
  "country": "USA",
  "state": "CA",
  "has_phone": true,
  "select": ["domain", "title", "emails", "phones"]
}

cURL

curl -X POST https://api.leadita.com/v1/leads/search \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your_api_key_here' \
  -d '{
    "query": "AI startups in California",
    "limit": 20,
    "technologies": ["React", "Stripe"],
    "has_phone": true
  }'

Filter-Only Search

Search using only filters without a natural language query. Perfect for precise targeting.

Request Body

{
  "keywords": ["pet", "animals"],
  "technologies": ["Shopify", "Klaviyo"],
  "country": "Canada",
  "has_phone": true,
  "limit": 50
}

SEO & Technical Filter Search

Use seo_score with comparison operators (>=80, less than 50) and load_time_ms with up to 2000 to find high-quality, fast websites.

Request Body

{
  "seo_score": ">=80",
  "load_time_ms": "<=2000",
  "not_secure": false,
  "missing_sitemap": false,
  "not_responsive": false,
  "limit": 20
}

cURL

curl -X POST https://api.leadita.com/v1/leads/search \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your_api_key_here' \
  -d '{"seo_score": ">=80", "load_time_ms": "<=2000", "not_secure": false, "missing_sitemap": false, "not_responsive": false, "limit": 20}'

Social Media & Contact Filters

Find businesses that are active on specific social media platforms and have genuine contact information.

Request Body

{
  "technologies": ["Shopify", "WooCommerce"],
  "has_instagram": true,
  "has_facebook": true,
  "has_pinterest": true,
  "exclude_generic_emails": true,
  "country": "Canada",
  "limit": 15
}

Business, Spending & AI Filters

Target businesses based on spending ranges, SEO score, and AI-powered business category filters.

Request Body

{
  "min_spending": 500,
  "max_spending": 10000,
  "min_score": 60,
  "max_score": 100,
  "categories_uses": ["analytics", "crm"],
  "service_type": "SaaS",
  "offers": "crm",
  "limit": 20
}

Wrapped Query DSL Search

Use the wrapped_query parameter to bypass AI generation and provide precise search criteria directly.

Request Body

{
  "wrapped_query": "@lang(en)\n@technology(Shopify)\n@technology(Mailchimp)\n@country(USA)\n@score(>70)",
  "limit": 20
}

cURL

curl -X POST https://api.leadita.com/v1/leads/search \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your_api_key_here' \
  -d '{
    "wrapped_query": "@lang(en)\n@technology(Shopify)\n@country(USA)\n@score(>70)",
    "limit": 20
  }'

Wrapped Query with Negation

Exclude specific criteria using the ! prefix. This example finds law firms in California that need CRM, excluding results from the USA.

Request Body

{
  "wrapped_query": "@lang(en)\n@offers(legal_service)\n@lacks(crm)\n@state(CA)\n!@country(USA)",
  "limit": 20
}

Wrapped Query with OR Conditions

Use comma-separated values for OR conditions. Find Shopify stores that use analytics OR CRM, located in the USA OR Canada.

Request Body

{
  "wrapped_query": "@lang(en)\n@technology(Shopify)\n@categories_uses(analytics,crm)\n@country(USA,Canada)\n@score(>50)",
  "limit": 20
}

Pagination

The API uses cursor-based pagination for efficient navigation through large result sets. Use the next and previous paths from the response.

Next Page Request

cURL

curl -X POST https://api.leadita.com/v1/leads/search/eyJzZWFyY2hfaWQiOiI1NTBlODQwMC... \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your_api_key_here' \
  -d '{}'

Credit Usage

API Call Credit

No credits per search request (regardless of results returned)

Lead Credit

1 credit per lead with email address returned in the results

Get Your API Key