Core Concepts

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.

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:

$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:

1{
2  "$schema": "https://api.v3.taxcloud.com/core/schemas/TicSearchResponse.json",
3  "query": "organic cotton t-shirts",
4  "results": [
5    {
6      "ticId": 20010,
7      "naturalLabel": "Clothing means all human wearing apparel suitable for general use",
8      "label": "Clothing",
9      "description": "Clothing",
10      "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; ...",
11      "rank": 1,
12      "score": 0.984
13    },
14    {
15      "ticId": 0,
16      "naturalLabel": "Uncategorized tangible personal property",
17      "label": "General",
18      "description": "Uncategorized tangible personal property",
19      "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.",
20      "rank": 2,
21      "score": 0.926
22    },
23    {
24      "ticId": 92062,
25      "naturalLabel": "Baby and toddler clothing",
26      "label": "Baby and toddler clothing",
27      "description": "Baby and toddler clothing",
28      "documentation": "Baby and toddler clothing, apparel, and shoes primarily intended for and marketed for children ages 5 and younger.",
29      "rank": 3,
30      "score": 0.500
31    }
32  ]
33}

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

ParameterTypeRequiredDefaultDescription
querystringYes—Product description, category name, or search term. Must be non-empty.
limitintegerNo10Number of results to return. Must be between 1 and 25.

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:

FieldTypeDescription
ticIdintegerThe TIC code. Use this value when assigning a TIC to a product or transaction.
naturalLabelstringA human-readable label describing the TIC category in natural language.
labelstringThe short canonical label for the TIC (e.g., “Clothing”, “Computer”).
descriptionstringA brief description of what the TIC covers.
documentationstringThe 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.
rankintegerThe position in the result set, starting at 1 (most relevant).
scorenumberA relevance score between 0 and 1, where 1 indicates the strongest match. Use this to gauge confidence in the result.

The response also includes:

FieldTypeDescription
$schemastringJSON schema URL for this response type.
querystringEcho of the input query.

Error handling

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

Error codeHTTP statusMeaning
INVALID_QUERY400The query field is missing or empty.
INVALID_LIMIT400The limit value is outside the allowed range (1-25).
RATE_LIMIT_EXCEEDED429Too many requests. Retry after the period indicated in the response.
INTERNAL_ERROR500An unexpected server error occurred.

Example error response:

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

Cold starts

On rare occasions, the first request after a period of inactivity may return a 503 status with a Retry-After: 60 header. Simply retry the request after the indicated interval, subsequent requests will respond normally.

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.

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