> For the complete documentation index, see [llms.txt](https://docs.coresignal.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coresignal.com/guides/search-filters-or-elasticsearch-dsl.md). # Choosing How to Search: Search Filters or Elasticsearch DSL Choose Search Filters or Elasticsearch DSL for Coresignal API queries, sorting, and pagination. 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
FeatureSearch FiltersElasticsearch DSL
Best forSimple, everyday searchesComplex, precise, or advanced searches
Learning curveLowModerate
FormatFlat JSON object with named fields (e.g. "industry": "Software Development")Structured Elasticsearch query object (query, bool, must, filter, etc.)
What you get backRecord IDs onlyRecord IDs only
Need a separate Collect step?YesYes
Endpoint pattern.../search/filter.../search/es_dsl or .../semantic_search/es_dsl
AvailabilityOnly on a selection of APIsAvailable across all APIs
CostFree to queryFree to query
Character/clause limitN/A15,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. {% tabs %} {% tab title="cURL" %} {% code title="Find IT companies with search filters" expandable="true" %} ```json 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" } ' ``` {% endcode %} {% endtab %} {% tab title="Python" %} {% code title="Find IT companies with search filters" expandable="true" %} ```python 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() ``` {% endcode %} {% endtab %} {% endtabs %} ### Combining values within a single field Some filters accept `AND` / `OR` operators inside their own value, using parentheses: {% code title="OR operator" expandable="true" %} ```json { "name": "(IT Consulting) OR (IT Security)" } ``` {% endcode %} {% code title="AND operator" expandable="true" %} ```json { "industry": "(Information technology) AND Internet" } ``` {% endcode %} ### Partial matches You can use `*` as a wildcard to match partial values: {% code title="\* wildcard" expandable="true" %} ```json { "name": "Eng*" } ``` {% endcode %} 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: {% code title="json" expandable="true" %} ```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" }' ``` {% endcode %} ### 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 3. Add `?after={x-next-page-after}` to your next request to get the following page. {% code title="Search filters pagination" expandable="true" %} ```json 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" }' ``` {% endcode %} ### 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. {% code title="items per page parameter" expandable="true" %} ```json 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" }' ``` {% endcode %} ### Summary | Pros | Cons | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | | ## 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](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html). 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 {% tabs %} {% tab title="cURL" %} {% code title="Find IT companies with Elasticsearch DSL" expandable="true" %} ```json 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" } } } ] } } }' ``` {% endcode %} {% endtab %} {% tab title="Python" %} {% code title="Find IT companies with Elasticsearch DSL" expandable="true" %} ```python 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() ``` {% endcode %} {% endtab %} {% endtabs %} {% hint style="success" %} #### Need help writing queries? If Search Filters no longer meet your requirements, use Elasticsearch DSL without writing queries manually. Coresignal’s [Agentic Search API](/self-service/features-and-tools/agentic-search-api-playground.md) and the dashboard’s [API playgrounds](/self-service/features-and-tools/api-playgrounds.md) 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. {% endhint %} ### 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 {% tabs %} {% tab title="Sort by \_score" %} {% code title="\_score" expandable="true" %} ```json 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" ] }' ``` {% endcode %} {% endtab %} {% tab title="Sort by id" %} {% code title="id" expandable="true" %} ```json 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" ] }' ``` {% endcode %} {% endtab %} {% endtabs %} 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. {% code title="Elasticsearch pagination" expandable="true" %} ```json 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": {...} }' ``` {% endcode %} ### 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. {% code title="" expandable="true" %} ```json 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": {...} }' ``` {% endcode %} ### [Semantic search](/api-introduction/requests/semantic-search.md) 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 | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | | ## Before you write your first query * [Search Filters](/api-introduction/requests/search-filters.md): confirm the endpoint supports Search Filters, then check its accepted filters and formats. * [Elasticsearch DSL](/api-introduction/requests/elasticsearch-dsl.md): 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.
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.coresignal.com/guides/search-filters-or-elasticsearch-dsl.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.