> ## 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.

# How it works

> What happens between your request and a list of verified companies or people.

You describe the companies or people you want. Avina works out what that means, finds candidates (A company or person that might match your request and still has to be checked.) across its data providers, checks each one against every requirement, and returns only the ones that pass.

Every search goes through the same four stages. Press **Play**, or select a stage:

Back
Next

| Stage | What happens | What you can observe |
| - | - | - |
| 1. Interpret | The request is turned into exact requirements. Nothing you asked for is dropped. | `interpretation` and `assumptions` on the search |
| 2. Route | Avina picks data sources from what the request contains: data providers for structured conditions, AI web search for requirements that need research. | `progress.candidates` |
| 3. Verify | Each candidate is checked against every requirement. A candidate passes only when every requirement is matched with evidence. | `progress.accepted`, `progress.rejected`, `progress.unknown` |
| 4. Return | Passing records are deduplicated and added to the results, in the order they were found. | `GET .../results`, `stop_reason` |

> [!NOTE]
>
> The companies in the animation are illustrative.

## The four stages

**1. Interpret the request**

A plain-language `query` is split into requirements of two kinds:

* **Filters**: exact conditions on known fields, such as country, employee count and company type.
* **Criteria**: free-text statements, such as "offers same-day implants", for anything no field covers.

Job titles, industries and places are normalized, so "SDR" and "sales development representative" are treated as the same role.

Ambiguous wording does not stop a search. Avina reads it the likeliest way and reports the reading in `assumptions`. A search stops before any provider is called, with `stop_reason: query_needs_clarification`, only when a requirement cannot be checked from the data available, or when the query gives nothing to search on.

You can run this stage on its own, at no cost, with [Parse](https://docs.data.avina.io/capabilities/parse.md).

**2. Route to data sources**

Different sources hold different kinds of data: company databases, job listings, technology data, and AI search of the public web. Avina picks sources from what the request contains.

* Structured conditions, such as industry, size or an open job, go to data providers that can filter on them directly.
* Requirements that need research, such as "opened a location this year", go to AI web search.
* If the data providers run out of candidates, the search continues with AI web search.

You do not choose providers, and you do not maintain an integration with any of them. See [The data network](https://docs.data.avina.io/concepts/data-network.md).

**3. Verify every requirement**

Each candidate is checked one requirement at a time. Every check ends in one of three verdicts (The outcome of checking one requirement against one candidate: matched, not\_matched or unknown.): matched, not matched, or unknown. Missing information is never treated as a "no", and an unknown is never treated as a "yes".

A company or person is accepted only when every requirement is matched. See [Evidence and verdicts](https://docs.data.avina.io/concepts/evidence.md).

**4. Return results**

Accepted records are deduplicated (Merged so that the same company or person appears once, even when several data providers returned it.) and added to the search's results. You can read results while the search is still running.

The search stops when it reaches your `limit`, runs out of sources, or reaches a spend limit. `stop_reason` tells you which.

## What you get back

A search is asynchronous (The API accepts your request and answers immediately, before the work is done. You check back for the outcome.). `POST` returns immediately with a search `id`. You then poll the search's status and read results page by page as they arrive.

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    participant C as Your server
    participant A as Avina Data API
    C->>A: POST /v1/companies/search
    A-->>C: 202 { id, status: "queued" }
    loop until the search finishes
        C->>A: GET /v1/companies/search/{id}/status
        A-->>C: 200 { status: "running", progress }
        C->>A: GET /v1/companies/search/{id}/results?after=cursor
        A-->>C: 200 { data, next_cursor, has_more }
    end
```

Each result carries the reason it matched:

```json One result (shortened) theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "result_id": "res_8Zk2Qm4vT1",
  "name": "Lakeview Dental Group",
  "domain": "lakeviewdental.example",
  "matched_criteria": [
    {
      "criterion": "open_jobs",
      "verdict": "matched",
      "evidence": {
        "summary": "1 open job matches.",
        "sources": ["https://lakeviewdental.example/careers/sdr"],
        "items": [{ "type": "job", "title": "Sales Development Representative" }]
      }
    }
  ]
}
```

> [!NOTE]
>
> Example values on this page are illustrative. Field definitions are in the [API reference](https://docs.data.avina.io/api-reference/companies/list-results.md).

## What a search does and does not promise

| A search does | A search does not |
| - | - |
| Check every requirement for every result | Return every matching company in the world. `completed` means this run finished, not that the list is exhaustive |
| Keep your original requirements. No condition is silently relaxed to find more results | Guess. If the evidence is missing, the verdict is unknown and the candidate is not accepted |
| Return each company once, with the evidence for each requirement | Guarantee an email or phone number for every person |
| Stop new spending when it reaches a limit, and keep the results found so far | Charge you for reading status or results |

## Next steps

> [card] [Three ways to search](https://docs.data.avina.io/concepts/queries.md)
>
> Plain language, free-text criteria and structured filters.

> [card] [Evidence and verdicts](https://docs.data.avina.io/concepts/evidence.md)
>
> How to read why a result matched.

> [card] [Search lifecycle](https://docs.data.avina.io/concepts/search-lifecycle.md)
>
> Statuses, stop reasons, cancellation and partial results.

> [card] [Quickstart](https://docs.data.avina.io/quickstart.md)
>
> Run your first search.


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