Search API Documentation

This section provides comprehensive details on using the Leadita Search API to find and filter leads from our extensive database.

Overview

The Search API allows you to programmatically query Leadita's database for websites and associated data. You can specify search queries, apply various filters (e.g., technologies, keywords, location), and control the number of results returned. This endpoint supports cursor-based pagination for efficient retrieval of large datasets.

Key Features:

Powerful keyword and phrase searching.
Extensive filtering options (technologies, location, spending, etc.).
Customizable result fields using the `select` parameter.
Efficient cursor-based pagination for large result sets.
Optimized credit usage with 24-hour result caching.

Base URL

All API requests should be made to the following base URL:

API Base URL

https://api.leadita.com

Authentication

All requests to the Leadita API must include an X-API-Key header with your valid API key. If the key is missing or invalid, the API will respond with a 401 Unauthorized error.

You can generate and manage your API keys from your dashboard settings.

HTTP Header

X-API-Key: your_api_key_here

Endpoint

The Search API is accessed via a POST request to the following URL:

POST /v1/leads/search

For subsequent pages, use the next or previous URLs provided in the response. These URLs contain an encoded pagination token.

POST /v1/leads/search/:encoded_token

Request Body Parameters

The following parameters can be included in the JSON request body for the `/v1/leads/search` endpoint.

Parameter	Type	Required/Optional	Description	Example Value(s)
`query`	string	Optional	The main search query string. Required if `slug` is not provided.	`"e-commerce stores"`
`slug`	string	Optional	A unique identifier for a specific pre-defined search. Required if `query` is not provided.	`"saas-companies-in-california"`
`limit`	integer	Optional	The maximum number of results to return. Default is 20.	`20`
`workspace_id`	string	Optional	The ID of the workspace to perform the search within. If not provided, the workspace ID from the API key's context will be used.	`"wk_abcdef123456"`
`language`	string	Optional	The language to filter search results by (e.g., "en", "fr").	`"en"`
`technologies`	array of strings	Optional	A list of technologies to filter websites by.	`["Shopify", "WordPress"]`
`keywords`	array of strings	Optional	A list of keywords to filter websites by.	`["e-commerce", "B2B"]`
`country`	string	Optional	The country to filter websites by.	`"USA"`
`state`	string	Optional	The state to filter websites by.	`"CA"`
`city`	string	Optional	The city to filter websites by.	`"San Francisco"`
`pages`	array of strings	Optional	A list of specific page paths to filter websites by.	`["/pricing", "/careers"]`
`updated_after`	string	Optional	Filter for websites crawled or updated after a specific date and time. Must be in RFC3339 format.	`"2024-01-01T00:00:00Z"`
`spending`	string	Optional	Filter by estimated spending range.	`"100-500"`, `"1000+"`
`select`	array of strings	Optional	A list of fields to return for each result. If not provided, all available fields will be returned. `crawled_at` is always included if `select` is used.	`["url", "title", "crawled_at"]`

Responses

A successful request to the Search API will return a `200 OK` status code with a JSON body containing the search results and pagination tokens.

JSON (200 OK)

{
    "result_id": "sr_1234567890abcdef",
    "total_results": 150,
    "size": 2,
    "results": [
        {
            "id": "web_abc123def456",
            "title": "ExampleTech Solutions - Innovating SaaS",
            "url": "https://www.exampletech.com",
            "snippet": "ExampleTech is a leading SaaS provider offering cloud-based solutions for businesses.",
            "crawled_at": "2024-07-15T10:30:00Z",
            "language": "en",
            "technologies": ["React", "Node.js", "MongoDB"],
            "country": "USA",
            "state": "CA",
            "city": "San Francisco",
            "emails": ["[email protected]"],
            "phones": ["+1-800-555-1234"],
            "social_accounts": ["linkedin: https://linkedin.com/company/exampletech"],
            "keywords": ["SaaS", "cloud solutions", "business software"],
            "spending": 7500.00,
            "score": 95
        },
        {
            "id": "web_ghi789jkl012",
            "title": "Global Innovations Inc. - Enterprise Software",
            "url": "https://www.globalinnovations.net",
            "snippet": "Delivering cutting-edge enterprise software solutions worldwide.",
            "crawled_at": "2024-07-20T14:00:00Z",
            "language": "en",
            "technologies": ["Angular", "Java", "PostgreSQL"],
            "country": "USA",
            "state": "NY",
            "city": "New York",
            "emails": ["[email protected]"],
            "phones": [],
            "social_accounts": ["twitter: https://twitter.com/globalinnovations"],
            "keywords": ["enterprise software", "B2B solutions", "global"],
            "spending": 3500.00,
            "score": 88
        }
    ],
    "filters": {
        "technologies": ["React", "Node.js"],
        "keywords": ["SaaS", "cloud solutions"],
        "country": "USA",
        "state": "NY",
        "city": "",
        "pages": [],
        "updated_after": "2023-06-01T00:00:00Z",
        "spending": "500-2000",
        "select": ["url", "title", "crawled_at"]
    },
    "next": "eyJxdWVyeSI6IlNhYVMgY29tcGFuaWVzIiwibGltaXQiOjIsImxhbmd1YWdlIjoiZW4iLCJ0ZWNobm9sb2dpZXMiOlsiUmVhY3QiLCJOb2RlLmpzIl0sImNvdW50cnkiOiJVU0EiLCJzdGF0ZSI6Ik5ZIiwidXBkYXRlZF9hZnRlciI6IjIwMjMtMDYtMDFUMDA6MDA6MDBaIiwic3BlbmRpbmciOiI1MDAtMjAwMCIsImxhc3RfY3Jhd2xlZF9hdCI6IjIwMjQtMDctMjBUMTQ6MDA6MDBaIn0=",
    "previous": null
}

Error Responses

The API may return the following error codes:

JSON (401 Unauthorized)

{
    "error": "UNAUTHORIZED",
    "message": "Invalid or expired API Key"
}

JSON (429 Too Many Requests)

{
    "error": "TOO_MANY_REQUESTS",
    "message": "You have exceeded your rate limit."
}

Examples

Basic Search Request

This example demonstrates a basic search for leads with a query and a limit on results.

Request Body

{
    "query": "AI startups in California",
    "limit": 5,
    "select": ["url", "title", "emails"]
}

cURL Example

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": 5,
    "select": ["url", "title", "emails"]
  }'

Advanced Search Request

This example shows how to use multiple filtering parameters for a more targeted search.

Request Body

{
    "query": "e-commerce stores",
    "limit": 10,
    "language": "en",
    "technologies": ["Shopify", "Stripe"],
    "country": "Canada",
    "state": "ON",
    "city": "Toronto",
    "updated_after": "2024-01-01T00:00:00Z",
    "spending": "1000-5000"
}

cURL Example

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": "e-commerce stores",
    "limit": 10,
    "language": "en",
    "technologies": ["Shopify", "Stripe"],
    "country": "Canada",
    "state": "ON",
    "city": "Toronto",
    "updated_after": "2024-01-01T00:00:00Z",
    "spending": "1000-5000"
  }'

Search by Pre-defined Slug

Use a pre-defined slug to quickly access specific search configurations.

Request Body

{
    "slug": "fintech-companies-new-york",
    "limit": 5
}

cURL Example

curl -X POST \
  https://api.leadita.com/v1/leads/search \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your_api_key_here' \
  -d '{
    "slug": "fintech-companies-new-york",
    "limit": 5
  }'

Pagination Request

After an initial search, use the `next` or `previous` URLs from the response to fetch subsequent pages.

cURL Example (fetching next page)

curl -X POST 'https://api.leadita.com/v1/leads/search/eyJxdWVyeSI6IlNhYVMgY29tcGFuaWVzIiwibGltaXQiOjIsImxhbmd1YWdlIjoiZW4iLCJ0ZWNobm9sb2dpZXMiOlsiUmVhY3QiLCJOb2RlLmpzIl0sImNvdW50cnkiOiJVU0EiLCJzdGF0ZSI6Ik5ZIiwidXBkYXRlZF9hZnRlciI6IjIwMjMtMDYtMDFUMDA6MDA6MDBaIiwic3BlbmRpbmciOiI1MDAtMjAwMCIsImxhc3RfY3Jhd2xlZF9hdCI6IjIwMjQtMDctMjBUMTQ6MDA6MDBaIn0=' \
  -H 'X-API-Key: your_api_key_here'

Pagination

The Leadita Search API uses cursor-based pagination. Initial search requests are made to /v1/leads/search with a JSON request body. The response will include next and previous URLs if more pages are available.

These next and previous URLs contain an encoded pagination token in the path, which includes information like the last_crawled_at timestamp. To fetch the next or previous page, simply make a POST request to the provided URL. The original request body (query, filters, limit) should be re-sent with the paginated request.

The previous URL will be empty if you are on the first page of results.

Rate Limiting

The Leadita API is subject to rate limiting to ensure fair usage and system stability. For authenticated requests using an API key, the rate limit is 60 requests per minute. If you exceed your rate limit, the API will respond with a 429 Too Many Requests error.

Credit Usage & Caching

Each successful search request consumes lead credits from your account. To optimize credit usage and improve performance, Leadita caches search results for 24 hours. If you make the exact same search request within this 24-hour window, and your credit balance has not increased, the cached results will be returned without consuming additional credits. This ensures that repeated queries for the same data are efficient and cost-effective.

Get Your API Key