Returns the roles for the current account. Account is resolved from the JWT claim avatax_account_id. Restricted to Avalara admin users.

Unique correlation ID for distributed tracing. If not provided, the server generates one.

X-Correlation-Id

API version. Required for all Avalara public APIs.

avalara-version

Returns the matrix of (account type, role) x (feature) toggles plus the catalogs the admin UI needs to render rows / columns. Restricted to Avalara admin users.

Forbidden — requires Avalara admin role.

Applies a list of (accountType, role, featureKey, enabled) updates as upserts. Subsequent /v1/me/access calls observe the new state immediately. Restricted to Avalara admin users.

Invalid request body or unknown account type / role / feature.

Validates the file inline and returns the outcome in the same response. Reports whether the file is valid or invalid, with any issues found.

Unique identifier of the file to validate.

Validation completed; outcome is valid or invalid

Infers the structure of the file (sheets and columns with detected types) and returns it synchronously.

Unique identifier of the file to analyze.

Schema could not be inferred from the file

Sets document and all its intake requests to ACTIVE. Only allowed when document status is IN_REVIEW.

Unique identifier of the document to activate.

Document and intake requests activated successfully.

Bad request - document is not in IN_REVIEW status.

Activate a document and its intake requests.

Accepts a list of filenames. For each filename, creates a document record and returns a pre-signed
upload URL and form fields. Response order matches the request. After upload, files are validated
and processed; validation failures are reported asynchronously.


Upload service unavailable or init failed.

Records a document for a file that the caller has already validated and uploaded.
The standard upload flow exposed via /upload-sessions still applies for
external clients that need a pre-signed upload URL.


Register a document for a file already placed in storage.

Creates intake requests by manually entering all required data fields.
If no document is set on the requests, a new document is created and assigned to all requests.
Validates all required fields and returns the created intake requests.

**Required Fields:**
- `name` - Product name
- `sku` - Stock Keeping Unit
- `quantity` - Order quantity (must be positive)
- `unitPrice` - Unit price (must be positive).


Bad request - validation failed or empty list.

Sets a single intake request to ACTIVE. Only allowed when intake request status is IN_REVIEW. If all intake requests for the parent document become ACTIVE, the document is also activated automatically.

Unique identifier of the intake request to activate.

intakeRequestId

Bad request - intake request is not in IN_REVIEW status.

Retrieves documents with optional filters and pagination.
Returns basic document metadata only; for aggregated metrics (line count, totals), use GET /documents/report.

**Available Filters:**
- `status` - Filter by document status (e.g., NEW, PROCESSED, ERROR)
- `documentType` - Filter by document type (e.g., MANUAL, PURCHASE_ORDER_REQUISITION, ISF_FILING)
- `fromDate` - Filter by creation date from (inclusive)
- `toDate` - Filter by creation date to (inclusive)
- `deleted` - Include soft-deleted documents (default: false)

**Pagination:**
- `$skip` - Number of items to skip (offset)
- `$top` - Maximum number of items to return (default: 10)
- `$orderby` - Sorting criteria, e.g. `createdAt desc`.


Filter criteria for retrieving documents.

query

page

size

Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.

sort

List documents with optional filters and pagination.

Returns a single document by ID for the current tenant. Returns 404 if not found or document belongs to another tenant.

Unique identifier of the document to retrieve.

Marks the document and all its intake requests as deleted. Records are retained with deletedAt and deletedBy set.

Unique identifier of the document to delete.

Document and intake requests soft-deleted successfully.

Bad request - document is already deleted.

Soft delete a document and its intake requests.

Returns a tenant-scoped document report used to render the operations landing page:
total, breakdown per status, plus pre-computed buckets (needsAction, errors, delivered).
Soft-deleted records are excluded.


Document report aggregates for landing page.

Returns the count of documents per status (ERROR, NEW, IN_REVIEW, ACTIVE) for the current tenant. Excludes soft-deleted documents. Optionally filter by documentType query parameter to count only documents of that type.

Optional single document type filter; when set, only documents of this type are counted.

documentType

Optional list of document types; when provided, takes precedence over documentType and counts documents whose type is in this list.

documentTypes

Document status counts retrieved successfully. Returns the number of documents grouped by status, optionally filtered by document type.

Retrieves documents with computed metrics from related intake requests (paginated).

**Available Filters:**
- `status` - Filter by document status (e.g., NEW, ERROR, IN_REVIEW, ACTIVE)
- `fileName` - Filter by original file name (partial, case-insensitive)
- `documentType` - Filter by document type
- `fromDate` - Filter by creation date from (inclusive)
- `toDate` - Filter by creation date to (inclusive)
- `deleted` - Include soft-deleted documents (default: false).


Filter criteria for retrieving document report results.

Bad request - invalid pagination parameters.

List documents with aggregated intake request metrics.

Returns a single ERP account mapping by its identifier, scoped to the current tenant.

Unique identifier of the ERP account mapping.

Updates an existing ERP ↔ tenant mapping for the current tenant. The request body
carries the full editable state of the mapping; server-managed fields
(`status`, `versoriConnectionId`, `lastIntegrationStartedAt`, timestamps) are
not part of the payload and are not touched directly by the caller.

When `erpAccountId` or `erpType` change, or when the mapping is not currently
in the `ACTIVE` state, the integration is re-triggered against the Versori
management API; on failure the call returns `502` and the mapping is left
in the `FAILED` state with the new values persisted so the caller can retry.


Another mapping for this ERP account already exists.

Versori integration could not be re-started.

Replace the editable fields of an existing ERP account mapping.

Returns a paginated list of ERP account mappings for the current tenant.

List ERP account mappings for the current tenant.

Persists a new ERP account ↔ TradeHub tenant mapping for the current tenant
(`avataxAccountId` from the JWT) and immediately calls the Versori management API
to start the integration for the resulting `(tenantId, erpAccountId)` pair.

The returned `versoriConnectionId` is the connection that fronts subsequent
inbound and outbound syncs for vendors, items and purchase orders.

If Versori cannot start the integration, the mapping is still persisted but its
`status` is set to `FAILED`; the caller can retry later.


A mapping for this ERP account already exists.

Versori integration could not be started.

Register ERP ↔ tenant mapping and start Versori integration.

Retrieves an intake request by its unique identifier.

Unique identifier of the intake request to retrieve.

Updates an existing intake request by its unique identifier. Updated fields are marked as user-edited in the detail response.

Unique identifier of the intake request to update.

Marks the intake request as deleted. The record is retained with deletedAt and deletedBy values and is excluded from default lists and status counts.

Unique identifier of the intake request to delete.

Intake request soft-deleted successfully.

Retrieves intake requests with optional filters and pagination.

Filter criteria for retrieving intake requests.

Intake requests retrieved successfully. Returns a paginated list of intake requests.

List intake requests with optional filters and pagination.

Validates the intake request and returns details about missing mandatory fields. This endpoint re-validates the request on each call based on current field values. Use it for detail views, troubleshooting, and on-demand validation checks. Avoid using it for list views or high-frequency polling.

Unique identifier of the intake request to validate.

Validation details retrieved successfully.

Retrieves an intake request by its unique identifier, including extracted field metadata such as confidence level, extracted value, and bounding box coordinates.

Detailed intake request retrieved successfully.

Returns a tenant-scoped intake request report used to render the operations landing page:
total, breakdown per status, plus pre-computed buckets (needsReview, ready, failed,
pendingClassification). Soft-deleted records are excluded.


Intake request report aggregates for landing page.

Returns the count of intake requests per status (ACTIVE, IN_REVIEW, COMPLETED, FAILED) for the current tenant. Excludes soft-deleted requests.

Status counts retrieved successfully. Returns the number of intake requests grouped by status.

Returns the supported ISO country codes and country names for use in select and dropdown components.

Supported countries retrieved successfully. Returns a list of country codes and names.

Returns a stored inventory item record scoped to the current tenant.

Replaces the caller-editable fields of an existing tenant item (identity, classification,
pricing, physical attributes, flags, custom fields and product attributes). ERP-derived and
read-only fields (averageCost, lastPurchasePrice, quantities, source and audit) are preserved.


Another item with the same name already exists.

Returns inventory items for the current tenant, paginated. Soft-deleted records are excluded.
Supports Avalara-style **$skip**, **$top**, and **$orderby** (or **page**, **size**, **sort**).
Optional **search** matches item name, display name, or ERP internal ID (case-insensitive).
Optional **itemType** filters to an exact enum value.
Optional **unclassifiedOnly** restricts results to items still pending HS classification.


Free-text search (item name, display name, ERP ID).

search

itemType

When true, returns only items pending HS classification (no HS tariff number).

unclassifiedOnly

Creates an inventory item record for the current tenant. The payload follows standard
item catalog concepts (name, type, pricing, weight, HS tariff, manufacturer details).
Optional `versoriConnectionId` and `erpInternalId` support ERP sync metadata.


An item with the same identifier already exists.

Searches the tenant Item Master for catalog rows similar to the supplied product text and
optional attributes. Returns ranked candidates with blended similarity scoring.


Maximum number of matches to return (1–10).

minScorePercent

When true, only items with an HS tariff number are candidates.

onlyClassified

Runs similarity search for up to 100 product queries. Response lists align with the request order.

Updates the HS tariff number and its origin (sourceType) on a tenant item.
Used by the classification worksheet write-back when a classification is completed.


Returns a tenant-scoped item report used to render the operations landing page:
total, pendingHts, classified, and the classification coverage ratio (0.0 to 1.0).
Soft-deleted records are excluded.


Invalidates the cached entitlements for the authenticated user and re-fetches them from AvaTax. Use this after a plan change (e.g. a new product was purchased for the account) so the new capabilities become visible without waiting for the cache TTL.

Returns the Avalara product capabilities (AvaTax, MTCC, ATCC, etc.) granted to the authenticated user, resolved from the AvaTax entitlements endpoint and cached server-side.

Returns the effective access for the authenticated user: the AvaTax capabilities, the single resolved account tier (highest of ATCC > MTCC > AVATAX > TRADE_HUB), the user's role inside that tier (ADMIN / USER / NO_ACCESS) derived from AvaTax entitlements, and the feature keys enabled for that (accountType, role) cell in the admin matrix. The portal uses allowedFeatures to gate routes and menus.

Creates or updates an onboarding task with JSON payload.

companyId

Optional request identifier used for tracing and diagnostics.

X-Request-ID

Creates or updates an onboarding task with a multipart file upload.

Unique request identifier used for tracing and idempotency.

Retrieves all onboarding task data for a given tenant and optional company.

Returns all companies available for onboarding from the AvaTax account.

For each scenario, creates the intake request, keeps the best classification suggestion, runs the vendor comparison and auto-selects the best vendor, persisting how each decision was made.

Scenarios processed; one result per request item.

Bad request. The payload is empty or invalid.

Run one or more procurement scenarios end to end.

Returns purchase orders for the current tenant, paginated. Soft-deleted records are excluded.
Supports Avalara-style **$skip**, **$top**, and **$orderby** (or **page**, **size**, **sort**).


Filter by overall status (RED, AMBER, GREEN, BLACK).

status

Free-text search across P.O. number and vendor name.

Filter by vendor entity ID (Mongo entityId).

vendorId

Filter by catalog item ID on PO line items.

itemId

Paginated purchase orders for the tenant.

Creates a purchase order for the current tenant. Payload follows standard purchase order
concepts (vendor entity, currency, addresses, item lines).
Optional `versoriConnectionId` and `erpInternalId` support ERP sync metadata.


Posts the purchase order to the Versori switchboard incoming-webhook node configured
for this tenant, which routes the payload to the customer's ERP. The Versori
organisation/board/node ids are read from the tenant's ERP account mapping
(see `POST /v1/onboarding/erp-mappings`).

Returns 200 OK with sync metadata once Versori has accepted the payload. If the
tenant has no mapping or the mapping is missing Versori board details, returns
422 Unprocessable Entity. If Versori itself rejects the call, returns 502 Bad Gateway.


Tenant has no Versori sync configuration.

Trigger an outbound purchase-order sync to the ERP via Versori.

Endpoint invoked by an ERP integration (Versori) after it has pulled purchase
orders from the customer's ERP. Accepts a batch of purchase orders and upserts
each one for the target tenant.

Tenant resolution:
The token used by the integration is **not** required to carry an
`avatax_account_id` claim. Instead, the tenant is read from the
`X-Avalara-Tenant-Id` request header, which the integration must populate
with the AvaTax account ID of the customer whose purchase orders are being
delivered. The token itself is still validated by the standard JWT filter and
must grant the `INTAKE_API` role.

Upsert behaviour:
Each entry is matched against existing purchase orders by the tuple
`(tenantId, erpInternalId)`. Match → in-place update preserving the
TradeHub id and audit timestamps. No match (or no `erpInternalId`) → create.
Per-item failures are isolated: one bad entry does not roll back the batch;
the failure is reported in the corresponding `results[i]` entry.


AvaTax account ID of the customer whose purchase orders are being delivered. Required.

X-Avalara-Tenant-Id

Batch processed (some items may have failed; see `results[]`).

Validation failed (missing header or empty batch).

Receive an inbound batch of purchase orders from an ERP integration (Versori callback).

Fires the global Versori-hosted inbound webhook so Versori pulls purchase
orders from the customer's ERP and pushes them back to TradeHub via
`POST /v1/purchase-orders/inbound`. They then appear on the Purchase Order
Visibility list for the tenant.

The call is fire-and-forget: a `200 OK` response means Versori has accepted
the trigger; purchase orders may still take a few moments to land on the list.
Returns `502 Bad Gateway` if Versori rejects the call.


Trigger an inbound purchase-order import from the ERP via Versori.

Sets the classificationStatus on the purchase order header. Only the CLASSIFICATION_WORKSHEET module is currently accepted.

Unsupported moduleName or invalid status value.

Sets the classificationStatus on a specific purchase order line. Only the CLASSIFICATION_WORKSHEET module is currently accepted.

lineNumber

Returns a stored purchase order scoped to the current tenant.

Returns a tenant-scoped purchase order report used to render the operations landing page:
overall status breakdown plus pre-computed buckets (pastDueEntrySummary, preEntryPending,
approachingEta within next 7 days). Soft-deleted records are excluded.


Purchase order report aggregates for landing page.

Returns aggregated counts of purchase orders grouped by overall status for the current tenant.

Accepts a single audio clip (WAV, MP3, M4A, OGG, FLAC, or WebM) of a person describing
a product and returns a structured description with per-property confidence: a
description score, scored keywords ({value, confidence}), scored attributes
({name, value, confidence}), and a coarse overall confidence. The audio is processed
in-memory and not stored.


Opt-in diagnostics. When present (and not "false"/"0"), the response includes x-speech-model, x-speech-token-input, x-speech-token-output, and x-speech-estimated-cost headers describing the model call.

x-speech-trace-model

The audio is missing, empty, oversized, of an unsupported type, or could not be read

The audio was rejected by the speech model's content filter (finish_reason=content_filter)

Speech model request failed, returned no/invalid JSON, or was truncated (finish_reason=length)

Transcribe an uploaded audio clip into a product description

Calculates the total landed cost for multiple vendors, including duties, taxes, and Incoterm-driven logistics cost components.

Landed cost calculation completed successfully.

Bad request. The request payload is invalid or contains missing required fields.

Calculate landed cost for multiple vendors.

Exports tariff or landed cost comparison results to an XLSX file with formatted tables and calculated values.

Internal server error. An unexpected error occurred while generating the XLSX file.

Export tariff or landed cost comparison results to an XLSX file.

Calculates duty and tariff rates for multiple vendors and returns ranked comparison results.

Calculate duty rates for multiple vendors.

Classifies a product description and returns the corresponding tariff classification result.

Classify a product and return the corresponding HS code.

Retrieves the first saved vendor comparison scenario for the specified intake request, if one exists.

Unique identifier of the intake request whose saved scenario is retrieved.

Vendor comparison scenario retrieved successfully.

Intake request not found or no scenario saved.

Get the saved vendor comparison scenario for an intake request.

Creates a new vendor comparison scenario, or updates the existing one when an id is supplied. Scenario names must be unique within an intake request.

Unique identifier of the intake request for which the scenario is saved.

Vendor comparison scenario saved successfully.

A scenario with the same name already exists for this intake request

Save a vendor comparison scenario for an intake request.

Creates a copy of the specified vendor comparison scenario and appends (copy) to the scenario name.

Unique identifier of the intake request associated with the scenario.

Unique identifier of the scenario to duplicate.

scenarioId

Vendor comparison scenario duplicated successfully.

Returns a paginated list of vendor comparison scenarios for the specified intake request, with optional search and date filters.

Unique identifier of the intake request whose scenarios are retrieved.

Filter scenarios by scenario name using a case-insensitive search.

Filter scenarios by creation date in yyyy-MM-dd format.

createdDate

List vendor comparison scenarios for an intake request.

Soft-deletes the specified vendor comparison scenario. The scenario will no longer appear in list results.

Unique identifier of the scenario to delete.

Vendor comparison scenario deleted successfully.

Called by the screening engine when a historical screening run changes decision
after a watchlist update. Flips all vendors whose `lastScreeningRunId` matches the
supplied `originalRunId` back to `PENDING` so the standard screening scheduler
re-screens them and applies per-vendor decisions. Idempotent on `(tenantId, reverseRunId)`.


Callback accepted; vendors re-queued for screening.

Returns vendors for the current tenant, paginated. Soft-deleted records are excluded.
Supports Avalara-style **$skip**, **$top**, and **$orderby** (or **page**, **size**, **sort**).
Optional **search** matches company name, email, or ERP internal ID (case-insensitive).
Optional **status**, **category**, and **screeningStatus** filter to exact enum values.


Free-text search (company name, email, ERP ID).

TradeHub Crossborder API

Modules