How to build a Search query

Every Search request has two parts: a module that names your intent, and a query that expresses what you're looking for. The query is where you compose filters into the exact condition you want.

The methodology on this page is the same no matter which module you use. The module only decides which filters are allowed and which anchor is required.

The building blocks

A request pairs a module with a query, and the query is the filter tree directly:

{
  "module": "segmentation",
  "query": {
    "and": [
      { "attribute": "company_naics_code", "relation": "in", "value": ["541512"] }
    ]
  }
}

A filter has three parts:

• attribute: the company property to filter on (for example company_naics_code).
• relation: how to compare (for example in, between, greater_than, match_expression).
• value: what to match. Membership relations (in, not_in) always take an array, so a single value is a one-element array (["541512"]).

Every filter and the relations it accepts are documented in Filters & relations.

Combining filters with and / or

The query always starts with a single logical relation at its root, and or or, whose value is a list of filters:

• and: every filter in the group must match.
• or: at least one filter in the group must match.

For example, the query below searches a company that is named "Nationwide" and operates in the United Kingdom.

{
    "module": "company_lookup",
    "query": {
        "and": [
            {
                "attribute": "company_name",
                "relation": "in",
                "value": [
                    "Nationwide"
                ]
            },
            {
                "attribute": "company_location",
                "relation": "in",
                "value": [
                    {
                        "country": "GB"
                    }
                ]
            }
        ]
    }
}

Building complex queries with nesting

To express conditions like "this AND (that OR the other)", nest a logical group inside another. For example, companies in a given industry that are either large by headcount or large by revenue:

{
  "module": "segmentation",
  "query": {
    "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
                }
            ]
        }
    ]
  }
}

The module anchor

Each module requires an anchor filter suited to its intent: a product for supplier_discovery, an identity (website or veridion_id) for company_lookup and company_verification, and at least one profile filter for segmentation. The anchor must sit at the top level of the root and, alongside any other filters.

For example, company_verification is anchored on an identity. Here its company_website anchor sits at the top level, with a claim check beside it:

{
    "module": "company_verification",
    "query": {
        "and": [
            {
                "attribute": "company_website",
                "relation": "in",
                "value": [
                    "nationwide.co.uk"
                ]
            },
            {
                "attribute": "company_location",
                "relation": "in",
                "value": [
                    {
                        "country": "GB"
                    }
                ]
            }
        ]
    }
}

Each module page lists its required anchor and the filters it allows and rejects. See Choosing a module.

A few rules to keep in mind

• Membership relations take arrays. in and not_in always expect an array of values, even for a single value.
• Repeating a filter is allowed. You can use the same attribute more than once (for example two company_location clauses) to build up a condition.
• Conflicting filters return nothing. Combining mutually exclusive conditions with and (for example two different exact headquarters locations) is valid, but will simply return no results.