REST API

Classifications

Classify one product to an HTS code for each destination. The US code is computed first, then mapped to the other destinations.

curl -X POST "https://api.tarifflo.com/api/v1/classifications" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Wireless over-ear headphones, plastic housing",
    "destinations": ["US", "CA"],
    "webhookUrl": "https://your-server.com/webhooks/tarifflo"
  }'

{
  "jobId": "0193c1f2-...",
  "status": "queued",
  "destinationsQueued": 2,
  "totalClassifications": 2,
  "estimatedCompletionTime": 90,
  "message": "Classification job queued. ..."
}

Returns status queued, processing, complete (with data) or needs_info (with questions). To answer questions, add the answers to the description and classify again.

Bulk classification

Classify many short descriptions in one batch. Send up to 10,000 items inline, or upload a JSONL file of { "id", "text" } rows. The webhook carries a compact completion event; page through the results with GET.

Takes filename and returns uploadUrl and inputKey. PUT the file (up to 100 MB) to uploadUrl within 15 minutes, then POST the batch with the inputKey.

Status, then results 1,000 per page once the batch is complete. Each result carries id, hts10, confidence and top5.

Tariff rates

Rate up to 50 lines. Each line returns the effective ad valorem rate with Chapter 99 stacking (Section 301, 232, IEEPA) and a cost breakdown, priced as of its date. Unknown field names are rejected, so a typo fails instead of returning a wrong rate.

curl -X POST "https://api.tarifflo.com/api/v1/tariff-rates" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-server.com/webhooks/tarifflo",
    "modeOfTransport": "ocean",
    "rates": [
      { "htsCode": "7318.15.8060", "origin": "CN", "destination": "US", "value": 25000, "metals": { "steel": 100 } }
    ]
  }'

Progress while running; once complete, data holds one result per line, the same object the webhook carries.

Audit

Run a pre-audit over an entry's documents. Upload each file to a signed URL (the bytes never pass through our API), then start a run with the file ids. PDF, Excel, Word, CSV and images are accepted; a file whose content does not match its type is refused.

Takes filename and mimeType; returns fileId and uploadUrl, valid for 15 minutes. POST /api/v1/audit/uploads/bulk takes files (up to 50) and returns one upload per file.

Stage progress while running; once complete, the same data as pre_audit.completed.

Export control

Determine the export-control classification (ECCN, or a foreign control code) of up to 50 products.

Origin

Determine a finished good's country of origin under the rules of origin from its bill of materials. Each job takes minutes, so a request carries at most 5.

Entries

File an entry summary with CBP. The entry is validated in full first: if anything is wrong, the response lists every error by its path in your payload and nothing is saved. A valid entry is saved, encoded and sent to CBP in the same request.

• Field reference: Entry shape.
• An Idempotency-Key header is required. Repeating a key returns the first answer with Idempotent-Replayed: true and never files twice. A repeat while the first request is still filing returns 409 IDEMPOTENCY_KEY_IN_USE.
• Entries need a live key for now: a test key (tflo_test_) is refused with 403 TEST_KEY_NOT_SUPPORTED.
• CBP's answer arrives later as an entry.disposition event on your webhook. See Webhooks.

{
  "efid": "0193c1f2-...",
  "entryNumber": 1234567,
  "shortJobId": "AB12CD",
  "status": "AWAITING_CBP"
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The entry is not valid; nothing was filed",
    "errors": [
      { "path": "lineItems[3].tariffRows[0].htsNumber", "message": "..." }
    ]
  }
}

If the entry was saved but could not be sent to CBP, the answer is 422 or 502 with code SUBMIT_FAILED and the efid of the saved entry.