# CreateHSClassificationRequest

Create an HS classification request (auto-classifies synchronously for Auto HS / Auto HS Pro / Auto HS ICP customers; otherwise queues for manual classification).

`POST /api/v2/companies/{companyId}/classifications/hs`

**API:** Avalara Item Classification API
**Tag:** CreateHSClassificationRequest
**API Version:** 16.0.1-oas3
**Base URL:** https://api-sandbox.classification.avalara.net
**Authentication:** Basic (username + license key)

Source: https://developer.avalara.com/products/managed-and-premium-tariff-code/api/methods/CreateHSClassificationRequest/CreateHSClassificationRequest/

## Description

Submit a product for HS classification for one or more countries of
destination. Each product (item) must be uniquely identified by itemCode
for a particular company. It is recommended to use your internal SKU
number as itemCode. Item classifications belong to the company you
designate.

## Dual-mode behavior

The same endpoint serves both auto-classification and manual
classification customers. The mode is chosen server-side based on
customer entitlement and the `async` query parameter:

- **Auto classification path** (synchronous prediction). Selected when:
  - The customer is entitled to **Auto HS**, **Auto HS Pro**, or **Auto HS ICP**, **and**
  - `async` is **not** `true` (i.e. omitted or `false`).

  The request is internally routed to the ML-based auto-classify flow
  (previously exposed as `/classifications/hscodes/auto`, now deprecated
  and removed from the public surface). The classification result is
  returned **synchronously** in the response body — there is no need to
  poll the GetHSClassification endpoint afterwards.

- **Manual classification path** (asynchronous parking-lot creation).
  Selected when:
  - The customer is **not** entitled to Auto HS / Auto HS Pro / Auto HS ICP, **or**
  - `async=true` is supplied (force manual flow even for entitled customers).

  The item is queued for manual classification. The response carries a
  `PENDING` status and the classification result can be retrieved later
  via `GET /classifications/hs/{hsClassificationId}`.

If the auto-classify path is selected but fails before invoking the
prediction service (e.g. authentication or payload conversion error),
the request automatically falls back to the manual classification path
so the call still succeeds.

## Request body

Both modes accept the **same** request body shape
(`HSClassificationModel` / `HSClassificationWithComplianceModel`).
Existing integrations do not need to change their payload to benefit
from auto-classification: simply enable Auto HS on the customer.

## Limits

- **Manual path:** maximum payload size of approximately 60KB. Exceeding
  this returns **413 Payload Too Large**. Split bulk-country requests if
  you hit the limit.
- **Auto path:** combined count (items × countries of destination) must
  not exceed the configured per-request limit (e.g. 10). Exceeding it
  returns **413 Payload Too Large**.

## Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `companyId` | integer | path | Yes | The ID of the company that owns this item. This is your integer company ID, not the string company code. |
| `customerId` | string | query | No | The unique identifier of the customer (for multi-tenant scenarios). When omitted, the customer is resolved from the authentication token. |
| `returnIcAccountId` | boolean | query | No | When `true`, the response includes the Item Classification account id (`icAccountId`) for each classification entry. Defaults to `false` when not supplied. |
| `async` | boolean | query | No | Forces the **manual classification path** (parking-lot creation) even when the customer is entitled to Auto HS / Auto HS Pro / Auto HS ICP. When omitted or `false`, entitled customers are auto-classified synchronously. When `true`, the item is always queued for manual classification and the response status will be `PENDING`. |
| `Context` | string | header | No | Optional contextual metadata propagated to downstream services. |

## Request Body

**Content-Type:** `application/json`

## Responses

| Status | Description | Schema |
|---|---|---|
| 201 | Created. Returned for both modes:
- **Manual path:** the classification request was accepted and parked
  for manual classification; `status` is `PENDING`.
- **Auto path** (auto-HS-entitled customer, `async != true`): the
  classification was performed synchronously and the result is in
  the response body. `status` can be `CLASSIFIED_AUTOMATICALLY` (HS
  code predicted with sufficient confidence), `PENDING` (confidence
  threshold not met — item routed for manual classification), or a
  "Failed to Classify - Insufficient product information..." status
  when the model could not produce a prediction.
All country codes in the request were valid. |  |
| 207 | Multi-Status. Returned in two situations:
- **Manual path:** the request was partially successful — some
  country codes were valid and processed, while others were
  invalid (see `validCODs` / `invalidCODs`).
- **Auto path** (auto-HS-entitled customer, `async != true`,
  multiple items in the request): the body is a **JSON array** with
  one element per request item, in the **same order** as the input.
  Each element is either a full classification object or an error
  object describing the failure for that slot. |  |
| 400 | Bad request. Can be caused by a malformed JSON request or invalid parameter values. | `ErrorInfo` |
| 401 | Authentication required. Can be caused by missing or incorrect credentials. | `ErrorInfo` |
| 413 | Payload Too Large. Returned when either:
- **Manual path:** the request body exceeds the approximate 60KB
  size limit. Split into multiple smaller requests.
- **Auto path:** the combined count (items × countries of
  destination) exceeds the configured per-request limit. | `ErrorInfo` |
| 415 | Unsupported media type. The `Content-type` header has to be `application/json`. | `ErrorInfo` |
| 422 | Request cannot be processed due to validation errors. | `ErrorInfo` |

## Example Request

```bash
curl -X POST "https://api-sandbox.classification.avalara.net/api/v2/companies/{companyId}/classifications/hs" \
  -H "Authorization: Basic <credentials>" \
  -H "Accept: application/json"
```