Choosing How to Search: Search Filters or Elasticsearch DSL

If you are new to Coresignal's API, one of your first decisions is how to search for data. Two approaches are available:

• Search Filters – a simplified, field-based query format

• Elasticsearch DSL – a more powerful, code-like query language

Both serve the same purpose: they provide a list of record IDs (such as company, employee, or job IDs) that match your criteria. You then use these IDs with Collect or Bulk Collect endpoints to retrieve the complete data records. The main difference lies in the level of control offered and the effort required to achieve your goal. This guide explains these differences clearly, including real query examples for each approach.

Overview

Feature	Search Filters	Elasticsearch DSL
Best for	Simple, everyday searches	Complex, precise, or advanced searches
Learning curve	Low	Moderate
Format	Flat JSON object with named fields (e.g. "industry": "Software Development")	Structured Elasticsearch query object (query, bool, must, filter, etc.)
What you get back	Record IDs only	Record IDs only
Need a separate Collect step?	Yes	Yes
Endpoint pattern	.../search/filter	.../search/es_dsl or .../semantic_search/es_dsl
Availability	Only on a selection of APIs	Available across all APIs
Cost	Free to query	Free to query
Character/clause limit	N/A	15,000 characters, up to 1,024 boolean clauses

Search Filters

Search Filters are designed for users unfamiliar with query syntax. You send a flat JSON object where each key is a filter name (such as industry, country, employees_count_gte) and each value is a search criterion. There is no nesting or query language involved – only fields and values. The response contains matching record IDs, which you then pass to a Collect endpoint to retrieve complete records.

Before crafting a query, review the complete list of supported filters and their correct formats for the specific endpoint. Field names, value types (string, integer, boolean, date), and options can vary across APIs. Using an unsupported filter or an incorrect format will result in a failed request.

Example: Find IT companies

This request returns the IDs of every company where the industry matches "Information technology" and it was created on or after July 1, 2025 and it was last updated on or after July 1, 2026. When you provide multiple fields, Search Filters automatically combines them with AND.

cURL

Find IT companies with search filters

curl -X 'POST' \
  'https://api.coresignal.com/cdapi/v2/company_base/search/filter' \
  -H 'accept: application/json' \
  -H 'apikey: {API key}' \
  -H 'Content-Type: application/json' \
  -d '{
  "industry": "Information technology",
  "created_at_gte": "2025-07-01 00:00:01",
  "last_updated_gte": "2026-07-01 00:00:01"
}
'

Python

Find IT companies with search filters

import requests

url = "https://api.coresignal.com/cdapi/v2/company_base/search/filter"
headers = {
    "accept": "application/json",
    "apikey": "{API key}",
    "Content-Type": "application/json",
}
payload = {
    "industry": "Information technology",
    "created_at_gte": "2025-07-01 00:00:01",
    "last_updated_gte": "2026-07-01 00:00:01",
}

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()

company_ids = response.json()

Combining values within a single field

Some filters accept AND / OR operators inside their own value, using parentheses:

OR operator

{
  "name": "(IT Consulting) OR (IT Security)"
}

AND operator

{
  "industry": "(Information technology) AND Internet"
}

Partial matches

You can use * as a wildcard to match partial values:

* wildcard

{
  "name": "Eng*"
}

This matches "Engineering Solutions," "Engelbert Robotics," and other values beginning with "Eng".

Sorting

By default, Search Filters results are sorted by last_updated and id, both in descending order. For predictable incremental ordering, such as synchronization or data export, add the sort query parameter to sort by id in ascending order:

json

curl -X 'POST' \
  'https://api.coresignal.com/cdapi/v2/company_base/search/filter?sort=id' \
  -H 'accept: application/json' \
  -H 'apikey: {API key}' \
  -H 'Content-Type: application/json' \
  -d '{
  "industry": "Information Technology & Services"
}'

Pagination

A single request typically returns more results than can appear on one page, since the current limit is 1,000 results per page. Coresignal uses cursor-based pagination with the after query parameter instead of traditional page numbers, utilizing a value from the previous response to fetch the next set of results.

1. Send your search request as normal.

2. Check the response headers for:

• x-total-results – total number of matching records

• x-total-pages – total number of pages at the current page size

• x-next-page-after – the cursor value to use for the next page

1. Add ?after={x-next-page-after} to your next request to get the following page.

Search filters pagination

curl -X 'POST' \
  'https://api.coresignal.com/cdapi/v2/company_base/search/filter?after="2026-05-20 15:35:28",40513386' \
  -H 'accept: application/json' \
  -H 'apikey: {API key}' \
  -H 'Content-Type: application/json' \
  -d '{
  "industry": "Information Technology & Services"
}'

Controlling page size

A standard page includes up to 1,000 results, but you can request a lower number of results per page using the items_per_page query parameter.

items per page parameter

curl -X 'POST' \
  'https://api.coresignal.com/cdapi/v2/company_base/search/filter?items_per_page=100' \
  -H 'accept: application/json' \
  -H 'apikey: {API key}' \
  -H 'Content-Type: application/json' \
  -d '{
  "industry": "Information Technology & Services"
}'

Summary

Pros	Cons
No need to know Elasticsearch. Every filter is documented with its own expected format (string, integer, boolean, date). Predefined value lists exist for fields like industry, country, and size, so you know exactly what's available.	Only available on a selection of APIs. You can't mix AND/OR/NOT logic across different fields – only within a single field's own value. You can't exclude something directly (e.g.,"companies NOT in Retail"). No fuzzy matching, ranges of text relevance, or scoring control.

Elasticsearch DSL

Elasticsearch DSL (Domain Specific Language) is Elasticsearch's native query language. Coresignal's search/es_dsl endpoint accepts standard Elasticsearch queries directly, providing full boolean logic, wildcards, fuzzy search, and precise ranges. Every query is built around a query object, and in most cases, the logic resides within a bool block. For the full set of query types and clauses, see the official Elasticsearch query DSL documentation.

Before writing a query, review the supported schema for your chosen endpoint. It lists all available fields and their data types, such as text, keyword, numeric, date, and boolean. Because query clauses vary by field type, understanding a field's type in advance can prevent queries that run but return no results silently.

Equivalent IT company search in Elasticsearch DSL

cURL

Find IT companies with Elasticsearch DSL

curl -X 'POST' \
'https://api.coresignal.com/cdapi/v2/company_base/search/es_dsl' \
  -H 'accept: application/json' \
  -H 'apikey: {API Key}' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": {
    "bool": {
      "must": [
        {
          "match": {
            "industry": "Information Technology"
          }
        }
      ],
      "filter": [
        {
          "term": {
            "deleted": 0
          }
        },
        {
          "range": {
            "created": {
              "gt": "2025-07-01 00:00:00"
            }
          }
        },
        {
          "range": {
            "last_updated": {
              "gt": "2026-07-01 00:00:00"
            }
          }
        }
      ]
    }
  }
}'

Python

Find IT companies with Elasticsearch DSL

import requests

url = "https://api.coresignal.com/cdapi/v2/company_base/search/es_dsl"
headers = {
    "accept": "application/json",
    "apikey": "{API Key}",
    "Content-Type": "application/json",
}
payload = {
    "query": {
        "bool": {
            "must": [
                {
                    "match": {
                        "industry": "Information Technology",
                    },
                },
            ],
            "filter": [
                {
                    "term": {
                        "deleted": 0,
                    },
                },
                {
                    "range": {
                        "created": {
                            "gt": "2025-07-01 00:00:00",
                        },
                    },
                },
                {
                    "range": {
                        "last_updated": {
                            "gt": "2026-07-01 00:00:00",
                        },
                    },
                },
            ],
        },
    },
}

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()

company_ids = response.json()

Need help writing queries?

If Search Filters no longer meet your requirements, use Elasticsearch DSL without writing queries manually. Coresignal’s Agentic Search API and the dashboard’s API playgrounds generate a query from a plain-language prompt. Playgrounds access the latest Elasticsearch DSL schema for available APIs. The generated queries are ready for use in your workflows.

Sorting

Unlike Search Filters, Elasticsearch DSL makes sorting explicit in the query body via a sort array:

• Sort by relevance _score – best match first

• Sort by id – ascending, useful for stable, predictable ordering

Sort by _score

_score

curl -X 'POST' \
'https://api.coresignal.com/cdapi/v2/company_base/search/es_dsl' \
  -H 'accept: application/json' \
  -H 'apikey: {API Key}' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": {
    "bool": {
      "must": [
        {
          "match": {
            "industry": "Information Technology"
          }
        }
      ],
      "filter": [
        {
          "term": {
            "deleted": 0
          }
        },
        {
          "range": {
            "created": {
              "gt": "2025-07-01 00:00:00"
            }
          }
        },
        {
          "range": {
            "last_updated": {
              "gt": "2026-07-01 00:00:00"
            }
          }
        }
      ]
    }
  },
  "sort": [
    "_score"
  ]
}'

Sort by id

id

curl -X 'POST' \
'https://api.coresignal.com/cdapi/v2/company_base/search/es_dsl' \
  -H 'accept: application/json' \
  -H 'apikey: {API Key}' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": {
    "bool": {
      "must": [
        {
          "match": {
            "industry": "Information Technology"
          }
        }
      ],
      "filter": [
        {
          "term": {
            "deleted": 0
          }
        },
        {
          "range": {
            "created": {
              "gt": "2025-07-01 00:00:00"
            }
          }
        },
        {
          "range": {
            "last_updated": {
              "gt": "2026-07-01 00:00:00"
            }
          }
        }
      ]
    }
  },
  "sort": [
    "id"
  ]
}'

If no sort value is specified, the results follow the API's default order, which usually prioritizes freshness, similar to Search Filters.

Pagination

Elasticsearch DSL uses the same cursor-based pagination mechanism as Search Filters:

1. Send your query.

2. Read the response headers: x-total-results, x-total-pages, and x-next-page-after.

3. Add ?after={x-next-page-after} to fetch the next page.

Elasticsearch pagination

curl -X 'POST' \
'https://api.coresignal.com/cdapi/v2/company_base/search/es_dsl?after="2026-08-25",251910' \
  -H 'accept: application/json' \
  -H 'apikey: {API Key}' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": {...}
}'

Controlling page size

Controlling the number of page results functions similarly to Search Filters, using items_per_page, where you can select any value up to 1,000.

curl -X 'POST' \
'https://api.coresignal.com/cdapi/v2/company_base/search/es_dsl?items_per_page=100' \
  -H 'accept: application/json' \
  -H 'apikey: {API Key}' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": {...}
}'

Semantic search version of Elasticsearch DSL

Alongside the standard /search/es_dsl endpoint, Coresignal also provides /semantic_search/es_dsl endpoints. The query format matches standard Elasticsearch DSL. The endpoint applies the query to semantic search data rather than the standard search index.

Summary

Pros	Cons
Full boolean logic (must, should, must_not, filter) across any combination of fields. Wildcard and fuzzy queries for less exact or inconsistent values. Available on every API. Includes all available schema fields. Direct control over sorting and relevance scoring.	Writing queries manually can be challenging. Queries are capped at 15,000 characters, and a single query cannot contain more than 1,024 boolean clauses. Analytics/aggregation features are not supported, even though standard Elasticsearch supports them elsewhere.

Before you write your first query

• Search Filters: confirm the endpoint supports Search Filters, then check its accepted filters and formats.

• Elasticsearch DSL: check the endpoint's schema for available fields and their types.

• You'll need a Collect or Bulk Collect call afterward to turn matching IDs into full records.

• Paginate with ?after={x-next-page-after} from the response header and control page size with ?items_per_page query parameters.

FAQ

Can I combine Search Filters and Elasticsearch DSL?

Not in a single request. Pick one per query, based on what the endpoint supports.

Why did my query return zero results?

Usually, this results from a field-name or type mismatch. Verify the endpoint's supported filters in Search Filters or its schema in Elasticsearch DSL.

Do I always need a Collect call afterward to get the data?

Yes, both methods return IDs only, not the full records.