Three ways to search

Every search answers the same question: which companies, or people, meet all of these requirements? You can state the requirements in three ways.

	`query`	`criteria`	`filters`
What it is	A sentence or paragraph in plain language	A list of free-text requirements	Exact conditions on named fields
Example	`"Private dental practices in Texas hiring SDRs"`	`["independently owned", "offers same-day implants"]`	`company.employee_count between [10, 200]`
How it is checked	Turned into `filters` and `criteria`, which are then checked	Against the company’s own description and the public web	Against structured data records
Best for	End-user input, agents, exploration	Anything no field can express	Repeatable pipelines, exact control

Send query on its own, or send filters and criteria together. A request with query plus filters or criteria is rejected with 400 invalid_request.

Plain language

{ "query": "Privately held dental practices in Texas hiring SDRs", "limit": 20 }

Avina turns the sentence into structured filters and free-text criteria, then runs the search. (An SDR is a sales development representative: a salesperson who finds and qualifies new prospects.) The search’s interpretation field shows exactly how the sentence was read:

{
  "interpretation": {
    "filters": {
      "all": [
        { "field": "company.industry", "operator": "in", "value": ["Dentists"] },
        { "field": "company.business_description", "operator": "matches", "value": "dental practices" },
        { "field": "company.headquarters.state", "operator": "in", "value": ["Texas"] },
        { "field": "company.type", "operator": "in", "value": ["Privately Held"] },
        { "related": { "relationship": "open_jobs", "where": { "all": [
          { "field": "title", "operator": "in", "value": ["Sales Development Representative", "SDR"] }
        ] } } }
      ]
    },
    "criteria": [],
    "unsupported_criteria": []
  },
  "assumptions": []
}

Interpretation follows three rules:

Nothing is dropped. Every requirement in your sentence becomes a filter or a criterion. A requirement is never relaxed to return more results.
Ambiguity is reported, not hidden. When a phrase has more than one reasonable reading, Avina picks the likeliest and lists it under assumptions, with the alternatives. The search still runs. Reword the query if the reading is wrong.
Requirements that cannot be checked stop the search. Things no public source can confirm, such as “visited our pricing page” or “has a great culture”, are listed under unsupported_criteria. The search ends with stop_reason: query_needs_clarification before any provider is called, and nothing is charged.

For example, “recently” has no fixed meaning, so a query for “recently funded fintech companies in New York” reports how it was read:

{
  "assumptions": [
    {
      "text": "recently funded",
      "assumed": "Last funding round was within the last 90 days",
      "alternatives": ["Last funding round was within the last 12 months"]
    }
  ]
}

To see how a query will be read before spending anything, send it to Parse. It returns the same interpretation and a ready-to-send structured request.

Structured filters

Filters are exact conditions on named fields. Use them when you know precisely what you want and need the request to mean the same thing every time.

{
  "filters": {
    "all": [
      { "field": "company.headquarters.country", "operator": "in", "value": ["US"] },
      { "field": "company.employee_count", "operator": "between", "value": [10, 200] },
      { "field": "company.total_funding", "operator": "gte", "value": { "amount": 5000000, "currency": "USD" } }
    ]
  }
}

A company must meet every condition in all. Conditions cover company facts (industry, location, employee count, revenue, company type, founding year), funding (total raised, last round, how recent), technologies in use, and two kinds of activity: open jobs and recent hires. The filter reference lists every field, operator and value format.

Free-text criteria

Criteria cover what no field can express. Each one is a statement that must be true of a match, and each is checked separately against evidence.

{
  "filters": { "all": [{ "field": "company.industry", "operator": "in", "value": ["Dentists"] }] },
  "criteria": [
    { "text": "independently owned, not part of a dental support organization", "kind": "attribute" },
    { "text": "opened a new location this year", "kind": "event" }
  ]
}

`kind`	Use for	How it is checked
`attribute`	A lasting fact the company would state about itself: “sells to hospitals”, “manufactures industrial heat pumps”	Against the company’s own description, then the web
`event`	Something that happened: “opened a location in Texas this year”, “announced a partnership with Stripe”	Web research with sources

A plain string is treated as an event. A search takes at most 10 criteria.

Write each criterion as one statement that can be checked. “B2B SaaS company that sells to hospitals and recently raised funding” is three requirements: an industry filter, an attribute criterion and a funding filter. Splitting them gives clearer evidence for each.

How they combine

All requirements are combined with AND. A company is returned only when it matches every filter condition and every criterion. There is no relevance score that lets a strong match on one requirement make up for failing another. To express OR on one field, put the alternatives in a single in list:

{ "field": "company.headquarters.country", "operator": "in", "value": ["US", "CA", "GB"] }

Choosing between them

You are giving an agent a search tool

Let the agent send query. Have it read interpretation and assumptions from the status response and reword if the reading is off.

You run the same search on a schedule

Send filters and criteria. A structured request is interpreted the same way every time. Use Parse once to draft it, then store and edit the result.

Your requirement is not a field

Keep the structured parts as filters and add the rest as criteria.

Next steps

Filter reference

Every field, operator and value format.

Evidence and verdicts

How each requirement is checked and reported.

Get started

Concepts

Capabilities

Guides

Plain language

Structured filters

Free-text criteria

How they combine

Choosing between them

Next steps

Filter reference

Evidence and verdicts

​Plain language

​Structured filters

​Free-text criteria

​How they combine

​Choosing between them

​Next steps

Filter reference

Evidence and verdicts

Plain language

Structured filters

Free-text criteria

How they combine

Choosing between them

Next steps