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.

The code for destination country in ISO 3166-1 alpha-2 format.

destination

The code for origin country in ISO 3166-1 alpha-2 format.

origin

txid

The HS (Harmonized System) code for the product.

hscode

The username associated with the certificate.

username

fullname

avalara-version

Authentication failed due to invalid or missing authentication token.

Customer is not authorized to access this resource.

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

Classification request body. The 'state' field in the request must be either 'START' or 'CONTINUE' and determines which type of request is processed.

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.

language

Indicates whether to retrieve import notes. Set to true to retrieve import notes, or false to retrieve export notes.

import

The format for the response. Allowed values: json, html.

format

Returns notes and documentation for the requested HS code, destination, and language.

Notes not found for the specified HS code, destination, and language.

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

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.

avalaraId

Returns the user profile for the authenticated request.

selfservicetarrifclassification

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.

Invalid Request

Human-readable explanation of the specific error condition. Suitable for surfacing to end users or logging.

HTTP status code returned with the error response.

Identifier of the interaction (question) being answered. This corresponds to the 'id' field of an interaction returned in the previous classification response.

Discriminator identifying this as a request to continue an existing classification. Must be 'CONTINUE'.

Identifier of the classification transaction returned by a previous classification response. Note: this request field is named 'txid' (lowercase 'i') for backwards compatibility, while the corresponding response field is 'txId'. Both refer to the same value.

Answers selected for the current interaction. Each entry in the list is a map with the fixed keys 'first' and 'second'. The semantics depend on the interaction's 'type' field returned in the previous response:
- SELECTION (single answer): one entry where 'first' is the selected option id and 'second' is the option's user-visible label.
- VALUED (multiple ingredients, mixed content): one entry per ingredient where 'first' is the option id and 'second' is the ingredient's percentage as a numeric string. The percentages across all entries must sum to 100.

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.

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.

antique

Definition or descriptive gloss of the option when available. May be empty.

Frequency count from the underlying ontology, indicating how often this option occurs for products of this type.

Identifier of this option (UUID). Echo this value as the 'first' field of a values entry in a continue request to select this option.

Optional generalization category ("kind of") for the option, such as a material family or product class. May be empty.

Display name of the option in the response language.

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.

Concept hierarchy path of the option, with components separated by '//'. Populated for ITEM-type interactions; null for other interaction types.

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"

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.

composition

True when the currently-selected option is the "other" / fallback option.

Available options (candidate answers) for this interaction. Each entry describes one option, including its identifier, display name, and current selection state.

True when this interaction includes an explicit "other" / fallback option.

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.

Comma-separated list of HS headings or subheadings that remain in scope for this interaction's solution space. Sorted ascending.

Identifier of this interaction. Echo this value as 'interactionid' in a continue request to answer this specific question.

Source of the answer for this interaction.

Localized display label of the question's category. Always equal to 'name' (both fields carry the same value, retained for backward compatibility).

Response language as an ISO 639-1 code. Defaults to 'EN'.

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".

True when the answer chosen for this interaction conflicts with a profile rule that would otherwise apply.

Definition of the selected option, populated only for SELECTION interactions when the selected option has a definition. Empty otherwise.

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 "<percentage>% <name>" entries. Lazily computed from 'attrs' when not explicitly set.

True when the question carries a known semantic ambiguity (for example, the product description matches multiple distinct concepts).

Wire-level interaction type. Determines how the caller should answer the question and how 'attrs[].value' / 'attrs[].number' should be interpreted.

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.

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.

Interactions whose answer was assumed by the engine via exception rules rather than asked of the user.

Authoritative sources (for example, CROSS rulings) that support the current classification.

Definition of the selected item from the underlying ontology. Empty when no definition is available.

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.

Display name of the item currently selected by the engine. Set to "UNKNOWN_ITEM" when no item could be identified.

Concept hierarchy paths ("//"-separated) of candidate items inferred from the product description. Useful for understanding how the engine interpreted the input.

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.

Selected Item Path: concept hierarchy path ("//"-separated, root-to-leaf) of the selected item.

Build timestamp of the underlying classification graph used for this response. Returned as a free-form string wrapped in literal single quotes.

HS schedule version used for this classification. Equal to 'schedule'.

Time spent processing the request, in milliseconds.

Human-readable detail of the error, populated when one of the *Error flags is set.

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.

True when the engine raised an ItemOutOfScopeException, indicating the selected item falls outside the supported tariff scope (HTTP-level status 900). Null otherwise.

Interactions whose answer is currently known (resolved), either by a profile rule or because the user has already answered them.

Response language as an ISO 639-1 code, echoing the language used to build the response.

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.

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.

All past interactions in the order they were asked or resolved during this classification session.

HS headings that remain in scope as potential matches given the information gathered so far.

Product description that was submitted in the originating classification request, echoed back here for reference.

Comma-separated list of GRI rules and HS legal notes that justify the current classification.

HS schedule version used for this classification. Equal to 'dataVersion'.

True when the engine encountered an unhandled or unrecoverable error (HTTP-level status 901). Null when no system error occurred.

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.

Destination country code in ISO 3166-1 alpha-2 format. When provided, the customer must be subscribed to this destination.

Response language as an ISO 639-1 code. Defaults to 'EN' when omitted.

Country of origin in ISO 3166-1 alpha-2 format.

Free-form product description to classify. Required.

Discriminator identifying this as a request to start a new classification. Must be 'START'.

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.

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.

United States

Date from which the current HS version became effective for this destination, in ISO 8601 (YYYY-MM-DD) format.

Harmonized System (HS) version that applies to this destination.

Destination country code in ISO 3166-1 alpha-2 format.

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.

AvaTax account identifier for the customer.

Display name of the customer or organization.

Destination countries supported by the customer's profile, with the HS version and effective date that applies to each.

Maximum number of destinations the customer is allowed to subscribe to.

Destination country codes (ISO 3166-1 alpha-2, uppercase) the customer is currently subscribed to.

Services the customer is subscribed to. Known values include XBOSelfServe (Self-Serve Tariff Classification), XBOTariffContent (Tariff Content), and XBOTradecompliance (Trade Compliance).

### 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=<avatax_account_id>&client_secret=<license key>&scope=avatax_api"
    ```
    Sample response (json)
    ```json
        {
            "access_token": "<jwt_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.


Avalara Cross Border Classification

Classification request with state field that must be either 'START' or 'CONTINUE'.