> ## Documentation Index
> Fetch the complete documentation index at: https://docs.data.avina.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Structured filters

> Every field, operator and value format you can use in filters, for companies and people.

Filters are exact conditions on named fields. A request made of filters means the same thing every time you send it. This page lists every field, operator and value format.

## Shape

`filters` is an object with one key, `all`, which holds a list of conditions. A record must meet every condition in the list.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "filters": {
    "all": [
      { "field": "company.headquarters.country", "operator": "in", "value": ["US"] },
      { "field": "company.employee_count", "operator": "between", "value": [10, 200] },
      {
        "related": {
          "relationship": "open_jobs",
          "where": { "all": [{ "field": "title", "operator": "in", "value": ["SDR"] }] }
        }
      }
    ]
  }
}
```

A condition is one of two things:

* A **field condition**: `{ "field", "operator", "value" }`.
* A **related condition**: `{ "related": { "relationship", "where" } }`, about the company's job listings or recent hires.

> [!NOTE]
>
> Conditions are combined with AND. For OR on a single field, list the alternatives in one `in` condition. Grouping conditions with `any` or `not` is not supported.

## Operators

| Operator | Meaning | Value |
| - | - | - |
| `in` | Is any of these | A list of strings. A single string is also accepted. |
| `matches` | Text describes this | A non-empty string |
| `eq` | Equals | A number, or a money object |
| `gt`, `gte` | Greater than, at least | A number, or a money object |
| `lt`, `lte` | Less than, at most | A number, or a money object |
| `between` | Within a range, inclusive | A two-item list: `[low, high]` |
| `within_last_days` | Happened in the last N days | A whole number from 1 to 36500 |

Each field accepts only the operators listed for it below. Relative windows such as `within_last_days` are counted from when the search started.

## Company fields

| Field | Type | Operators | Value |
| - | - | - | - |
| `company.industry` | List | `in` | LinkedIn industry names, case-insensitive: `["Dentists", "Software Development"]` |
| `company.business_description` | Text | `matches` | What the company does: `"payments infrastructure for lenders"` |
| `company.headquarters.country` | List | `in` | Two-letter ISO country codes: `["US", "CA"]`. Common country names are accepted and converted. |
| `company.headquarters.state` | List | `in` | US state names or codes: `["Texas"]` or `["TX"]`. Other regions as written. |
| `company.employee_count` | Number | `eq` `gt` `gte` `lt` `lte` `between` | `50`, or `[10, 200]` |
| `company.annual_revenue` | Money | `eq` `gt` `gte` `lt` `lte` `between` | `{ "amount": 1000000, "currency": "USD" }` |
| `company.total_funding` | Money | `eq` `gt` `gte` `lt` `lte` `between` | `{ "amount": 5000000, "currency": "USD" }` |
| `company.founded_year` | Number | `eq` `gt` `gte` `lt` `lte` `between` | `2015`, or `[2015, 2020]` |
| `company.last_funding_date` | Days | `within_last_days` | `180` |
| `company.last_funding_round` | List | `in` | [Round slugs](#funding-rounds): `["series_a", "series_b"]` |
| `company.type` | List | `in` | [Company types](#company-types): `["Privately Held"]` |
| `company.technologies` | List | `in` | Product or vendor names: `["Salesforce", "Snowflake"]`. Matches companies using any of them. |

### Rules

* A list field can appear once per request. Put every value in one `in` list.
* A number or money field can appear more than once. The ranges are intersected: `gte 50` and `lte 200` together mean 50 to 200. Ranges that cannot both be true are rejected.
* Money values use `currency: "USD"`. Other currencies are not supported.
* An unknown industry name is rejected with the problem named in `details`. If an industry is not in the list, describe it with `company.business_description` or a [criterion](https://docs.data.avina.io/concepts/queries.md#free-text-criteria) instead.

### Money ranges

For `between` on a money field, give two money objects:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "field": "company.total_funding",
  "operator": "between",
  "value": [
    { "amount": 5000000, "currency": "USD" },
    { "amount": 50000000, "currency": "USD" }
  ]
}
```

### Company types

`Privately Held`, `Public Company`, `Nonprofit`, `Partnership`, `Self-Employed`, `Sole Proprietorship`, `Educational Institution`, `Government Agency`. Case-insensitive.

### Funding rounds

> [accordion] All round slugs
>
> `angel`, `pre_seed`, `seed`, `series_a`, `series_b`, `series_c`, `series_d`, `series_e`, `series_f`, `series_g`, `series_h`, `series_i`, `series_j`, `series_unknown`, `convertible_note`, `corporate_round`, `debt_financing`, `equity_crowdfunding`, `product_crowdfunding`, `grant`, `initial_coin_offering`, `non_equity_assistance`, `private_equity`, `secondary_market`, `post_ipo_debt`, `post_ipo_equity`, `post_ipo_secondary`, `undisclosed`.
>
> Natural spellings are normalized: `"Series A"` becomes `series_a`.

## Related conditions

A related condition asks about records that belong to a company: its job listings or its recent hires. All conditions in `where` must be true of the **same** record. For example, one job listing must have both the title and the posting date you asked for.

### `open_jobs`

The company has at least one open job that matches.

| Inner field | Operator | Required | Value |
| - | - | - | - |
| `title` | `in` | Yes | Job titles |
| `posted_at` | `within_last_days` | No | Days. Without it, any open job counts, however long ago it was posted. |

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "related": {
    "relationship": "open_jobs",
    "where": {
      "all": [
        { "field": "title", "operator": "in", "value": ["Sales Development Representative", "SDR"] },
        { "field": "posted_at", "operator": "within_last_days", "value": 30 }
      ]
    }
  }
}
```

### `new_hires`

Someone with a matching title joined the company within the window. Promotions inside the company do not count.

| Inner field | Operator | Required | Value |
| - | - | - | - |
| `title` | `in` | Yes | Job titles |
| `started_at` | `within_last_days` | Yes | Days |

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "related": {
    "relationship": "new_hires",
    "where": {
      "all": [
        { "field": "title", "operator": "in", "value": ["Chief Revenue Officer", "CRO"] },
        { "field": "started_at", "operator": "within_last_days", "value": 90 }
      ]
    }
  }
}
```

Each relationship can appear once per request.

> [!TIP]
>
> "Hiring" and "hired" are different questions. `open_jobs` finds companies with a vacancy now. `new_hires` finds companies where someone has already started.

## Person fields

People search accepts these fields, plus every company field above. Company fields describe the person's current employer.

| Field | Type | Operators | Value |
| - | - | - | - |
| `person.title` | List | `in` | Job titles: `["VP Sales", "Head of Sales"]` |
| `person.seniority` | List | `in` | `owner`, `c_suite`, `vp`, `head`, `director`, `manager`, `senior`, `entry` |
| `person.department` | List | `in` | Functions, such as `sales`, `marketing`, `engineering`, `operations`, `finance`, `product` |
| `person.location.country` | List | `in` | Two-letter ISO country codes for where the person is |
| `person.location.state` | List | `in` | State or region where the person is |

```json People search theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "filters": {
    "all": [
      { "field": "person.seniority", "operator": "in", "value": ["vp", "c_suite"] },
      { "field": "person.department", "operator": "in", "value": ["sales"] },
      { "field": "company.industry", "operator": "in", "value": ["Software Development"] },
      { "field": "company.employee_count", "operator": "between", "value": [50, 500] }
    ]
  }
}
```

Related conditions (`open_jobs`, `new_hires`) describe the employer and work in people search too: "VPs of sales at companies hiring SDRs".

## Filters and criteria together

Use filters for everything a field can express and [criteria](https://docs.data.avina.io/concepts/queries.md#free-text-criteria) for the rest. A search can have up to 10 criteria.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "filters": {
    "all": [
      { "field": "company.industry", "operator": "in", "value": ["Dentists"] },
      { "field": "company.headquarters.state", "operator": "in", "value": ["Texas"] }
    ]
  },
  "criteria": [
    { "text": "independently owned, not part of a dental support organization", "kind": "attribute" }
  ],
  "limit": 20
}
```

## Validation errors

An invalid filter returns `400 invalid_request`. `details` names each problem by its path:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": {
    "code": "invalid_request",
    "message": "filters.all.0: unknown field 'company.size'",
    "request_id": "req_8f2a61c09d4e7b3a5f10c2d8",
    "details": [
      { "field": "filters.all.0", "message": "unknown field 'company.size'" },
      { "field": "filters.all.2", "message": "operator 'eq' is not supported for company.industry; use one of: in" }
    ]
  }
}
```

| Message | Fix |
| - | - |
| `unknown field` | Use a field from this page. |
| `operator ... is not supported for ...` | Use an operator listed for that field. |
| `appears more than once` | Merge the values into one `in` list. |
| `'any' groups are not supported` | Use `all`, with alternatives in an `in` list. |

> [!TIP]
>
> Not sure how to express something? Send it in plain language to [Parse](https://docs.data.avina.io/capabilities/parse.md) and read the filters it produces.

## Related

* [Three ways to search](https://docs.data.avina.io/concepts/queries.md)
* [Start a company search](https://docs.data.avina.io/api-reference/companies/search.md)
* [Start a people search](https://docs.data.avina.io/api-reference/people/search.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.