> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.taxcloud.com/api-v-3/guides/core-concepts/tic-search/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.taxcloud.com/_mcp/server.

# TIC Search

TaxCloud TIC Search endpoint helps you find the correct Taxability Information Codes (TICs) for your products. It uses semantic matching to return the most relevant tax classification codes based on a product description, category name, or search term. As a result, you don't need to know the exact TIC taxonomy to find the right code.

## Why Use TIC Search?

Every product in TaxCloud needs a TIC to determine how it's taxed across different states. Assigning the wrong TIC can lead to over-collection or under-collection of sales tax.

TIC Search eliminates the guesswork by letting you describe your product in plain language and receive ranked results with confidence scores. This is especially useful when:

* Onboarding a large product catalog and need to classify items in bulk  
* Building a product management experience where merchants self-assign TICs  
* Replacing manual TIC lookup with an automated classification workflow  
* Validating existing TIC assignments against the current taxonomy

## How It Works

1. Send a product description or search term to the TIC Search endpoint.  
2. The API runs your query through a semantic search model that understands product intent, not just keywords.  
3. You receive a ranked list of matching TICs, ordered by relevance score (highest first).

## Quick Start

Make a `POST` request to the TIC Search endpoint with a product description:

```shell
curl -X POST https://api.v3.taxcloud.com/tax/tic/search \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "organic cotton t-shirts",
    "limit": 5
  }'
```

The response returns the top matches, ranked by relevance:

```json
{
  "$schema": "https://api.v3.taxcloud.com/core/schemas/TicSearchResponse.json",
  "query": "organic cotton t-shirts",
  "results": [
    {
      "ticId": 20010,
      "naturalLabel": "Clothing means all human wearing apparel suitable for general use",
      "label": "Clothing",
      "description": "Clothing",
      "documentation": "Clothing means all human wearing apparel suitable for general use. \"Clothing\" shall include: Aprons, household and shop; Athletic supporters; Baby receiving blankets; Bathing suits and caps; ...",
      "rank": 1,
      "score": 0.984
    },
    {
      "ticId": 0,
      "naturalLabel": "Uncategorized tangible personal property",
      "label": "General",
      "description": "Uncategorized tangible personal property",
      "documentation": "Any tangible personal property that does not fit within the other defined categories. This TIC defaults to taxable in all states. For uncategorized services, use TIC 00001.",
      "rank": 2,
      "score": 0.926
    },
    {
      "ticId": 92062,
      "naturalLabel": "Baby and toddler clothing",
      "label": "Baby and toddler clothing",
      "description": "Baby and toddler clothing",
      "documentation": "Baby and toddler clothing, apparel, and shoes primarily intended for and marketed for children ages 5 and younger.",
      "rank": 3,
      "score": 0.500
    }
  ]
}
```

In this example, TIC `20010` (Clothing) is the top result with a score of 0.984, the correct classification for a cotton t-shirt.

## Request Parameters

| Parameter | Type | Required | Default | Description |
| ----- | ----- | ----- | ----- | ----- |
| `query` | string | Yes | — | Product description, category name, or search term. Must be non-empty. |
| `limit` | integer | No | 10 | Number of results to return. Must be between 1 and 100\. |
| `cursor` | string | No | — | The `nextCursor` value from a previous response, to get the next page of results. |

### Tips for Writing Effective Queries

* **Be specific.** "Men's waterproof hiking boots" returns better results than "shoes."  
* **Use natural product descriptions.** The system understands product language, describe items the way a merchant or customer would.  
* **Include material or category context when relevant.** "Ceramic pottery kiln" is more precise than "kiln."  
* **Try variations if the first result isn't ideal.** The model interprets intent semantically, so rephrasing can surface different matches.

## Response Fields

Each result in the `results` array contains:

| Field | Type | Description |
| ----- | ----- | ----- |
| `ticId` | integer | The TIC code. Use this value when assigning a TIC to a product or transaction. |
| `naturalLabel` | string | A human-readable label describing the TIC category in natural language. |
| `label` | string | The short canonical label for the TIC (e.g., "Clothing", "Computer"). |
| `description` | string | A brief description of what the TIC covers. |
| `documentation` | string | The full regulatory documentation for the TIC, including examples of what is and isn't included in the category. This field can be lengthy for some TICs. |
| `rank` | integer | The position in the result set, starting at 1 (most relevant). |
| `score` | number | A relevance score between 0 and 1, where 1 indicates the strongest match. Use this to gauge confidence in the result. |

The response also includes:

| Field | Type | Description |
| ----- | ----- | ----- |
| `$schema` | string | JSON schema URL for this response type. |
| `query` | string | Echo of the input query. |
| `nextCursor` | string | Cursor for the next page of results. Pass it as `cursor` in your next request. |

## Error Handling

TIC Search returns standard error responses, in a format consistent with all other TaxCloud API endpoints.

| Error code | HTTP status | Meaning |
| ----- | ----- | ----- |
| `INVALID_QUERY` | 400 | The `query` field is missing or empty. |
| `INVALID_LIMIT` | 400 | The `limit` value is outside the allowed range (1-100). |
| `RATE_LIMIT_EXCEEDED` | 429 | Too many requests. Retry after the period indicated in the response. |
| `INTERNAL_ERROR` | 500 | An unexpected server error occurred. |
| — | 503 | The search service is temporarily unavailable. See the note below. |

Example error response:

```json
{
  "$schema": "https://api.v3.taxcloud.com/core/schemas/ErrorModel.json",
  "title": "Bad Request",
  "status": 400,
  "detail": "INVALID_QUERY: Query is missing or empty"
}
```

> **Temporary unavailability**
>
> The search service can return a `503` status, for example on the first request after a period of inactivity or when the service is rate limited. Retry after the interval in the `Retry-After` header when one is present, and use exponential backoff for repeated retries.

## Common Use Cases

### Classifying a Product Catalog

If you're onboarding a large catalog, you can call TIC Search for each product and use the top-ranked result to assign TICs programmatically. For most products, the rank-1 result will be the correct classification.

```shell
# For each product in your catalog
curl -X POST https://api.v3.taxcloud.com/tax/tic/search \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Bluetooth wireless headphones",
    "limit": 3
  }'
```

For high-confidence matches (e.g., `score` above 0.9), you can auto-assign the top TIC. For lower-confidence or ambiguous results, flag those items for manual review.

### Building a TIC Lookup in Your Application

If you're building a product management UI where merchants classify their own products, you can use TIC Search as the backend for a search-as-you-type experience. Send the merchant's input as the `query` parameter and display the results for them to choose from.

### Validating Existing TIC Assignments

Run your current product descriptions through TIC Search and compare the top result against the TIC you currently have assigned. If they differ, it may be worth reviewing whether the original assignment is still correct, especially if TaxCloud has added more specific TIC categories since the original classification.

## Performance Considerations

* **Typical response times** are under 1 second for most queries.  
* **Set an appropriate limit.** If you only need the top match, use `limit=1` to minimize response payload size. For use cases where you want to present options to a user, `limit=5` or `limit=10` provides a good range.  
* **Rate limits apply.** If you're classifying a large catalog, implement reasonable pacing between requests to avoid hitting rate limits.

## Related Resources

* [API Reference: TIC Search endpoint](https://docs.taxcloud.com/api-reference/api-reference/sales-tax-api/utilities/tic-search) — Full endpoint specification with request/response schemas.  
* [Tax Codes overview](https://docs.taxcloud.com/guides/core-concepts/taxability-information-codes-ti-cs) — Learn more about how TICs work and why correct classification matters.