# HSCode classification service

# Access to the Production API
API access requires a bearer token, which can be obtained using your Avatax account ID and license key.

To acquire a bearer token:
1. [Create a License Key if not already created](https://knowledge.avalara.com/bundle/nps1728373667883_nps1728373667883/page/kys1728459996876.html).
2. Call Avalara Identity to get an access token (choose based on your endpoint URL):


 hscode.api.avalara.com — scope: hs-code-classification

```bash
curl -X POST https://identity.avalara.com/connect/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id=&client_secret=&scope=hs-code-classification"
```

Sample response:

```json
{
   "access_token": "",
   "expires_in": 3600,
   "token_type": "Bearer",
   "scope": "hs-code-classification"
}
```




 hscode.avatax.avalara.com (legacy) — scope: avatax_api

```bash
curl -X POST https://identity.avalara.com/connect/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id=&client_secret=&scope=avatax_api"
```

Sample response:

```json
{
   "access_token": "",
   "expires_in": 3600,
   "token_type": "Bearer",
   "scope": "avatax_api"
}
```



3. The `access_token` can be used to interact with the API.
4. The `access_token` is valid for 1 hour, after which you will need to request a fresh token.

# Access to the Sandbox API
API access requires a bearer token, which can be obtained using your Avatax account ID and license key.

To acquire a bearer token:
1. [Create a License Key if not already created](https://knowledge.avalara.com/bundle/nps1728373667883_nps1728373667883/page/kys1728459996876.html).
2. Call Avalara Identity to get an access token (choose based on your endpoint URL):


 hscode.api.sbx.avalara.com — scope: hs-code-classification

```bash
curl -X POST https://ai-sbx.avlr.sh/connect/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id=&client_secret=&scope=hs-code-classification"
```

Sample response:

```json
{
   "access_token": "",
   "expires_in": 3600,
   "token_type": "Bearer",
   "scope": "hs-code-classification"
}
```




 hscode.avatax.sbx.avalara.com (legacy) — scope: avatax_api

```bash
curl -X POST https://ai-sbx.avlr.sh/connect/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id=&client_secret=&scope=avatax_api"
```

Sample response:

```json
{
   "access_token": "",
   "expires_in": 3600,
   "token_type": "Bearer",
   "scope": "avatax_api"
}
```



3. The `access_token` can be used to interact with the API.
4. The `access_token` is valid for 1 hour, after which you will need to request a fresh token.

Note: The sandbox API is only available for a fixed number of classification requests.

Source: https://developer.avalara.com/products/automated-tariff-code/api/

**Version:** 1.2.0
**Base URL:** https://hscode.api.avalara.com

---

## Endpoints

### public

#### Predict HS Code

`POST /hscode/classify`

Predicts the HS code using the provided product information for the specified country of destination.

**Performance and timeout guidance**
- `standard`: ~300 ms (typical).
- `enhanced_quick`: response time can vary from near-standard latency to ~8-12 seconds (p95 observed for slower requests).
- `enhanced_precise`: response time can vary from near-standard latency to ~25-30 seconds (p95 observed for slower requests).
- Actual latency varies by request and selected mode; not every request in an enhanced mode will be at the upper range.

**Client timeout recommendation**
- Configure your client timeout to at least **60 seconds** when using enhanced modes.

**Batch size limit**
- Send a maximum of **10 products per request** (applies to all prediction modes).

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `depth` | string | query | No | The length of the HS code to be predicted. `full` = 10 digits; `6` = 6 digits. |
| `api_version` | string | query | No | The API version to use. |
| `prediction_mode` | string | query | No | Customer-facing prediction strategy:
- `standard`: Default path; optimized for speed and efficiency.
- `enhanced_quick`: Enhanced path designed for improved capability (requires entitlement).
- `enhanced_precise`: Enhanced path designed for higher accuracy and quality (requires entitlement).
If entitlement is missing, enhanced modes return a forbidden response. |

#### Smart predict HS Code (batch) from provided HS6 code

`POST /hscode/classify_from_hs6`

Predicts the HS code using the provided product information.
- `prediction_mode=standard` routes to the smart HS6-aware full-code path.
- `prediction_mode=enhanced_quick` / `enhanced_precise` route to the enhanced ICP path (requires entitlement).
If entitlement is missing, enhanced modes return a forbidden response.

**Performance and timeout guidance**
- `standard`: ~300 ms (typical).
- `enhanced_quick`: response time can vary from near-standard latency to ~8-12 seconds (p95 observed for slower requests).
- `enhanced_precise`: response time can vary from near-standard latency to ~25-30 seconds (p95 observed for slower requests).
- Actual latency varies by request and selected mode; not every request in an enhanced mode will be at the upper range.

**Client timeout recommendation**
- Configure your client timeout to at least **60 seconds** when using enhanced modes.

**Batch size limit**
- Send a maximum of **10 products per request** (applies to all prediction modes).

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `api_version` | string | query | No | The API version to use. |
| `prediction_mode` | string | query | No | Customer-facing prediction strategy:
- `standard`: Default smart HS6-aware path.
- `enhanced_quick`: Enhanced path designed for improved capability (requires entitlement).
- `enhanced_precise`: Enhanced path designed for higher accuracy and quality (requires entitlement).
If entitlement is missing, enhanced modes return a forbidden response. |

#### Predict enriched content

`POST /hscode-enhanced/classify`

Predicts the HS code along with additional compliance prediction.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `depth` | string | query | No | The length of the HS code to be predicted. `full` = 10 digits; `6` = 6 digits. |
| `api_version` | string | query | No | The API version to use. |
| `validate_hscode` | boolean | query | No | validity details along with hscode |

#### Possible HS Codes

`POST /hscode/hints`

Predicts a list of possible HS code using the provided product information for the specified country of destination.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `api_version` | string | query | No | The API version to use. |

---

## Models

### Context

The context of a product.

| Property | Type | Description |
|---|---|---|
| `product_title` | string | Primary product text used for classification. This should clearly describe what the product actually is.
Include crisp and specific details such as product type, key material, specifications, and intended use where available.
A clear and detailed title materially improves classification quality. |
| `cod` | string | The country of destination. This field is required if `depth = full`. This field expects a two-character ISO 3166 country code. |
| `image_url` | string | A URL that points to an image of the product. |
| `product_url` | string | The product URL that includes full details about the product. |
| `price` | string | The price of the product. |
| `product_category` | string | The category of the product. |
| `product_description` | string | A detailed description of the product. |
| `attributes` | list of dictionary | A list of product attributes as key/value pairs.
For best classification quality, send commonly used attribute names exactly as:
`material`, `price`, `weight`, `gender`, `dimensions`, or `length`/`width`/`height`.
Other attribute names can also be sent as additional fields. |
| `hs6_code` | string | The HS6 code of the product. |

### EnrichedContext

The enriched context of a product, with required enhanced_field.

| Property | Type | Description |
|---|---|---|
| `product_title` | string | Primary product text used for classification. This should clearly describe what the product actually is.
Include crisp and specific details such as product type, key material, specifications, and intended use where available.
A clear and detailed title materially improves classification quality. |
| `cod` | string |  |
| `image_url` | string |  |
| `product_url` | string |  |
| `price` | string |  |
| `product_category` | string |  |
| `product_description` | string |  |
| `attributes` | array |  |
| `enhanced_field` | object |  |

### EnhancedPrediction

Prediction of Hscode along with additional compliance message

| Property | Type | Description |
|---|---|---|
| `hscode_prediction` | Prediction |  |
| `compliancePrediction` | object | A compliance message for the Hscode |
| `validation` | string | A validation message for the hscode provided by customer |

### Prediction

A prediction of a Harmonized System code or an Avalara tax code.

| Property | Type | Description |
|---|---|---|
| `code` | string | The predicted Harmonized System code or Avalara tax code. |
| `confidence` | string | The level of confidence. Accepted values are HIGH, MID, and LOW.

HIGH - Codes that have historically had an accuracy rate of 85% or higher are classified as "HIGH".

MID  - Codes that have historically had an accuracy rate between 75% and 85% are classified as "MID".

LOW  - Codes that have historically had an accuracy rate below 75% are classified as "LOW". |
| `description` | string | A description of the predicted Harmonized System code or Avalara tax code. |

### JSONErrorResponse

| Property | Type | Description |
|---|---|---|
| `message` | string | A detailed message about the JSON error response. |

### HTTPValidationError

A HTTP validation error reponse.

| Property | Type | Description |
|---|---|---|
| `detail` | array | Details about the HTTP validation error. |

### ValidationError

A validation error response.

| Property | Type | Description |
|---|---|---|
| `loc` | array | The location where the validation error occured. |
| `msg` | string | A detailed message about the validation error response. |
| `type` | string | The type of validation error. |

### UnauthorizedErrorResponse

A JSON unauthorized error response.

### InvalidInputErrorResponse

A JSON invalid input error response.

### ForbiddenErrorResponse

A JSON forbidden error response.

### InternalErrorResponse

A JSON internal error response.