# HSCodeVerificationRequest

Verify HS Code for Product

`POST /api/v2/companies/{companyId}/classifications/hscodes/verify`

**API:** Avalara Item Classification API
**Tag:** HSCodeVerificationRequest
**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/HSCodeVerificationRequest/HSCodeVerificationRequest/

## Description

Verifies whether a provided HS code is appropriate for a given product using ML-based classification.

**Behavior:**
- If the HS code is verified as appropriate, returns `verified: true`
- If the HS code is NOT verified, automatically submits the product for classification and returns the classification response

**Requirements:**
- The customer must be enabled for HS code validation service
- HS code must be 6-12 digits, optionally followed by up to 2 letters (e.g., 7323997000, 7323997000AB)
- All standard classification fields are required (companyId, itemCode, description, itemGroup, countryOfDestination)

**Performance:**
- Typical response time: 1-2 seconds
- Timeout: 5 seconds
- Circuit breaker protection for service resilience

## Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `companyId` | string | path | Yes | The unique identifier of the company. |
| `customerId` | string | query | No | The unique identifier of the customer (for multi-tenant scenarios). |
| `Context` | string | header | No | Optional header context. |

## Request Body

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

| Property | Type | Required | Description |
|---|---|---|---|
| `hsCode` | string | **Yes** | The HS code to verify. Must be 6-12 digits, optionally followed by up to 2 letters. Example: `7323997000`. |
| `classification` | HSClassificationModel | **Yes** |  |

## Responses

| Status | Description | Schema |
|---|---|---|
| 200 | Successful verification response | `HsCodeVerificationResponse` |
| 401 | Authentication required. Can be caused by a missing or incorrect credentials. | `ErrorInfo` |
| 402 | The company is not provisioned for hs_code validation. | `ErrorInfo` |
| 422 | Validation error - missing required fields or invalid HS code format. | `ErrorInfo` |
| 500 | An invalid exception handler routine has been detected. | `ErrorInfo` |
| 503 | Service unavailable - ML classification service not responding or circuit breaker is open. | `ErrorInfo` |

### 200 Response: `HsCodeVerificationResponse`

| Property | Type | Required | Description |
|---|---|---|---|
| `verified` | boolean | **Yes** | Whether the HS code was verified as appropriate for the product Example: `true`. |
| `providedHsCode` | string | **Yes** | Echo of the HS code that was submitted for verification Example: `7323997000`. |
| `classification` | object | No |  |
| `message` | string | **Yes** | Human-readable message about the verification result Example: `The provided HS code has been verified as appropriate for your product.`. |

## Example Request

```bash
curl -X POST "https://api-sandbox.classification.avalara.net/api/v2/companies/{companyId}/classifications/hscodes/verify" \
  -H "Authorization: Basic <credentials>" \
  -H "Accept: application/json" \
  -d '{
  "hsCode": "7323997000",
  "classification": {
    "id": "1234-SKU001-CA",
    "item": {
      "id": 56789,
      "companyId": 3402,
      "itemCode": "ABC",
      "parentCode": "",
      "description": "Vera Wang Night Gown",
      "summary": "",
      "itemGroup": "Clothing > Women > Formal",
      "createdDate": "",
      "classificationParameters": [
        {
          "name": "url",
          "value": "http://merchant_host.com/path_to_product/SKU001",
          "unit": ""
        },
        {
          "name": "hs_code_test",
          "value": "9504900090",
          "unit": "USD"
        },
        {
          "name": "price",
          "value": "12.31",
          "unit": "USD"
        }
      ],
      "parameters": [
        {
          "name": "weight",
          "value": "10.2",
          "unit": "lb"
        }
      ]
    },
    "activity": "HS_FULL",
    "countryOfDestination": "CA",
    "hsCode": 320250,
    "status": "CLASSIFIED",
    "resolution": "",
    "confidence": "",
    "confidenceDescription": "",
    "possibleHsCodes": "[ \"1009\", \"1065\" ]",
    "productUpdate": "",
    "validCODs": [
      "CA",
      "US"
    ],
    "invalidCODs": [
      "XX",
      "ZZ"
    ]
  }
}'
```