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

# Parse a company query

> Turns a natural-language request into the structured `filters` and `criteria` a company search takes, without searching.

Free.

Use Parse to show users how their request was understood, let them edit it, or build a filter UI on top of natural language.

When nothing blocks the search, `search_request` is a ready body for [`POST /companies/search`](https://docs.data.avina.io/api-reference/companies/search): send it as-is, or edit it first. Otherwise `search_request` is `null`, and `unsupported_criteria` or `errors` say what to change.

Parse runs no search and spends no credits.

### Headers

**Idempotency-Key** `string`

A unique string for this request, 1 to 255 characters. Retrying with the same key and body returns the original response instead of starting new work. Reusing a key with a different body returns `409 idempotency_key_reused`. Always send one when starting a search.

### Body

**query** `string` *required*

The request to parse, from one sentence to a pasted paragraph of requirements.

Maximum 1,000 characters.

### Response

**`200`** How the query was read.

**object** `string` *required*

`company_search_parse` or `people_search_parse`.

**query** `string` *required*

The original text.

**filters** `object | null` *required*

The structured reading of the query. `null` when nothing in the query maps to a structured field.

**properties**

**all** `object[]` *required*

The conditions. A record must meet every one. Each item is a field condition (`field`, `operator`, `value`) or a `related` condition.

**item properties**

**field** `string`

The field to test, such as `company.industry` or `person.title`.

**operator** `string`

How to compare. Which operators a field accepts depends on its type.

Options: `in`, `matches`, `eq`, `gt`, `gte`, `lt`, `lte`, `between`, `within_last_days`.

**value** `any`

The value to compare against. A list for `in`, a two-item list for `between`, a `{amount, currency}` object for money fields, a number of days for `within_last_days`.

**related** `object`

A condition on records related to the company. All conditions in `where` must be true of the same record, for example one job listing.

**properties**

**relationship** `string` *required*

`open_jobs`: the company has at least one open job that matches. `new_hires`: someone with a matching title joined the company within the window.

**where** `object` *required*

Conditions on the related record.

**properties**

**all** `object[]` *required*

Conditions on `title` (`in`), `posted_at` (`within_last_days`, for `open_jobs`) or `started_at` (`within_last_days`, for `new_hires`).

**item properties**

**field** `string` *required*

The field on the related record.

Options: `title`, `posted_at`, `started_at`.

**operator** `string` *required*

`in` for `title`; `within_last_days` for `posted_at` and `started_at`.

**value** `any` *required*

A list of titles for `in`, or a whole number of days from 1 to 36500 for `within_last_days`.

**criteria** `object[]` *required*

Requirements that will be checked against evidence for each candidate.

**item properties**

**text** `string` *required*

The requirement, written as a statement that is true of a match.

**kind** `string`

`attribute`: a lasting fact the company's own description could state, such as "sells to hospitals". `event`: something that happened, such as "opened a location in Texas this year"; checked by web research.

**unsupported\_criteria** `string[]` *required*

Requirements no public source can confirm, quoted from the query, such as visits to your own website or subjective quality. The search cannot run while there are any.

**assumptions** `object[]` *required*

Ambiguous wording and how it was read. Assumptions do not block the search.

**item properties**

**text** `string` *required*

The exact phrase from the query.

**assumed** `string` *required*

The reading that was used.

**alternatives** `string[]` *required*

Other readings. Reword the query if one of these is what you meant.

**errors** `object[]` *required*

Problems validating the filters the query was read as.

**item properties**

**field** `string`

The filter path with the problem.

**message** `string` *required*

What is wrong.

**search\_request** `object | null` *required*

A ready request body for the matching search endpoint. `null` when `unsupported_criteria` or `errors` is not empty, or the query gave nothing to search on.

**properties**

**filters** `object | null`

Structured conditions. A record must meet every condition in `all`. `null` is treated the same as leaving `filters` out. See the [filter reference](https://docs.data.avina.io/guides/structured-filters.md) for every field and operator.

**properties**

**all** `object[]` *required*

The conditions. A record must meet every one. Each item is a field condition (`field`, `operator`, `value`) or a `related` condition.

**item properties**

**field** `string`

The field to test, such as `company.industry` or `person.title`.

**operator** `string`

How to compare. Which operators a field accepts depends on its type.

Options: `in`, `matches`, `eq`, `gt`, `gte`, `lt`, `lte`, `between`, `within_last_days`.

**value** `any`

The value to compare against. A list for `in`, a two-item list for `between`, a `{amount, currency}` object for money fields, a number of days for `within_last_days`.

**related** `object`

A condition on records related to the company. All conditions in `where` must be true of the same record, for example one job listing.

**properties**

**relationship** `string` *required*

`open_jobs`: the company has at least one open job that matches. `new_hires`: someone with a matching title joined the company within the window.

**where** `object` *required*

Conditions on the related record.

**properties**

**all** `object[]` *required*

Conditions on `title` (`in`), `posted_at` (`within_last_days`, for `open_jobs`) or `started_at` (`within_last_days`, for `new_hires`).

**item properties**

**field** `string` *required*

The field on the related record.

Options: `title`, `posted_at`, `started_at`.

**operator** `string` *required*

`in` for `title`; `within_last_days` for `posted_at` and `started_at`.

**value** `any` *required*

A list of titles for `in`, or a whole number of days from 1 to 36500 for `within_last_days`.

**criteria** `object[] | null`

**item properties**

**text** `string` *required*

The requirement, written as a statement that is true of a match.

**kind** `string`

`attribute`: a lasting fact the company's own description could state, such as "sells to hospitals". `event`: something that happened, such as "opened a location in Texas this year"; checked by web research.

### Errors

| Status | Code | When |
| - | - | - |
| `400` | `invalid_request` | The request is invalid, for example a missing `query` or one longer than 1,000 characters. |
| `401` | `invalid_api_key` | The API key is missing, invalid or revoked. |
| `409` | `idempotency_key_reused` | The `Idempotency-Key` was already used with a different request, or its first request is still running. |
| `429` | `rate_limited` | Too many requests. Retry after `Retry-After` seconds. |
| `500` | `internal_error` | Something went wrong on our side. Retry with backoff, and with the same `Idempotency-Key` if you sent one. |

Every error uses the same shape. See [Errors](https://docs.data.avina.io/api-reference/errors.md).

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.avina.io/v1/companies/search/parse \
  -H "Authorization: Bearer $AVINA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "query": "Private dental practices in Texas hiring SDRs"
  }'
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
import uuid
import requests

response = requests.post(
    "https://api.avina.io/v1/companies/search/parse",
    headers={"Authorization": f"Bearer {os.environ['AVINA_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
      "query": "Private dental practices in Texas hiring SDRs"
    },
)
response.raise_for_status()
print(response.json())
```

```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await fetch(`https://api.avina.io/v1/companies/search/parse`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AVINA_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    "query": "Private dental practices in Texas hiring SDRs"
  }),
});
const data = await response.json();
console.log(data);
```

```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "object": "company_search_parse",
  "query": "Private dental practices in Texas hiring SDRs",
  "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": [],
  "errors": [],
  "search_request": {
    "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": null
  }
}
```

```json 400 theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": {
    "code": "invalid_request",
    "message": "query: must be at most 1000 characters",
    "request_id": "req_8f2a61c09d4e7b3a5f10c2d8",
    "details": [
      { "field": "query", "message": "must be at most 1000 characters" }
    ]
  }
}
```


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