> ## Documentation index > Fetch the complete documentation index at: https://docs.htspilot.com/llms.txt > Use this file to discover all available pages before exploring further. # Review > The queue of lookups that need a person, and the reviewer's decision on a lookup - approve, override, reject, reopen or comment. The review queue holds the lookups that need a person: those that ended in `needs_review`, `needs_info` or `error` and have no decision yet. A reviewer decides on a lookup, and the decision is recorded next to the proposal, with who decided and why. The objects are lookups ([Lookups](/lookups.md)). Reading the queue takes the `entry` role, which sees its own lookups. Deciding and resolving need the `reviewer` or the `admin` role. ## The decision | `action` | Needs | Effect | | --- | --- | --- | | `approve` | - | Accepts the recommended code. `decision` becomes `approved`, `final_code` the recommended code | | `override` | `code` and `note` | Settles on another code. `code` must be a declarable line of the lookup's tariff schedule. `decision` becomes `overridden` | | `reject` | `note` | No code is accepted. `decision` becomes `rejected` | | `reopen` | - | Removes the decision. Answers `409` when there is none | | `comment` | `note` | Adds a note to the history without deciding | Every action is added to the `events` of the lookup. `approve`, `override` and `reject` send the webhook event `lookup.decided` ([Webhooks](/webhooks.md)); `reopen` and `comment` send none. A lookup that already has a decision answers `409` to another one: reopen it first. An `override` with the recommended code itself is recorded as `approved`. When the lookup belongs to a SKU, the decided code becomes the SKU's `current_code`. Comments are limited per minute ([Rate limits and quotas](/rate-limits.md)). ## List the review queue `GET /api/review` Lookups that need information, need review or failed, and have no decision yet. **Query parameters** | Name | Type | Required | Description | | --- | --- | --- | --- | | `q` | string or null | No | Up to 200 characters | | `status` | string[] or null | No | - | | `market` | string or null | No | - | | `include_resolved` | boolean | No | Default `false` | | `page` | integer | No | Minimum 1, default `1` | | `page_size` | integer | No | Minimum 1, maximum 200, default `20` | | `sort` | one of: newest, oldest, confidence, risk | No | Newest (default), oldest, confidence (least certain first), or risk (highest first, then oldest first). With confidence, failed lookups (confidence 0.0) come first. Default `"newest"` | | `date_from` | string or null | No | Created on or after this day (UTC) | | `date_to` | string or null | No | Created on or before this day (UTC) | | `created_by` | string or null | No | User id, or 'me'. Up to 32 characters | | `confidence_min` | number or null | No | Minimum 0, maximum 1 | | `confidence_max` | number or null | No | Minimum 0, maximum 1 | | `flag` | string or null | No | Review flag code, e.g. low_confidence. Pattern `^[a-z0-9_]{1,40}$` | **Returns** `200` with `Page`. **Errors**: `401` No valid API key was sent; `403` The role of the key, or the plan of the account, does not allow this call; `422` The request is not valid; `500` An unexpected failure. **Example request** ```bash curl "https://htspilot.com/api/review?page=1&page_size=20&sort=risk" \ -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME" ``` **Example response** `200` ```json { "items": [], "total": 0, "page": 1, "page_size": 20 } ``` Try it: https://docs.htspilot.com/explorer/#/Review/listReviewQueue The filters are those of the lookup list, without `kind` and `decision`. `sort=risk` puts the highest risk first. `include_resolved=true` also returns the lookups that were taken out of the queue. ## Count the review queue `GET /api/review/counts` The number of queue items per status, for the same filters as `GET /api/review`. **Query parameters** | Name | Type | Required | Description | | --- | --- | --- | --- | | `q` | string or null | No | Up to 200 characters | | `status` | string[] or null | No | - | | `market` | string or null | No | - | | `include_resolved` | boolean | No | Default `false` | | `date_from` | string or null | No | Created on or after this day (UTC) | | `date_to` | string or null | No | Created on or before this day (UTC) | | `created_by` | string or null | No | User id, or 'me'. Up to 32 characters | | `confidence_min` | number or null | No | Minimum 0, maximum 1 | | `confidence_max` | number or null | No | Minimum 0, maximum 1 | | `flag` | string or null | No | Review flag code, e.g. low_confidence. Pattern `^[a-z0-9_]{1,40}$` | **Returns** `200` with `ReviewCounts`. **Errors**: `401` No valid API key was sent; `403` The role of the key, or the plan of the account, does not allow this call; `422` The request is not valid; `500` An unexpected failure. **Example request** ```bash curl "https://htspilot.com/api/review/counts" \ -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME" ``` **Example response** `200` ```json { "total": 0, "counts": { "needs_info": 0, "needs_review": 0, "error": 0 } } ``` Try it: https://docs.htspilot.com/explorer/#/Review/countReviewQueue ## Decide on a lookup `POST /api/lookups/{lookup_id}/decision` **Changes data in your account when executed.** `approve` accepts the recommended code. `override` needs `code`, a declarable line of the lookup's tariff schedule, and a `note` with the reason. `reject` needs a `note`. `reopen` removes a decision. `comment` adds a note without deciding. Needs the reviewer or the admin role. **Path parameters** | Name | Type | Description | | --- | --- | --- | | `lookup_id` | string | - | **Request body** (`application/json`) | Name | Type | Required | Description | | --- | --- | --- | --- | | `action` | one of: approve, override, reject, reopen, comment | Yes | - | | `code` | string or null | No | Final code when action=override. Up to 24 characters | | `note` | string | No | Up to 2000 characters | **Returns** `200` with `LookupDetail`. **Errors**: `401` No valid API key was sent; `403` The role of the key, or the plan of the account, does not allow this call; `422` The request is not valid; `500` An unexpected failure. **Example request** ```bash curl -X POST "https://htspilot.com/api/lookups/2655d2f9c3b047c6906b25d45a24c522/decision" \ -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME" \ -H "Content-Type: application/json" \ -d '{ "action": "approve", "note": "Checked against the heading notes" }' ``` **Example response** `200` (long lists and texts are cut) ```json { "id": "2655d2f9c3b047c6906b25d45a24c522", "created_at": "2026-10-03T19:48:03.200629", "kind": "single", "batch_id": null, "row_index": null, "parent_lookup_id": "f4a2251d5dc941ec99f7d459e05082a5", "description": "Men's T-shirt, knitted, 100% cotton, short sleeves, crew neck", "market": "US", "dataset_version": "2026-SAMPLE", "status": "proposed", "status_label": "Proposed", "recommended_code": "6109.10.00.14", "recommended_description": "Chapter 61: Articles of apparel and clothing accessories, knitted or crocheted > T-shirts, singlets, tank tops and similar garments, knitted or crocheted > Of cotton > Men's or boys' > Other T-shirts", "hs6": "610910", "confidence": 0.74, "review_flags": [ { "code": "no_official_evidence", "message": "No official source confirms the proposed code" }, { "code": "demo_data", "message": "Tariff data is incomplete" } ], "risk": 18, "risk_level": "low", "resolved": true, "processing_ms": 37, "decision": "approved", "decision_label": "AI code approved", "final_code": "6109.10.00.14", "decided_at": "2026-10-03T19:48:03.423841Z", "created_by": "a7ba4a2440c7422fb695a1fd80d65ce5", "created_by_name": "Administrator", "sku_id": null, "language": "en", "comment_count": 1, "input": { "description": "Men's T-shirt, knitted, 100% cotton, short sleeves, crew neck", "material": "cotton", "use": "apparel", "composition": "60% cotton, 40% polyester", "origin": "VN", "notes": "Crew neck, no pockets", "market": "US", "tariff_version": "2026-SAMPLE" }, "origin_label": "Vietnam (VN)", "normalized": { "raw_description": "Men's T-shirt, knitted, 100% cotton, short sleeves, crew neck", "clean_description": "Men's T-shirt, knitted, 100% cotton, short sleeves, crew neck", "search_text": "men's t-shirt, knitted, 100% cotton, short sleeves, crew neck cotton 60% cotton, 40% polyester apparel crew neck, no pockets t-shirts", "language": "en", "category": "apparel", "materials": [ { "name": "cotton", "group": "textile", "percent": 60 }, { "name": "polyester", "group": "textile_manmade", "percent": 40 } ], "construction": "knitted", "gender": "men", "state": null, "electrical": false, "extra": { "material": "cotton", "use": "apparel", "composition": "60% cotton, 40% polyester", "origin": "VN", "notes": "Crew neck, no pockets" }, "missing": [], "flags": [], "product_type": null, "function": null, "search_terms": [], "extraction": { "method": "rules" }, "hs_headings": [], "abbreviations": {}, "translation": null, "material_groups": [ "textile", "textile_manmade" ] }, "result": { "status": "proposed", "status_label": "Proposed", "lang": "en", "recommended": { "code": "6109.10.00.14", "code_digits": "6109100014", "hs6": "610910", "hs6_display": "6109.10", "national_extension": "0014", "description": "Other T-shirts", "full_description": "Chapter 61: Articles of apparel and clothing accessories, knitted or crocheted > T-shirts, singlets, tank tops and similar garments, knitted or crocheted > Of cotton > Men's or boys' > Other T-shirts", "duty_rate": "16.5%", "retrieval_score": 0.916, "scores": { "bm25": 11.6074, "vector": 0.4186, "rrf": 0.03226, "overlap": 0.333, "leaf_overlap": 1, "attributes": 0.8, "tree": 1, "cross": 0, "final": 0.916, "legal": 0 }, "verdict": "recommended", "reasoning": "Tariff line: “Chapter 61: Articles of apparel and clothing accessories, knitted or crocheted > T-shirts, singlets, tank tops and similar garments, knitted or crocheted > Of cotton > Men's or boys' > Other T-shirts”. Matches: heading usually used for 'apparel' products; matches main material: cotton; matches construction: knitted; matches intended user: men.", "exclusion_reason": "", "citations": [ "W1", "N1" ], "signals": [ "heading usually used for 'apparel' products", "matches main material: cotton" ], "legal": { "status": "ok", "penalty": 0, "findings": [] }, "precedents": [], "duty": { "available": true, "rate_text": "16.5%", "rate_basis": "general", "effective_pct": 16.5, "min_pct": null, "max_pct": 16.5, "additional_pct": 0, "additional": [], "may_apply": [], "specific": false, "currency": "USD" } }, "tentative": false, "alternatives": [ { "code": "6109.10.00.12", "code_digits": "6109100012", "hs6": "610910", "hs6_display": "6109.10", "national_extension": "0012", "description": "T-shirts, all white, short hemmed sleeves, hemmed bottom, crew or round neckline, or V-neck, without pockets, trim or embroidery", "full_description": "Chapter 61: Articles of apparel and clothing accessories, knitted or crocheted > T-shirts, singlets, tank tops and similar garments, knitted or crocheted > Of cotton > Men's or boys' > T-shirts, all white, short hemmed sleeves, hemmed bottom, crew or round neckline, or V-neck, without pockets, trim or embroidery", "duty_rate": "16.5%", "retrieval_score": 0.8672, "scores": { "bm25": 26.7971, "vector": 0.4887, "rrf": 0.03279, "overlap": 0.667, "leaf_overlap": 0.429, "attributes": 0.8, "tree": 1, "cross": 0, "final": 0.8672, "legal": 0 }, "verdict": "possible", "reasoning": "Tariff line: “nglets, tank tops and similar garments, knitted or crocheted > Of cotton > Men's or boys' > T-shirts, all white, short hemmed sleeves, hemmed bottom, crew or round neckline, or V-neck, without pockets, trim or embroidery”. Matches: heading usually used for 'apparel' products; matches main material: cotton; matches construction: knitted; matches intended user: men.", "exclusion_reason": "Same HS6 subheading, but the national line matches the details (user/style) less well than the top candidate.", "citations": [ "W2", "N1" ], "signals": [ "heading usually used for 'apparel' products", "matches main material: cotton" ], "legal": { "status": "ok", "penalty": 0, "findings": [] }, "precedents": [], "duty": { "available": true, "rate_text": "16.5%", "rate_basis": "general", "effective_pct": 16.5, "min_pct": null, "max_pct": 16.5, "additional_pct": 0, "additional": [], "may_apply": [], "specific": false, "currency": "USD" } }, { "code": "6110.20.20.20", "code_digits": "6110202020", "hs6": "611020", "hs6_display": "6110.20", "national_extension": "2020", "description": "Men's or boys' sweatshirts of cotton", "full_description": "Chapter 61: Articles of apparel and clothing accessories, knitted or crocheted > Sweaters, pullovers, sweatshirts, waistcoats (vests) and similar articles, knitted or crocheted > Of cotton > Men's or boys' sweatshirts of cotton", "duty_rate": "", "retrieval_score": 0.8024, "scores": { "bm25": 8.2297, "vector": 0.3391, "rrf": 0.02963, "overlap": 0.267, "leaf_overlap": 0.5, "attributes": 0.88, "tree": 0.9154, "cross": 0, "final": 0.8024, "legal": 0 }, "verdict": "possible", "reasoning": "Tariff line: “ 61: Articles of apparel and clothing accessories, knitted or crocheted > Sweaters, pullovers, sweatshirts, waistcoats (vests) and similar articles, knitted or crocheted > Of cotton > Men's or boys' sweatshirts of cotton”. Matches: heading usually used for 'apparel' products; matches main material: cotton; matches construction: knitted; matches intended user: men.", "exclusion_reason": "Different HS subheading 611020; matches the description less well than the top candidate.", "citations": [ "W3", "N1" ], "signals": [ "heading usually used for 'apparel' products", "matches main material: cotton" ], "legal": { "status": "ok", "penalty": 0, "findings": [] }, "precedents": [], "duty": { "available": false, "rate_text": "" } } ], "confidence": 0.74, "flags": [ { "code": "no_official_evidence", "message": "No official source confirms the proposed code" }, { "code": "demo_data", "message": "Tariff data is incomplete" } ], "uncertainties": [], "missing_info": [], "questions": [], "summary": "Proposed 6109.10.00.14 based on how well the description and attributes match.", "deciding_factors": [ "6109.10.00.14: heading usually used for 'apparel' products", "6109.10.00.14: matches main material: cotton" ], "duty": { "origin": "VN", "country": "VN", "codes_compared": 2, "min_pct": 16.5, "max_pct": 16.5, "spread_pp": 0 }, "raw_confidence": 0.74, "sources": [ { "key": "W1", "url": "https://hts.usitc.gov/", "title": "Loaded tariff data – US 2026-SAMPLE – 6109.10.00.14", "publisher": "Mô phỏng theo cấu trúc bản xuất JSON của USITC (hts.usitc.gov). Dòng thuế 8–10 số và mô tả được rút gọn/minh họa.", "snippet": "6109.10.00.14: Chapter 61: Articles of apparel and clothing accessories, knitted or crocheted > T-shirts, singlets, tank tops and similar garments, knitted or crocheted > Of cotton > Men's or boys' > Other T-shirts", "accessed_at": "2026-10-03T19:48:03.234689+00:00", "is_official": false, "is_demo": true, "provider": "tariff_data", "related_codes": [ "6109100014" ] }, { "key": "W2", "url": "https://hts.usitc.gov/", "title": "Loaded tariff data – US 2026-SAMPLE – 6109.10.00.12", "publisher": "Mô phỏng theo cấu trúc bản xuất JSON của USITC (hts.usitc.gov). Dòng thuế 8–10 số và mô tả được rút gọn/minh họa.", "snippet": "6109.10.00.12: Chapter 61: Articles of apparel and clothing accessories, knitted or crocheted > T-shirts, singlets, tank tops and similar garments, knitted or crocheted > Of cotton > Men's or boys' > T-shirts, all white, short hemmed sleeves, hemmed bottom, crew or round neckline, or V-neck, without pockets, trim or embroidery", "accessed_at": "2026-10-03T19:48:03.234689+00:00", "is_official": false, "is_demo": true, "provider": "tariff_data", "related_codes": [ "6109100012" ] } ], "precedents": [], "legal": { "guidance": [ { "rule": "sxi-note2-predominant-fibre", "effect": "guidance", "ref": "HS Section XI, Note 2(A)", "note_ref": "", "params": { "dominant": "cotton", "percent": "60" }, "message": "Goods of two or more textile materials are classified as if wholly of the fibre that predominates by weight: cotton (60%)." }, { "rule": "gri6-same-level", "effect": "guidance", "ref": "GRI 6", "note_ref": "GRI6", "params": { "dominant": "cotton", "percent": "60" }, "message": "Subheadings are compared only with subheadings at the same level, by their terms and the related notes." } ], "excluded": [ { "code": "6205202046", "code_display": "6205.20.20.46", "findings": [ { "rule": "ch62-not-knitted", "effect": "exclude", "ref": "HS Chapter 62, Note 1", "note_ref": "62", "params": { "dominant": "cotton", "percent": "60" }, "message": "Chapter 62 excludes knitted or crocheted articles (other than those of heading 62.12); the product is knitted." } ] }, { "code": "6205202016", "code_display": "6205.20.20.16", "findings": [ { "rule": "ch62-not-knitted", "effect": "exclude", "ref": "HS Chapter 62, Note 1", "note_ref": "62", "params": { "dominant": "cotton", "percent": "60" }, "message": "Chapter 62 excludes knitted or crocheted articles (other than those of heading 62.12); the product is knitted." } ] } ], "rules_fired": [ "gender_line", "ch62-not-knitted" ] }, "pipeline": { "understanding": { "method": "rules" }, "translation": null, "sufficient_info": true, "early_exit": false, "tree": { "chapters": [ { "code": "61", "title": "Articles of apparel and clothing accessories, knitted or crocheted", "score": 1.15 }, { "code": "62", "title": "Articles of apparel and clothing accessories, not knitted or crocheted", "score": 1.087 } ], "headings": [ { "code": "6109", "title": "T-shirts, singlets, tank tops and similar garments, knitted or crocheted", "score": 1.15 }, { "code": "6205", "title": "Men's or boys' shirts (not knitted or crocheted)", "score": 1.087 } ], "hs6": 19, "leaves": 36, "widened": false }, "retrievers": { "bm25": 25, "vector": 36, "cross": 0, "precedents": 0 }, "reranker": "default", "calibrated": false, "pool": 31, "legal_excluded": 5, "shortlist": null, "top_k": 16, "top_k_codes": [ "6109100014", "6109100012" ], "line_select": null, "national_line": null }, "ranking": { "model": "default", "candidates": [ { "code": "6109100014", "hs6": "610910", "features": { "rrf": 0.9839, "bm25": 0.4332, "vector": 0.4186, "overlap": 0.3333, "leaf_overlap": 1, "attributes": 0.8, "tree": 1, "cross": 0, "legal": 0, "xrerank": 0 } }, { "code": "6109100012", "hs6": "610910", "features": { "rrf": 1, "bm25": 1, "vector": 0.4887, "overlap": 0.6667, "leaf_overlap": 0.4286, "attributes": 0.8, "tree": 1, "cross": 0, "legal": 0, "xrerank": 0 } } ] }, "notes": [ { "key": "N1", "doc_type": "chapter_note", "ref_code": "61", "title": "Chapter 61 – Scope", "content": "Chapter 61 applies only to made up knitted or crocheted articles. Heading 6109 covers T-shirts, singlets and tank tops. Articles of apparel that are not knitted or crocheted fall in Chapter 62. [Illustrative summary for demo mode – check against the official text before use.]", "source_url": "https://hts.usitc.gov/" }, { "key": "N2", "doc_type": "gri", "ref_code": "GRI1", "title": "GRI 1 – Terms of headings and legal notes", "content": "Classification is determined according to the terms of the headings and any relative Section or Chapter Notes; titles of sections and chapters are for ease of reference only. [Illustrative summary for demo mode – check against the official text before use.]", "source_url": "https://hts.usitc.gov/" } ], "retrieval": { "mode": "hybrid", "reason": null, "embedded": 71, "lines": 71 }, "checks": [ { "check": "evidence_matches_source", "ok": true, "detail": "W1", "label": "Evidence matches source" }, { "check": "evidence_matches_source", "ok": true, "detail": "W2", "label": "Evidence matches source" } ], "warnings": [], "timings_ms": { "understand": 2, "retrieve": 13, "legal": 13, "evidence": 0, "llm": 0, "validate": 3, "duty": 1 }, "dataset": { "id": "76235cf1803b4782be050a08c64c3cad", "market": "US", "version": "2026-SAMPLE", "name": "HTSUS – bộ dữ liệu mẫu (DEMO, không phải dữ liệu chính thức)", "is_demo": true, "source_name": "Mô phỏng theo cấu trúc bản xuất JSON của USITC (hts.usitc.gov). Dòng thuế 8–10 số và mô tả được rút gọn/minh họa.", "source_url": "https://hts.usitc.gov/", "loaded_at": "2026-10-03T19:48:02.737682", "national_digits": 10, "effective_date": "2026-01-01" }, "disclaimer": "This result is an automated suggestion for reference only, not an official classification decision. The declarant is responsible for the declared code; for complex cases, request an advance ruling from the customs authority." }, "missing_info": [], "error": null, "final_description": "Chapter 61: Articles of apparel and clothing accessories, knitted or crocheted > T-shirts, singlets, tank tops and similar garments, knitted or crocheted > Of cotton > Men's or boys' > Other T-shirts", "review_note": "Checked against the heading notes", "decided_by_name": "Administrator", "events": [ { "id": 3, "action": "created", "user_name": "Administrator", "user_role": "admin", "from_code": null, "to_code": "6109.10.00.14", "note": "Rerun of f4a2251d5dc941ec99f7d459e05082a5; AI: Proposed", "dataset_version": "2026-SAMPLE", "created_at": "2026-10-03T19:48:03.242335" }, { "id": 4, "action": "approve", "user_name": "Administrator (API: Documentation examples)", "user_role": "admin", "from_code": "6109.10.00.14", "to_code": "6109.10.00.14", "note": "Checked against the heading notes", "dataset_version": "2026-SAMPLE", "created_at": "2026-10-03T19:48:03.423841" } ], "progress": null } ``` Try it: https://docs.htspilot.com/explorer/#/Review/decideLookup ## Resolve a lookup without a decision `POST /api/lookups/{lookup_id}/resolve` **Changes data in your account when executed.** Needs the reviewer or the admin role. **Path parameters** | Name | Type | Description | | --- | --- | --- | | `lookup_id` | string | - | **Query parameters** | Name | Type | Required | Description | | --- | --- | --- | --- | | `resolved` | boolean | No | Default `true` | **Returns** `200` with `LookupSummary`. **Errors**: `401` No valid API key was sent; `403` The role of the key, or the plan of the account, does not allow this call; `422` The request is not valid; `500` An unexpected failure. **Example request** ```bash curl -X POST "https://htspilot.com/api/lookups/2655d2f9c3b047c6906b25d45a24c522/resolve?resolved=true" \ -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME" ``` **Example response** `200` ```json { "id": "2655d2f9c3b047c6906b25d45a24c522", "created_at": "2026-10-03T19:48:03.200629", "kind": "single", "batch_id": null, "row_index": null, "parent_lookup_id": "f4a2251d5dc941ec99f7d459e05082a5", "description": "Men's T-shirt, knitted, 100% cotton, short sleeves, crew neck", "market": "US", "dataset_version": "2026-SAMPLE", "status": "proposed", "status_label": "Proposed", "recommended_code": "6109.10.00.14", "recommended_description": "Chapter 61: Articles of apparel and clothing accessories, knitted or crocheted > T-shirts, singlets, tank tops and similar garments, knitted or crocheted > Of cotton > Men's or boys' > Other T-shirts", "hs6": "610910", "confidence": 0.74, "review_flags": [ { "code": "no_official_evidence", "message": "No official source confirms the proposed code" }, { "code": "demo_data", "message": "Tariff data is incomplete" } ], "risk": 18, "risk_level": "low", "resolved": true, "processing_ms": 37, "decision": "approved", "decision_label": "AI code approved", "final_code": "6109.10.00.14", "decided_at": "2026-10-03T19:48:03.423841", "created_by": "a7ba4a2440c7422fb695a1fd80d65ce5", "created_by_name": null, "sku_id": null, "language": "en", "comment_count": null } ``` Try it: https://docs.htspilot.com/explorer/#/Review/resolveLookup `resolved=false` puts the lookup back in the queue.