# AIsearch

Parse natural language query into structured filters

`POST /api/v2/companies/{companyId}/items/nlq/$parse`

**API:** AvaTax API
**Tag:** Items
**API Version:** v2
**Base URL:** https://sandbox-rest.avatax.com/
**Content-Type:** `application/json`
**Accepts:** `application/json`
**Authentication:** API Key (`Authorization` in header) or OAuth 2.0 or Basic (username + license key)

Source: https://developer.avalara.com/products/avatax/api/methods/Items/AIsearch/

## Description

Parse natural language queries into structured API filters. This endpoint forwards the query to NLQ (Natural Language Query)
service for interpretation and returns only the intent and structured filters.
            
Example queries:
- "give me items created in last 1 week which are having status complete"
- "show me all items with item code CERMUG"
- "find items containing 'mug' in description"
            
Response format:
{
  "intent": "GET",
  "filters": {
    "createdDate": { "value": "from: 2025-09-12 to: 2025-09-19" },
    "itemStatus": { "value": ["Complete"] }
  }
}
            
Raw NLQ responses are logged for debugging purposes.

### Security Policies

* This API requires one of the following user roles: AccountAdmin, AccountOperator, AccountUser, AvaTaxOnlyAccountAdmin, AvaTaxOnlyAccountUser, AvaTaxOnlyCompanyAdmin, AvaTaxOnlyCompanyUser, BatchServiceAdmin, CompanyAdmin, CompanyUser, CSPAdmin, CSPTester, ReturnsOnlyAccountAdmin, ReturnsOnlyAccountUser, ReturnsOnlyCompanyAdmin, ReturnsOnlyCompanyUser, SiteAdmin, SSTAdmin, SystemAdmin, TechnicalSupportAdmin, TechnicalSupportUser.

## Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `companyId` | integer | path | Yes | The ID of the company that owns these items |
| `X-Avalara-Client` | string | header | No | Identifies the software you are using to call this API.  For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/) . |

## Request Body

**Schema:** `NaturalLanguageSearchRequestModel`

Request model for natural language search

| Property | Type | Required | Description |
|---|---|---|---|
| `query` | string | **Yes** | Natural language query to search for items |

## Responses

| Status | Description | Schema |
|---|---|---|
| 200 | Success | `NaturalLanguageSearchResponseModel` |
| 400 | Bad Request | `ErrorResult` |
| 401 | Unauthorized | `ProblemDetails` |
| 404 | Not Found | `ProblemDetails` |
| 500 | Server Error |  |

### 200 Response: `NaturalLanguageSearchResponseModel`

Response model for natural language search

| Property | Type | Required | Description |
|---|---|---|---|
| `intent` | string | No | Intent of the search query (e.g., "GET" for read operations, "WRITE" for write operations) |
| `filters` | object | No | Structured filters extracted from the natural language query |

## Example Request

```bash
curl -X POST "https://sandbox-rest.avatax.com/api/v2/companies/{companyId}/items/nlq/$parse" \
  -H "Authorization: Basic <credentials>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "query": "give me items created in last 1 week which are having status complete"
}'
```