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

# Use cases

> Example searches for sales, investing, research and AI agents, ready to adapt.

Each example below is a complete request body. Change the specifics and send it. Every example sets `max_credits` so a first run is bounded.

## Build a target account list

Find companies that fit your ideal customer profile and show a sign that now is a good time to reach out, such as hiring for a relevant role.

```json Natural language theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "query": "B2B software companies in the US with 50 to 500 employees that are hiring sales development representatives",
  "limit": 50,
  "max_credits": 50
}
```

```json Structured theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "filters": {
    "all": [
      { "field": "company.industry", "operator": "in", "value": ["Software Development"] },
      { "field": "company.headquarters.country", "operator": "in", "value": ["US"] },
      { "field": "company.employee_count", "operator": "between", "value": [50, 500] },
      {
        "related": {
          "relationship": "open_jobs",
          "where": { "all": [
            { "field": "title", "operator": "in", "value": ["Sales Development Representative", "SDR"] }
          ] }
        }
      }
    ]
  },
  "criteria": [{ "text": "sells to other businesses", "kind": "attribute" }],
  "limit": 50,
  "max_credits": 50
}
```

Add `persona_ids` to get the buyers at each account. See [Contacts with personas](https://docs.data.avina.io/guides/contacts-with-personas.md).

## Catch a change in leadership

A new executive often reviews the tools their team uses. Find companies where one just started.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "filters": {
    "all": [
      { "field": "company.employee_count", "operator": "between", "value": [200, 2000] },
      {
        "related": {
          "relationship": "new_hires",
          "where": { "all": [
            { "field": "title", "operator": "in", "value": ["Chief Revenue Officer", "CRO", "VP Sales"] },
            { "field": "started_at", "operator": "within_last_days", "value": 60 }
          ] }
        }
      }
    ]
  },
  "limit": 25,
  "max_credits": 25
}
```

## Find companies by their tech stack

Target companies that use a product you integrate with, or one you replace.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "filters": {
    "all": [
      { "field": "company.technologies", "operator": "in", "value": ["Salesforce"] },
      { "field": "company.headquarters.country", "operator": "in", "value": ["US", "CA"] },
      { "field": "company.employee_count", "operator": "gte", "value": 100 }
    ]
  },
  "limit": 50,
  "max_credits": 40
}
```

## Source deals

Find recently funded companies in an area you invest in.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "filters": {
    "all": [
      { "field": "company.last_funding_round", "operator": "in", "value": ["seed", "series_a"] },
      { "field": "company.last_funding_date", "operator": "within_last_days", "value": 180 },
      { "field": "company.headquarters.country", "operator": "in", "value": ["US", "GB", "DE", "FR"] }
    ]
  },
  "criteria": [
    { "text": "builds software for industrial or manufacturing companies", "kind": "attribute" }
  ],
  "limit": 50,
  "max_credits": 60
}
```

## Map a market or segment

When no industry name fits, describe the segment in plain language. Each company is confirmed by research.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "query": "US companies that manufacture industrial heat pumps",
  "limit": 100,
  "max_credits": 100
}
```

Every result cites the evidence that it belongs in the segment, so you can check the list before using it in a market map or a due-diligence memo.

## Find acquisition targets

Combine size, ownership and a specific capability.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "filters": {
    "all": [
      { "field": "company.type", "operator": "in", "value": ["Privately Held"] },
      { "field": "company.headquarters.state", "operator": "in", "value": ["Texas", "Florida", "Arizona"] },
      { "field": "company.industry", "operator": "in", "value": ["Dentists"] },
      { "field": "company.employee_count", "operator": "between", "value": [20, 200] }
    ]
  },
  "criteria": [
    { "text": "independently owned, not part of a dental support organization", "kind": "attribute" },
    { "text": "operates more than one location", "kind": "attribute" }
  ],
  "limit": 50,
  "max_credits": 60
}
```

## Build a contact list for a role

Start from the person instead of the company.

```json POST /v1/people/search theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "query": "Heads of data and analytics at US healthcare companies with more than 1,000 employees",
  "limit": 50,
  "enrich_emails": true,
  "max_credits": 40
}
```

## Extend a list you already have

Run the same search again and skip what you have. Each run returns only new companies.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "query": "Series B fintech companies in New York",
  "limit": 25,
  "exclude_domains": ["northwindpay.example", "ledgerline.example"],
  "max_credits": 25
}
```

## Give an agent a research tool

Wrap search in a function and let an agent call it with whatever the user asks for. The agent gets structured records and the sources to cite.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def find_companies(query: str, limit: int = 10) -> list[dict]:
    """Find companies matching a description. Each result includes evidence with sources."""
    ...
```

The full function is in [Build with AI](https://docs.data.avina.io/build-with-ai.md#use-the-api-as-an-agent-tool).

## Writing queries that work well

> [accordion] Say what must be true, not what you hope for
>
> "Companies that sell to hospitals" can be checked. "Companies that would be a good fit for us" cannot. Unsupported requirements stop a search before it spends anything.

> [accordion] Be specific about time
>
> "Hiring" means any open job, however long ago it was posted. If you only want recent postings, say "posted in the last 30 days" or set `posted_at`.

> [accordion] Use a field when one exists
>
> A job title, technology or funding round written as a filter is checked against data records. The same requirement written as free text has to be researched, which costs more.

> [accordion] Test with a small limit
>
> Run with `limit: 5` and read `interpretation`, `assumptions` and the evidence. Adjust, then run the full search.

## Related

* [Three ways to search](https://docs.data.avina.io/concepts/queries.md)
* [Filter reference](https://docs.data.avina.io/guides/structured-filters.md)


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