# Avalara Cross Border Classification

### Access to the Production API
To interact with this API, you need to acquire a bearer token.
To acquire a bearer token:
1. [Create a License Key](https://knowledge.avalara.com/bundle/bhk1662649440973_bhk1662649440973/page/Get_your_license_key.html).
2. Call Avalara Identity to get an access token:
    ```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)
    ```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
To interact with the Sandbox API, you can request for a bearer token from your Avalara integration specialist.
You can use the bearer token issued for a fixed number of requests against the sandbox API.

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

**Version:** 1.0
**Base URL:** /

---

## Endpoints

### Classification

#### Classify products.

`POST /hscodeselfclassify/classification`

Classifies products based on the provided request data. Supports start and continue actions for interactive classification.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `avalara-version` |  | header | Yes | API version. Current version is 1.0. |


### Profile

#### Get user profile.

`GET /hscodeselfclassify/profile/{avalaraId}`

Gets the user profile based on the authentication token. Returns profile details including ID, customer information, and subscribed destinations.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `avalaraId` | string | path | Yes | AvaTax account identifier of the profile to retrieve. Must match the 'avatax_account_id' claim of the bearer token; the request is rejected with HTTP 401 otherwise. |
| `avalara-version` |  | header | Yes | API version. Current version is 1.0. |


### Notes

#### Get notes for HS code.

`GET /hscodeselfclassify/notes/{destination}/{language}/{hscode}`

Gets notes and documentation for a specific HS code based on destination country and language. Supports both import and export notes with JSON or HTML format options.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `destination` | string | path | Yes | The code for destination country in ISO 3166-1 alpha-2 format. |
| `language` | string | path | Yes | The language code for the response. |
| `hscode` | string | path | Yes | The HS (Harmonized System) code for the product. |
| `import` | boolean | query | No | Indicates whether to retrieve import notes. Set to true to retrieve import notes, or false to retrieve export notes. |
| `format` | string | query | No | The format for the response. Allowed values: json, html. |
| `avalara-version` |  | header | Yes | API version. Current version is 1.0. |


### Certificates

#### Get certificate.

`GET /hscodeselfclassify/certificate/{destination}/{origin}/{txid}/{hscode}`

Gets a PDF certificate based on destination country, origin country, transaction id, and HS code. Returns the certificate as a PDF file attachment ready for download or viewing.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `destination` | string | path | Yes | The code for destination country in ISO 3166-1 alpha-2 format. |
| `origin` | string | path | Yes | The code for origin country in ISO 3166-1 alpha-2 format. |
| `txid` | string | path | Yes | The transaction ID of the product. |
| `hscode` | string | path | Yes | The HS (Harmonized System) code for the product. |
| `username` | string | query | No | The username associated with the certificate. |
| `fullname` | string | query | No | Full name to include on the certificate. |
| `avalara-version` |  | header | Yes | API version. Current version is 1.0. |

---

## Models

### ClassificationStartRequest

Request body used to start a new self-serve tariff classification. The 'state' field acts as the discriminator and must be 'START'. 'proddesc' is required; 'destination', 'origin', and 'lang' are optional.

### ClassificationContinueRequest

Request body used to continue an in-progress self-serve tariff classification by answering the questions returned in a prior response. The 'state' field acts as the discriminator and must be 'CONTINUE'. All fields are required.

### ClassificationRequest

| Property | Type | Description |
|---|---|---|
| `state` | string |  |

### ClassificationResponseAttribute

An option/attribute returned for a classification interaction. Each attribute represents a candidate answer (e.g. a material, condition, or ingredient) the caller may select when continuing the classification.

| Property | Type | Description |
|---|---|---|
| `id` | string | Identifier of this option (UUID). Echo this value as the 'first' field of a values entry in a continue request to select this option. |
| `name` | string | Display name of the option in the response language. |
| `path` | string | Concept hierarchy path of the option, with components separated by '//'. Populated for ITEM-type interactions; null for other interaction types. |
| `value` | string | Selection or weighting state of the option. For VALUED interactions, this is the percentage assigned to the option as a numeric string ("0" when no percentage was set). For SELECTION and other interaction types, this is the literal string of the option, e.g. "knitted" |
| `number` | number | Numeric form of 'value', provided as a convenience for VALUED (mixed-content) interactions so clients do not need to parse the string. When populated, equals Double.valueOf(value). Null for non-VALUED interactions, and also null when 'value' is non-numeric. |
| `kindOf` | string | Optional generalization category ("kind of") for the option, such as a material family or product class. May be empty. |
| `def` | string | Definition or descriptive gloss of the option when available. May be empty. |
| `frequency` | number | Frequency count from the underlying ontology, indicating how often this option occurs for products of this type. |
| `part` | boolean |  |

### ClassificationResponseInteraction

A classification interaction returned in a classification response. Interactions group together a question prompt, the available options (attrs), and metadata about how the question was answered or inferred.

| Property | Type | Description |
|---|---|---|
| `id` | string | Identifier of this interaction. Echo this value as 'interactionid' in a continue request to answer this specific question. |
| `name` | string | Localized display label of the question's category. Always equal to 'label' (both fields carry the same value, retained for backward compatibility). May include compositional context, for example "whole of the propeller" or "power source location of the power source". For TARIFF_SCHEDULE interactions this is the literal string "underspecified". |
| `label` | string | Localized display label of the question's category. Always equal to 'name' (both fields carry the same value, retained for backward compatibility). |
| `category` | string | Canonical, untranslated machine-readable identifier of the question's category. Stable across response languages. |
| `type` | string | Wire-level interaction type. Determines how the caller should answer the question and how 'attrs[].value' / 'attrs[].number' should be interpreted. |
| `heading` | string | Single HS heading or subheading(4 or 6-digit code) associated with this interaction, if any. Empty string when the interaction is not tied to a specific heading. |
| `attrs` | array | Available options (candidate answers) for this interaction. Each entry describes one option, including its identifier, display name, and current selection state. |
| `headings` | string | Comma-separated list of HS headings or subheadings that remain in scope for this interaction's solution space. Sorted ascending. |
| `inputType` | string | Source of the answer for this interaction. |
| `selectedString` | string | Display string of the currently-selected answer(s). For SELECTION interactions, this is the selected option's name. For VALUED interactions, this is a semicolon-separated list of "% " entries. Lazily computed from 'attrs' when not explicitly set. |
| `unSelectedString` | string | Display string for unselected options, with a language-specific negative prefix (for example, "not cotton; not wool"). Lazily computed from 'attrs' when not explicitly set; null until first computed. |
| `selectedDefinition` | string | Definition of the selected option, populated only for SELECTION interactions when the selected option has a definition. Empty otherwise. |
| `ruleMismatch` | boolean | True when the answer chosen for this interaction conflicts with a profile rule that would otherwise apply. |
| `hasOther` | boolean | True when this interaction includes an explicit "other" / fallback option. |
| `language` | string | Response language as an ISO 639-1 code. Defaults to 'EN'. |
| `semanticAmbiguity` | boolean | True when the question carries a known semantic ambiguity (for example, the product description matches multiple distinct concepts). |
| `answerIsOther` | boolean | True when the currently-selected option is the "other" / fallback option. |
| `answeredWithRule` | boolean |  |

### ClassificationResponseProjection

Response payload for a self-serve classification request. Carries the transaction identifier, the current state of the classification (selected item, candidate HS code, pending and resolved interactions), supporting metadata, and any error indicators.

| Property | Type | Description |
|---|---|---|
| `txId` | string | Identifier of the classification transaction. Echo this value as 'txid' (lowercase 'i') in a continue request. Note: this response field is named 'txId' (camelCase) while the corresponding request field is 'txid' (lowercase 'i'); both refer to the same value, the casing difference is retained for backward compatibility. |
| `languageCode` | string | Response language as an ISO 639-1 code, echoing the language used to build the response. |
| `productDescription` | string | Product description that was submitted in the originating classification request, echoed back here for reference. |
| `currentItemPaths` | array | Concept hierarchy paths ("//"-separated) of candidate items inferred from the product description. Useful for understanding how the engine interpreted the input. |
| `currentItemName` | string | Display name of the item currently selected by the engine. Set to "UNKNOWN_ITEM" when no item could be identified. |
| `currentSIP` | string | Selected Item Path: concept hierarchy path ("//"-separated, root-to-leaf) of the selected item. |
| `currentItemDef` | string | Definition of the selected item from the underlying ontology. Empty when no definition is available. |
| `hsCode` | string | Classified HS code (typically 6 or 8 digits; 4-digit headings are zero-padded to 6 digits when the schedule stops at HS6). Empty until enough information has been gathered to reach a classification. |
| `assumedInteractions` | array | Interactions whose answer was assumed by the engine via exception rules rather than asked of the user. |
| `knownInteractions` | array | Interactions whose answer is currently known (resolved), either by a profile rule or because the user has already answered them. |
| `orderedInteractions` | array | All past interactions in the order they were asked or resolved during this classification session. |
| `currentItemInteraction` | ClassificationResponseInteraction | The currently pending item-selection interaction, when the engine is asking the caller to confirm which item the product description refers to. Null when no item-selection question is pending. |
| `currentQuestionInteraction` | ClassificationResponseInteraction | The currently pending question that the caller is expected to answer in a continue request. Null when the classification has reached a final HS code or has errored out. |
| `potentialHeadings` | array | HS headings that remain in scope as potential matches given the information gathered so far. |
| `rational` | string | Comma-separated list of GRI rules and HS legal notes that justify the current classification. |
| `authSources` | array | Authoritative sources (for example, CROSS rulings) that support the current classification. |
| `duration` | integer | Time spent processing the request, in milliseconds. |
| `systemError` | boolean | True when the engine encountered an unhandled or unrecoverable error (HTTP-level status 901). Null when no system error occurred. |
| `mixedContentError` | boolean | True when the engine raised a MixedContentException, indicating the product description requires a mixed-content (VALUED) breakdown that has not been provided (HTTP-level status 905). Null otherwise. |
| `multiItemError` | boolean | True when the engine raised a MultipleItemException, indicating the product description references more than one distinct item (HTTP-level status 902), like sets and kits. Null otherwise. |
| `itemOutOfScopeError` | boolean | True when the engine raised an ItemOutOfScopeException, indicating the selected item falls outside the supported tariff scope (HTTP-level status 900). Null otherwise. |
| `errorDetail` | string | Human-readable detail of the error, populated when one of the *Error flags is set. |
| `dataVersion` | string | HS schedule version used for this classification. Equal to 'schedule'. |
| `dataBuildDate` | string | Build timestamp of the underlying classification graph used for this response. Returned as a free-form string wrapped in literal single quotes. |
| `schedule` | string | HS schedule version used for this classification. Equal to 'dataVersion'. |

### AvalaraAPIExceptionDetails

Standard error response payload returned by the API when a request fails. Provides a short error title, the HTTP status code, and a human-readable detail message.

| Property | Type | Description |
|---|---|---|
| `title` | string | Short, human-readable error category. |
| `status` | integer | HTTP status code returned with the error response. |
| `detail` | string | Human-readable explanation of the specific error condition. Suitable for surfacing to end users or logging. |

### DestinationProjection

A destination country supported by the customer's profile, including the country code, display name, and the Harmonized System (HS) version that applies for that destination.

| Property | Type | Description |
|---|---|---|
| `iso2Code` | string | Destination country code in ISO 3166-1 alpha-2 format. |
| `name` | string | Display name of the destination country. |
| `hsVersion` | string | Harmonized System (HS) version that applies to this destination. |
| `effectiveDate` | string | Date from which the current HS version became effective for this destination, in ISO 8601 (YYYY-MM-DD) format. |

### ProfileProjection

Customer profile information, including the AvaTax account identifier, the customer name, the list of subscribed services, the supported and subscribed destination countries, and the customer's destination subscription limit.

| Property | Type | Description |
|---|---|---|
| `avalaraId` | string | AvaTax account identifier for the customer. |
| `customer` | string | Display name of the customer or organization. |
| `subscribedServices` | array | Services the customer is subscribed to. Known values include XBOSelfServe (Self-Serve Tariff Classification), XBOTariffContent (Tariff Content), and XBOTradecompliance (Trade Compliance). |
| `destinations` | array | Destination countries supported by the customer's profile, with the HS version and effective date that applies to each. |
| `subscribedDestinations` | array | Destination country codes (ISO 3166-1 alpha-2, uppercase) the customer is currently subscribed to. |
| `maxSubscribedDestinations` | integer | Maximum number of destinations the customer is allowed to subscribe to. |