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

# Companies

> Find companies by what they are, what they do and what is happening to them, with evidence for every match.

Company search turns a description of the companies you want into a verified list. Each result is one company that has been checked against every requirement you set, with the evidence for each.

```bash Request theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.avina.io/v1/companies/search \
  -H "Authorization: Bearer $AVINA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "query": "Series B fintech companies in New York that are hiring compliance engineers",
    "limit": 25,
    "max_credits": 25
  }'
```

```json One result (matched_criteria shortened) theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "object": "company_search_result",
  "result_id": "res_6Tq1Wd9nB3",
  "name": "Northwind Pay",
  "domain": "northwindpay.example",
  "description": "Payments infrastructure for mid-market lenders.",
  "industries": ["Financial Services"],
  "headquarters": { "country": "US", "state": "New York", "city": "New York" },
  "employee_count": { "low": 201, "high": 500 },
  "total_funding_usd": { "low": 62000000, "high": 62000000 },
  "last_funding": { "date": "2026-06-18", "round": "series_b" },
  "company_type": "Privately Held",
  "founded_year": 2019,
  "matched_criteria": [
    { "criterion": "company.last_funding_round", "verdict": "matched",
      "evidence": { "summary": "Last funding round: Series B", "sources": [], "items": [] } },
    { "criterion": "open_jobs", "verdict": "matched",
      "evidence": { "summary": "2 open jobs match.", "sources": ["https://northwindpay.example/careers"],
        "items": [{ "type": "job", "title": "Senior Compliance Engineer", "posted_at": "2026-11-02" }] } }
  ],
  "contacts": [],
  "contact_status": "not_requested",
  "found_at": "2026-11-12T17:03:40Z"
}
```

## What you can search on

> [card] Company facts
>
> Industry, headquarters country and state, employee count, annual revenue, company type and founding year. These are often called firmographics.

> [card] Funding
>
> Total raised, the last round, and how recently it closed.

> [card] Hiring
>
> Open jobs by title, and people who recently joined in a given role.

> [card] Technology
>
> Products and vendors the company uses.

> [card] What the company does
>
> A match on the company's own description of its business.

> [card] Anything you can describe
>
> Free-text criteria checked by research: "opened a location this year", "sells to hospitals".

Describe these in a sentence with `query`, or state them exactly with `filters` and `criteria`. See [Three ways to search](https://docs.data.avina.io/concepts/queries.md).

## The workflow

**1. Start**

`POST /companies/search` with a `query`, or with `filters` and `criteria`. You get a search `id` back immediately.

**2. Watch**

`GET /companies/search/{search_id}/status` shows progress, spend, and how a `query` was interpreted.

**3. Read**

`GET /companies/search/{search_id}/results` returns companies as they are found, in pages.

**4. Stop early (optional)**

`POST /companies/search/{search_id}/cancel` stops new work and keeps what was found.

## Request options

| Field | Purpose |
| - | - |
| `query` | The request in plain language. Use this or `filters`/`criteria`, not both. |
| `filters` | Exact conditions on structured fields. [Reference](https://docs.data.avina.io/guides/structured-filters.md). |
| `criteria` | Up to 10 free-text requirements checked against evidence. |
| `limit` | The most companies to return, 1 to 500. Default 20. |
| `persona_ids` | Find contacts at each matching company. A persona is a saved description of who to look for. See [Contacts with personas](https://docs.data.avina.io/guides/contacts-with-personas.md). |
| `exclude_domains` | Companies to skip, such as ones already in your CRM. |
| `max_credits` | The most this search may spend. |

Full details are in the [API reference](https://docs.data.avina.io/api-reference/companies/search.md).

## What a result contains

| Group | Fields |
| - | - |
| Identity | `result_id`, `name`, `domain`, `linkedin_url`, `description` |
| Firmographics | `industries`, `headquarters`, `employee_count`, `annual_revenue_usd`, `company_type`, `founded_year` |
| Funding | `total_funding_usd`, `last_funding` |
| Proof | `matched_criteria`, with a verdict and evidence for each requirement |
| People | `contacts` and `contact_status`, when you sent `persona_ids` |

Numbers such as employee count and revenue are returned as a range, `{ "low": 51, "high": 200 }`, because data providers usually report them that way. An exact figure has `low` equal to `high`. A field is `null` when its value is not known. Values are never estimated.

## Add the people you need

Often you need people at those companies too. Add `persona_ids` and each matching company comes back with the people you want to reach:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "query": "Series B fintech companies in New York",
  "limit": 10,
  "persona_ids": ["c92d77d7-cc85-4a62-bcec-518b1d7d6260"]
}
```

A persona names the job titles to look for, how many contacts to find per company, and whether to look up emails and phone numbers. Personas choose who to find at each company. They do not change which companies match. See [Contacts with personas](https://docs.data.avina.io/guides/contacts-with-personas.md).

## Good to know

* **One result per company.** Results are deduplicated by website domain. `limit` counts companies, not rows.
* **Not exhaustive.** A search returns verified matches up to `limit`. It does not claim to have found every match that exists.
* **Get more of the same.** To extend a list, run the search again with the domains you already have in `exclude_domains`.
* **"Hiring" means an open job.** Any open job counts, however long ago it was posted, unless you set a time window. "Hired" is a separate requirement, about people who have already joined.

## Next steps

> [card] [Start a company search](https://docs.data.avina.io/api-reference/companies/search.md)
>
> Endpoint reference with every field.

> [card] [Filter reference](https://docs.data.avina.io/guides/structured-filters.md)
>
> Every searchable field and operator.

> [card] [Contacts with personas](https://docs.data.avina.io/guides/contacts-with-personas.md)
>
> Get decision-makers at each company.

> [card] [Use cases](https://docs.data.avina.io/guides/use-cases.md)
>
> Example searches for sales, investing and research.


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