Description Guidance

POST/v1/compliance/description-guidance$0.05 per call

Evaluate commodity descriptions for customs compliance quality.

Send an Idempotency-Key header to retry safely.

Request body

Field	Type	Description
commodityDescriptionrequired	string	max length 2000
destinationCountryoptional	string	max length 3
hsCodeoptional	string

Response fields

Field	Type	Description
success	boolean	e.g. `true`
data	object
data.id	string	e.g. `dg_f525f46cb27771f5`
data.originalDescription	string	e.g. `parts`
data.destinationCountry	string	e.g. `US`
data.hsCode	null
data.evaluation	object
data.evaluation.score	number	e.g. `27`
data.evaluation.grade	string	e.g. `F`
data.evaluation.isAcceptable	boolean	e.g. `false`
data.evaluation.issues	array
data.evaluation.suggestions	array
data.evaluation.improvedDescription	string	e.g. `[ADD: specific item name], parts, [ADD: material composition,…`
data.customsRequirements	array
data.customsRequirements[].country	string	e.g. `US`
data.customsRequirements[].requirement	string	e.g. `Commodity description must clearly identify WHAT the item is,…`
data.customsRequirements[].mandatory	boolean	e.g. `true`
data.evaluatedAt	string	e.g. `2026-11-04T09:01:09.565Z`
meta	object
meta.requestId	string	e.g. `dg_f525f46cb27771f5`
meta.timestamp	string	e.g. `2026-11-04T09:01:09.565Z`
meta.processingTimeMs	number	e.g. `1`
meta.dataSource	object
meta.dataSource.name	string	e.g. `ComplianceGrid`
meta.dataSource.provenance	string	e.g. `computed`

Fields are read from a real response captured 2026-11-04, shortened. Optional fields may be absent in other responses.

Errors

400 invalid request
401 missing or bad key
403 not in your plan
429 rate limited, see Retry-After
402 payment required
5xx retry with backoff

Error bodies and codes are described in Error codes and troubleshooting.

curl -X POST "https://api.compliancegrid.ai/v1/compliance/description-guidance" \
  -H "Authorization: Bearer $CG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "commodityDescription": "parts",
    "destinationCountry": "US"
  }'

Try it in the sandbox

Runs against sandbox.api.compliancegrid.ai with your own sandbox key, which stays in this browser. Sandbox responses are mock data. Get a free key.

Sandbox key

Remember for this tab

Request body (JSON)

Example response · captured from production 2026-11-04 · shortened

{
  "success": true,
  "data": {
    "id": "dg_f525f46cb27771f5",
    "originalDescription": "parts",
    "destinationCountry": "US",
    "hsCode": null,
    "evaluation": {
      "score": 27,
      "grade": "F",
      "isAcceptable": false,
      "issues": [
        {
          "type": "TOO_SHORT",
          "severity": "HIGH",
          "message": "Description is too short for reliable customs processing. Expand with material, composition, and use."
        }
      ],
      "suggestions": [
        {
          "field": "ITEM_TYPE",
          "recommendation": "Include WHAT the item is (e.g., 'cotton t-shirt', 'stainless steel bolt', 'laptop computer'). This is the most critical element for customs classification."
        },
        {
          "field": "MATERIAL_COMPOSITION",
          "recommendation": "Include material composition (e.g., '100% cotton', 'stainless steel 304', 'ABS plastic'). Required for accurate duty calculation."
        }
      ],
      "improvedDescription": "[ADD: specific item name], parts, [ADD: material composition, e.g. cotton, steel, plastic], [ADD: intended use, e.g. for personal wear, for industrial use]"
    },
    "customsRequirements": [
      {
        "country": "US",
        "requirement": "Commodity description must clearly identify WHAT the item is, WHAT it is made of, and WHAT it is used for",
        "mandatory": true
      },
      {
        "country": "US",
        "requirement": "HS/tariff code is required for commercial shipments",
        "mandatory": true
      }
    ],
    "evaluatedAt": "2026-11-04T09:01:09.565Z"
  },
  "meta": {
    "requestId": "dg_f525f46cb27771f5",
    "timestamp": "2026-11-04T09:01:09.565Z",
    "processingTimeMs": 1,
    "dataSource": {
      "name": "ComplianceGrid",
      "provenance": "computed"
    }
  }
}