How to build a Search Query

A Search query is simply a collection of filters and rules that indicate the relation between those filters.

Search filters

A search filter is a set of criteria used to refine search results within the Veridion database. It specifies the data attributes, the relation used for searching, and the values to be considered when querying the database.

In the context of the Search API, search filters are used to query a database of companies and their products or services, based on various company and product / service-related attributes.

Filter structure and syntax

Each filter must include the base fields below:

📘

Note

Some filters will include additional fields and options to be considered when running a search, specific to their respective attribute.

These specifics are documented under each filter, in the Search filters section.

Filter example

In the search filter Company NAICS code (company_naics_code):

{
   "attribute": "company_naics_code",
   "relation": "equals",
   "value": "541512"
}

The filter can be broken down as follows:

• attribute is set to: company_naics_code

This is a search filter which refers to the NAICS (North American Industry Classification System) code assigned to the company.

• relation is set to: equals

This indicates that the filter is looking for companies with a NAICS code that exactly matches the specified value.

• value is set to: 541512

This represents the NAICS code that is specifically queried ("Computer Systems Design Services").

The filter above will therefore return companies from the database with an exact NAICS code of 541512, indicating that they belong to the "Computer Systems Design Services" industry.

Search queries

Each search query includes a filters object that serves as a container for one or more search filters. It organizes the filters and their relationships by using rules. Rules determine how the filters interact with each other in order to identify the most relevant results.

{
    "filters": {
        "<rule>": [
            {
                "attribute": "<filter name>",
                "relation": "<relation between values>",
                "value": "<value(s) to be queried>"
            }
        ]
    }
}

Rules

Rules are logical operators that determine the relationship between filters in a search query. There are two types of rules supported by the API:

1. and: Requires that all filters in the group must be satisfied for a result to be included.
2. or: Requires that at least one filter in the group must be satisfied for a result to be included.

Query structure and syntax

Each query must include the following fields:

Query example

For example, the following query returns all companies in the 541512 Computer Systems Design Services NAICS code:

{
    "filters": {
        "and": [
            {
                "attribute": "company_naics_code",
                "relation": "equals",
                "value": "541512"
            }
        ]
    }
}

📘

Mandatory parameter

Please make sure to always include a rule ("and" or "or") at the root level of the filters object.

If the rule parameter is not present or has no value, the API will return a 400 Bad Request error.

Complex queries

The API will work with just a filter, but in real-life business scenarios, you need to combine multiple filters to create complex queries.

The API allows you to create complex search queries by combining filters and using rules. This provides you with increased flexibility and granularity when searching the database.

How to combine filters

To combine filters using and and or rules, follow these steps:

• Always include a rule field (either and or or) at the root of the filters field, even if there is only a single filter being passed. The rule will act as a wrapper that specifies the relation between the defined filters.
• Wrap any following two filters in an and or an or rule, as required.

Complex query example

Let's take the following query example:

{
    "filters": {
        "and": [
            {
                "attribute": "company_naics_code",
                "relation": "equals",
                "value": "541512"
            },
            {
                "or": [
                    {
                        "attribute": "company_employee_count",
                        "relation": "greater_than",
                        "value": 1000
                    },
                    {
                        "attribute": "company_estimated_revenue",
                        "relation": "greater_than",
                        "value": 1000000
                    }
                ]
            }
        ]
    }
}

This query will return all companies in the 541512 (Computer Systems Design Services) NAICS code ("attribute": "company_naics_code"), having an employee count of over ("relation": "greater_than") 1000 or an estimated revenue ("attribute": "company_estimated_revenue") of over ("relation": "greater_than") 1000000 USD.

📘

Nesting level

The current filter wrapping structure allows a depth of only 2, which means that you can have only two levels of nesting when specifying the relation between filters.

Duplicating filters

There is no limit on the number of filters that can be passed to the API. However, you need to make sure you are not providing conflicting information.

For example, if passing in two separate location filters using an and rule and specifying different headquarters for each of them, the API will not return any results.

📖

Reference

To view all available search filters, please consult the Search filters section.