API reference

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /sort-sessions/{sortSessionId}/sort

curl "https://api.tarifflo.com/api/v2/sort-sessions/01a19e37-837d-7c16-9a5d-3bef820fcff7/sort" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "sortSessionId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "name": "Example",
  "gated": true,
  "entryCount": 1,
  "entriesMissingCommercialInvoice": 100,
  "queue": {
    "total": 1,
    "remaining": 100,
    "assigned": 100,
    "skipped": 100,
    "excluded": 100,
    "escalated": 100
  },
  "byStatusAndDocType": [
    {
      "status": "unmatched",
      "canonicalDocType": "string",
      "count": 1
    }
  ],
  "flagKinds": [
    {
      "kind": "string",
      "title": "string",
      "fix": "string",
      "where": "string",
      "use": "string"
    }
  ],
  "flagsRecorded": 100
}

Unplaced documents' cards

posthttps://api.tarifflo.com/api/v2/sort-sessions/{sortSessionId}/sort/cards

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

sortSessionIdstringrequired
The upload (sort session).

Request body

application/json

object

docIdstring
Re-read this card.
cursornumber
Undecided documents to skip — the nextCursor of the previous page.
limitnumber
Cards to return, 1-5. Default 1.

Responses

200Successful response

application/json

object

cardsobject[]required
Empty: the queue is drained (or the cursor is past it) — read sort_findings_report, then finish_sorting if nothing was handed back.
18 fields per item
- docIdstringrequired
- documentIdstringrequired
- canonicalDocTypestring | nullrequired
- pageRangesobject[]required
  2 fields per item
  startnumberrequired
  endnumberrequired
- pageCountnumberrequired
- textCharsnumberrequired
- mimeTypestringrequired
- sharedCopybooleanrequired
- queueStatusstringrequired
  One ofunmatchedambiguous
- stageCandidatesobject[]required
  What the stage tied it to. Search an identifier off the card with search_documents to decide.
  3 fields per item
  entrySessionIdstringrequired
  entryNumberstring | nullrequired
  labelstringrequired
- missingEntryNumberstring | nullrequired
- resolutionobject | nullrequired
  2 options
  Any of
  1.object
  kindstringrequired
  One ofassignedskippedexcluded
  entrySessionIdsstring[]required
  2.null
- agentNoteobject | nullrequired
  2 options
  Any of
  1.object
  kindstringrequired
  One of 13 values
  doctype_misclassifiednon_filing_contentno_anchor_for_entry_numberextraction_gapneedle_gapneedle_too_genericocr_damagedeterministic_rule_candidatematcher_correct_but_gatedduplicate_not_dedupedshared_documentneeds_human_eyesunrenderable_source
  detailstringrequired
  evidencestring | nullrequired
  2.null
- identifiersobject[]required
  2 fields per item
  labelstringrequired
  valuestringrequired
- needlesobject[]required
  2 fields per item
  valuestringrequired
  tierstringrequired
  One of 15 values
  entry_numberbillcommercialpl_numberpopartmidhtstextvaluetotalsgoodsfuzzypacketpath
- blockersstring[]required
  Any blocker means there is no path to a match: dispose of the document instead of searching.
- headerSnippetstringrequired
- remainingnumberrequired
nextCursornumber | nullrequired
Pass as cursor for the next page; null on the last.
remainingnumberrequired
Undecided documents in the queue.

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /sort-sessions/{sortSessionId}/sort/cards

curl -X POST "https://api.tarifflo.com/api/v2/sort-sessions/01a19e37-837d-7c16-9a5d-3bef820fcff7/sort/cards" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "docId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "cursor": 100,
    "limit": 100
  }'

Response · 200

JSON

{
  "cards": [
    {
      "docId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "documentId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "canonicalDocType": "string",
      "pageRanges": [
        {
          "start": 100,
          "end": 100
        }
      ],
      "pageCount": 0,
      "textChars": 100,
      "mimeType": "string",
      "sharedCopy": true,
      "queueStatus": "unmatched",
      "stageCandidates": [
        {
          "entrySessionId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
          "entryNumber": "string",
          "label": "string"
        }
      ],
      "missingEntryNumber": "string",
      "resolution": {
        "kind": "assigned",
        "entrySessionIds": [
          "01a19e37-837d-7c16-9a5d-3bef820fcff7"
        ]
      },
      "agentNote": {
        "kind": "shared_document",
        "detail": "string",
        "evidence": "01a19e37-837d-7c16-9a5d-3bef820fcff7"
      },
      "identifiers": [
        {
          "label": "string",
          "value": "string"
        }
      ],
      "needles": [
        {
          "value": "string",
          "tier": "entry_number"
        }
      ],
      "blockers": [
        "no_needles"
      ],
      "headerSnippet": "string",
      "remaining": 100
    }
  ],
  "nextCursor": 100,
  "remaining": 100
}

Regex search over the documents placed in entries

posthttps://api.tarifflo.com/api/v2/sort/search

Requires the API key scope filing.

AuthApiKeyorBearer

Request body

application/json

object

sortSessionIdstring
The upload (sort session).
entrySessionIdstring
Search one entry instead of the whole upload (sortSessionId is then optional).
patternstringrequired
Postgres ARE regex, case-insensitive, with a ≥3-character literal run.
entrySessionIdsstring[]
Scope to these entries — for adjudicating between candidates.
docTypestring
Only documents of this canonical doctype.
maxEntriesnumber
Entries detailed. Default 8.
maxWindowsnumber
Text windows per entry, 1-3. Default 3.
forDocIdstring
The document you are placing, so the effort lands on it in the findings report.

Responses

200Successful response

application/json

object

patternstringrequired
errorstring | nullrequired
Set: the search did not run, and this says why.
entriesScannednumberrequired
entriesHitnumberrequired
Every entry the pattern reached, not just the ones detailed. Many hits = a needle too generic to decide.
totalHitsnumberrequired
truncatedbooleanrequired
More entries hit than were detailed.
entriesobject[]required
5 fields per item
- entrySessionIdstringrequired
- entryNumberstring | nullrequired
- labelstringrequired
- hitCountnumberrequired
- docsobject[]required
  5 fields per item
  docIdstringrequired
  canonicalDocTypestring | nullrequired
  isAnchorbooleanrequired
  The entry's own 7501: a hit here is far stronger than one in a satellite.
  hitCountnumberrequired
  windowsstring[]required
  before «match» after, whitespace-collapsed.
notestring

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /sort/search

curl -X POST "https://api.tarifflo.com/api/v2/sort/search" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pattern": "string"
  }'

Response · 200

JSON

{
  "pattern": "string",
  "error": "string",
  "entriesScanned": 100,
  "entriesHit": 100,
  "totalHits": 1,
  "truncated": true,
  "entries": [
    {
      "entrySessionId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "entryNumber": "string",
      "label": "string",
      "hitCount": 1,
      "docs": [
        {
          "docId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
          "canonicalDocType": "string",
          "isAnchor": true,
          "hitCount": 1,
          "windows": [
            "string"
          ]
        }
      ]
    }
  ],
  "note": "string"
}

One page range of a sort document

posthttps://api.tarifflo.com/api/v2/sort-sessions/{sortSessionId}/sort/documents/{docId}/read

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

sortSessionIdstringrequired
The upload (sort session).
docIdstringrequired
A document the sort left for review.

Request body

application/json

object

fromPagenumber
1-based page to start at — the previous range's nextPage.
forDocIdstring
The document you are placing, if different from the one being read.

Responses

200Successful response

application/json

object

docIdstringrequired
canonicalDocTypestring | nullrequired
pageCountnumberrequired
pagesobject[]required
4 fields per item
- pagenumberrequired
- textstringrequired
- scannedbooleanrequired
- imageUnavailabletrue
  A scanned page with no stored image: read its OCR text.
imagesobject[]required
2 fields per item
- mimeTypestringrequired
- datastringrequired
nextPagenumber | nullrequired
Call again with this as fromPage for the rest; null when this range reached the end.

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /sort-sessions/{sortSessionId}/sort/documents/{docId}/read

curl -X POST "https://api.tarifflo.com/api/v2/sort-sessions/01a19e37-837d-7c16-9a5d-3bef820fcff7/sort/documents/01a19e37-837d-7c16-9a5d-3bef820fcff7/read" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fromPage": 0,
    "forDocId": "01a19e37-837d-7c16-9a5d-3bef820fcff7"
  }'

Response · 200

JSON

{
  "docId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "canonicalDocType": "string",
  "pageCount": 0,
  "pages": [
    {
      "page": 0,
      "text": "string",
      "scanned": true,
      "imageUnavailable": true
    }
  ],
  "images": [
    {
      "mimeType": "string",
      "data": "string"
    }
  ],
  "nextPage": 0
}

Decide unplaced documents

posthttps://api.tarifflo.com/api/v2/sort-sessions/{sortSessionId}/sort/placements

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

sortSessionIdstringrequired
The upload (sort session).

Request body

application/json

object

placementsobject[]required
min items 1max items 50
4 fields per item
- docIdstringrequired
  min length 1
- decisionstringrequired
  One ofplaceskipexclude
- entrySessionIdsstring[]
  Required for place: every entry this document belongs to.
  default: []
- findingobjectrequired
  Why the deterministic pipeline could not place this. start_sorting returns the kinds and when each applies.
  6 fields
  kindstringrequired
  One of 13 values
  doctype_misclassifiednon_filing_contentno_anchor_for_entry_numberextraction_gapneedle_gapneedle_too_genericocr_damagedeterministic_rule_candidatematcher_correct_but_gatedduplicate_not_dedupedshared_documentneeds_human_eyesunrenderable_source
  detailstringrequired
  What you observed, specifically — the field, the number, the rule (20+ characters).
  min length 1
  evidencestring
  The text or identifier that PROVES it — a search window, a needle, a metadata value.
  confidencestring
  One ofhighmediumlow
  docIdsstring[]
  Further documents this same finding covers.
  default: []
  entrySessionIdsstring[]

Responses

200Successful response

application/json

object

outcomesobject | object[]required
One row per placement, in order.
2 options per item
Any of
1.object
docIdstringrequired
dispositionstringrequired
One ofassignedskippedexcludedescalated
entrySessionIdsstring[]required
flagobjectrequired
9 fields
kindstringrequired
One of 13 values
doctype_misclassifiednon_filing_contentno_anchor_for_entry_numberextraction_gapneedle_gapneedle_too_genericocr_damagedeterministic_rule_candidatematcher_correct_but_gatedduplicate_not_dedupedshared_documentneeds_human_eyesunrenderable_source
docIdsstring[]required
entrySessionIdsstring[]
detailstringrequired
evidencestring
confidencestringrequired
One ofhighmediumlow
dispositionstring | null
effortobject
2 fields
searchesnumberrequired
fullReadsnumberrequired
atstringrequired
2.object
docIdstringrequired
errorstringrequired
Why this placement was refused; the others still applied.
countsobjectrequired
Undecided beyond the handed-back ones: call next_unplaced_document. Otherwise read sort_findings_report, then finish_sorting.
6 fields
- totalnumberrequired
- remainingnumberrequired
  Still undecided, handed-back documents included: the gate holds on these.
- assignednumberrequired
- skippednumberrequired
- excludednumberrequired
- escalatednumberrequired
  The subset of remaining handed back to a person.

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /sort-sessions/{sortSessionId}/sort/placements

curl -X POST "https://api.tarifflo.com/api/v2/sort-sessions/01a19e37-837d-7c16-9a5d-3bef820fcff7/sort/placements" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "placements": [
      {
        "docId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
        "decision": "place",
        "finding": {
          "kind": "shared_document",
          "detail": "string"
        }
      }
    ]
  }'

Response · 200

JSON

{
  "outcomes": [
    {
      "docId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "disposition": "assigned",
      "entrySessionIds": [
        "01a19e37-837d-7c16-9a5d-3bef820fcff7"
      ],
      "flag": {
        "kind": "shared_document",
        "docIds": [
          "01a19e37-837d-7c16-9a5d-3bef820fcff7"
        ],
        "entrySessionIds": [
          "01a19e37-837d-7c16-9a5d-3bef820fcff7"
        ],
        "detail": "string",
        "evidence": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
        "confidence": "high",
        "disposition": "assigned",
        "effort": {
          "searches": 100,
          "fullReads": 100
        },
        "at": "string"
      }
    }
  ],
  "counts": {
    "total": 1,
    "remaining": 100,
    "assigned": 100,
    "skipped": 100,
    "excluded": 100,
    "escalated": 100
  }
}

Put a decided document back in the queue

posthttps://api.tarifflo.com/api/v2/sort-sessions/{sortSessionId}/sort/documents/{docId}/reopen

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

sortSessionIdstringrequired
The upload (sort session).
docIdstringrequired
A document the sort left for review.

Responses

200Successful response

application/json

object

The queue's dispositions.

totalnumberrequired
remainingnumberrequired
Still undecided, handed-back documents included: the gate holds on these.
assignednumberrequired
skippednumberrequired
excludednumberrequired
escalatednumberrequired
The subset of remaining handed back to a person.

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /sort-sessions/{sortSessionId}/sort/documents/{docId}/reopen

curl -X POST "https://api.tarifflo.com/api/v2/sort-sessions/01a19e37-837d-7c16-9a5d-3bef820fcff7/sort/documents/01a19e37-837d-7c16-9a5d-3bef820fcff7/reopen" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "total": 1,
  "remaining": 100,
  "assigned": 100,
  "skipped": 100,
  "excluded": 100,
  "escalated": 100
}

Wait on the upload's running rematch

gethttps://api.tarifflo.com/api/v2/sort-sessions/{sortSessionId}/sort/rematch

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

sortSessionIdstringrequired
The upload (sort session).

Responses

200Successful response

application/json

object

The upload's rematch, waited on for up to ~90 s.

statusstringrequired
nothing_unplaced: every document has a decision. no_rematch: none ran, call rematch_unplaced. disappeared: call rematch_unplaced again. running: call wait_for_sort to keep waiting. failed: see error. done: see placed.
One ofnothing_unplacedno_rematchdisappearedrunningfaileddone
jobIdstring
jobStatusstring
errorstring
placedobject[]
What the matcher filed, with the needle and tier it used. Empty: every remaining document still needs a decision.
5 fields per item
- docIdstringrequired
- canonicalDocTypestring | nullrequired
- entrySessionIdsstring[]required
- needlestringrequired
- tierstringrequired
  One of 15 values
  entry_numberbillcommercialpl_numberpopartmidhtstextvaluetotalsgoodsfuzzypacketpath
countsobject | null
2 options
Any of
1.object
The queue's dispositions.
totalnumberrequired
remainingnumberrequired
Still undecided, handed-back documents included: the gate holds on these.
assignednumberrequired
skippednumberrequired
excludednumberrequired
escalatednumberrequired
The subset of remaining handed back to a person.
2.null
stillUnplacedobject[]
3 fields per item
- docIdstringrequired
- canonicalDocTypestring | nullrequired
- statusstringrequired
  One ofunmatchedambiguous
stillUnplacedTotalnumber

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /sort-sessions/{sortSessionId}/sort/rematch

curl "https://api.tarifflo.com/api/v2/sort-sessions/01a19e37-837d-7c16-9a5d-3bef820fcff7/sort/rematch" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "status": "no_rematch",
  "jobId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "jobStatus": "string",
  "error": "string",
  "placed": [
    {
      "docId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "canonicalDocType": "string",
      "entrySessionIds": [
        "01a19e37-837d-7c16-9a5d-3bef820fcff7"
      ],
      "needle": "string",
      "tier": "entry_number"
    }
  ],
  "counts": {
    "total": 1,
    "remaining": 100,
    "assigned": 100,
    "skipped": 100,
    "excluded": 100,
    "escalated": 100
  },
  "stillUnplaced": [
    {
      "docId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "canonicalDocType": "string",
      "status": "unmatched"
    }
  ],
  "stillUnplacedTotal": 1
}

Re-run the matcher over the unplaced documents

posthttps://api.tarifflo.com/api/v2/sort-sessions/{sortSessionId}/sort/rematch

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

sortSessionIdstringrequired
The upload (sort session).

Responses

200Successful response

application/json

object

The upload's rematch, waited on for up to ~90 s.

statusstringrequired
nothing_unplaced: every document has a decision. no_rematch: none ran, call rematch_unplaced. disappeared: call rematch_unplaced again. running: call wait_for_sort to keep waiting. failed: see error. done: see placed.
One ofnothing_unplacedno_rematchdisappearedrunningfaileddone
jobIdstring
jobStatusstring
errorstring
placedobject[]
What the matcher filed, with the needle and tier it used. Empty: every remaining document still needs a decision.
5 fields per item
- docIdstringrequired
- canonicalDocTypestring | nullrequired
- entrySessionIdsstring[]required
- needlestringrequired
- tierstringrequired
  One of 15 values
  entry_numberbillcommercialpl_numberpopartmidhtstextvaluetotalsgoodsfuzzypacketpath
countsobject | null
2 options
Any of
1.object
The queue's dispositions.
totalnumberrequired
remainingnumberrequired
Still undecided, handed-back documents included: the gate holds on these.
assignednumberrequired
skippednumberrequired
excludednumberrequired
escalatednumberrequired
The subset of remaining handed back to a person.
2.null
stillUnplacedobject[]
3 fields per item
- docIdstringrequired
- canonicalDocTypestring | nullrequired
- statusstringrequired
  One ofunmatchedambiguous
stillUnplacedTotalnumber

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /sort-sessions/{sortSessionId}/sort/rematch

curl -X POST "https://api.tarifflo.com/api/v2/sort-sessions/01a19e37-837d-7c16-9a5d-3bef820fcff7/sort/rematch" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "status": "nothing_unplaced",
  "jobId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "jobStatus": "string",
  "error": "string",
  "placed": [
    {
      "docId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "canonicalDocType": "string",
      "entrySessionIds": [
        "01a19e37-837d-7c16-9a5d-3bef820fcff7"
      ],
      "needle": "string",
      "tier": "entry_number"
    }
  ],
  "counts": {
    "total": 1,
    "remaining": 100,
    "assigned": 100,
    "skipped": 100,
    "excluded": 100,
    "escalated": 100
  },
  "stillUnplaced": [
    {
      "docId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "canonicalDocType": "string",
      "status": "unmatched"
    }
  ],
  "stillUnplacedTotal": 1
}

The upload's entries and their document coverage

posthttps://api.tarifflo.com/api/v2/sort-sessions/{sortSessionId}/sort/packets

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

sortSessionIdstringrequired
The upload (sort session).

Request body

application/json

object

entrySessionIdstring
missingDocTypestring
limitnumber
offsetnumber

Responses

200Successful response

application/json

object

entryobject
With entrySessionId: that packet's document inventory.
6 fields
- entrySessionIdstringrequired
- entryNumberstring | nullrequired
- labelstringrequired
- warningsstring[]required
- anchorKeysstring[]required
- docsobject[]required
  6 fields per item
  docIdstringrequired
  canonicalDocTypestring | nullrequired
  pageRangesobject[]required
  2 fields per item
  startnumberrequired
  endnumberrequired
  pageCountnumberrequired
  isAnchorbooleanrequired
  identifiersobject[]required
  2 fields per item
  labelstringrequired
  valuestringrequired
totalnumber
Without entrySessionId: entries matching the filter.
rowsobject[]
Without entrySessionId: this page of entries with their coverage.
5 fields per item
- entrySessionIdstringrequired
- entryNumberstring | nullrequired
- labelstringrequired
- warningsstring[]required
- countsobjectrequired
  4 fields
  commercialInvoicenumberrequired
  billOfLadingnumberrequired
  packingListnumberrequired
  totalnumberrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /sort-sessions/{sortSessionId}/sort/packets

curl -X POST "https://api.tarifflo.com/api/v2/sort-sessions/01a19e37-837d-7c16-9a5d-3bef820fcff7/sort/packets" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entrySessionId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "missingDocType": "string",
    "limit": 100,
    "offset": 100
  }'

Response · 200

JSON

{
  "entry": {
    "entrySessionId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "entryNumber": "string",
    "label": "string",
    "warnings": [
      "string"
    ],
    "anchorKeys": [
      "string"
    ],
    "docs": [
      {
        "docId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
        "canonicalDocType": "string",
        "pageRanges": [
          {
            "start": 100,
            "end": 100
          }
        ],
        "pageCount": 0,
        "isAnchor": true,
        "identifiers": [
          {
            "label": "string",
            "value": "string"
          }
        ]
      }
    ]
  },
  "total": 1,
  "rows": [
    {
      "entrySessionId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "entryNumber": "string",
      "label": "string",
      "warnings": [
        "string"
      ],
      "counts": {
        "commercialInvoice": 100,
        "billOfLading": 100,
        "packingList": 100,
        "total": 1
      }
    }
  ]
}

The sort's findings, ranked

gethttps://api.tarifflo.com/api/v2/sort-sessions/{sortSessionId}/sort/findings

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

sortSessionIdstringrequired
The upload (sort session).

Responses

200Successful response

application/json

object

summaryobjectrequired
9 fields
- totalnumberrequired
- remainingnumberrequired
- assignednumberrequired
- skippednumberrequired
- excludednumberrequired
- escalatednumberrequired
- placedUnaidednumberrequired
  Decided straight off the card.
- neededSearchnumberrequired
- neededFullReadnumberrequired
byKindobject[]required
What to fix, biggest first: ranked by how many documents each fix would recover.
5 fields per item
- kindstringrequired
- documentsnumberrequired
- fixstringrequired
- wherestringrequired
- flagsobject[]required
  9 fields per item
  kindstringrequired
  One of 13 values
  doctype_misclassifiednon_filing_contentno_anchor_for_entry_numberextraction_gapneedle_gapneedle_too_genericocr_damagedeterministic_rule_candidatematcher_correct_but_gatedduplicate_not_dedupedshared_documentneeds_human_eyesunrenderable_source
  docIdsstring[]required
  entrySessionIdsstring[]
  detailstringrequired
  evidencestring
  confidencestringrequired
  One ofhighmediumlow
  dispositionstring | null
  effortobject
  2 fields
  searchesnumberrequired
  fullReadsnumberrequired
  atstringrequired
markdownstringrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /sort-sessions/{sortSessionId}/sort/findings

curl "https://api.tarifflo.com/api/v2/sort-sessions/01a19e37-837d-7c16-9a5d-3bef820fcff7/sort/findings" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "summary": {
    "total": 1,
    "remaining": 100,
    "assigned": 100,
    "skipped": 100,
    "excluded": 100,
    "escalated": 100,
    "placedUnaided": 100,
    "neededSearch": 100,
    "neededFullRead": 100
  },
  "byKind": [
    {
      "kind": "string",
      "documents": 100,
      "fix": "string",
      "where": "string",
      "flags": [
        {
          "kind": "doctype_misclassified",
          "docIds": [
            "01a19e37-837d-7c16-9a5d-3bef820fcff7"
          ],
          "entrySessionIds": [
            "01a19e37-837d-7c16-9a5d-3bef820fcff7"
          ],
          "detail": "string",
          "evidence": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
          "confidence": "high",
          "disposition": "assigned",
          "effort": {
            "searches": 100,
            "fullReads": 100
          },
          "at": "string"
        }
      ]
    }
  ],
  "markdown": "string"
}

Record a finding across documents

posthttps://api.tarifflo.com/api/v2/sort-sessions/{sortSessionId}/sort/findings

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

sortSessionIdstringrequired
The upload (sort session).

Request body

application/json

object

findingobjectrequired
6 fields
- kindstringrequired
  One of 13 values
  doctype_misclassifiednon_filing_contentno_anchor_for_entry_numberextraction_gapneedle_gapneedle_too_genericocr_damagedeterministic_rule_candidatematcher_correct_but_gatedduplicate_not_dedupedshared_documentneeds_human_eyesunrenderable_source
- detailstringrequired
  What you observed, specifically — the field, the number, the rule (20+ characters).
  min length 1
- evidencestring
  The text or identifier that PROVES it — a search window, a needle, a metadata value.
- confidencestring
  One ofhighmediumlow
- docIdsstring[]required
  Every document this finding covers.
  min items 1
- entrySessionIdsstring[]

Responses

200Successful response

application/json

object

kindstringrequired
One of 13 values
doctype_misclassifiednon_filing_contentno_anchor_for_entry_numberextraction_gapneedle_gapneedle_too_genericocr_damagedeterministic_rule_candidatematcher_correct_but_gatedduplicate_not_dedupedshared_documentneeds_human_eyesunrenderable_source
docIdsstring[]required
entrySessionIdsstring[]
detailstringrequired
evidencestring
confidencestringrequired
One ofhighmediumlow
dispositionstring | null
effortobject
2 fields
- searchesnumberrequired
- fullReadsnumberrequired
atstringrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /sort-sessions/{sortSessionId}/sort/findings

curl -X POST "https://api.tarifflo.com/api/v2/sort-sessions/01a19e37-837d-7c16-9a5d-3bef820fcff7/sort/findings" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "finding": {
      "kind": "shared_document",
      "detail": "string",
      "docIds": [
        "01a19e37-837d-7c16-9a5d-3bef820fcff7"
      ]
    }
  }'

Response · 200

JSON

{
  "kind": "shared_document",
  "docIds": [
    "01a19e37-837d-7c16-9a5d-3bef820fcff7"
  ],
  "entrySessionIds": [
    "01a19e37-837d-7c16-9a5d-3bef820fcff7"
  ],
  "detail": "string",
  "evidence": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "confidence": "high",
  "disposition": "assigned",
  "effort": {
    "searches": 100,
    "fullReads": 100
  },
  "at": "string"
}

Release the sort gate and dispatch the entries

posthttps://api.tarifflo.com/api/v2/sort-sessions/{sortSessionId}/sort/finish

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

sortSessionIdstringrequired
The upload (sort session).

Responses

200Successful response

application/json

object

dispatchednumberrequired
Entries dispatched to filing. Keep calling wait_for_work.
heldbooleanrequired
True: sorting is done, and Tarifflo holds the upload before entries are dispatched.
countsobjectrequired
The queue's dispositions.
6 fields
- totalnumberrequired
- remainingnumberrequired
  Still undecided, handed-back documents included: the gate holds on these.
- assignednumberrequired
- skippednumberrequired
- excludednumberrequired
- escalatednumberrequired
  The subset of remaining handed back to a person.

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /sort-sessions/{sortSessionId}/sort/finish

curl -X POST "https://api.tarifflo.com/api/v2/sort-sessions/01a19e37-837d-7c16-9a5d-3bef820fcff7/sort/finish" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "dispatched": 100,
  "held": true,
  "counts": {
    "total": 1,
    "remaining": 100,
    "assigned": 100,
    "skipped": 100,
    "excluded": 100,
    "escalated": 100
  }
}

5 endpoints

Configuration

The pipeline configurations an upload can run on.

Get one pipeline configuration

gethttps://api.tarifflo.com/api/v2/pipeline-configurations/{configurationId}

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

configurationIdstringrequired
The configuration's id (list_configurations).
min length 1

Responses

200Successful response

application/json

object

configurationobjectrequired
12 fields
- idstringrequired
- namestringrequired
- descriptionstringrequired
- isDefaultbooleanrequired
- lockedbooleanrequired
- isTemporarybooleanrequired
- generalobjectrequired
  11 fields
  requiredContentmap<string, boolean>required
  Keysfiled_baselineproduct_descriptionhts_codeline_valuequantitycountry_of_originentry_datetransport_eventimporter_identity
  unidentifiedDocumentsstringrequired
  One ofskipask
  filerIdstring | nullrequired
  importerProfileIdstring | nullrequired
  reuseByHashmap<string, boolean>required
  Keysocrbeads_facts
  includeLiquidatedbooleanrequired
  askUsContentbooleanrequired
  changeRiskThresholdintegerrequired
  ≥ 0≤ 100
  filingobjectrequired
  2 fields
  savingsThresholdUsdnumberrequired
  ≥ 0
  dutyDecreasesOnlybooleanrequired
  asycudaCountrystring | nullrequired
  rateReportobjectrequired
  5 fields
  primaryDatestring | nullrequired
  loadingDatestring | nullrequired
  templateIdstring | nullrequired
  includeRationalesbooleanrequired
  includeChapter99booleanrequired
- jobsmap<string, object>required
  Keys 18 values
  sort_documentsagent_sortclassify_productsweb_searchinvoice_htseccncoospipgaadcvddutyreviewreportvalidateapproved_codesstage_filingcargo_release_valueasycuda_declaration
  1 field per value
  onbooleanrequired
- validationRulesmap<string, boolean>required
  Keys 42 values
  civ_ior_namedciv_us_consignee_for_foreign_iorciv_description_sufficientciv_country_of_originciv_quantityciv_set_components_reconcileciv_unit_and_total_valueciv_total_reconcilesciv_currencyciv_incoterms_or_chargesciv_value_adjustmentsciv_manufacturer_identifiedciv_documents_belonges_parties_match_cives_coo_matches_cives_country_of_export_matches_transportes_export_date_after_ladinges_hts_matches_cives_part_number_correctes_all_civ_hts_presentes_spi_supportedes_values_match_cives_quantities_match_cives_currency_and_exchange_ratees_adjustments_match_incotermses_assists_declaredes_commissions_declaredes_first_sale_supportedes_mid_is_actual_manufactureres_relationship_recordedes_article_set_reproducedes_set_origin_dominancees_set_component_quantitieses_ch99_consistentes_232_claim_matches_descriptiones_232_claim_contradictedes_fees_mpf_hmfes_lines_completees_port_of_lading_matches_transportes_gross_weight_matches_packinges_ior_number_matches_profilees_pga_evidence_present
- unsetValidationRulesstring[]requiredread-only
- billingobjectrequired
  1 field
  actionstringrequired
  One ofentry_preparedper_beadnone
- lanestringrequired
  One ofentryclassification
posturestringrequired
Pre-entry (builds entries from the documents) or post-entry (corrects entries already filed).
pricingstringrequired
What a run of it bills, at this organization's prices.
planstringrequired
The plan it runs, in plain words.
jobCatalogobject[]required
Every job a configuration can switch: the keys jobs takes.
7 fields per item
- keystringrequired
  One of 18 values
  sort_documentsagent_sortclassify_productsweb_searchinvoice_htseccncoospipgaadcvddutyreviewreportvalidateapproved_codesstage_filingcargo_release_valueasycuda_declaration
- labelstringrequired
- summarystringrequired
- comingSoonstring | nullrequired
  Set while the job cannot be switched on.
- alwaysOnstring | nullrequired
  Set while the job cannot be switched off.
- withinstring | nullrequired
  The job this one refines: it runs only when that one runs.
- requiresstring[]required
requirementCatalogobject[]required
Every content requirement: the keys requiredContent takes.
2 fields per item
- keystringrequired
  One offiled_baselineproduct_descriptionhts_codeline_valuequantitycountry_of_originentry_datetransport_eventimporter_identity
- labelstringrequired
ruleCatalogobject[]required
Every validation rule: the keys validationRules takes.
3 fields per item
- keystringrequired
  One of 42 values
  civ_ior_namedciv_us_consignee_for_foreign_iorciv_description_sufficientciv_country_of_originciv_quantityciv_set_components_reconcileciv_unit_and_total_valueciv_total_reconcilesciv_currencyciv_incoterms_or_chargesciv_value_adjustmentsciv_manufacturer_identifiedciv_documents_belonges_parties_match_cives_coo_matches_cives_country_of_export_matches_transportes_export_date_after_ladinges_hts_matches_cives_part_number_correctes_all_civ_hts_presentes_spi_supportedes_values_match_cives_quantities_match_cives_currency_and_exchange_ratees_adjustments_match_incotermses_assists_declaredes_commissions_declaredes_first_sale_supportedes_mid_is_actual_manufactureres_relationship_recordedes_article_set_reproducedes_set_origin_dominancees_set_component_quantitieses_ch99_consistentes_232_claim_matches_descriptiones_232_claim_contradictedes_fees_mpf_hmfes_lines_completees_port_of_lading_matches_transportes_gross_weight_matches_packinges_ior_number_matches_profilees_pga_evidence_present
- labelstringrequired
- groupstringrequired
  One ofcommercial_invoiceentry_summary

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /pipeline-configurations/{configurationId}

curl "https://api.tarifflo.com/api/v2/pipeline-configurations/01a19e37-837d-7c16-9a5d-3bef820fcff7" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "configuration": {
    "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "name": "Example",
    "description": "Laptop computer, 14 inch",
    "isDefault": true,
    "locked": true,
    "isTemporary": true,
    "general": {
      "requiredContent": {
        "filed_baseline": true
      },
      "unidentifiedDocuments": "skip",
      "filerId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "importerProfileId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "reuseByHash": {
        "ocr": true
      },
      "includeLiquidated": true,
      "askUsContent": true,
      "changeRiskThreshold": 1,
      "filing": {
        "savingsThresholdUsd": 100,
        "dutyDecreasesOnly": true
      },
      "asycudaCountry": "BB",
      "rateReport": {
        "primaryDate": "2026-01-15",
        "loadingDate": "2026-01-15",
        "templateId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
        "includeRationales": true,
        "includeChapter99": true
      }
    },
    "jobs": {
      "sort_documents": {
        "on": true
      }
    },
    "validationRules": {
      "civ_ior_named": true
    },
    "unsetValidationRules": [
      "civ_ior_named"
    ],
    "billing": {
      "action": "entry_prepared"
    },
    "lane": "entry"
  },
  "posture": "string",
  "pricing": "string",
  "plan": "string",
  "jobCatalog": [
    {
      "key": "sort_documents",
      "label": "string",
      "summary": "string",
      "comingSoon": "string",
      "alwaysOn": "string",
      "within": "sort_documents",
      "requires": [
        "filed_baseline"
      ]
    }
  ],
  "requirementCatalog": [
    {
      "key": "filed_baseline",
      "label": "string"
    }
  ],
  "ruleCatalog": [
    {
      "key": "civ_ior_named",
      "label": "string",
      "group": "commercial_invoice"
    }
  ]
}

Change a pipeline configuration (writes a new version)

posthttps://api.tarifflo.com/api/v2/pipeline-configurations/{configurationId}

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

configurationIdstringrequired
The configuration's id (list_configurations).
min length 1

Request body

application/json

object

namestring
Max 80 characters.
descriptionstring
One sentence on what this configuration is for (max 240 characters).
jobsstring[]
The COMPLETE list of jobs to switch on; every job not listed is off. Read get_configuration's jobCatalog for what each does. Omit to keep the starting point's jobs.
requiredContentstring[]
The COMPLETE list of content the documents must carry, on top of what the jobs already lock. filed_baseline makes it a post-entry (already filed) configuration. Omit to keep the starting point's.
unidentifiedDocumentsstring
ask holds the upload when a document cannot be identified; skip leaves it unread.
One ofskipask
importerProfileIdstring | null
The CLIENT: the importer profile (see list_importer_profiles) every entry of an upload files for. Required on an entry configuration. An importer organization's is always its own.
filerIdstring | null
The filer whose codes the run transmits under (see list_filers). Required when stage_filing is on.
asycudaCountrystring | null
The ASYCUDA World administration asycuda_declaration builds for. Required when that job is on.
validationRulesmap<string, boolean>
Rule key → on/off, merged over the starting point's rules. get_configuration lists every rule key.
Keys 42 values
civ_ior_namedciv_us_consignee_for_foreign_iorciv_description_sufficientciv_country_of_originciv_quantityciv_set_components_reconcileciv_unit_and_total_valueciv_total_reconcilesciv_currencyciv_incoterms_or_chargesciv_value_adjustmentsciv_manufacturer_identifiedciv_documents_belonges_parties_match_cives_coo_matches_cives_country_of_export_matches_transportes_export_date_after_ladinges_hts_matches_cives_part_number_correctes_all_civ_hts_presentes_spi_supportedes_values_match_cives_quantities_match_cives_currency_and_exchange_ratees_adjustments_match_incotermses_assists_declaredes_commissions_declaredes_first_sale_supportedes_mid_is_actual_manufactureres_relationship_recordedes_article_set_reproducedes_set_origin_dominancees_set_component_quantitieses_ch99_consistentes_232_claim_matches_descriptiones_232_claim_contradictedes_fees_mpf_hmfes_lines_completees_port_of_lading_matches_transportes_gross_weight_matches_packinges_ior_number_matches_profilees_pga_evidence_present

Responses

200Successful response

application/json

object

idstringrequired
The NEW version's id. Pass it to file_documents as configurationId.
namestringrequired
descriptionstringrequired
isDefaultbooleanrequired
postEntrybooleanrequired
true: post-entry, corrects entries already filed. false: pre-entry, builds entries from the documents.
jobsOnstring[]required
importerProfileIdstring | nullrequired
The client every entry files for; null while none is picked.
filerIdstring | nullrequired
asycudaCountrystring | nullrequired
billingstringrequired
One ofentry_preparedper_beadnone
planstringrequired
The plan this configuration runs, in plain words.
retiredIdstringrequired
The id it replaced, now retired. Uploads that picked it follow to the new id.

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /pipeline-configurations/{configurationId}

curl -X POST "https://api.tarifflo.com/api/v2/pipeline-configurations/01a19e37-837d-7c16-9a5d-3bef820fcff7" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example",
    "description": "Laptop computer, 14 inch",
    "jobs": [
      "sort_documents"
    ],
    "requiredContent": [
      "filed_baseline"
    ],
    "unidentifiedDocuments": "skip",
    "importerProfileId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "filerId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "asycudaCountry": "BB",
    "validationRules": {
      "civ_ior_named": true
    }
  }'

Response · 200

JSON

{
  "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "name": "Example",
  "description": "Laptop computer, 14 inch",
  "isDefault": true,
  "postEntry": true,
  "jobsOn": [
    "sort_documents"
  ],
  "importerProfileId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "filerId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "asycudaCountry": "BB",
  "billing": "entry_prepared",
  "plan": "string",
  "retiredId": "01a19e37-837d-7c16-9a5d-3bef820fcff7"
}

List the organization's pipeline configurations

gethttps://api.tarifflo.com/api/v2/pipeline-configurations

Requires the API key scope filing.

AuthApiKeyorBearer

Responses

200Successful response

application/json

object[]

idstringrequired
namestringrequired
descriptionstringrequired
isDefaultbooleanrequired
lockedbooleanrequired
isTemporarybooleanrequired
generalobjectrequired
11 fields
- requiredContentmap<string, boolean>required
  Keysfiled_baselineproduct_descriptionhts_codeline_valuequantitycountry_of_originentry_datetransport_eventimporter_identity
- unidentifiedDocumentsstringrequired
  One ofskipask
- filerIdstring | nullrequired
- importerProfileIdstring | nullrequired
- reuseByHashmap<string, boolean>required
  Keysocrbeads_facts
- includeLiquidatedbooleanrequired
- askUsContentbooleanrequired
- changeRiskThresholdintegerrequired
  ≥ 0≤ 100
- filingobjectrequired
  2 fields
  savingsThresholdUsdnumberrequired
  ≥ 0
  dutyDecreasesOnlybooleanrequired
- asycudaCountrystring | nullrequired
- rateReportobjectrequired
  5 fields
  primaryDatestring | nullrequired
  loadingDatestring | nullrequired
  templateIdstring | nullrequired
  includeRationalesbooleanrequired
  includeChapter99booleanrequired
jobsmap<string, object>required
Keys 18 values
sort_documentsagent_sortclassify_productsweb_searchinvoice_htseccncoospipgaadcvddutyreviewreportvalidateapproved_codesstage_filingcargo_release_valueasycuda_declaration
1 field per value
- onbooleanrequired
validationRulesmap<string, boolean>required
Keys 42 values
civ_ior_namedciv_us_consignee_for_foreign_iorciv_description_sufficientciv_country_of_originciv_quantityciv_set_components_reconcileciv_unit_and_total_valueciv_total_reconcilesciv_currencyciv_incoterms_or_chargesciv_value_adjustmentsciv_manufacturer_identifiedciv_documents_belonges_parties_match_cives_coo_matches_cives_country_of_export_matches_transportes_export_date_after_ladinges_hts_matches_cives_part_number_correctes_all_civ_hts_presentes_spi_supportedes_values_match_cives_quantities_match_cives_currency_and_exchange_ratees_adjustments_match_incotermses_assists_declaredes_commissions_declaredes_first_sale_supportedes_mid_is_actual_manufactureres_relationship_recordedes_article_set_reproducedes_set_origin_dominancees_set_component_quantitieses_ch99_consistentes_232_claim_matches_descriptiones_232_claim_contradictedes_fees_mpf_hmfes_lines_completees_port_of_lading_matches_transportes_gross_weight_matches_packinges_ior_number_matches_profilees_pga_evidence_present
unsetValidationRulesstring[]requiredread-only
billingobjectrequired
1 field
- actionstringrequired
  One ofentry_preparedper_beadnone
lanestringrequired
One ofentryclassification

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /pipeline-configurations

curl "https://api.tarifflo.com/api/v2/pipeline-configurations" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

[
  {
    "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "name": "Example",
    "description": "Laptop computer, 14 inch",
    "isDefault": true,
    "locked": true,
    "isTemporary": true,
    "general": {
      "requiredContent": {
        "filed_baseline": true
      },
      "unidentifiedDocuments": "skip",
      "filerId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "importerProfileId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "reuseByHash": {
        "ocr": true
      },
      "includeLiquidated": true,
      "askUsContent": true,
      "changeRiskThreshold": 1,
      "filing": {
        "savingsThresholdUsd": 100,
        "dutyDecreasesOnly": true
      },
      "asycudaCountry": "BB",
      "rateReport": {
        "primaryDate": "2026-01-15",
        "loadingDate": "2026-01-15",
        "templateId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
        "includeRationales": true,
        "includeChapter99": true
      }
    },
    "jobs": {
      "sort_documents": {
        "on": true
      }
    },
    "validationRules": {
      "civ_ior_named": true
    },
    "unsetValidationRules": [
      "civ_ior_named"
    ],
    "billing": {
      "action": "entry_prepared"
    },
    "lane": "entry"
  }
]

Create a pipeline configuration

posthttps://api.tarifflo.com/api/v2/pipeline-configurations

Requires the API key scope filing.

AuthApiKeyorBearer

Request body

application/json

object

namestringrequired
Max 80 characters.
copyFromstring
Optional: the configuration id to start from.
descriptionstring
One sentence on what this configuration is for (max 240 characters).
jobsstring[]
The COMPLETE list of jobs to switch on; every job not listed is off. Read get_configuration's jobCatalog for what each does. Omit to keep the starting point's jobs.
requiredContentstring[]
The COMPLETE list of content the documents must carry, on top of what the jobs already lock. filed_baseline makes it a post-entry (already filed) configuration. Omit to keep the starting point's.
unidentifiedDocumentsstring
ask holds the upload when a document cannot be identified; skip leaves it unread.
One ofskipask
importerProfileIdstring | null
The CLIENT: the importer profile (see list_importer_profiles) every entry of an upload files for. Required on an entry configuration. An importer organization's is always its own.
filerIdstring | null
The filer whose codes the run transmits under (see list_filers). Required when stage_filing is on.
asycudaCountrystring | null
The ASYCUDA World administration asycuda_declaration builds for. Required when that job is on.
validationRulesmap<string, boolean>
Rule key → on/off, merged over the starting point's rules. get_configuration lists every rule key.
Keys 42 values
civ_ior_namedciv_us_consignee_for_foreign_iorciv_description_sufficientciv_country_of_originciv_quantityciv_set_components_reconcileciv_unit_and_total_valueciv_total_reconcilesciv_currencyciv_incoterms_or_chargesciv_value_adjustmentsciv_manufacturer_identifiedciv_documents_belonges_parties_match_cives_coo_matches_cives_country_of_export_matches_transportes_export_date_after_ladinges_hts_matches_cives_part_number_correctes_all_civ_hts_presentes_spi_supportedes_values_match_cives_quantities_match_cives_currency_and_exchange_ratees_adjustments_match_incotermses_assists_declaredes_commissions_declaredes_first_sale_supportedes_mid_is_actual_manufactureres_relationship_recordedes_article_set_reproducedes_set_origin_dominancees_set_component_quantitieses_ch99_consistentes_232_claim_matches_descriptiones_232_claim_contradictedes_fees_mpf_hmfes_lines_completees_port_of_lading_matches_transportes_gross_weight_matches_packinges_ior_number_matches_profilees_pga_evidence_present

Responses

201Successful response

application/json

object

idstringrequired
Pass it to file_documents as configurationId.
namestringrequired
descriptionstringrequired
isDefaultbooleanrequired
postEntrybooleanrequired
true: post-entry, corrects entries already filed. false: pre-entry, builds entries from the documents.
jobsOnstring[]required
importerProfileIdstring | nullrequired
The client every entry files for; null while none is picked.
filerIdstring | nullrequired
asycudaCountrystring | nullrequired
billingstringrequired
One ofentry_preparedper_beadnone
planstringrequired
The plan this configuration runs, in plain words.

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /pipeline-configurations

curl -X POST "https://api.tarifflo.com/api/v2/pipeline-configurations" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example"
  }'

Response · 201

JSON

{
  "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "name": "Example",
  "description": "Laptop computer, 14 inch",
  "isDefault": true,
  "postEntry": true,
  "jobsOn": [
    "sort_documents"
  ],
  "importerProfileId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "filerId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "asycudaCountry": "BB",
  "billing": "entry_prepared",
  "plan": "string"
}

List the configurations a sort session can pick

gethttps://api.tarifflo.com/api/v2/sort-sessions/{sortSessionId}/pipeline-configurations

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

sortSessionIdstringrequired

Responses

200Successful response

application/json

object

configurationsobject[]required
12 fields per item
- idstringrequired
- namestringrequired
- descriptionstringrequired
- isDefaultbooleanrequired
- lockedbooleanrequired
- isTemporarybooleanrequired
- generalobjectrequired
  11 fields
  requiredContentmap<string, boolean>required
  Keysfiled_baselineproduct_descriptionhts_codeline_valuequantitycountry_of_originentry_datetransport_eventimporter_identity
  unidentifiedDocumentsstringrequired
  One ofskipask
  filerIdstring | nullrequired
  importerProfileIdstring | nullrequired
  reuseByHashmap<string, boolean>required
  Keysocrbeads_facts
  includeLiquidatedbooleanrequired
  askUsContentbooleanrequired
  changeRiskThresholdintegerrequired
  ≥ 0≤ 100
  filingobjectrequired
  2 fields
  savingsThresholdUsdnumberrequired
  ≥ 0
  dutyDecreasesOnlybooleanrequired
  asycudaCountrystring | nullrequired
  rateReportobjectrequired
  5 fields
  primaryDatestring | nullrequired
  loadingDatestring | nullrequired
  templateIdstring | nullrequired
  includeRationalesbooleanrequired
  includeChapter99booleanrequired
- jobsmap<string, object>required
  Keys 18 values
  sort_documentsagent_sortclassify_productsweb_searchinvoice_htseccncoospipgaadcvddutyreviewreportvalidateapproved_codesstage_filingcargo_release_valueasycuda_declaration
  1 field per value
  onbooleanrequired
- validationRulesmap<string, boolean>required
  Keys 42 values
  civ_ior_namedciv_us_consignee_for_foreign_iorciv_description_sufficientciv_country_of_originciv_quantityciv_set_components_reconcileciv_unit_and_total_valueciv_total_reconcilesciv_currencyciv_incoterms_or_chargesciv_value_adjustmentsciv_manufacturer_identifiedciv_documents_belonges_parties_match_cives_coo_matches_cives_country_of_export_matches_transportes_export_date_after_ladinges_hts_matches_cives_part_number_correctes_all_civ_hts_presentes_spi_supportedes_values_match_cives_quantities_match_cives_currency_and_exchange_ratees_adjustments_match_incotermses_assists_declaredes_commissions_declaredes_first_sale_supportedes_mid_is_actual_manufactureres_relationship_recordedes_article_set_reproducedes_set_origin_dominancees_set_component_quantitieses_ch99_consistentes_232_claim_matches_descriptiones_232_claim_contradictedes_fees_mpf_hmfes_lines_completees_port_of_lading_matches_transportes_gross_weight_matches_packinges_ior_number_matches_profilees_pga_evidence_present
- unsetValidationRulesstring[]requiredread-only
- billingobjectrequired
  1 field
  actionstringrequired
  One ofentry_preparedper_beadnone
- lanestringrequired
  One ofentryclassification
temporaryobject | nullrequired
2 options
Any of
1.object
idstringrequired
namestringrequired
descriptionstringrequired
isDefaultbooleanrequired
lockedbooleanrequired
isTemporarybooleanrequired
generalobjectrequired
11 fields
requiredContentmap<string, boolean>required
Keysfiled_baselineproduct_descriptionhts_codeline_valuequantitycountry_of_originentry_datetransport_eventimporter_identity
unidentifiedDocumentsstringrequired
One ofskipask
filerIdstring | nullrequired
importerProfileIdstring | nullrequired
reuseByHashmap<string, boolean>required
Keysocrbeads_facts
includeLiquidatedbooleanrequired
askUsContentbooleanrequired
changeRiskThresholdintegerrequired
≥ 0≤ 100
filingobjectrequired
2 fields
savingsThresholdUsdnumberrequired
≥ 0
dutyDecreasesOnlybooleanrequired
asycudaCountrystring | nullrequired
rateReportobjectrequired
5 fields
primaryDatestring | nullrequired
loadingDatestring | nullrequired
templateIdstring | nullrequired
includeRationalesbooleanrequired
includeChapter99booleanrequired
jobsmap<string, object>required
Keys 18 values
sort_documentsagent_sortclassify_productsweb_searchinvoice_htseccncoospipgaadcvddutyreviewreportvalidateapproved_codesstage_filingcargo_release_valueasycuda_declaration
1 field per value
onbooleanrequired
validationRulesmap<string, boolean>required
Keys 42 values
civ_ior_namedciv_us_consignee_for_foreign_iorciv_description_sufficientciv_country_of_originciv_quantityciv_set_components_reconcileciv_unit_and_total_valueciv_total_reconcilesciv_currencyciv_incoterms_or_chargesciv_value_adjustmentsciv_manufacturer_identifiedciv_documents_belonges_parties_match_cives_coo_matches_cives_country_of_export_matches_transportes_export_date_after_ladinges_hts_matches_cives_part_number_correctes_all_civ_hts_presentes_spi_supportedes_values_match_cives_quantities_match_cives_currency_and_exchange_ratees_adjustments_match_incotermses_assists_declaredes_commissions_declaredes_first_sale_supportedes_mid_is_actual_manufactureres_relationship_recordedes_article_set_reproducedes_set_origin_dominancees_set_component_quantitieses_ch99_consistentes_232_claim_matches_descriptiones_232_claim_contradictedes_fees_mpf_hmfes_lines_completees_port_of_lading_matches_transportes_gross_weight_matches_packinges_ior_number_matches_profilees_pga_evidence_present
unsetValidationRulesstring[]requiredread-only
billingobjectrequired
1 field
actionstringrequired
One ofentry_preparedper_beadnone
lanestringrequired
One ofentryclassification
2.null
selectedIdstring | nullrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /sort-sessions/{sortSessionId}/pipeline-configurations

curl "https://api.tarifflo.com/api/v2/sort-sessions/01a19e37-837d-7c16-9a5d-3bef820fcff7/pipeline-configurations" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "configurations": [
    {
      "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "name": "Example",
      "description": "Laptop computer, 14 inch",
      "isDefault": true,
      "locked": true,
      "isTemporary": true,
      "general": {
        "requiredContent": {
          "filed_baseline": true
        },
        "unidentifiedDocuments": "skip",
        "filerId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
        "importerProfileId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
        "reuseByHash": {
          "ocr": true
        },
        "includeLiquidated": true,
        "askUsContent": true,
        "changeRiskThreshold": 1,
        "filing": {
          "savingsThresholdUsd": 100,
          "dutyDecreasesOnly": true
        },
        "asycudaCountry": "BB",
        "rateReport": {
          "primaryDate": "2026-01-15",
          "loadingDate": "2026-01-15",
          "templateId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
          "includeRationales": true,
          "includeChapter99": true
        }
      },
      "jobs": {
        "sort_documents": {
          "on": true
        }
      },
      "validationRules": {
        "civ_ior_named": true
      },
      "unsetValidationRules": [
        "civ_ior_named"
      ],
      "billing": {
        "action": "entry_prepared"
      },
      "lane": "entry"
    }
  ],
  "temporary": {
    "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "name": "Example",
    "description": "Laptop computer, 14 inch",
    "isDefault": true,
    "locked": true,
    "isTemporary": true,
    "general": {
      "requiredContent": {
        "filed_baseline": true
      },
      "unidentifiedDocuments": "skip",
      "filerId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "importerProfileId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "reuseByHash": {
        "ocr": true
      },
      "includeLiquidated": true,
      "askUsContent": true,
      "changeRiskThreshold": 1,
      "filing": {
        "savingsThresholdUsd": 100,
        "dutyDecreasesOnly": true
      },
      "asycudaCountry": "BB",
      "rateReport": {
        "primaryDate": "2026-01-15",
        "loadingDate": "2026-01-15",
        "templateId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
        "includeRationales": true,
        "includeChapter99": true
      }
    },
    "jobs": {
      "sort_documents": {
        "on": true
      }
    },
    "validationRules": {
      "civ_ior_named": true
    },
    "unsetValidationRules": [
      "civ_ior_named"
    ],
    "billing": {
      "action": "entry_prepared"
    },
    "lane": "entry"
  },
  "selectedId": "01a19e37-837d-7c16-9a5d-3bef820fcff7"
}

16 endpoints

Uploads

Create an upload, add files, start the run, then read its products, open questions and answers.

Create an upload on a configuration

posthttps://api.tarifflo.com/api/v2/sort-sessions

Requires the API key scope filing.

AuthApiKeyorBearer

Request body

application/json

object

configurationIdstring
namestring
min length 1max length 100pattern: ^[a-zA-Z0-9-_ ]+$

Responses

200Successful response

application/json

object

idstringrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /sort-sessions

curl -X POST "https://api.tarifflo.com/api/v2/sort-sessions" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "configurationId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "name": "Example"
  }'

Response · 200

JSON

{
  "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7"
}

List the organization's uploads

posthttps://api.tarifflo.com/api/v2/sort-sessions/search

Requires the API key scope filing.

AuthApiKeyorBearer

Request body

application/json

object

flowTypesstring[]required
min items 1

Responses

200Successful response

application/json

object[]

idstringrequired
namestringrequired
flowTypestringrequired
One ofpscproduct_auditclassificationfilingpsc_filing
entriesnumberrequired
documentsnumberrequired
hasRunbooleanrequired
configurationNamestring | nullrequired
createdAtstringrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /sort-sessions/search

curl -X POST "https://api.tarifflo.com/api/v2/sort-sessions/search" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "flowTypes": [
      "psc"
    ]
  }'

Response · 200

JSON

[
  {
    "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "name": "Example",
    "flowType": "psc",
    "entries": 100,
    "documents": 100,
    "hasRun": true,
    "configurationName": "Example",
    "createdAt": "string"
  }
]

List the uploads a linked broker made for this organization

posthttps://api.tarifflo.com/api/v2/sort-sessions/broker-filed

Requires the API key scope filing.

AuthApiKeyorBearer

Responses

200Successful response

application/json

object[]

idstringrequired
namestringrequired
flowTypestringrequired
One ofpscproduct_auditclassificationfilingpsc_filing
entriesnumberrequired
documentsnumberrequired
hasRunbooleanrequired
configurationNamestring | nullrequired
createdAtstringrequired
filedBystringrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /sort-sessions/broker-filed

curl -X POST "https://api.tarifflo.com/api/v2/sort-sessions/broker-filed" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

[
  {
    "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "name": "Example",
    "flowType": "psc",
    "entries": 100,
    "documents": 100,
    "hasRun": true,
    "configurationName": "Example",
    "createdAt": "string",
    "filedBy": "string"
  }
]

A page of the upload's entries with their run and gates

posthttps://api.tarifflo.com/api/v2/sort-sessions/{sortSessionId}/entries

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

sortSessionIdstringrequired

Request body

application/json

object

offsetintegerrequired
≥ 0≤ 9007199254740991
limitintegerrequired
≥ 1≤ 100
statusFilterobject
2 fields
- sourcestringrequired
  One ofgateholdquestionfailureunfinished
- keystringrequired
  min length 1
sortobject
2 fields
- columnstringrequired
  One ofentrypartystatusvarianceupdated
- directionstringrequired
  One ofascdesc
searchstring
min length 1max length 100
statusstring
One ofneeds_youfailedheldin_progresscomplete

Responses

200Successful response

application/json

object

rowsobject[]required
14 fields per item
- idstringrequired
- labelstringrequired
- entryNumberstring | nullrequired
- partystring | nullrequired
- runobject | nullrequired
  2 options
  Any of
  1.object
  runobjectrequired
  21 fields
  idstringrequired
  organization_idstringrequired
  user_idstringrequired
  definitionobjectrequired
  1 field
  stagesobject[]required
  6 fields per item
  keystringrequired
  dependsOnstring[]required
  requiresApprovalboolean
  parkPolicystring
  One ofholdexclude
  unitFailurePolicystring
  One ofblockcontinue
  paramsobject
  contextobjectrequired
  2 fields
  productIdsstring[]required
  workliststring[]
  source_kindstring | nullrequired
  source_ref_idstring | nullrequired
  parent_run_idstring | nullrequired
  restartobject | nullrequired
  2 options
  Any of
  1.object
  fromStagestringrequired
  atstringrequired
  2.null
  holdsmap<string, object>required
  5 fields per value
  bystringrequired
  atstringrequired
  reasonstring | nullrequired
  expiresAtstringrequired
  inheritbooleanrequired
  statusstringrequired
  One ofrunningblockedcompletefailedcancelled
  recent_update_idstring | nullrequired
  errorstring | nullrequired
  last_swept_atstring | nullrequired
  blocked_atstring | nullrequired
  entry_reservation_idstring | nullrequired
  api_key_idstring | nullrequired
  api_environmentstring | nullrequired
  webhook_urlstring | nullrequired
  created_atstringrequired
  updated_atstringrequired
  stagesobject[]required
  28 fields per item
  run_idstringrequired
  stage_keystringrequired
  statusstringrequired
  One ofpendingrunningfinalizingcomplete_with_openawaiting_gateheldcompletefailedblockedskipped
  sealedbooleanrequired
  totalnumberrequired
  completednumberrequired
  failednumberrequired
  parkednumberrequired
  finalize_attemptsnumberrequired
  finalize_started_atstring | nullrequired
  approved_bystring | nullrequired
  hold_released_atstring | nullrequired
  hold_released_bystring | nullrequired
  recent_update_idstring | nullrequired
  errorstring | nullrequired
  noticestring | nullrequired
  started_atstring | nullrequired
  completed_atstring | nullrequired
  blocked_credits_neededstring | nullrequired
  blocked_atstring | nullrequired
  blocked_deltaobject | nullrequired
  2 options
  Any of
  1.object
  productIdsstring[]required
  2.null
  created_atstringrequired
  updated_atstringrequired
  awaitingInputCountnumberrequired
  failedUnitCountnumberrequired
  failedUnitsobject[]required
  4 fields per item
  jobIdstringrequired
  jobTypestringrequired
  productIdstring | nullrequired
  errorstring | nullrequired
  gateKeystring | nullrequired
  holdobject | nullrequired
  2 options
  Any of
  1.object
  sincestring | nullrequired
  expiresAtstring | nullrequired
  expiredbooleanrequired
  2.null
  2.null
- productDescriptionGateobjectrequired
  3 fields
  gatedbooleanrequired
  documentsobject[]required
  3 fields per item
  canonicalDocTypestringrequired
  rolestringrequired
  One ofheader_sourceline_sourcesupportingunknown
  countnumberrequired
  lineSourceDocCountnumberrequired
- invoiceCoverageGateobjectrequired
  4 fields
  gatedbooleanrequired
  missingInvoicesobject[]required
  2 fields per item
  invoiceNumberstringrequired
  entrystringrequired
  acknowledgedobject[]required
  2 fields per item
  invoiceNumberstringrequired
  entrystringrequired
  noCommercialInvoiceobject | nullrequired
  2 options
  Any of
  1.object
  packingListsnumberrequired
  titlestringrequired
  messagestringrequired
  2.null
- documentCoverageGateobjectrequired
  4 fields
  gatedbooleanrequired
  missingobject[]required
  3 fields per item
  requirementstringrequired
  One offiled_baselineproduct_descriptionhts_codeline_valuequantitycountry_of_originentry_datetransport_eventimporter_identity
  labelstringrequired
  docTypesstring[]required
  waivedobject[]required
  3 fields per item
  requirementstringrequired
  One offiled_baselineproduct_descriptionhts_codeline_valuequantitycountry_of_originentry_datetransport_eventimporter_identity
  labelstringrequired
  docTypesstring[]required
  noCommercialInvoiceobject | nullrequired
  2 options
  Any of
  1.object
  packingListsnumberrequired
  titlestringrequired
  messagestringrequired
  2.null
- valueGateobjectrequired
  2 fields
  gatedbooleanrequired
  linesnumberrequired
- validationGateobjectrequired
  3 fields
  gatedbooleanrequired
  findingsobject[]required
  17 fields per item
  idstringrequired
  rulestringrequired
  ruleLabelstring | nullrequired
  aboutRulestring | nullrequired
  severitystringrequired
  One oferrorwarninginfo
  subjectKeystringrequired
  subjectstring | nullrequired
  summarystringrequired
  expectedstring | nullrequired
  actualstring | nullrequired
  recommendedFixstringrequired
  sourceDocIdstring | nullrequired
  originalLineIdstring | nullrequired
  lineRefstring | nullrequired
  filerCodestring | nullrequired
  entryNumberstring | nullrequired
  exposureUsdnumber | nullrequired
  errorCountnumberrequired
- filedLineCountnumberrequired
- filedEnteredValuenumberrequired
- openQuestionsnumberrequired
- savingsobject | nullrequired
  2 options
  Any of
  1.object
  entrySessionIdstringrequired
  savingsnumberrequired
  dutyIncreasebooleanrequired
  proposedLineCountnumberrequired
  needsReviewCountnumberrequired
  entriesobject[]required
  5 fields per item
  filerCodestringrequired
  entryNumberstringrequired
  savingsnumberrequired
  dutyIncreasebooleanrequired
  baselinestringrequired
  One offiled_lines7501_totalsunavailable
  linesobject[]required
  11 fields per item
  idstringrequired
  filerCodestringrequired
  entryNumberstringrequired
  lineNumbernumberrequired
  statusstringrequired
  One ofproposedneeds_reviewcoo_unresolvedkept_originalunattributed_originalexcluded_from_entry
  reviewReasonsstring[]required
  countryOfOriginstring | nullrequired
  valuenumberrequired
  dutynumber | nullrequired
  htsobject[]required
  4 fields per item
  htsNumberstringrequired
  tierstringrequired
  One ofbasech99ch98
  valuenumber | nullrequired
  dutynumber | nullrequired
  itemsobject[]required
  4 fields per item
  productIdstringrequired
  partNumberstring | nullrequired
  descriptionstring | nullrequired
  valuenumberrequired
  dutyMeasuredbooleanrequired
  postEntrybooleanrequired
  dutyPayablenumberrequired
  2.null
totalnumberrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /sort-sessions/{sortSessionId}/entries

curl -X POST "https://api.tarifflo.com/api/v2/sort-sessions/01a19e37-837d-7c16-9a5d-3bef820fcff7/entries" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "offset": 1,
    "limit": 1
  }'

Response · 200

JSON

{
  "rows": [
    {
      "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "label": "string",
      "entryNumber": "string",
      "party": "string",
      "run": {
        "run": {
          "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
          "organization_id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
          "user_id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
          "definition": {
            "stages": null
          },
          "context": {
            "productIds": null,
            "worklist": null
          },
          "source_kind": "entry_session",
          "source_ref_id": null,
          "parent_run_id": null,
          "restart": null,
          "holds": {
            "key": null
          },
          "status": "running",
          "recent_update_id": null,
          "error": null,
          "last_swept_at": null,
          "blocked_at": null,
          "entry_reservation_id": null,
          "api_key_id": null,
          "api_environment": "live",
          "webhook_url": null,
          "created_at": "string",
          "updated_at": "2026-01-15"
        },
        "stages": [
          {
            "run_id": null,
            "stage_key": null,
            "status": "complete_with_open",
            "sealed": null,
            "total": null,
            "completed": null,
            "failed": null,
            "parked": null,
            "finalize_attempts": null,
            "finalize_started_at": null,
            "approved_by": null,
            "hold_released_at": null,
            "hold_released_by": null,
            "recent_update_id": null,
            "error": null,
            "notice": null,
            "started_at": null,
            "completed_at": null,
            "blocked_credits_needed": null,
            "blocked_at": null,
            "blocked_delta": null,
            "created_at": null,
            "updated_at": null,
            "awaitingInputCount": null,
            "failedUnitCount": null,
            "failedUnits": null,
            "gateKey": null,
            "hold": null
          }
        ]
      },
      "productDescriptionGate": {
        "gated": true,
        "documents": [
          {
            "canonicalDocType": "string",
            "role": "header_source",
            "count": 1
          }
        ],
        "lineSourceDocCount": 1
      },
      "invoiceCoverageGate": {
        "gated": true,
        "missingInvoices": [
          {
            "invoiceNumber": "string",
            "entry": "string"
          }
        ],
        "acknowledged": [
          {
            "invoiceNumber": "string",
            "entry": "string"
          }
        ],
        "noCommercialInvoice": {
          "packingLists": 100,
          "title": "string",
          "message": "string"
        }
      },
      "documentCoverageGate": {
        "gated": true,
        "missing": [
          {
            "requirement": "entry_date",
            "label": "string",
            "docTypes": [
              null
            ]
          }
        ],
        "waived": [
          {
            "requirement": "entry_date",
            "label": "string",
            "docTypes": [
              null
            ]
          }
        ],
        "noCommercialInvoice": {
          "packingLists": 100,
          "title": "string",
          "message": "string"
        }
      },
      "valueGate": {
        "gated": true,
        "lines": 100
      },
      "validationGate": {
        "gated": true,
        "findings": [
          {
            "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
            "rule": "string",
            "ruleLabel": null,
            "aboutRule": null,
            "severity": "error",
            "subjectKey": "string",
            "subject": null,
            "summary": "string",
            "expected": null,
            "actual": null,
            "recommendedFix": "string",
            "sourceDocId": null,
            "originalLineId": null,
            "lineRef": null,
            "filerCode": null,
            "entryNumber": null,
            "exposureUsd": null
          }
        ],
        "errorCount": 1
      },
      "filedLineCount": 1,
      "filedEnteredValue": 1000,
      "openQuestions": 100,
      "savings": {
        "entrySessionId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
        "savings": 100,
        "dutyIncrease": true,
        "proposedLineCount": 1,
        "needsReviewCount": 1,
        "entries": [
          {
            "filerCode": null,
            "entryNumber": null,
            "savings": null,
            "dutyIncrease": null,
            "baseline": "filed_lines"
          }
        ],
        "lines": [
          {
            "id": null,
            "filerCode": null,
            "entryNumber": null,
            "lineNumber": null,
            "status": "excluded_from_entry",
            "reviewReasons": null,
            "countryOfOrigin": null,
            "value": null,
            "duty": null,
            "hts": null,
            "items": null
          }
        ],
        "dutyMeasured": true,
        "postEntry": true,
        "dutyPayable": 100
      }
    }
  ],
  "total": 1
}

Where the upload stands

gethttps://api.tarifflo.com/api/v2/sort-sessions/{sortSessionId}

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

sortSessionIdstringrequired

Responses

200Successful response

application/json

object

idstringrequired
namestringrequired
configurationIdstringrequired
lanestringrequired
One ofentryclassification
runsobject[]required
5 fields per item
- scopestringrequired
  One ofuploadentry
- refIdstringrequired
- runIdstringrequired
- statusstringrequired
  One ofrunningblockedcompletefailedcancelled
- stagesobject[]required
  8 fields per item
  keystringrequired
  statusstringrequired
  One ofpendingrunningfinalizingcomplete_with_openawaiting_gateheldcompletefailedblockedskipped
  totalnumberrequired
  completednumberrequired
  failednumberrequired
  parkednumberrequired
  awaitingInputnumberrequired
  creditsNeedednumber | nullrequired
countsobject | nullrequired
2 options
Any of
1.object
productsnumberrequired
classifiednumberrequired
withOriginnumberrequired
pricednumberrequired
comparednumberrequired
unpriceablenumberrequired
pendingApprovalnumberrequired
2.null
reportobject | object | object | nullrequired
2 options
Any of
1.object | object | object
One of
1.object
state"ready"required
runIdstringrequired
reportIdstringrequired
fileNamestringrequired
urlstringrequired
expiresInMinutesnumberrequired
2.object
state"building"required
runIdstringrequired
3.object
state"unavailable"required
reasonstringrequired
2.null

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /sort-sessions/{sortSessionId}

curl "https://api.tarifflo.com/api/v2/sort-sessions/01a19e37-837d-7c16-9a5d-3bef820fcff7" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "name": "Example",
  "configurationId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "lane": "entry",
  "runs": [
    {
      "scope": "upload",
      "refId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "runId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "status": "running",
      "stages": [
        {
          "key": "string",
          "status": "pending",
          "total": 1,
          "completed": 0,
          "failed": 100,
          "parked": 100,
          "awaitingInput": 100,
          "creditsNeeded": 100
        }
      ]
    }
  ],
  "counts": {
    "products": 100,
    "classified": 100,
    "withOrigin": 100,
    "priced": 100,
    "compared": 100,
    "unpriceable": 100,
    "pendingApproval": 100
  },
  "report": {
    "state": "ready",
    "runId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "reportId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "fileName": "Example",
    "url": "https://example.com/webhooks/tarifflo",
    "expiresInMinutes": 100
  }
}

Delete an upload and everything under it

deletehttps://api.tarifflo.com/api/v2/sort-sessions/{sortSessionId}

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

sortSessionIdstringrequired

Responses

200Successful response

application/json

object

deletedtruerequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

DELETE /sort-sessions/{sortSessionId}

curl -X DELETE "https://api.tarifflo.com/api/v2/sort-sessions/01a19e37-837d-7c16-9a5d-3bef820fcff7" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "deleted": true
}

Add files to an upload: one signed PUT URL per file

posthttps://api.tarifflo.com/api/v2/sort-sessions/{sortSessionId}/files

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

sortSessionIdstringrequired

Request body

application/json

object

entrySessionIdstring | null
filesobject[]required
min items 1max items 200
6 fields per item
- filenamestringrequired
  min length 1
- mimeTypestringrequired
  min length 1
- sizeintegerrequired
  ≥ 0≤ 104857600
- pathstring[]
  max items 50default: []
- contentHashstring
- declaredDoctype"product_sheet"

Responses

200Successful response

application/json

object

resultsobject[]required
6 fields per item
- packetIdstringrequired
- signedUrlstring | nullrequired
- filenamestringrequired
- pathstring[]required
- reusedbooleanrequired
- entryAttachmentstring | nullrequired
mintednumberrequired
reusednumberrequired
attributednumberrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /sort-sessions/{sortSessionId}/files

curl -X POST "https://api.tarifflo.com/api/v2/sort-sessions/01a19e37-837d-7c16-9a5d-3bef820fcff7/files" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {
        "filename": "Example",
        "mimeType": "string",
        "size": 1
      }
    ]
  }'

Response · 200

JSON

{
  "results": [
    {
      "packetId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "signedUrl": "https://example.com/webhooks/tarifflo",
      "filename": "Example",
      "path": [
        "string"
      ],
      "reused": true,
      "entryAttachment": "in_sort_run"
    }
  ],
  "minted": 100,
  "reused": 0,
  "attributed": 100
}

Confirm the files whose PUT landed

posthttps://api.tarifflo.com/api/v2/sort-sessions/{sortSessionId}/files/confirm

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

sortSessionIdstringrequired

Request body

application/json

object

packetIdsstring[]required
min items 1max items 200

Responses

200Successful response

application/json

object

confirmednumberrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /sort-sessions/{sortSessionId}/files/confirm

curl -X POST "https://api.tarifflo.com/api/v2/sort-sessions/01a19e37-837d-7c16-9a5d-3bef820fcff7/files/confirm" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "packetIds": [
      "01a19e37-837d-7c16-9a5d-3bef820fcff7"
    ]
  }'

Response · 200

JSON

{
  "confirmed": 100
}

Upload one entry's documents inline and start it

posthttps://api.tarifflo.com/api/v2/entry-uploads/inline

Requires the API key scope filing.

AuthApiKeyorBearer

Request body

application/json

object

attachmentsobject[]required
Each document's filename and its bytes, base64.
min items 1
2 fields per item
- filenamestringrequired
- contentBase64stringrequired
configurationIdstring
REQUIRED for a new entry: the pipeline configuration it runs (list_configurations).
entryIdstring
Optional: add to this existing entry instead of starting a new one.
namestring
Optional name for a new entry.

Responses

200Successful response

application/json

object

The documents are stored on one entry summary and the analysis has started. Then call wait_for_work with jobType "filing" and this sortSessionId repeatedly until it says the entry is ready.

sortSessionIdstringrequired
The upload. wait_for_work with jobType "filing" takes it as jobId.
entrySessionIdstringrequired
The one entry; pass it as entryId to add more documents to it.
uploadednumberrequired
Documents stored by this call.
reusednumberrequired
Documents already on file, not stored again.
configurationobject | nullrequired
The configuration a NEW entry runs (null when the documents went to an existing entry).
2 options
Any of
1.object
idstringrequired
namestringrequired
posturestringrequired
2.null

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /entry-uploads/inline

curl -X POST "https://api.tarifflo.com/api/v2/entry-uploads/inline" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "attachments": [
      {
        "filename": "Example",
        "contentBase64": "string"
      }
    ]
  }'

Response · 200

JSON

{
  "sortSessionId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "entrySessionId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "uploaded": 100,
  "reused": 0,
  "configuration": {
    "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "name": "Example",
    "posture": "string"
  }
}

Start one entry's upload: one signed PUT URL per file

posthttps://api.tarifflo.com/api/v2/entry-uploads

Requires the API key scope filing.

AuthApiKeyorBearer

Request body

application/json

object

filesobject[]required
The files you will PUT yourself.
min items 1
6 fields per item
- filenamestringrequired
- sizenumberrequired
  Bytes.
- contentHashstring
  Optional SHA-256 hex of the bytes — a file already on the upload is not uploaded again.
- pathstring[]
  Optional folder path the file came from, outermost first.
- mimeTypestring
- declaredDoctypestring
  Optional: the user declared this spreadsheet a product sheet.
  One ofproduct_sheet
entryIdstring
Optional: attach to this existing entry instead of starting a new one.
namestring
Optional name for a new entry.
configurationIdstring
REQUIRED for a new entry: the pipeline configuration it runs (list_configurations).

Responses

200Successful response

application/json

object

Then call confirm_uploads with this sortSessionId, entrySessionId and the outcome of EVERY putUrl (uploaded / failed / skipped). The analysis starts only when every file is in storage.

sortSessionIdstringrequired
The upload. wait_for_work with jobType "filing" takes it as jobId.
entrySessionIdstringrequired
The one entry; pass it as entryId to add more documents to it.
uploadsobject[]required
5 fields per item
- filenamestringrequired
- packetIdstringrequired
- putUrlstring | nullrequired
  PUT the file's raw bytes here (e.g. curl -sf -X PUT -T <path> '<putUrl>'). Null when alreadyOnFile.
- alreadyOnFilebooleanrequired
  True: these bytes are already on the upload; nothing to PUT.
- entryAttachmentstring
  One ofattachedalready_on_entryin_sort_run
configurationobject | nullrequired
The configuration a NEW entry runs (null when the documents went to an existing entry).
2 options
Any of
1.object
idstringrequired
namestringrequired
posturestringrequired
2.null

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /entry-uploads

curl -X POST "https://api.tarifflo.com/api/v2/entry-uploads" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {
        "filename": "Example",
        "size": 100
      }
    ]
  }'

Response · 200

JSON

{
  "sortSessionId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "entrySessionId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "uploads": [
    {
      "filename": "Example",
      "packetId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "putUrl": "https://example.com/webhooks/tarifflo",
      "alreadyOnFile": true,
      "entryAttachment": "already_on_entry"
    }
  ],
  "configuration": {
    "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "name": "Example",
    "posture": "string"
  }
}

Settle one entry's PUTs against storage and start it

posthttps://api.tarifflo.com/api/v2/entry-uploads/{sortSessionId}/confirm

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

sortSessionIdstringrequired

Request body

application/json

object

entrySessionIdstringrequired
The entry file_documents returned.
uploadsobject[]required
One item per putUrl: the packetId and what the PUT did.
2 fields per item
- packetIdstringrequired
- outcomestringrequired
  uploaded = the PUT returned 2xx; failed = it did not; skipped = do not file this document.
  One ofuploadedfailedskipped
startAnalysisboolean
Default true. False only confirms; a later call starts the analysis.

Responses

200Successful response

application/json

object

Tarifflo checked storage for every putUrl file_documents returned.

sortSessionIdstringrequired
The upload. wait_for_work with jobType "filing" takes it as jobId.
entrySessionIdstringrequired
The one entry; pass it as entryId to add more documents to it.
confirmednumberrequired
skippednumberrequired
unsettledobject[]required
Files not in storage, so the analysis did NOT start. PUT each to its new putUrl, then call confirm_uploads again with an outcome for each; report "skipped" for a file the user does not want filed.
4 fields per item
- packetIdstringrequired
- filenamestringrequired
- reasonstringrequired
  One ofnot_reportedreported_failednot_in_storagesize_mismatch
- putUrlstringrequired
  A fresh URL: PUT the file again here.
startedbooleanrequired
True: every file is stored and the analysis started. Then call wait_for_work with jobType "filing" and this sortSessionId repeatedly until it says the entry is ready.

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /entry-uploads/{sortSessionId}/confirm

curl -X POST "https://api.tarifflo.com/api/v2/entry-uploads/01a19e37-837d-7c16-9a5d-3bef820fcff7/confirm" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entrySessionId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "uploads": [
      {
        "packetId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
        "outcome": "uploaded"
      }
    ]
  }'

Response · 200

JSON

{
  "sortSessionId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "entrySessionId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "confirmed": 100,
  "skipped": 100,
  "unsettled": [
    {
      "packetId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "filename": "Example",
      "reason": "not_in_storage",
      "putUrl": "https://example.com/webhooks/tarifflo"
    }
  ],
  "started": true
}

Start, or re-drive, the upload's run

posthttps://api.tarifflo.com/api/v2/sort-sessions/{sortSessionId}/start

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

sortSessionIdstringrequired

Responses

200Successful response

application/json

object

queuedCountnumberrequired
runIdstring | nullrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /sort-sessions/{sortSessionId}/start

curl -X POST "https://api.tarifflo.com/api/v2/sort-sessions/01a19e37-837d-7c16-9a5d-3bef820fcff7/start" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "queuedCount": 1,
  "runId": "01a19e37-837d-7c16-9a5d-3bef820fcff7"
}

A product's rate facts and its printed-code comparison

gethttps://api.tarifflo.com/api/v2/products/{productId}/classification

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

productIdstringrequired

Responses

200Successful response

application/json

object

factsobjectrequired
3 fields
- entryDatestring | nullrequired
- shipmentValuenumber | nullrequired
- sharesobjectrequired
  4 fields
  steelnumber
  aluminumnumber
  coppernumber
  usContentnumber
comparisonobject | nullrequired
2 options
Any of
1.object
product_idstringrequired
destinationstringrequired
originstring | nullrequired
original_codestringrequired
proposed_codestringrequired
original_ratenumber | nullrequired
proposed_ratenumber | nullrequired
delta_ptsnumber | nullrequired
customs_valuenumber | nullrequired
savingsnumber | nullrequired
risk_scorenumberrequired
riskstringrequired
risk_reasonsstring[]required
2.null
componentsobject[]required
13 fields per item
- product_idstringrequired
- destinationstringrequired
- originstring | nullrequired
- original_codestringrequired
- proposed_codestringrequired
- original_ratenumber | nullrequired
- proposed_ratenumber | nullrequired
- delta_ptsnumber | nullrequired
- customs_valuenumber | nullrequired
- savingsnumber | nullrequired
- risk_scorenumberrequired
- riskstringrequired
- risk_reasonsstring[]required

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /products/{productId}/classification

curl "https://api.tarifflo.com/api/v2/products/01a19e37-837d-7c16-9a5d-3bef820fcff7/classification" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "facts": {
    "entryDate": "2026-01-15",
    "shipmentValue": 1000,
    "shares": {
      "steel": 100,
      "aluminum": 100,
      "copper": 100,
      "usContent": 100
    }
  },
  "comparison": {
    "product_id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "destination": "US",
    "origin": "CN",
    "original_code": "CN",
    "proposed_code": "string",
    "original_rate": 100,
    "proposed_rate": 100,
    "delta_pts": 100,
    "customs_value": 1000,
    "savings": 100,
    "risk_score": 100,
    "risk": "string",
    "risk_reasons": [
      "string"
    ]
  },
  "components": [
    {
      "product_id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "destination": "US",
      "origin": "CN",
      "original_code": "CN",
      "proposed_code": "string",
      "original_rate": 100,
      "proposed_rate": 100,
      "delta_pts": 100,
      "customs_value": 1000,
      "savings": 100,
      "risk_score": 100,
      "risk": "string",
      "risk_reasons": [
        "string"
      ]
    }
  ]
}

A page of the upload's products, filtered and sorted

posthttps://api.tarifflo.com/api/v2/sort-sessions/{sortSessionId}/products

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

sortSessionIdstringrequired

Request body

application/json

object

startRowintegerrequired
≥ 0≤ 9007199254740991
endRowintegerrequired
≥ 1≤ 9007199254740991
statusstring
One ofPENDINGPROCESSINGAWAITING_INPUTPENDING_APPROVALAPPROVEDREJECTEDCOMPLETEDUPLOADEDFAILED
searchstring
min length 1max length 100
sortobject
2 fields
- columnstringrequired
  One ofnamedescriptionoriginhtsstatusupdatedAt
- directionstringrequired
  One ofascdesc

Responses

200Successful response

application/json

object

rowsobject[]required
11 fields per item
- idstringrequired
- namestringrequired
- descriptionstringrequired
- statusstringrequired
  One ofPENDINGPROCESSINGAWAITING_INPUTPENDING_APPROVALAPPROVEDREJECTEDCOMPLETEDUPLOADEDFAILED
- codestring | nullrequired
- originstring | nullrequired
- originalCodestring | nullrequired
- originalRatestring | nullrequired
- ratestring | nullrequired
- eccnstring | nullrequired
- updatedAtstringrequired
totalnumberrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /sort-sessions/{sortSessionId}/products

curl -X POST "https://api.tarifflo.com/api/v2/sort-sessions/01a19e37-837d-7c16-9a5d-3bef820fcff7/products" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "startRow": 1,
    "endRow": 1
  }'

Response · 200

JSON

{
  "rows": [
    {
      "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "name": "Example",
      "description": "Laptop computer, 14 inch",
      "status": "PENDING",
      "code": "string",
      "origin": "CN",
      "originalCode": "CN",
      "originalRate": "CN",
      "rate": "string",
      "eccn": "string",
      "updatedAt": "2026-01-15"
    }
  ],
  "total": 1
}

The open questions as a sheet to fill in

gethttps://api.tarifflo.com/api/v2/sort-sessions/{sortSessionId}/questions

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

sortSessionIdstringrequired

Query parameters

timeZonestring
max length 64

Responses

200Successful response

application/json

object | null

Any of

1.object

urlstringrequired
fileNamestringrequired
questionsnumberrequired

2.null

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /sort-sessions/{sortSessionId}/questions

curl "https://api.tarifflo.com/api/v2/sort-sessions/01a19e37-837d-7c16-9a5d-3bef820fcff7/questions" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "url": "https://example.com/webhooks/tarifflo",
  "fileName": "Example",
  "questions": 100
}

The questions sheet, filled in

posthttps://api.tarifflo.com/api/v2/sort-sessions/{sortSessionId}/answers

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

sortSessionIdstringrequired

Request body

application/json

object

fileBase64stringrequired
min length 1max length 30000000

Responses

200Successful response

application/json

object

answeredRowsnumberrequired
unmatchedRowsnumberrequired
answerednumberrequired
resumedJobsnumberrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /sort-sessions/{sortSessionId}/answers

curl -X POST "https://api.tarifflo.com/api/v2/sort-sessions/01a19e37-837d-7c16-9a5d-3bef820fcff7/answers" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileBase64": "string"
  }'

Response · 200

JSON

{
  "answeredRows": 100,
  "unmatchedRows": 100,
  "answered": 100,
  "resumedJobs": 100
}

1 endpoint

Rate report

Build or fetch the duty-rate report for an upload.

Build or fetch the upload's rate report at each product's origin on file

posthttps://api.tarifflo.com/api/v2/sort-sessions/{sortSessionId}/rate-report

Requires the API key scope tariff_rates.

AuthApiKeyorBearer

Path parameters

sortSessionIdstringrequired
The upload (file_documents returns it).
min length 1

Request body

application/json

object

restartboolean
Start a new report when the previous run failed or was cancelled.

Responses

200Successful response

application/json

object | object | object

One of

1.object

state"ready"required
runIdstringrequired
reportIdstringrequired
fileNamestringrequired
urlstringrequired
expiresInMinutesnumberrequired

2.object

state"building"required
runIdstringrequired

3.object

state"unavailable"required
reasonstringrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /sort-sessions/{sortSessionId}/rate-report

curl -X POST "https://api.tarifflo.com/api/v2/sort-sessions/01a19e37-837d-7c16-9a5d-3bef820fcff7/rate-report" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "restart": true
  }'

Response · 200

JSON

{
  "state": "ready",
  "runId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "reportId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "fileName": "Example",
  "url": "https://example.com/webhooks/tarifflo",
  "expiresInMinutes": 100
}

27 endpoints

Entries

File entry summaries with CBP, read CBP's responses and manage versions.

File an entry summary

posthttps://api.tarifflo.com/api/v2/entries

Validates, writes and submits a whole entry summary. CBP's answer arrives as an entry.disposition webhook. A repeat of an Idempotency-Key answers the first result with Idempotent-Replayed: true. Requires the API key scope entries:write.

AuthApiKeyorBearer

Headers

Idempotency-Keystringrequired
min length 1max length 255

Request body

application/json

object

entryobjectrequired
The entry summary to file; its shape is documented at https://tarifflo.com/docs/v2.
webhookUrlstring
Where the entry.disposition webhook goes; defaults to the key environment's URL.

Responses

201Filed and submitted to CBP

application/json

object

efidstringrequired
entryNumbernumber
shortJobIdstringrequired
status"AWAITING_CBP"required

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

409The first request with this Idempotency-Key is still filing

application/json

error.PRECONDITION_FAILED

errorobjectrequired
7 fields
- codestringrequired
  example: CONFLICT
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

412No webhook URL for the key's environment

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: PRECONDITION_FAILED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

422The entry is not valid

application/json

error.UNPROCESSABLE_CONTENT

errorobjectrequired
7 fields
- codestringrequired
  example: UNPROCESSABLE_CONTENT
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

502Submitting to CBP failed

application/json

error.BAD_GATEWAY

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_GATEWAY
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /entries

curl -X POST "https://api.tarifflo.com/api/v2/entries" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entry": {}
  }'

Response · 201

JSON

{
  "efid": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "entryNumber": 1,
  "shortJobId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "status": "AWAITING_CBP"
}

Create an entry, or records inside one (or list what can be created)

posthttps://api.tarifflo.com/api/v2/entries/create

Requires the API key scope filing.

AuthApiKeyorBearer

Request body

application/json

object

mapTypestring
'entry', 'lineItem', 'tariffRow' or a PGA type. Omit to list what can be created.
efidstring
For records: the entry they go on.
recordsobject[]
For records: one object per record (1-50). Coordinates take handles. Use {} when nothing needs naming.
min items 1max items 50
5 fields per item
- lineItemIdstring
  The line, by handle ('L1').
  min length 1
- tariffRowIdstring
  PGA only: the row it rides, by handle ('L1.R1').
  min length 1
- parentTariffRowIdstring
  Sub tariff row only: its main row, by handle ('L1.R1').
  min length 1
- chapterstring
  Sub tariff row only, required there.
  One ofch98ch99
- htsNumberstring
  Tariff row only: seed its HTS number (8 digits for Chapter 99, 10 for 1-97).
  min length 1
countinteger
For records, instead of records: how many blank ones (1-50). Defaults to 1.
≥ 1≤ 50
templateEntryNumberstring | number
Entry only, optional: the entry number to copy, however the user writes it — 12345678, S8L-1234567-8, or the full 11-digit form. list_recent_entries shows what the organization has.
templateEfidstring
Entry only, optional: the template's efid, if you already hold one instead of a number. Do not pass both.
includeLineItemsboolean
Entry only, optional, default true: copy the template's line items and their PGAs. Ignored without a template.

Responses

200Successful response

application/json

object | object | object

One of

1.object

What can be created. THIS connector creates entry forms, and inside an entry (efid) lineItem, tariffRow and the PGA types; the rest are made in the Tarifflo app.

kind"catalog"required
creatableobject[]required
5 fields per item
- mapTypestringrequired
- kindstringrequired
  form: a new form. child: a record inside one of forms.
  One offormchild
- formsstring[]required
- descriptionstringrequired
- coordinatesobject[]required
  4 fields per item
  namestringrequired
  requiredbooleanrequired
  inferablebooleanrequired
  May be omitted when the entry holds only one candidate.
  descriptionstringrequired
pgasobject | nullrequired
PGA message sets: each rides one tariff row, and every type takes the same coordinates.
2 options
Any of
1.object
formsstring[]required
coordinatesobject[]required
4 fields per item
namestringrequired
requiredbooleanrequired
inferablebooleanrequired
May be omitted when the entry holds only one candidate.
descriptionstringrequired
typesobject[]required
2 fields per item
pgaTypestringrequired
One of 25 values
odsvAndEpesticidets1Ts2hfchmsnhtsaaplaacApqAvsAbsegMOORPNttbomcfwsdeafsidrugsbiologicscosmeticMedicalRadiationtobaccopriorNoticefoodCombinedfoodNonPNnmfSection370nmfAmrnmfSim
namestringrequired
2.null

2.object

A new entry summary. It has no entry number: that is assigned at submission.

kind"entry"required
efidstringrequired
fromstringrequired
blank: add line items with create (mapType 'lineItem').
One ofblanktemplate
templateobject
The copied entry. Everything but the dates carries over verbatim, INCLUDING post-summary-correction status — check that before filing an original entry.
7 fields
- efidstringrequired
- entryNumberstring | nullrequired
- matchednumberrequired
  Entries carrying the requested number. More than one: the most recent was used.
- includeLineItemsbooleanrequired
  False: only the header was copied, NO line items — add the goods with create (mapType 'lineItem').
- lineItemCountnumberrequired
- pgaCountnumberrequired
- clearedDateFieldsstring[]required
  Every date was cleared: re-enter each for THIS shipment.
urlstringrequired
Where the user can watch the entry fill.
overviewobjectrequired
Work a section at a time with whats_left → set_fields. Sections: 'shipping' (header), then handles by position — L1 (line 1), L1.R1 (its first tariff row), L1.R1.nhtsa (that row's NHTSA record; a second is nhtsa-2). Field paths take the same handles: L1.R1.htsNumber.
7 fields
- efidstringrequired
- statusstring | nullrequired
  The entry's status (DRAFT, ACCEPTED, …).
- editablebooleanrequired
  False: the entry is filed and READ-ONLY. Read it freely, but call edit_entry to create a draft before changing it.
- linesnumberrequired
  Line items, addressed L1 … Ln.
- rowsnumberrequired
  Tariff rows across every line item.
- pgasnumberrequired
  PGA records across every tariff row.
- headerRequiredEmptynumberrequired
  Required header ('shipping') fields still empty.

3.object

kind"records"required
efidstringrequired
mapTypestringrequired
createdobject[]required
The new sections, by handle. Fill each with whats_left / set_fields.
3 fields per item
- handlestringrequired
- initPathstringrequired
- keystringrequired
lineCountnumberrequired
Line items on the entry now.
sectionobject
When exactly one tariff row or PGA record was created: its section, ready to fill.
8 fields
- sectionstringrequired
  The section's handle ('shipping', 'L1', 'L1.R1', 'L1.R1.nhtsa'); every path below is relative to it.
- requiredstring[]required
  Required fields still empty. Conditional fields appear as their triggers fill, so read the section again after each round of writes.
- optionalstring[]
  Optional fields still empty; listed only when asked for.
- datamap<string, object>
  The values the section already holds; empty fields are left out.
- errorsmap<string, string>
  Field path → error message.
- warningsmap<string, string[]>
  Field path → advisories; never blocking.
- editedByOthersmap<string, string>
  Fields another editor last wrote (who, how long ago). Treat a user's edit as intended — never change one back; if it blocks the filing, ask the user.
- notestring
  Set when someone outside this session changed the entry since you last looked: re-read before writing.

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /entries/create

curl -X POST "https://api.tarifflo.com/api/v2/entries/create" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mapType": "string",
    "efid": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "records": [
      {
        "lineItemId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
        "tariffRowId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
        "parentTariffRowId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
        "chapter": "ch98",
        "htsNumber": "8471.30.0100"
      }
    ],
    "count": 1,
    "templateEntryNumber": "string",
    "templateEfid": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "includeLineItems": true
  }'

Response · 200

JSON

{
  "kind": "catalog",
  "creatable": [
    {
      "mapType": "string",
      "kind": "form",
      "forms": [
        "string"
      ],
      "description": "Laptop computer, 14 inch",
      "coordinates": [
        {
          "name": "Example",
          "required": true,
          "inferable": true,
          "description": "Laptop computer, 14 inch"
        }
      ]
    }
  ],
  "pgas": {
    "forms": [
      "string"
    ],
    "coordinates": [
      {
        "name": "Example",
        "required": true,
        "inferable": true,
        "description": "Laptop computer, 14 inch"
      }
    ],
    "types": [
      {
        "pgaType": "ods",
        "name": "Example"
      }
    ]
  }
}

Get an entry's overview

gethttps://api.tarifflo.com/api/v2/entries/{efid}/summary

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

efidstringrequired
The entry summary's efid.
min length 1

Responses

200Successful response

application/json

object

Work a section at a time with whats_left → set_fields. Sections: 'shipping' (header), then handles by position — L1 (line 1), L1.R1 (its first tariff row), L1.R1.nhtsa (that row's NHTSA record; a second is nhtsa-2). Field paths take the same handles: L1.R1.htsNumber.

efidstringrequired
statusstring | nullrequired
The entry's status (DRAFT, ACCEPTED, …).
editablebooleanrequired
False: the entry is filed and READ-ONLY. Read it freely, but call edit_entry to create a draft before changing it.
linesnumberrequired
Line items, addressed L1 … Ln.
rowsnumberrequired
Tariff rows across every line item.
pgasnumberrequired
PGA records across every tariff row.
headerRequiredEmptynumberrequired
Required header ('shipping') fields still empty.

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /entries/{efid}/summary

curl "https://api.tarifflo.com/api/v2/entries/01a19e37-837d-7c16-9a5d-3bef820fcff7/summary" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "efid": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "status": "string",
  "editable": true,
  "lines": 100,
  "rows": 100,
  "pgas": 100,
  "headerRequiredEmpty": 100
}

Open an entry in the validation engine

posthttps://api.tarifflo.com/api/v2/entries/{efid}/open

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

efidstringrequired
The entry summary's efid.
min length 1

Responses

200Successful response

application/json

object

efidstringrequired
statusstring | nullrequired
The entry's status (DRAFT, ACCEPTED, …).
editablebooleanrequired
False: the entry is filed and READ-ONLY. Read it freely, but call edit_entry to create a draft before changing it.
linesnumberrequired
Line items, addressed L1 … Ln.
rowsnumberrequired
Tariff rows across every line item.
pgasnumberrequired
PGA records across every tariff row.
headerRequiredEmptynumberrequired
Required header ('shipping') fields still empty.

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /entries/{efid}/open

curl -X POST "https://api.tarifflo.com/api/v2/entries/01a19e37-837d-7c16-9a5d-3bef820fcff7/open" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "efid": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "status": "string",
  "editable": true,
  "lines": 100,
  "rows": 100,
  "pgas": 100,
  "headerRequiredEmpty": 100
}

Make a filed entry editable as a new draft

posthttps://api.tarifflo.com/api/v2/entries/{efid}/edit

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

efidstringrequired
The entry summary's efid.
min length 1

Responses

200Successful response

application/json

object

efidstringrequired
statusstring | nullrequired
The entry's status (DRAFT, ACCEPTED, …).
editablebooleanrequired
False: the entry is filed and READ-ONLY. Read it freely, but call edit_entry to create a draft before changing it.
linesnumberrequired
Line items, addressed L1 … Ln.
rowsnumberrequired
Tariff rows across every line item.
pgasnumberrequired
PGA records across every tariff row.
headerRequiredEmptynumberrequired
Required header ('shipping') fields still empty.
draftCreatedbooleanrequired
True: a new DRAFT version was created and the filed version stays as it was. False: the entry was already editable; nothing changed.
previousStatusstring | nullrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /entries/{efid}/edit

curl -X POST "https://api.tarifflo.com/api/v2/entries/01a19e37-837d-7c16-9a5d-3bef820fcff7/edit" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "efid": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "status": "string",
  "editable": true,
  "lines": 100,
  "rows": 100,
  "pgas": 100,
  "headerRequiredEmpty": 100,
  "draftCreated": true,
  "previousStatus": "string"
}

Save and re-read an entry

posthttps://api.tarifflo.com/api/v2/entries/{efid}/reload

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

efidstringrequired
The entry summary's efid.
min length 1

Responses

200Successful response

application/json

object

efidstringrequired
statusstring | nullrequired
The entry's status (DRAFT, ACCEPTED, …).
editablebooleanrequired
False: the entry is filed and READ-ONLY. Read it freely, but call edit_entry to create a draft before changing it.
linesnumberrequired
Line items, addressed L1 … Ln.
rowsnumberrequired
Tariff rows across every line item.
pgasnumberrequired
PGA records across every tariff row.
headerRequiredEmptynumberrequired
Required header ('shipping') fields still empty.

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /entries/{efid}/reload

curl -X POST "https://api.tarifflo.com/api/v2/entries/01a19e37-837d-7c16-9a5d-3bef820fcff7/reload" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "efid": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "status": "string",
  "editable": true,
  "lines": 100,
  "rows": 100,
  "pgas": 100,
  "headerRequiredEmpty": 100
}

Save an entry and finish with it

posthttps://api.tarifflo.com/api/v2/entries/{efid}/close

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

efidstringrequired
The entry summary's efid.
min length 1

Responses

200Successful response

application/json

object

efidstringrequired
outcomestringrequired
saved: everything written is saved. read_only: nothing to save. save_failed: the last save failed (see error).
One ofsavedread_onlysave_failed
errorstring

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /entries/{efid}/close

curl -X POST "https://api.tarifflo.com/api/v2/entries/01a19e37-837d-7c16-9a5d-3bef820fcff7/close" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "efid": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "outcome": "saved",
  "error": "string"
}

List what one section of an entry still needs

posthttps://api.tarifflo.com/api/v2/entries/{efid}/whats-left

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

efidstringrequired
The entry summary's efid.
min length 1

Request body

application/json

object

initPathstringrequired
'shipping' for the header, or a handle: 'L1', 'L1.R1', 'L1.R1.nhtsa'.
min length 1
optionalboolean
Also list the optional fields still empty. Default false.

Responses

200Successful response

application/json

object

sectionstringrequired
The section's handle ('shipping', 'L1', 'L1.R1', 'L1.R1.nhtsa'); every path below is relative to it.
requiredstring[]required
Required fields still empty. Conditional fields appear as their triggers fill, so read the section again after each round of writes.
optionalstring[]
Optional fields still empty; listed only when asked for.
datamap<string, object>
The values the section already holds; empty fields are left out.
errorsmap<string, string>
Field path → error message.
warningsmap<string, string[]>
Field path → advisories; never blocking.
editedByOthersmap<string, string>
Fields another editor last wrote (who, how long ago). Treat a user's edit as intended — never change one back; if it blocks the filing, ask the user.
notestring
Set when someone outside this session changed the entry since you last looked: re-read before writing.
awaitingCbpnumberrequired
Fields still waiting on an answer from CBP. Non-zero: call validate again for the final verdict.

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /entries/{efid}/whats-left

curl -X POST "https://api.tarifflo.com/api/v2/entries/01a19e37-837d-7c16-9a5d-3bef820fcff7/whats-left" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "initPath": "string"
  }'

Response · 200

JSON

{
  "section": "string",
  "required": [
    "string"
  ],
  "optional": [
    "string"
  ],
  "data": {
    "key": {}
  },
  "errors": {
    "key": "string"
  },
  "warnings": {
    "key": [
      "string"
    ]
  },
  "editedByOthers": {
    "key": "string"
  },
  "note": "string",
  "awaitingCbp": 100
}

Write field values to an entry

posthttps://api.tarifflo.com/api/v2/entries/{efid}/fields

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

efidstringrequired
The entry summary's efid.
min length 1

Request body

application/json

object

sectionstring
Optional: a section ('shipping', 'L1', 'L1.R1', 'L1.R1.nhtsa'). When given, fields keys are relative to it.
fieldsmap<string, object>required
Map of field path → value. Paths are relative to section when it is given, else full ('L1.countryOfOrigin', 'shipping.type').

Responses

200Successful response

application/json

object

writtennumberrequired
sectionsobject[]required
Each section the write touched. Read its errors before writing more.
9 fields per item
- sectionstringrequired
  The section's handle ('shipping', 'L1', 'L1.R1', 'L1.R1.nhtsa'); every path below is relative to it.
- requiredstring[]required
  Required fields still empty. Conditional fields appear as their triggers fill, so read the section again after each round of writes.
- optionalstring[]
  Optional fields still empty; listed only when asked for.
- datamap<string, object>
  The values the section already holds; empty fields are left out.
- errorsmap<string, string>
  Field path → error message.
- warningsmap<string, string[]>
  Field path → advisories; never blocking.
- editedByOthersmap<string, string>
  Fields another editor last wrote (who, how long ago). Treat a user's edit as intended — never change one back; if it blocks the filing, ask the user.
- notestring
  Set when someone outside this session changed the entry since you last looked: re-read before writing.
- derivedmap<string, object>
  Values the engine derived from your write (autofills); you did not write them.
overwroteobject[]
Fields this write replaced while another editor's change was the last one on them. A user's edit is intentional — if it blocks the filing, ask the user rather than changing it back.
3 fields per item
- pathstringrequired
- editorstringrequired
- agostringrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /entries/{efid}/fields

curl -X POST "https://api.tarifflo.com/api/v2/entries/01a19e37-837d-7c16-9a5d-3bef820fcff7/fields" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "key": {}
    }
  }'

Response · 200

JSON

{
  "written": 100,
  "sections": [
    {
      "section": "string",
      "required": [
        "string"
      ],
      "optional": [
        "string"
      ],
      "data": {
        "key": {}
      },
      "errors": {
        "key": "string"
      },
      "warnings": {
        "key": [
          "string"
        ]
      },
      "editedByOthers": {
        "key": "string"
      },
      "note": "string",
      "derived": {
        "key": {}
      }
    }
  ],
  "overwrote": [
    {
      "path": "string",
      "editor": "string",
      "ago": "string"
    }
  ]
}

Move a line item to another line number

posthttps://api.tarifflo.com/api/v2/entries/{efid}/line-items/{lineItemId}/move

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

efidstringrequired
The entry summary's efid.
min length 1
lineItemIdstringrequired
The line to move, by handle ('L3').
min length 1

Request body

application/json

object

lineNumberintegerrequired
The 1-based line number it takes. A number past the last line moves it to the end.
≥ 1≤ 9007199254740991

Responses

200Successful response

application/json

object

Handles of the lines between have shifted.

lineItemIdstringrequired
lineNumbernumberrequired
handlestringrequired
The line's handle now.

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /entries/{efid}/line-items/{lineItemId}/move

curl -X POST "https://api.tarifflo.com/api/v2/entries/01a19e37-837d-7c16-9a5d-3bef820fcff7/line-items/01a19e37-837d-7c16-9a5d-3bef820fcff7/move" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lineNumber": 1
  }'

Response · 200

JSON

{
  "lineItemId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "lineNumber": 1,
  "handle": "string"
}

List the PGA filings an entry's line items need

gethttps://api.tarifflo.com/api/v2/entries/{efid}/pgas

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

efidstringrequired
The entry summary's efid.
min length 1

Query parameters

initPathstring

Responses

200Successful response

application/json

object

linesobject[]required
Only the lines with something to act on; empty when no checked line carries a PGA tariff flag. For an applicable type not yet created, or a choice, call create (mapType the PGA type, tariffRowId the row, e.g. L1.R1), then fill the section it returns.
7 fields per item
- handlestringrequired
- flagsstring[]required
- articleSetHeaderbooleanrequired
  True: an article-set header line (articleSetIndicator 'X'). CBP does not allow PGA data here.
- applicableobject[]required
  7 fields per item
  pgaTypestringrequired
  One of 25 values
  odsvAndEpesticidets1Ts2hfchmsnhtsaaplaacApqAvsAbsegMOORPNttbomcfwsdeafsidrugsbiologicscosmeticMedicalRadiationtobaccopriorNoticefoodCombinedfoodNonPNnmfSection370nmfAmrnmfSim
  namestringrequired
  filerActionstringrequired
  required: a full filing is required — it cannot be disclaimed. disclaim-allowed: fill it if the goods apply; otherwise file a disclaimer. skip-allowed: fill it if the goods apply; otherwise it may be omitted entirely.
  One ofrequireddisclaim-allowedskip-allowed
  flagsstring[]required
  allowedDisclaimersstring[]
  Only these disclaim codes are allowed.
  guidancestringrequired
  existingnumberrequired
  Records of this type already on the line. Add another only if a second HTS needs one.
- choicesobject[]required
  Flags that need ONE program picked from options.
  3 fields per item
  flagstringrequired
  guidancestringrequired
  optionsobject[]required
  2 fields per item
  pgaTypestringrequired
  One of 25 values
  odsvAndEpesticidets1Ts2hfchmsnhtsaaplaacApqAvsAbsegMOORPNttbomcfwsdeafsidrugsbiologicscosmeticMedicalRadiationtobaccopriorNoticefoodCombinedfoodNonPNnmfSection370nmfAmrnmfSim
  namestringrequired
- existingobject[]required
  PGA records ALREADY CREATED on the line.
  4 fields per item
  pgaTypestringrequired
  One of 25 values
  odsvAndEpesticidets1Ts2hfchmsnhtsaaplaacApqAvsAbsegMOORPNttbomcfwsdeafsidrugsbiologicscosmeticMedicalRadiationtobaccopriorNoticefoodCombinedfoodNonPNnmfSection370nmfAmrnmfSim
  namestringrequired
  handlestringrequired
  htsNumberstring
- unsupportedFlagsobject[]required
  Agencies with no Tarifflo module: they cannot be filed here.
  2 fields per item
  flagstringrequired
  descriptionstringrequired
awaitingCbpnumberrequired
Fields still waiting on an answer from CBP. Non-zero: call validate again for the final verdict.
otherPgaTypesstring[]required
PGA types no checked line suggests. create still accepts them, with a not-applicable warning.

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /entries/{efid}/pgas

curl "https://api.tarifflo.com/api/v2/entries/01a19e37-837d-7c16-9a5d-3bef820fcff7/pgas" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "lines": [
    {
      "handle": "string",
      "flags": [
        "string"
      ],
      "articleSetHeader": true,
      "applicable": [
        {
          "pgaType": "ods",
          "name": "Example",
          "filerAction": "required",
          "flags": [
            "string"
          ],
          "allowedDisclaimers": [
            "string"
          ],
          "guidance": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
          "existing": 100
        }
      ],
      "choices": [
        {
          "flag": "string",
          "guidance": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
          "options": [
            {
              "pgaType": "ods",
              "name": null
            }
          ]
        }
      ],
      "existing": [
        {
          "pgaType": "ods",
          "name": "Example",
          "handle": "string",
          "htsNumber": "8471.30.0100"
        }
      ],
      "unsupportedFlags": [
        {
          "flag": "string",
          "description": "Laptop computer, 14 inch"
        }
      ]
    }
  ],
  "awaitingCbp": 100,
  "otherPgaTypes": [
    "ods"
  ]
}

Delete a PGA record

deletehttps://api.tarifflo.com/api/v2/entries/{efid}/pgas/{compositeKey}

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

efidstringrequired
The entry summary's efid.
min length 1
compositeKeystringrequired
The record, by handle ('L1.R1.nhtsa').
min length 1

Query parameters

pgaTypestringrequired
The record's PGA type, as list_pgas reports it.
One of 25 values
odsvAndEpesticidets1Ts2hfchmsnhtsaaplaacApqAvsAbsegMOORPNttbomcfwsdeafsidrugsbiologicscosmeticMedicalRadiationtobaccopriorNoticefoodCombinedfoodNonPNnmfSection370nmfAmrnmfSim

Responses

200Successful response

application/json

object

Later records of that type on the row moved up one handle.

deletedstringrequired
pgaTypestringrequired
One of 25 values
odsvAndEpesticidets1Ts2hfchmsnhtsaaplaacApqAvsAbsegMOORPNttbomcfwsdeafsidrugsbiologicscosmeticMedicalRadiationtobaccopriorNoticefoodCombinedfoodNonPNnmfSection370nmfAmrnmfSim
namestringrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

DELETE /entries/{efid}/pgas/{compositeKey}

curl -X DELETE "https://api.tarifflo.com/api/v2/entries/01a19e37-837d-7c16-9a5d-3bef820fcff7/pgas/string?pgaType=ods" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "deleted": "string",
  "pgaType": "ods",
  "name": "Example"
}

List an entry's tariff rows

gethttps://api.tarifflo.com/api/v2/entries/{efid}/tariff-rows

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

efidstringrequired
The entry summary's efid.
min length 1

Query parameters

initPathstring

Responses

200Successful response

application/json

object

linesobject[]required
Empty when the entry has no line items. Fill a row like any other section: whats_left / set_fields on its handle.
2 fields per item
- handlestringrequired
- rowsobject[]required
  7 fields per item
  handlestringrequired
  kindstringrequired
  main: the line's classification (Chapter 1-97). ch98 / ch99 / sub: stacked under the main row above it.
  One ofmainch98ch99sub
  htsNumberstring
  sequencenumber
  valueOfGoodsAmountnumber
  dutyAmountnumber
  suppressedbooleanrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /entries/{efid}/tariff-rows

curl "https://api.tarifflo.com/api/v2/entries/01a19e37-837d-7c16-9a5d-3bef820fcff7/tariff-rows" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "lines": [
    {
      "handle": "string",
      "rows": [
        {
          "handle": "string",
          "kind": "main",
          "htsNumber": "8471.30.0100",
          "sequence": 100,
          "valueOfGoodsAmount": 1000,
          "dutyAmount": 100,
          "suppressed": true
        }
      ]
    }
  ]
}

Delete a tariff row

deletehttps://api.tarifflo.com/api/v2/entries/{efid}/tariff-rows/{tariffRowKey}

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

efidstringrequired
The entry summary's efid.
min length 1
tariffRowKeystringrequired
The row, by handle ('L1.R2').
min length 1

Responses

200Successful response

application/json

object

Deleted with any subs and PGAs under it. Later rows on the line moved up one handle.

deletedstringrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

DELETE /entries/{efid}/tariff-rows/{tariffRowKey}

curl -X DELETE "https://api.tarifflo.com/api/v2/entries/01a19e37-837d-7c16-9a5d-3bef820fcff7/tariff-rows/string" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "deleted": "string"
}

Describe an entry field

gethttps://api.tarifflo.com/api/v2/entry-fields/{path}

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

pathstringrequired
Plain graph path, e.g. 'shipping.pscReasonCodes.reasonCode' or 'nhtsa.hs7Box' — no handles, indices or ids.
min length 1

Responses

200Successful response

application/json

object

pathstringrequired
The graph path that resolved.
foundbooleanrequired
shapestring
The value's shape in shorthand: str≤35 UPPERCASE, int 0–99, date YYYY-MM-DD, or code (pick one of codes).
guidancestring
Filing guidance on this field.
containerobject
Filing guidance from the nearest containing node that carries it.
2 fields
- pathstringrequired
- infostringrequired
codesobject[]
The allowed codes with their meanings. Write one of these values; never guess a code.
2 fields per item
- valuestringrequired
- descriptionstringrequired
notestring
Why the field was not found, and the paths it may have meant.

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /entry-fields/{path}

curl "https://api.tarifflo.com/api/v2/entry-fields/string" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "path": "string",
  "found": true,
  "shape": "string",
  "guidance": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "container": {
    "path": "string",
    "info": "string"
  },
  "codes": [
    {
      "value": "string",
      "description": "Laptop computer, 14 inch"
    }
  ],
  "note": "string"
}

Validate an entry or one section

posthttps://api.tarifflo.com/api/v2/entries/{efid}/validate

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

efidstringrequired
The entry summary's efid.
min length 1

Request body

application/json

object

initPathstring
Optional: 'shipping' or a handle ('L1', 'L1.R1', 'L1.R1.nhtsa').

Responses

200Successful response

application/json

object

errorCountnumberrequired
0: it validates clean.
errorsmap<string, string>required
Field path (by handle) → error message.
awaitingCbpnumberrequired
Fields still waiting on an answer from CBP. Non-zero: call validate again for the final verdict.
sectionobject
The validated section, when initPath named one.
8 fields
- sectionstringrequired
  The section's handle ('shipping', 'L1', 'L1.R1', 'L1.R1.nhtsa'); every path below is relative to it.
- requiredstring[]required
  Required fields still empty. Conditional fields appear as their triggers fill, so read the section again after each round of writes.
- optionalstring[]
  Optional fields still empty; listed only when asked for.
- datamap<string, object>
  The values the section already holds; empty fields are left out.
- errorsmap<string, string>
  Field path → error message.
- warningsmap<string, string[]>
  Field path → advisories; never blocking.
- editedByOthersmap<string, string>
  Fields another editor last wrote (who, how long ago). Treat a user's edit as intended — never change one back; if it blocks the filing, ask the user.
- notestring
  Set when someone outside this session changed the entry since you last looked: re-read before writing.

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /entries/{efid}/validate

curl -X POST "https://api.tarifflo.com/api/v2/entries/01a19e37-837d-7c16-9a5d-3bef820fcff7/validate" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "initPath": "string"
  }'

Response · 200

JSON

{
  "errorCount": 1,
  "errors": {
    "key": "string"
  },
  "awaitingCbp": 100,
  "section": {
    "section": "string",
    "required": [
      "string"
    ],
    "optional": [
      "string"
    ],
    "data": {
      "key": {}
    },
    "errors": {
      "key": "string"
    },
    "warnings": {
      "key": [
        "string"
      ]
    },
    "editedByOthers": {
      "key": "string"
    },
    "note": "string"
  }
}

Delete an entry

deletehttps://api.tarifflo.com/api/v2/entries/{efid}

Requires the API key scope entries:write.

AuthApiKeyorBearer

Path parameters

efidstringrequired

Responses

200Successful response

application/json

object

idstringrequired
messagestringrequired
One ofSuccessfully deletedRequest to delete sent to CBP

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

DELETE /entries/{efid}

curl -X DELETE "https://api.tarifflo.com/api/v2/entries/01a19e37-837d-7c16-9a5d-3bef820fcff7" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "message": "Successfully deleted"
}

Get CBP's entry summary response for an entry

gethttps://api.tarifflo.com/api/v2/entries/{efid}/responses

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

efidstringrequired
min length 1

Responses

200Successful response

application/json

object

dispositionobject | nullrequired
2 options
Any of
1.object
groupReferenceobjectrequired
3 fields
dataTypestringrequired
contentstring
positionnumber
responseobjectrequired
8 fields
dispositionTypestring
severityCodestring
conditionCodestringrequired
descriptionstringrequired
filerCodestring
entryNumbernumber
entryVersionnumber
referenceNumberstring
2.null
conditionsobject[]required
2 fields per item
- referencePathobject[]required
  3 fields per item
  dataTypestringrequired
  contentstring
  positionnumber
- responsesobject[]required
  8 fields per item
  dispositionTypestring
  severityCodestring
  conditionCodestringrequired
  descriptionstringrequired
  filerCodestring
  entryNumbernumber
  entryVersionnumber
  referenceNumberstring
hasInternalErrorbooleanrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /entries/{efid}/responses

curl "https://api.tarifflo.com/api/v2/entries/01a19e37-837d-7c16-9a5d-3bef820fcff7/responses" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "disposition": {
    "groupReference": {
      "dataType": "string",
      "content": "string",
      "position": 100
    },
    "response": {
      "dispositionType": "string",
      "severityCode": "string",
      "conditionCode": "string",
      "description": "Laptop computer, 14 inch",
      "filerCode": "string",
      "entryNumber": 1,
      "entryVersion": 100,
      "referenceNumber": "string"
    }
  },
  "conditions": [
    {
      "referencePath": [
        {
          "dataType": "string",
          "content": "string",
          "position": 100
        }
      ],
      "responses": [
        {
          "dispositionType": "string",
          "severityCode": "string",
          "conditionCode": "string",
          "description": "Laptop computer, 14 inch",
          "filerCode": "string",
          "entryNumber": 1,
          "entryVersion": 100,
          "referenceNumber": "string"
        }
      ]
    }
  ],
  "hasInternalError": true
}

Get CBP's cargo release response for an entry

gethttps://api.tarifflo.com/api/v2/entries/{efid}/cargo-release

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

efidstringrequired
min length 1

Responses

200Successful response

application/json

object | null

Any of

1.object

dispositionobjectrequired
3 fields
- messageTypeCodestringrequired
- statusstringrequired
  One ofDRAFTAWAITING CBPAPPROVEDDENIEDWARNINGINFOINTERNAL ERROR
- descriptionstringrequired
conditionGroupsobject[]required
2 fields per item
- referencePathobject[]required
  3 fields per item
  dataTypestringrequired
  contentstring
  positionnumber
- responsesobject[]required
  6 fields per item
  messageTypeCodestringrequired
  messageIdentifierCodestringrequired
  narrativeMessagestringrequired
  actionDatestring
  actionTimestring
  releaseDatestring

2.null

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /entries/{efid}/cargo-release

curl "https://api.tarifflo.com/api/v2/entries/01a19e37-837d-7c16-9a5d-3bef820fcff7/cargo-release" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "disposition": {
    "messageTypeCode": "string",
    "status": "DRAFT",
    "description": "Laptop computer, 14 inch"
  },
  "conditionGroups": [
    {
      "referencePath": [
        {
          "dataType": "string",
          "content": "string",
          "position": 100
        }
      ],
      "responses": [
        {
          "messageTypeCode": "string",
          "messageIdentifierCode": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
          "narrativeMessage": "string",
          "actionDate": "2026-01-15",
          "actionTime": "string",
          "releaseDate": "2026-01-15"
        }
      ]
    }
  ]
}

Get CBP's ISF response for an entry

gethttps://api.tarifflo.com/api/v2/entries/{efid}/isf

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

efidstringrequired
min length 1

Responses

200Successful response

application/json

object | null

Any of

1.object

dispositionobjectrequired
4 fields
- messageTypeCodestringrequired
- statusstringrequired
  One ofDRAFTAWAITING CBPAPPROVEDDENIEDWARNINGINTERNAL ERROR
- descriptionstringrequired
- isfTransactionNumberstring
conditionGroupsobject[]required
2 fields per item
- referencePathobject[]required
  3 fields per item
  dataTypestringrequired
  contentstring
  positionnumber
- responsesobject[]required
  3 fields per item
  messageTypeCodestringrequired
  messageIdentifierCodestringrequired
  narrativeMessagestringrequired

2.null

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /entries/{efid}/isf

curl "https://api.tarifflo.com/api/v2/entries/01a19e37-837d-7c16-9a5d-3bef820fcff7/isf" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "disposition": {
    "messageTypeCode": "string",
    "status": "DRAFT",
    "description": "Laptop computer, 14 inch",
    "isfTransactionNumber": "string"
  },
  "conditionGroups": [
    {
      "referencePath": [
        {
          "dataType": "string",
          "content": "string",
          "position": 100
        }
      ],
      "responses": [
        {
          "messageTypeCode": "string",
          "messageIdentifierCode": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
          "narrativeMessage": "string"
        }
      ]
    }
  ]
}

List CBP batch rejects against an entry

gethttps://api.tarifflo.com/api/v2/entries/{efid}/batch-errors

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

efidstringrequired
min length 1

Responses

200Successful response

application/json

object[]

idstringrequired
shortJobIdstringrequired
appIdCodestring
conditionsobject[]required
7 fields per item
- idstringrequired
- severityCodestringrequired
- conditionCodestringrequired
- narrativeTextstringrequired
- referenceTypestring
- referenceOccurrencenumber
- referenceTextstring
receivedAtstringrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /entries/{efid}/batch-errors

curl "https://api.tarifflo.com/api/v2/entries/01a19e37-837d-7c16-9a5d-3bef820fcff7/batch-errors" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

[
  {
    "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "shortJobId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "appIdCode": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "conditions": [
      {
        "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
        "severityCode": "string",
        "conditionCode": "string",
        "narrativeText": "string",
        "referenceType": "string",
        "referenceOccurrence": 100,
        "referenceText": "string"
      }
    ],
    "receivedAt": "string"
  }
]

List CBP status notifications for an entry

gethttps://api.tarifflo.com/api/v2/entries/{efid}/notifications

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

efidstringrequired
min length 1

Responses

200Successful response

application/json

object[]

idstringrequired
entryNumberstringrequired
filerCodestringrequired
receivedAtstringrequired
dispositionTypeCodestringrequired
notificationReasonCodestringrequired
dateOfActionstring
lineItemIdentifierstringrequired
remarksTextstringrequired
cbpUserstringrequired
telephoneNumberstringrequired
telephoneExtensionNumberstringrequired
actionIdentificationNumberstringrequired
quotaLinesobject[]required
8 fields per item
- idstringrequired
- lineItemIdentifierstringrequired
- statusCodestringrequired
- statusDescriptionstringrequired
- requestedQuantitynumber
- requestedUomstringrequired
- reservedQuantitynumber
- reservedUomstringrequired
pgaStatusesobject[]required
10 fields per item
- idstringrequired
- agencyCodestringrequired
- programCodestringrequired
- entryLevelStatusCodestringrequired
- entryLevelStatusMessagestringrequired
- lineLevelStatusCodestringrequired
- statusReasonCodestringrequired
- lineRangestring
- actionAtstring
- commentsstring[]required

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /entries/{efid}/notifications

curl "https://api.tarifflo.com/api/v2/entries/01a19e37-837d-7c16-9a5d-3bef820fcff7/notifications" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

[
  {
    "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "entryNumber": "string",
    "filerCode": "string",
    "receivedAt": "string",
    "dispositionTypeCode": "string",
    "notificationReasonCode": "string",
    "dateOfAction": "2026-01-15",
    "lineItemIdentifier": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "remarksText": "string",
    "cbpUser": "string",
    "telephoneNumber": "string",
    "telephoneExtensionNumber": "string",
    "actionIdentificationNumber": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "quotaLines": [
      {
        "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
        "lineItemIdentifier": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
        "statusCode": "string",
        "statusDescription": "Laptop computer, 14 inch",
        "requestedQuantity": 12,
        "requestedUom": "string",
        "reservedQuantity": 2,
        "reservedUom": "string"
      }
    ],
    "pgaStatuses": [
      {
        "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
        "agencyCode": "string",
        "programCode": "string",
        "entryLevelStatusCode": "string",
        "entryLevelStatusMessage": "string",
        "lineLevelStatusCode": "string",
        "statusReasonCode": "string",
        "lineRange": "string",
        "actionAt": "string",
        "comments": [
          "string"
        ]
      }
    ]
  }
]

Set or clear an entry's importer

posthttps://api.tarifflo.com/api/v2/entries/{efid}/importer

Requires the API key scope entries:write.

AuthApiKeyorBearer

Path parameters

efidstringrequired
min length 1

Request body

application/json

object

importerIdstring | nullrequired

Responses

200Successful response

application/json

any

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /entries/{efid}/importer

curl -X POST "https://api.tarifflo.com/api/v2/entries/01a19e37-837d-7c16-9a5d-3bef820fcff7/importer" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "importerId": "01a19e37-837d-7c16-9a5d-3bef820fcff7"
  }'

Response · 200

JSON

{}

Search the organization's entry summaries

posthttps://api.tarifflo.com/api/v2/entries/search

Requires the API key scope filing.

AuthApiKeyorBearer

Request body

application/json

object

startRownumberrequired
First row to return, from 0.
endRownumberrequired
Row to stop before (exclusive).
allFilersboolean
Show every filer's entries, not only the session filer's.
filterModelobject
AG Grid filter model: status/type take values, entryNumber takes filter.
3 fields
- statusobject
  2 fields
  filterTypestring
  One ofsetnumbertext
  valuesstring[]
- typeobject
  2 fields
  filterTypestring
  One ofsetnumbertext
  valuesstring[]
- entryNumberobject
  3 fields
  filterTypestring
  One ofsetnumbertext
  typestring
  "equals" (default) or "startsWith".
  filterstring
  The entry number or its leading digits.

Responses

200Successful response

application/json

object

rowsobject[]required
17 fields per item
- idstringrequired
- versionIdstringrequired
- headerIdstring
- organizationIdstringrequired
- entryNumbernumber
- submittedAtstring
- importerNamestring
- totalValuenumber
- totalDutynumber
- productsnumber
- statusstringrequired
  One of 18 values
  DRAFTAWAITING CBPAPPROVEDDENIEDWARNINGPGA WARNINGINFOINTERNAL ERRORUNKNOWNCBP CONTROLLEDDOCUMENTS REQUESTEDDOCUMENTS RECEIVEDINACTIVATEDCANCELLEDPSC REVERTEDTIB DENIEDPGA UPDATELIQUIDATED
- numActionItemsnumberrequired
- typestring
- brokerReferenceNumberstring
- internalNamestring
- cbpSourcedboolean
- isLatestboolean
totalnumber

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /entries/search

curl -X POST "https://api.tarifflo.com/api/v2/entries/search" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "startRow": 100,
    "endRow": 100
  }'

Response · 200

JSON

{
  "rows": [
    {
      "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "versionId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "headerId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "organizationId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "entryNumber": 1,
      "submittedAt": "string",
      "importerName": "Example",
      "totalValue": 1,
      "totalDuty": 1,
      "products": 100,
      "status": "DRAFT",
      "numActionItems": 100,
      "type": "string",
      "brokerReferenceNumber": "string",
      "internalName": "Example",
      "cbpSourced": true,
      "isLatest": true
    }
  ],
  "total": 1
}

List every version of an entry

gethttps://api.tarifflo.com/api/v2/entries/{versionId}/versions

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

versionIdstringrequired
min length 1

Responses

200Successful response

application/json

object[]

idstringrequired
versionIdstringrequired
headerIdstring
organizationIdstringrequired
entryNumbernumber
submittedAtstring
importerNamestring
totalValuenumber
totalDutynumber
productsnumber
statusstringrequired
One of 18 values
DRAFTAWAITING CBPAPPROVEDDENIEDWARNINGPGA WARNINGINFOINTERNAL ERRORUNKNOWNCBP CONTROLLEDDOCUMENTS REQUESTEDDOCUMENTS RECEIVEDINACTIVATEDCANCELLEDPSC REVERTEDTIB DENIEDPGA UPDATELIQUIDATED
numActionItemsnumberrequired
typestring
brokerReferenceNumberstring
internalNamestring
cbpSourcedboolean
isLatestboolean

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /entries/{versionId}/versions

curl "https://api.tarifflo.com/api/v2/entries/01a19e37-837d-7c16-9a5d-3bef820fcff7/versions" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

[
  {
    "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "versionId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "headerId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "organizationId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "entryNumber": 1,
    "submittedAt": "string",
    "importerName": "Example",
    "totalValue": 1,
    "totalDuty": 1,
    "products": 100,
    "status": "DRAFT",
    "numActionItems": 100,
    "type": "string",
    "brokerReferenceNumber": "string",
    "internalName": "Example",
    "cbpSourced": true,
    "isLatest": true
  }
]

Create a new entry from an existing one

posthttps://api.tarifflo.com/api/v2/entries/{efid}/copies

Requires the API key scope entries:write.

AuthApiKeyorBearer

Path parameters

efidstringrequired
min length 1

Responses

200Successful response

application/json

object

shippingobjectrequired
1 field
- idstringrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /entries/{efid}/copies

curl -X POST "https://api.tarifflo.com/api/v2/entries/01a19e37-837d-7c16-9a5d-3bef820fcff7/copies" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "shipping": {
    "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7"
  }
}

Open a new draft version of an entry

posthttps://api.tarifflo.com/api/v2/entries/{efid}/drafts

Requires the API key scope entries:write.

AuthApiKeyorBearer

Path parameters

efidstringrequired
min length 1

Responses

200Successful response

application/json

object

efidstringrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /entries/{efid}/drafts

curl -X POST "https://api.tarifflo.com/api/v2/entries/01a19e37-837d-7c16-9a5d-3bef820fcff7/drafts" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "efid": "01a19e37-837d-7c16-9a5d-3bef820fcff7"
}

4 endpoints

Audit

Pre-audit document runs: get upload URLs, start a run, poll for the result.

Get an audit upload URL

posthttps://api.tarifflo.com/api/v2/audit/uploads

A presigned PUT URL for one document. PUT the bytes, then start a run with the returned fileId. Requires the API key scope audit.

AuthApiKeyorBearer

Request body

application/json

object

filenamestringrequired
PDF, Excel, Word, CSV or an image; the type is checked again from the bytes.
min length 1max length 500
mimeTypestringrequired
min length 1max length 200

Responses

200Successful response

application/json

object

fileIdstringrequired
Pass it in fileIds when starting the run.
uploadUrlstringrequired
PUT the file's bytes here, with the declared mimeType as Content-Type.
expiresInSecondsnumberrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /audit/uploads

curl -X POST "https://api.tarifflo.com/api/v2/audit/uploads" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "Example",
    "mimeType": "string"
  }'

Response · 200

JSON

{
  "fileId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "uploadUrl": "https://example.com/webhooks/tarifflo",
  "expiresInSeconds": 100
}

Get many audit upload URLs

posthttps://api.tarifflo.com/api/v2/audit/uploads/bulk

Presigned PUT URLs for up to 50 documents; one unsupported file type refuses the whole call. Requires the API key scope audit.

AuthApiKeyorBearer

Request body

application/json

object

filesobject[]required
min items 1max items 50
2 fields per item
- filenamestringrequired
  PDF, Excel, Word, CSV or an image; the type is checked again from the bytes.
  min length 1max length 500
- mimeTypestringrequired
  min length 1max length 200

Responses

200Successful response

application/json

object

uploadsobject[]required
3 fields per item
- fileIdstringrequired
  Pass it in fileIds when starting the run.
- uploadUrlstringrequired
  PUT the file's bytes here, with the declared mimeType as Content-Type.
- expiresInSecondsnumberrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /audit/uploads/bulk

curl -X POST "https://api.tarifflo.com/api/v2/audit/uploads/bulk" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {
        "filename": "Example",
        "mimeType": "string"
      }
    ]
  }'

Response · 200

JSON

{
  "uploads": [
    {
      "fileId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "uploadUrl": "https://example.com/webhooks/tarifflo",
      "expiresInSeconds": 100
    }
  ]
}

Start a pre-audit run

posthttps://api.tarifflo.com/api/v2/audit/runs

Files the uploaded documents under a fresh audit request and runs the pre-audit (ingest, classification, rate and savings). Answers 202 with the run id; the result is delivered as a pre_audit.completed webhook to the key environment's URL (or Tarifflo-Webhook-Url) and pollable at GET /audit/runs/{jobId}. config: "post" (PSC) is not available yet. Requires the API key scope audit.

AuthApiKeyorBearer

Headers

Idempotency-Keystring
Repeats of the same request with the same key answer the first result (72 hours) with Idempotent-Replayed: true.
max length 255

Request body

application/json

object

configstringrequired
One ofprepost
fileIdsstring[]required
min items 1max items 50
clientNamestring
The audit client to file under (default "API Intake").
min length 1max length 200
requestNamestring
min length 1max length 200
destinationCountriesstring[]
Markets to rate for (default US).
dryRunboolean
Price the request at the organization's card and reserve nothing; answers 200 with the estimate.

Responses

202Queued (or, for dryRun, priced with 200)

application/json

object | object

Any of

1.object

jobIdstringrequired
The run id: poll GET /audit/runs/{jobId}.
creditsobject
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
status"queued"required
config"pre"required
filesQueuednumberrequired
messagestringrequired

2.object

dryRuntruerequired
estimatedCreditsnumberrequired
linesobject[]required
3 fields per item
- actionstringrequired
  One of 16 values
  rate_lookupadcvd_screenpga_applicabilitycode_classifiedexport_controlorigin_determinationentry_filedentry_prepareddocument_ocrdocument_extractdocument_sortproduct_enrichentry_reviewrationale_documentaudit_parsedata_export
- unitsnumberrequired
- creditsnumberrequired
balancenumberrequired
unitstringrequired
One oftokencredit
notestring

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

402Not enough credits

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: PAYMENT_REQUIRED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

409The first request with this Idempotency-Key is still filing

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: CONFLICT
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

501config: "post" is not available yet

application/json

error.NOT_IMPLEMENTED

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_IMPLEMENTED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /audit/runs

curl -X POST "https://api.tarifflo.com/api/v2/audit/runs" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "config": "pre",
    "fileIds": [
      "01a19e37-837d-7c16-9a5d-3bef820fcff7"
    ]
  }'

Response · 202

JSON

{
  "jobId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "credits": {
    "action": "audit_parse",
    "reserved": 2,
    "used": 0,
    "refunded": 0
  },
  "status": "queued",
  "config": "pre",
  "filesQueued": 1,
  "message": "string"
}

Get a pre-audit run

gethttps://api.tarifflo.com/api/v2/audit/runs/{jobId}

The run's status; once complete, data is the pre_audit.completed webhook's data. Requires the API key scope audit.

AuthApiKeyorBearer

Path parameters

jobIdstringrequired

Responses

200Successful response

application/json

object | object | object

Any of

1.object

jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
status"failed"required
errorobjectrequired
2 fields
- code"RUN_FAILED"required
- messagestringrequired

2.object

jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
statusstringrequired
One ofqueuedprocessingblocked
stagesCompletenumberrequired
stagesTotalnumberrequired
creditsNeedednumber
Credits the run waits for (blocked only).
purchaseUrlstring
Where to add credits (blocked only).

3.object

jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
status"complete"required
eventstringrequired
The webhook event that delivered the same data.
dataobjectrequired
The run's result, exactly the webhook's data.

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /audit/runs/{jobId}

curl "https://api.tarifflo.com/api/v2/audit/runs/01a19e37-837d-7c16-9a5d-3bef820fcff7" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "jobId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "credits": {
    "action": "audit_parse",
    "reserved": 2,
    "used": 0,
    "refunded": 0
  },
  "status": "failed",
  "error": {
    "code": "RUN_FAILED",
    "message": "string"
  }
}

4 endpoints

Billing

Prices, credit balance and settled usage.

Get the price list

gethttps://api.tarifflo.com/api/v2/pricing

Credits per unit for every billable action at list price. Public: needs no key.

Responses

200Successful response

application/json

object

creditCentsnumberrequired
What one credit costs, in US cents.
actionsobject[]required
5 fields per item
- actionstringrequired
  One of 16 values
  rate_lookupadcvd_screenpga_applicabilitycode_classifiedexport_controlorigin_determinationentry_filedentry_prepareddocument_ocrdocument_extractdocument_sortproduct_enrichentry_reviewrationale_documentaudit_parsedata_export
- unitstringrequired
- creditsnumberrequired
- listCreditsnumberrequired
- usdnumberrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /pricing

curl "https://api.tarifflo.com/api/v2/pricing" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "creditCents": 100,
  "actions": [
    {
      "action": "rate_lookup",
      "unit": "string",
      "credits": 100,
      "listCredits": 100,
      "usd": 100
    }
  ]
}

Get the credit balance

gethttps://api.tarifflo.com/api/v2/credits

The organization's balance, the current cycle's allowance and what each action consumed this cycle. Any valid API key.

AuthApiKeyorBearer

Responses

200Successful response

application/json

object

unitstringrequired
Always "credit": every amount here is presented in credits, whatever the ledger counts in.
One oftokencredit
balancenumberrequired
reservednumberrequired
Held by running work.
usednumberrequired
floornumberrequired
currentCycleobject | nullrequired
2 options
Any of
1.object
startstringrequired
endstring | nullrequired
allowancenumberrequired
consumednumberrequired
2.null
perActionobject[]required
3 fields per item
- actionstringrequired
- unitsnumberrequired
- creditsnumberrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /credits

curl "https://api.tarifflo.com/api/v2/credits" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "unit": "credit",
  "balance": 100,
  "reserved": 2,
  "used": 0,
  "floor": 100,
  "currentCycle": {
    "start": "string",
    "end": "string",
    "allowance": 100,
    "consumed": 100
  },
  "perAction": [
    {
      "action": "string",
      "units": 100,
      "credits": 100
    }
  ]
}

Get the credit balance and this organization's prices

gethttps://api.tarifflo.com/api/v2/credits/prices

The balance, the current cycle's consumption per action, and the price list at this organization's prices. Requires the API key scope classifications.

AuthApiKeyorBearer

Responses

200Successful response

application/json

object

summaryobjectrequired
7 fields
- unitstringrequired
  Always "credit": every amount here is presented in credits, whatever the ledger counts in.
  One oftokencredit
- balancenumberrequired
- reservednumberrequired
  Held by running work.
- usednumberrequired
- floornumberrequired
- currentCycleobject | nullrequired
  2 options
  Any of
  1.object
  startstringrequired
  endstring | nullrequired
  allowancenumberrequired
  consumednumberrequired
  2.null
- perActionobject[]required
  3 fields per item
  actionstringrequired
  unitsnumberrequired
  creditsnumberrequired
pricesobjectrequired
This organization's prices: credits is what it pays per unit, listCredits the list price.
2 fields
- creditCentsnumberrequired
  What one credit costs, in US cents.
- actionsobject[]required
  5 fields per item
  actionstringrequired
  One of 16 values
  rate_lookupadcvd_screenpga_applicabilitycode_classifiedexport_controlorigin_determinationentry_filedentry_prepareddocument_ocrdocument_extractdocument_sortproduct_enrichentry_reviewrationale_documentaudit_parsedata_export
  unitstringrequired
  creditsnumberrequired
  listCreditsnumberrequired
  usdnumberrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /credits/prices

curl "https://api.tarifflo.com/api/v2/credits/prices" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "summary": {
    "unit": "credit",
    "balance": 100,
    "reserved": 2,
    "used": 0,
    "floor": 100,
    "currentCycle": {
      "start": "string",
      "end": "string",
      "allowance": 100,
      "consumed": 100
    },
    "perAction": [
      {
        "action": "string",
        "units": 100,
        "credits": 100
      }
    ]
  },
  "prices": {
    "creditCents": 100,
    "actions": [
      {
        "action": "rate_lookup",
        "unit": "string",
        "credits": 100,
        "listCredits": 100,
        "usd": 100
      }
    ]
  }
}

Get settled usage

gethttps://api.tarifflo.com/api/v2/usage

Settled usage between from and to (ISO dates; default the last 30 days, at most a year), grouped by action, key, user or run. Any valid API key.

AuthApiKeyorBearer

Query parameters

groupBystring
One ofactionkeyuserrun
fromstring
tostring
limitstring

Responses

200Successful response

application/json

object

fromstringrequired
tostringrequired
groupBystringrequired
One ofactionkeyuserrun
unitstringrequired
Always "credit": every amount here is presented in credits, whatever the ledger counts in.
One oftokencredit
rowsobject[]required
4 fields per item
- keystring | nullrequired
- unitsnumberrequired
- creditsnumberrequired
- listCreditsnumberrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /usage

curl "https://api.tarifflo.com/api/v2/usage" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "from": "string",
  "to": "string",
  "groupBy": "action",
  "unit": "token",
  "rows": [
    {
      "key": "string",
      "units": 100,
      "credits": 100,
      "listCredits": 100
    }
  ]
}

6 endpoints

Classification

Classify one product to each destination, or many products in a batch, and poll for the result.

Classify a product

posthttps://api.tarifflo.com/api/v2/classifications

Classifies one product to a code in each destination: the US HTS code is computed first, then mapped to the other destinations. Answers 202 with the job id; the result is delivered as a classification.completed webhook to the key environment's URL (or Tarifflo-Webhook-Url) and pollable at GET /classifications/{jobId}. When the classifier needs more information, the poll answers needs_info with its questions. Requires the API key scope classifications.

AuthApiKeyorBearer

Headers

Idempotency-Keystring
Repeats of the same request with the same key answer the first result (72 hours) with Idempotent-Replayed: true.
max length 255

Request body

application/json

object

namestring
Product name; echoed back as productName on the result.
min length 3max length 200
descriptionstringrequired
What the product is: materials, function, how it is sold. The more specific, the better the code.
min length 10max length 2000
partialHtsCodestring
A known heading (4 digits) or subheading (6 digits) that constrains the result.
pattern: ^(\d{4}|\d{6})$
destinationsstring[]required
Import countries, ISO-3166 alpha-2. The US code is computed first, then mapped to the others.
min items 1max items 10
folderPathstring[]
Product-grid folder for the created products, as folder names below the root (created when absent), e.g. ["Imports", "2026"]. Omitted: the root folder.
max items 10
dryRunboolean
Price the request at the organization's card and reserve nothing; answers 200 with the estimate.

Responses

202Queued (or, for dryRun, priced with 200)

application/json

object | object

Any of

1.object

jobIdstringrequired
The job id: poll GET /classifications/{jobId}.
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
status"queued"required
destinationsQueuednumberrequired
messagestringrequired

2.object

dryRuntruerequired
estimatedCreditsnumberrequired
linesobject[]required
3 fields per item
- actionstringrequired
  One of 16 values
  rate_lookupadcvd_screenpga_applicabilitycode_classifiedexport_controlorigin_determinationentry_filedentry_prepareddocument_ocrdocument_extractdocument_sortproduct_enrichentry_reviewrationale_documentaudit_parsedata_export
- unitsnumberrequired
- creditsnumberrequired
balancenumberrequired
unitstringrequired
One oftokencredit
notestring

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

402Not enough credits

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: PAYMENT_REQUIRED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

409The first request with this Idempotency-Key is still filing

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: CONFLICT
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /classifications

curl -X POST "https://api.tarifflo.com/api/v2/classifications" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Laptop computer, 14 inch",
    "destinations": [
      "US"
    ]
  }'

Response · 202

JSON

{
  "jobId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "credits": {
    "action": "code_classified",
    "reserved": 2,
    "used": 0,
    "refunded": 0
  },
  "status": "queued",
  "destinationsQueued": 1,
  "message": "string"
}

Get a classification job

gethttps://api.tarifflo.com/api/v2/classifications/{jobId}

The job's status. needs_info lists the open questions; once complete, data is the classification.completed webhook's data. Requires the API key scope classifications.

AuthApiKeyorBearer

Path parameters

jobIdstringrequired

Responses

200Successful response

application/json

object | object | object

Any of

1.object

jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
status"needs_info"required
event"classification.needs_info"required
questionsobject[]required
The job is parked on these. Fold the answers into description and start a new classification.
4 fields per item
- productNamestring
- destinationstringrequired
- questionIdstringrequired
- questionstringrequired
productsQueuednumberrequired
productsCompletednumberrequired

2.object

jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
status"complete"required
event"classification.completed"required
dataobjectrequired
The result, exactly the webhook's data.
1 field
- productsobject[]required
  3 fields per item
  productNamestring
  setKindstring
  Set parents only: the set provision the classifications follow.
  classificationsobject[]required
  One row per destination.
  10 fields per item
  countrystringrequired
  codestringrequired
  The classification code in the destination's tariff (10-digit HTS for US).
  goodsstringrequired
  rationalestringrequired
  unitstringrequired
  hsDescriptionstringrequired
  eccnstringrequired
  eccnReasoningstringrequired
  scheduleBstringrequired
  followUpQuestionsstring[]required

3.object

jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
statusstringrequired
One ofqueuedprocessingblockedfailed
productsQueuednumberrequired
productsCompletednumberrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /classifications/{jobId}

curl "https://api.tarifflo.com/api/v2/classifications/01a19e37-837d-7c16-9a5d-3bef820fcff7" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "jobId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "credits": {
    "action": "code_classified",
    "reserved": 2,
    "used": 0,
    "refunded": 0
  },
  "status": "needs_info",
  "event": "classification.needs_info",
  "questions": [
    {
      "productName": "Example",
      "destination": "US",
      "questionId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "question": "string"
    }
  ],
  "productsQueued": 1,
  "productsCompleted": 0
}

Classify a product and wait for the result

posthttps://api.tarifflo.com/api/v2/classifications/wait

Starts a classification like POST /classifications, then waits up to 40 s for it. Answers the finished job, or the job still running with its jobId to poll at GET /classifications/{jobId}. Requires the API key scope classifications.

AuthApiKeyorBearer

Headers

Idempotency-Keystring
Repeats of the same request with the same key answer the first result (72 hours) with Idempotent-Replayed: true.
max length 255

Request body

application/json

object

namestring
Product name; echoed back as productName on the result.
min length 3max length 200
descriptionstringrequired
What the product is: materials, function, how it is sold. The more specific, the better the code.
min length 10max length 2000
partialHtsCodestring
A known heading (4 digits) or subheading (6 digits) that constrains the result.
pattern: ^(\d{4}|\d{6})$
destinationsstring[]
Import countries, ISO-3166 alpha-2. Defaults to ["US"].
max items 10
folderPathstring[]
Product-grid folder for the created products, as folder names below the root (created when absent), e.g. ["Imports", "2026"]. Omitted: the root folder.
max items 10

Responses

200Successful response

application/json

object | object | object

Where the job stands. complete: data holds one classification per destination; a set carries its components[]. needs_info: answer questions, then call classify again with the answers folded into description. queued / processing / blocked: still running (blocked = waiting for credits, it resumes on its own); call wait_for_work with jobType "classification" and this jobId. failed: tell the user.

Any of

1.object

jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
status"needs_info"required
event"classification.needs_info"required
questionsobject[]required
The job is parked on these. Fold the answers into description and start a new classification.
4 fields per item
- productNamestring
- destinationstringrequired
- questionIdstringrequired
- questionstringrequired
productsQueuednumberrequired
productsCompletednumberrequired

2.object

jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
status"complete"required
event"classification.completed"required
dataobjectrequired
The result, exactly the webhook's data.
1 field
- productsobject[]required
  3 fields per item
  productNamestring
  setKindstring
  Set parents only: the set provision the classifications follow.
  classificationsobject[]required
  One row per destination.
  10 fields per item
  countrystringrequired
  codestringrequired
  The classification code in the destination's tariff (10-digit HTS for US).
  goodsstringrequired
  rationalestringrequired
  unitstringrequired
  hsDescriptionstringrequired
  eccnstringrequired
  eccnReasoningstringrequired
  scheduleBstringrequired
  followUpQuestionsstring[]required

3.object

jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
statusstringrequired
One ofqueuedprocessingblockedfailed
productsQueuednumberrequired
productsCompletednumberrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

402Not enough credits

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: PAYMENT_REQUIRED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

409The first request with this Idempotency-Key is still filing

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: CONFLICT
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /classifications/wait

curl -X POST "https://api.tarifflo.com/api/v2/classifications/wait" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Laptop computer, 14 inch"
  }'

Response · 200

JSON

{
  "jobId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "credits": {
    "action": "code_classified",
    "reserved": 2,
    "used": 0,
    "refunded": 0
  },
  "status": "needs_info",
  "event": "classification.needs_info",
  "questions": [
    {
      "productName": "Example",
      "destination": "US",
      "questionId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "question": "string"
    }
  ],
  "productsQueued": 1,
  "productsCompleted": 0
}

Classify many products

posthttps://api.tarifflo.com/api/v2/classifications/batch

Bulk HTS classification of items (inline) or inputKey (an uploaded JSONL file). Answers 202 with the batch id; the results are delivered to the key environment's webhook URL (or Tarifflo-Webhook-Url) and pollable at GET /classifications/batch/{batchId}. Requires the API key scope classifications.

AuthApiKeyorBearer

Headers

Idempotency-Keystring
Repeats of the same request with the same key answer the first result (72 hours) with Idempotent-Replayed: true.
max length 255

Request body

application/json

object

itemsobject[]
Up to 10000 rows inline; id is echoed back on each result.
max items 10000
2 fields per item
- idstring
- textstringrequired
  min length 1
inputKeystring
A JSONL file of {id?,text} rows, from POST /classifications/batch/upload-url.
dryRunboolean
Price the request at the organization's card and reserve nothing; answers 200 with the estimate.

Responses

202Queued (or, for dryRun, priced with 200)

application/json

object | object

Any of

1.object

jobIdstringrequired
The batch id: poll GET /classifications/batch/{batchId}.
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
status"queued"required
itemsQueuednumberrequired
messagestringrequired

2.object

dryRuntruerequired
estimatedCreditsnumberrequired
linesobject[]required
3 fields per item
- actionstringrequired
  One of 16 values
  rate_lookupadcvd_screenpga_applicabilitycode_classifiedexport_controlorigin_determinationentry_filedentry_prepareddocument_ocrdocument_extractdocument_sortproduct_enrichentry_reviewrationale_documentaudit_parsedata_export
- unitsnumberrequired
- creditsnumberrequired
balancenumberrequired
unitstringrequired
One oftokencredit
notestring

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

402Not enough credits

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: PAYMENT_REQUIRED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

409The first request with this Idempotency-Key is still filing

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: CONFLICT
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

413The file or the row count is over the limit

application/json

error.PAYLOAD_TOO_LARGE

errorobjectrequired
7 fields
- codestringrequired
  example: PAYLOAD_TOO_LARGE
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /classifications/batch

curl -X POST "https://api.tarifflo.com/api/v2/classifications/batch" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "text": "string"
      }
    ],
    "inputKey": "string"
  }'

Response · 202

JSON

{
  "jobId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "credits": {
    "action": "code_classified",
    "reserved": 2,
    "used": 0,
    "refunded": 0
  },
  "status": "queued",
  "itemsQueued": 1,
  "message": "string"
}

Get a batch upload URL

posthttps://api.tarifflo.com/api/v2/classifications/batch/upload-url

A presigned PUT URL (valid 900 seconds) for a JSONL file of {id?,text} rows. PUT the file, then start the batch with the returned inputKey. Requires the API key scope classifications.

AuthApiKeyorBearer

Request body

application/json

object

filenamestringrequired
min length 1max length 256

Responses

200Successful response

application/json

object

uploadUrlstringrequired
inputKeystringrequired
expiresInSecondsnumberrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /classifications/batch/upload-url

curl -X POST "https://api.tarifflo.com/api/v2/classifications/batch/upload-url" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "Example"
  }'

Response · 200

JSON

{
  "uploadUrl": "https://example.com/webhooks/tarifflo",
  "inputKey": "string",
  "expiresInSeconds": 100
}

Get a classification batch

gethttps://api.tarifflo.com/api/v2/classifications/batch/{batchId}

The batch's status and one page (1000 rows, page from 0) of its results once it completes. Requires the API key scope classifications.

AuthApiKeyorBearer

Path parameters

batchIdstringrequired

Query parameters

pagestring

Responses

200Successful response

application/json

object

batchIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
statusstringrequired
statestringrequired
SUBMITTED, RUNNING, COMPLETED or FAILED; results appear once COMPLETED.
expectedCountnumberrequired
shardsSettlednumberrequired
expectedShardsnumberrequired
pagenumberrequired
pageSizenumberrequired
resultsobject[]required
5 fields per item
- idstringrequired
- hts10string | nullrequired
- confidencenumber | nullrequired
- chosenModelstring | nullrequired
- top5objectrequired
  The top alternatives the classifier weighed.

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /classifications/batch/{batchId}

curl "https://api.tarifflo.com/api/v2/classifications/batch/01a19e37-837d-7c16-9a5d-3bef820fcff7" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "batchId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "credits": {
    "action": "code_classified",
    "reserved": 2,
    "used": 0,
    "refunded": 0
  },
  "status": "string",
  "state": "string",
  "expectedCount": 1,
  "shardsSettled": 100,
  "expectedShards": 100,
  "page": 0,
  "pageSize": 50,
  "results": [
    {
      "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "hts10": "8471.30.0100",
      "confidence": 100,
      "chosenModel": "string",
      "top5": {}
    }
  ]
}

3 endpoints

Export control

Export-control (ECCN) determinations for products.

Determine export-control codes

posthttps://api.tarifflo.com/api/v2/export-control

ECCN (or a foreign jurisdiction's control code) for up to 50 products. Answers 202 with the run id; the result is delivered as an export_control.completed webhook to the key environment's URL (or Tarifflo-Webhook-Url) and pollable at GET /export-control/{jobId}. Requires the API key scope eccn.

AuthApiKeyorBearer

Headers

Idempotency-Keystring
Repeats of the same request with the same key answer the first result (72 hours) with Idempotent-Replayed: true.
max length 255

Request body

application/json

object

productsobject[]required
min items 1max items 50
5 fields per item
- idstring
  Your correlation id, echoed back on the result line.
  max length 200
- namestring
  max length 500
- descriptionstringrequired
  min length 3max length 5000
- originstringrequired
  Country of origin, ISO-3166 alpha-2.
  pattern: ^[A-Z]{2}$
- contextstring
  Anything else the determination should weigh.
  max length 5000
folderPathstring[]
Product-grid folder for the created products, as folder names below the root (created when absent), e.g. ["Imports", "2026"]. Omitted: the root folder.
max items 10
dryRunboolean
Price the request at the organization's card and reserve nothing; answers 200 with the estimate.

Responses

202Queued (or, for dryRun, priced with 200)

application/json

object | object

Any of

1.object

jobIdstringrequired
The run id: poll GET /export-control/{jobId}.
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
status"queued"required
productsQueuednumberrequired
messagestringrequired

2.object

dryRuntruerequired
estimatedCreditsnumberrequired
linesobject[]required
3 fields per item
- actionstringrequired
  One of 16 values
  rate_lookupadcvd_screenpga_applicabilitycode_classifiedexport_controlorigin_determinationentry_filedentry_prepareddocument_ocrdocument_extractdocument_sortproduct_enrichentry_reviewrationale_documentaudit_parsedata_export
- unitsnumberrequired
- creditsnumberrequired
balancenumberrequired
unitstringrequired
One oftokencredit
notestring

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

402Not enough credits

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: PAYMENT_REQUIRED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

409The first request with this Idempotency-Key is still filing

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: CONFLICT
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /export-control

curl -X POST "https://api.tarifflo.com/api/v2/export-control" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {
        "description": "Laptop computer, 14 inch",
        "origin": "CN"
      }
    ]
  }'

Response · 202

JSON

{
  "jobId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "credits": {
    "action": "export_control",
    "reserved": 2,
    "used": 0,
    "refunded": 0
  },
  "status": "queued",
  "productsQueued": 1,
  "message": "string"
}

Get an export-control run

gethttps://api.tarifflo.com/api/v2/export-control/{jobId}

The run's status; once complete, data is the export_control.completed webhook's data. Requires the API key scope eccn.

AuthApiKeyorBearer

Path parameters

jobIdstringrequired

Responses

200Successful response

application/json

object | object | object

Any of

1.object

jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
status"failed"required
errorobjectrequired
2 fields
- code"RUN_FAILED"required
- messagestringrequired

2.object

jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
statusstringrequired
One ofqueuedprocessingblocked
stagesCompletenumberrequired
stagesTotalnumberrequired
creditsNeedednumber
Credits the run waits for (blocked only).
purchaseUrlstring
Where to add credits (blocked only).

3.object

jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
status"complete"required
eventstringrequired
The webhook event that delivered the same data.
dataobjectrequired
The run's result, exactly the webhook's data.

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /export-control/{jobId}

curl "https://api.tarifflo.com/api/v2/export-control/01a19e37-837d-7c16-9a5d-3bef820fcff7" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "jobId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "credits": {
    "action": "export_control",
    "reserved": 2,
    "used": 0,
    "refunded": 0
  },
  "status": "failed",
  "error": {
    "code": "RUN_FAILED",
    "message": "string"
  }
}

Determine one product's export-control code and wait for it

posthttps://api.tarifflo.com/api/v2/export-control/wait

Starts a determination for one product like POST /export-control, then waits up to 40 s for it. Answers the finished run, or the run still going (or parked for credits) with its jobId to poll at GET /export-control/{jobId}. Requires the API key scope eccn.

AuthApiKeyorBearer

Headers

Idempotency-Keystring
Repeats of the same request with the same key answer the first result (72 hours) with Idempotent-Replayed: true.
max length 255

Request body

application/json

object

descriptionstringrequired
What the product is (the primary signal).
min length 3max length 5000
originstringrequired
Country of origin, 2-letter ISO-3166 alpha-2 (e.g. CN, DE, US).
pattern: ^[A-Za-z]{2}$
namestring
Optional short product name.
max length 500
contextstring
Optional extra detail (end use, materials, specs) — folded into the description.
max length 5000
folderPathstring[]
Product-grid folder for the created products, as folder names below the root (created when absent), e.g. ["Imports", "2026"]. Omitted: the root folder.
max items 10

Responses

200Successful response

application/json

object | object | object

Where the run stands. complete: data is the determination; a NEEDS_INFO determination carries clarifyingQuestions. queued / processing: still running; call wait_for_work with jobType "eccn" and this jobId. blocked: waiting for creditsNeeded credits; give the user purchaseUrl, the run resumes on its own, then call wait_for_work again. failed: tell the user.

Any of

1.object

jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
status"failed"required
errorobjectrequired
2 fields
- code"RUN_FAILED"required
- messagestringrequired

2.object

jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
statusstringrequired
One ofqueuedprocessingblocked
stagesCompletenumberrequired
stagesTotalnumberrequired
creditsNeedednumber
Credits the run waits for (blocked only).
purchaseUrlstring
Where to add credits (blocked only).

3.object

jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
status"complete"required
eventstringrequired
The webhook event that delivered the same data.
dataobjectrequired
The run's result, exactly the webhook's data.

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

402Not enough credits

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: PAYMENT_REQUIRED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

409The first request with this Idempotency-Key is still filing

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: CONFLICT
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /export-control/wait

curl -X POST "https://api.tarifflo.com/api/v2/export-control/wait" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Laptop computer, 14 inch",
    "origin": "CN"
  }'

Response · 200

JSON

{
  "jobId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "credits": {
    "action": "export_control",
    "reserved": 2,
    "used": 0,
    "refunded": 0
  },
  "status": "failed",
  "error": {
    "code": "RUN_FAILED",
    "message": "string"
  }
}

2 endpoints

Jobs

Wait for a job

posthttps://api.tarifflo.com/api/v2/jobs/wait

Waits up to ~45 s for an async job, then answers where it stands; answers at once when something already needs you. jobType picks the job kind, and the key needs that kind's scope: filing → filing, eccn → eccn, classification → classifications, origin → origin, rate → tariff_rates. Any valid API key.

AuthApiKeyorBearer

Request body

application/json

object

jobTypestringrequired
What kind of job jobId names.
One offilingeccnclassificationoriginrate
jobIdstring
The id the starting tool returned.

Responses

200Successful response

application/json

object | object | object | object | object

Where the job stands. A job still queued / processing: wait again with the same jobType and jobId. blocked: waiting for credits; give the user purchaseUrl when present, the run resumes on its own, then wait again.

One of

1.object

jobType"filing"required
summarystringrequired
Stage progress, questions to answer (answer_question, then wait again), entries ready for review (review_link), or why the run stopped: failed, cancelled, blocked on credits or held by Tarifflo (stop and tell the user).
workobjectrequired
The run's stages, open questions, holds and entries ready for review.

2.object

jobType"classification"required
jobobject | object | objectrequired
3 options
Any of
1.object
jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
actionstring | nullrequired
reservednumberrequired
usednumberrequired
refundednumberrequired
status"needs_info"required
event"classification.needs_info"required
questionsobject[]required
The job is parked on these. Fold the answers into description and start a new classification.
4 fields per item
productNamestring
destinationstringrequired
questionIdstringrequired
questionstringrequired
productsQueuednumberrequired
productsCompletednumberrequired
2.object
jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
actionstring | nullrequired
reservednumberrequired
usednumberrequired
refundednumberrequired
status"complete"required
event"classification.completed"required
dataobjectrequired
The result, exactly the webhook's data.
1 field
productsobject[]required
3 fields per item
productNamestring
setKindstring
Set parents only: the set provision the classifications follow.
classificationsobject[]required
One row per destination.
10 fields per item
countrystringrequired
codestringrequired
The classification code in the destination's tariff (10-digit HTS for US).
goodsstringrequired
rationalestringrequired
unitstringrequired
hsDescriptionstringrequired
eccnstringrequired
eccnReasoningstringrequired
scheduleBstringrequired
followUpQuestionsstring[]required
3.object
jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
actionstring | nullrequired
reservednumberrequired
usednumberrequired
refundednumberrequired
statusstringrequired
One ofqueuedprocessingblockedfailed
productsQueuednumberrequired
productsCompletednumberrequired

3.object

jobType"rate"required
jobobject | object | objectrequired
3 options
Any of
1.object
jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
actionstring | nullrequired
reservednumberrequired
usednumberrequired
refundednumberrequired
status"failed"required
errorobjectrequired
2 fields
code"RUN_FAILED"required
messagestringrequired
2.object
jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
actionstring | nullrequired
reservednumberrequired
usednumberrequired
refundednumberrequired
status"complete"required
event"tariff_rate.completed"required
dataobjectrequired
{ results: [...] }, one entry per rate in request order, exactly the webhook's data.
3.object
jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
actionstring | nullrequired
reservednumberrequired
usednumberrequired
refundednumberrequired
statusstringrequired
Lines are still being rated.
One ofqueuedprocessing
ratesQueuednumberrequired
ratesCompletednumberrequired

4.object

jobType"eccn"required
jobobject | object | objectrequired
3 options
Any of
1.object
jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
actionstring | nullrequired
reservednumberrequired
usednumberrequired
refundednumberrequired
status"failed"required
errorobjectrequired
2 fields
code"RUN_FAILED"required
messagestringrequired
2.object
jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
actionstring | nullrequired
reservednumberrequired
usednumberrequired
refundednumberrequired
statusstringrequired
One ofqueuedprocessingblocked
stagesCompletenumberrequired
stagesTotalnumberrequired
creditsNeedednumber
Credits the run waits for (blocked only).
purchaseUrlstring
Where to add credits (blocked only).
3.object
jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
actionstring | nullrequired
reservednumberrequired
usednumberrequired
refundednumberrequired
status"complete"required
eventstringrequired
The webhook event that delivered the same data.
dataobjectrequired
The run's result, exactly the webhook's data.

5.object

jobType"origin"required
jobobject | object | objectrequired
3 options
Any of
1.object
jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
actionstring | nullrequired
reservednumberrequired
usednumberrequired
refundednumberrequired
status"failed"required
errorobjectrequired
2 fields
code"RUN_FAILED"required
messagestringrequired
2.object
jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
actionstring | nullrequired
reservednumberrequired
usednumberrequired
refundednumberrequired
statusstringrequired
One ofqueuedprocessingblocked
stagesCompletenumberrequired
stagesTotalnumberrequired
creditsNeedednumber
Credits the run waits for (blocked only).
purchaseUrlstring
Where to add credits (blocked only).
3.object
jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
actionstring | nullrequired
reservednumberrequired
usednumberrequired
refundednumberrequired
status"complete"required
eventstringrequired
The webhook event that delivered the same data.
dataobjectrequired
The run's result, exactly the webhook's data.

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /jobs/wait

curl -X POST "https://api.tarifflo.com/api/v2/jobs/wait" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jobType": "filing"
  }'

Response · 200

JSON

{
  "jobType": "filing",
  "summary": "string",
  "work": {}
}

Watch a pipeline run

posthttps://api.tarifflo.com/api/v2/pipeline-runs/watch

Blocks up to 100 s and answers as soon as any stage changes state since cursor, or with the active stage's unit counts when nothing moved. Requires the API key scope filing.

AuthApiKeyorBearer

Request body

application/json

object

runIdstring
The pipeline run to watch.
sortSessionIdstring
Watch the latest run of a multi-entry upload. A connector upload has none: pass its entrySessionId.
entrySessionIdstring
Watch the latest run of this entry.
cursorstring
The cursor the previous watch_run returned; omit on the first call.

Responses

200Successful response

application/json

object

summarystringrequired
What changed since cursor (on a first call, where the run stands), then the next step. When it reports questions, answer them (list_open_questions → answer_question) before watching again. Stop when the run is finished, failed, cancelled, held or parked for credits.
cursorstringrequired
Pass it to the next watch_run call with the same id.
runIdstringrequired
runStatusstringrequired
One ofrunningblockedcompletefailedcancelled
sourceKindstring | nullrequired
sourceRefIdstring | nullrequired
changedbooleanrequired
False when the budget ran out with no stage moving.
transitionsobject[]required
4 fields per item
- stageKeystringrequired
- fromstring | nullrequired
- tostringrequired
  One ofpendingrunningfinalizingcomplete_with_openawaiting_gateheldcompletefailedblockedskipped
- questionsChangedboolean
finishedbooleanrequired
failedbooleanrequired
cancelledbooleanrequired
heldstring[]required
Stages held by Tarifflo: only Tarifflo can release them; tell the user.
awaitingGatestring[]required
awaitingInputstring[]required
Stages with units parked on questions.
parkedstring[]required
Stages parked for credits; start when the run parked before any stage.
stagesobject[]required
14 fields per item
- stageKeystringrequired
- statusstringrequired
  One ofpendingrunningfinalizingcomplete_with_openawaiting_gateheldcompletefailedblockedskipped
- totalnumberrequired
  Barrier units; 0 until the stage is sealed.
- donenumberrequired
  Units finished: completed + failed.
- failednumberrequired
- awaitingInputnumberrequired
  Units parked on an unanswered question.
- gateKeystring | nullrequired
- startedAtstring | nullrequired
- completedAtstring | nullrequired
- durationMsnumber | nullrequired
- errorstring | nullrequired
- noticestring | nullrequired
- creditsNeedednumber | nullrequired
  Credits the stage waits for, when it is parked.
- subProgressobject
  A sub-step's progress seen live during this call.
  3 fields
  donenumberrequired
  totalnumberrequired
  labelstring

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /pipeline-runs/watch

curl -X POST "https://api.tarifflo.com/api/v2/pipeline-runs/watch" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "runId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "sortSessionId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "entrySessionId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "cursor": "string"
  }'

Response · 200

JSON

{
  "summary": "string",
  "cursor": "string",
  "runId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "runStatus": "running",
  "sourceKind": "string",
  "sourceRefId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "changed": true,
  "transitions": [
    {
      "stageKey": "string",
      "from": "pending",
      "to": "pending",
      "questionsChanged": true
    }
  ],
  "finished": true,
  "failed": true,
  "cancelled": true,
  "held": [
    "string"
  ],
  "awaitingGate": [
    "string"
  ],
  "awaitingInput": [
    "string"
  ],
  "parked": [
    "string"
  ],
  "stages": [
    {
      "stageKey": "string",
      "status": "pending",
      "total": 1,
      "done": 100,
      "failed": 100,
      "awaitingInput": 100,
      "gateKey": "string",
      "startedAt": "string",
      "completedAt": "string",
      "durationMs": 100,
      "error": "string",
      "notice": "string",
      "creditsNeeded": 100,
      "subProgress": {
        "done": 100,
        "total": 1,
        "label": "string"
      }
    }
  ]
}

6 endpoints

Filing agent

Everything waiting on a human in an upload or entry

gethttps://api.tarifflo.com/api/v2/open-questions

Requires the API key scope filing.

AuthApiKeyorBearer

Query parameters

sortSessionIdstring
entrySessionIdstring

Responses

200Successful response

application/json

object

questionsobject[]required
Everything waiting on a human. Empty (or only stage_hold) = nothing to answer right now.
7 fields per item
- idstringrequired
  The questionId to answer with.
- kindstringrequired
  stage_hold is not a question: Tarifflo holds that work and only Tarifflo can release it; tell the user.
  One ofhitldoctype_reviewsort_groupingcoverageover_coveragecommercial_documentstage_hold
- promptstringrequired
  What is needed, for a person.
- blockingbooleanrequired
- answerViastring | nullrequired
- answerShapestringrequired
  The answer payload answer_question takes for this question.
- contextanyrequired
  The answer handles and gate counts; copy it verbatim into answer_question.
holdsobjectrequired
6 fields
- armedbooleanrequired
- liveRunsnumberrequired
- heldRunsnumberrequired
- idleHeldbooleanrequired
  True: nothing more happens until Tarifflo releases it; stop waiting and tell the user.
- waitingobject[]required
  3 fields per item
  entrySessionIdstringrequired
  stageKeystringrequired
  reasonstringrequired
  One ofgatequestions
- waitingCountnumberrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /open-questions

curl "https://api.tarifflo.com/api/v2/open-questions" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "questions": [
    {
      "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "kind": "hitl",
      "prompt": "string",
      "blocking": true,
      "answerVia": "filing.answerEntrySessionHitlQuestions",
      "answerShape": "string",
      "context": {}
    }
  ],
  "holds": {
    "armed": true,
    "liveRuns": 100,
    "heldRuns": 100,
    "idleHeld": true,
    "waiting": [
      {
        "entrySessionId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
        "stageKey": "string",
        "reason": "questions"
      }
    ],
    "waitingCount": 1
  }
}

Answer open questions, many per call

posthttps://api.tarifflo.com/api/v2/open-questions/answers

Requires the API key scope filing.

AuthApiKeyorBearer

Request body

application/json

object

answersobject[]required
min items 1max items 100
6 fields per item
- questionIdstringrequired
- kindstringrequired
  The question's kind, copied from list_open_questions.
  One ofhitldoctype_reviewsort_groupingcoverageover_coveragecommercial_documentstage_hold
- answerobject
  The answer payload, shaped as the question's answerShape describes.
- contextmap<string, object>
  The question's context object, copied verbatim — it carries the answer handles.
- sortSessionIdstring
  The upload (file_documents returns it).
- entrySessionIdstring
  One entry of the upload.
sortSessionIdstring
The upload (file_documents returns it).
entrySessionIdstring
One entry of the upload.

Responses

200Successful response

application/json

object

One outcome per answer, in order. Keep calling wait_for_work; it may ask a smaller question.

answerednumberrequired
Answers that were taken (every status but refused).
outcomesobject[]required
5 fields per item
- questionIdstringrequired
- okbooleanrequired
- statusstringrequired
  recorded: taken; keep calling wait_for_work. held: taken, but Tarifflo holds the upload before it continues; do not start filing agents. needs_document: cannot be answered; ask the user for the commercial invoice or packing list, then upload_documents (or file_documents) with that file and the entryId. tarifflo_hold: nothing to answer; only Tarifflo can release it, so tell the user it is held by Tarifflo. refused: not taken; error says why.
  One ofrecordedheldneeds_documenttarifflo_holdrefused
- errorstring | nullrequired
- resumedJobsnumber | nullrequired
  Jobs a classifier answer resumed (null when not known).

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /open-questions/answers

curl -X POST "https://api.tarifflo.com/api/v2/open-questions/answers" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "answers": [
      {
        "questionId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
        "kind": "hitl"
      }
    ]
  }'

Response · 200

JSON

{
  "answered": 100,
  "outcomes": [
    {
      "questionId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "ok": true,
      "status": "recorded",
      "error": "string",
      "resumedJobs": 100
    }
  ]
}

Recent entry summaries, newest first

posthttps://api.tarifflo.com/api/v2/entries/recent

Requires the API key scope filing.

AuthApiKeyorBearer

Request body

application/json

object

limitnumber
entryNumberstring

Responses

200Successful response

application/json

object

entriesobject[]required
Newest first. Empty = no entry summary (matching entryNumber, when given) in this organization.
6 fields per item
- efidstringrequired
- entryNumberstringrequired
- filerCodestringrequired
- statusstring | nullrequired
- entrySessionIdstring | nullrequired
- isPostSummaryCorrectionbooleanrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /entries/recent

curl -X POST "https://api.tarifflo.com/api/v2/entries/recent" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 100,
    "entryNumber": "string"
  }'

Response · 200

JSON

{
  "entries": [
    {
      "efid": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "entryNumber": "string",
      "filerCode": "string",
      "status": "string",
      "entrySessionId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "isPostSummaryCorrection": true
    }
  ]
}

The 7501 extract of an entry's documents

posthttps://api.tarifflo.com/api/v2/entry-sessions/{entrySessionId}/source-docs

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

entrySessionIdstringrequired

Request body

application/json

object

lineIndexnumber
Omit for the header.

Responses

200Successful response

application/json

object

lineCountnumberrequired
Lines available; lineIndex runs from 0.
extractmap<string, object> | nullrequired
The header's (or the line's) extract; null when there is none.

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /entry-sessions/{entrySessionId}/source-docs

curl -X POST "https://api.tarifflo.com/api/v2/entry-sessions/01a19e37-837d-7c16-9a5d-3bef820fcff7/source-docs" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lineIndex": 100
  }'

Response · 200

JSON

{
  "lineCount": 1,
  "extract": {
    "key": {}
  }
}

Report a field the documents cannot answer

posthttps://api.tarifflo.com/api/v2/blocked-fields

Requires the API key scope filing.

AuthApiKeyorBearer

Request body

application/json

object

fieldPathstringrequired
questionstringrequired

Responses

200Successful response

application/json

object

Recorded. Ask the user this question directly, in your own words. Do not guess a value.

fieldPathstringrequired
questionstringrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /blocked-fields

curl -X POST "https://api.tarifflo.com/api/v2/blocked-fields" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fieldPath": "string",
    "question": "string"
  }'

Response · 200

JSON

{
  "fieldPath": "string",
  "question": "string"
}

The link a person reviews and submits from

gethttps://api.tarifflo.com/api/v2/review-link

Requires the API key scope filing.

AuthApiKeyorBearer

Query parameters

sortSessionIdstring
efidstring

Responses

200Successful response

application/json

object

urlstringrequired
Give this to the user to review and submit; you never submit.

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /review-link

curl "https://api.tarifflo.com/api/v2/review-link" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "url": "https://example.com/webhooks/tarifflo"
}

3 endpoints

Origin

Country-of-origin determinations for products.

Determine country of origin

posthttps://api.tarifflo.com/api/v2/origin

Rules-of-origin determinations (non-preferential, marking, FTA-preferential) for up to 5 goods from their bill of materials. Answers 202 with the run id; a run takes minutes. The result is delivered as an origin.completed webhook to the key environment's URL (or Tarifflo-Webhook-Url) and pollable at GET /origin/{jobId}. Requires the API key scope origin.

AuthApiKeyorBearer

Headers

Idempotency-Keystring
Repeats of the same request with the same key answer the first result (72 hours) with Idempotent-Replayed: true.
max length 255

Request body

application/json

object

jobsobject[]required
min items 1max items 5
10 fields per item
- idstring
  Your correlation id, echoed back on the result line.
  max length 200
- import_intostring
  The importing country (default US).
  pattern: ^[A-Za-z]{2}$
- finished_goodobjectrequired
  4 fields
  descriptionstringrequired
  min length 3max length 5000
  htsstring
  max length 20
  value_usdnumber
  ex_works_price_usdnumber
- country_of_finished_productionstringrequired
  pattern: ^[A-Za-z]{2}$
- claimed_country_of_originstring
  pattern: ^[A-Za-z]{2}$
- processingstring
  What is done in the country of finished production.
  max length 10000
- bomobject[]required
  min items 1max items 200
  4 fields per item
  itemstringrequired
  max length 500
  htsstring
  max length 20
  originstringrequired
  pattern: ^[A-Za-z]{2}$
  value_usdnumber
- automotivemap<string, object>
- fungible_inventorymap<string, object>
- qualitystring
  "ship" (default, the full ensemble) or "screen" (one draft, about half the cost).
  One ofshipscreen
folderPathstring[]
Product-grid folder for the created products, as folder names below the root (created when absent), e.g. ["Imports", "2026"]. Omitted: the root folder.
max items 10
dryRunboolean
Price the request at the organization's card and reserve nothing; answers 200 with the estimate.

Responses

202Queued (or, for dryRun, priced with 200)

application/json

object | object

Any of

1.object

jobIdstringrequired
The run id: poll GET /origin/{jobId}.
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
status"queued"required
jobsQueuednumberrequired
messagestringrequired

2.object

dryRuntruerequired
estimatedCreditsnumberrequired
linesobject[]required
3 fields per item
- actionstringrequired
  One of 16 values
  rate_lookupadcvd_screenpga_applicabilitycode_classifiedexport_controlorigin_determinationentry_filedentry_prepareddocument_ocrdocument_extractdocument_sortproduct_enrichentry_reviewrationale_documentaudit_parsedata_export
- unitsnumberrequired
- creditsnumberrequired
balancenumberrequired
unitstringrequired
One oftokencredit
notestring

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

402Not enough credits

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: PAYMENT_REQUIRED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

409The first request with this Idempotency-Key is still filing

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: CONFLICT
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /origin

curl -X POST "https://api.tarifflo.com/api/v2/origin" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jobs": [
      {
        "finished_good": {
          "description": "Laptop computer, 14 inch"
        },
        "country_of_finished_production": "US",
        "bom": [
          {
            "item": "string",
            "origin": "CN"
          }
        ]
      }
    ]
  }'

Response · 202

JSON

{
  "jobId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "credits": {
    "action": "origin_determination",
    "reserved": 2,
    "used": 0,
    "refunded": 0
  },
  "status": "queued",
  "jobsQueued": 1,
  "message": "string"
}

Get an origin run

gethttps://api.tarifflo.com/api/v2/origin/{jobId}

The run's status; once complete, data is the origin.completed webhook's data. Requires the API key scope origin.

AuthApiKeyorBearer

Path parameters

jobIdstringrequired

Responses

200Successful response

application/json

object | object | object

Any of

1.object

jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
status"failed"required
errorobjectrequired
2 fields
- code"RUN_FAILED"required
- messagestringrequired

2.object

jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
statusstringrequired
One ofqueuedprocessingblocked
stagesCompletenumberrequired
stagesTotalnumberrequired
creditsNeedednumber
Credits the run waits for (blocked only).
purchaseUrlstring
Where to add credits (blocked only).

3.object

jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
status"complete"required
eventstringrequired
The webhook event that delivered the same data.
dataobjectrequired
The run's result, exactly the webhook's data.

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /origin/{jobId}

curl "https://api.tarifflo.com/api/v2/origin/01a19e37-837d-7c16-9a5d-3bef820fcff7" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "jobId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "credits": {
    "action": "origin_determination",
    "reserved": 2,
    "used": 0,
    "refunded": 0
  },
  "status": "failed",
  "error": {
    "code": "RUN_FAILED",
    "message": "string"
  }
}

Determine one good's country of origin and wait for it

posthttps://api.tarifflo.com/api/v2/origin/wait

Starts one determination like POST /origin (the job's fields at the top level), then waits up to 40 s for it. A run takes minutes, so this usually answers the run still going with its jobId to poll at GET /origin/{jobId}. Requires the API key scope origin.

AuthApiKeyorBearer

Headers

Idempotency-Keystring
Repeats of the same request with the same key answer the first result (72 hours) with Idempotent-Replayed: true.
max length 255

Request body

application/json

object

finished_goodobjectrequired
The finished good: description (required, be specific), optional hts, value_usd (needed for RVC/MaxNOM math), ex_works_price_usd.
4 fields
- descriptionstringrequired
  min length 3max length 5000
- htsstring
  max length 20
- value_usdnumber
- ex_works_price_usdnumber
bomobject[]required
Bill of materials: every meaningful component/material with its own origin: {item, origin (2-letter ISO), hts?, value_usd?}.
min items 1max items 200
4 fields per item
- itemstringrequired
  max length 500
- htsstring
  max length 20
- originstringrequired
  pattern: ^[A-Za-z]{2}$
- value_usdnumber
country_of_finished_productionstringrequired
Where final production/assembly happens, 2-letter ISO.
pattern: ^[A-Za-z]{2}$
import_intostring
Importing country, 2-letter ISO. Defaults to US.
pattern: ^[A-Za-z]{2}$
claimed_country_of_originstring
Optional: the origin the party claims — the engine checks consistency.
pattern: ^[A-Za-z]{2}$
processingstring
What is actually done in the country of final production (operations performed).
max length 10000
automotivemap<string, object>
Optional USMCA automotive block (RVC averaging / LVC / steel-aluminum inputs).
fungible_inventorymap<string, object>
Optional GN 11(f) fungible-inventory block (commingled originating/non-originating inputs).
qualitystring
"ship" (default: 3-draft ensemble + verify, deliverable grade) or "screen" (single draft + audit, ~half cost).
One ofshipscreen
idstring
Optional correlation id echoed back on the result.
max length 200
folderPathstring[]
Product-grid folder for the created products, as folder names below the root (created when absent), e.g. ["Imports", "2026"]. Omitted: the root folder.
max items 10

Responses

200Successful response

application/json

object | object | object

Where the run stands. complete: data is the determination; a needs_info verdict carries follow_up_questions: refine the job and call find_origin again. queued / processing: still running (a run takes minutes); call wait_for_work with jobType "origin" and this jobId. blocked: waiting for creditsNeeded credits; give the user purchaseUrl, the run resumes on its own, then call wait_for_work again. failed: tell the user.

Any of

1.object

jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
status"failed"required
errorobjectrequired
2 fields
- code"RUN_FAILED"required
- messagestringrequired

2.object

jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
statusstringrequired
One ofqueuedprocessingblocked
stagesCompletenumberrequired
stagesTotalnumberrequired
creditsNeedednumber
Credits the run waits for (blocked only).
purchaseUrlstring
Where to add credits (blocked only).

3.object

jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
status"complete"required
eventstringrequired
The webhook event that delivered the same data.
dataobjectrequired
The run's result, exactly the webhook's data.

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

402Not enough credits

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: PAYMENT_REQUIRED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

409The first request with this Idempotency-Key is still filing

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: CONFLICT
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /origin/wait

curl -X POST "https://api.tarifflo.com/api/v2/origin/wait" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "finished_good": {
      "description": "Laptop computer, 14 inch"
    },
    "bom": [
      {
        "item": "string",
        "origin": "CN"
      }
    ],
    "country_of_finished_production": "US"
  }'

Response · 200

JSON

{
  "jobId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "credits": {
    "action": "origin_determination",
    "reserved": 2,
    "used": 0,
    "refunded": 0
  },
  "status": "failed",
  "error": {
    "code": "RUN_FAILED",
    "message": "string"
  }
}

3 endpoints

Tariff rates

Total landed duty for HTS lines at an origin, destination and date: base rate, Chapter 99, AD/CVD and fees.

Look up duty rates

posthttps://api.tarifflo.com/api/v2/tariff-rates

Total landed duty for up to 50 lines: base rate, Chapter 99 overlays (Section 232, 301, IEEPA), AD/CVD deposits and fees, each line at its own origin, destination and date. Answers 202 with the job id; the result is delivered as a tariff_rate.completed webhook to the key environment's URL (or Tarifflo-Webhook-Url) and pollable at GET /tariff-rates/{jobId}. A line that cannot be rated comes back status: "failed" with its reason, so an accepted request never dies silently. Requires the API key scope tariff_rates.

AuthApiKeyorBearer

Headers

Idempotency-Keystring
Repeats of the same request with the same key answer the first result (72 hours) with Idempotent-Replayed: true.
max length 255

Request body

application/json

object

ratesobject[]required
min items 1max items 50
14 fields per item
- htsCodestringrequired
  HTS code, 4 to 10 digits; dots tolerated.
  min length 4max length 20
- originstringrequired
  Country of origin, ISO-3166 alpha-2.
  pattern: ^[A-Z]{2}$
- destinationstringrequired
  Import country, ISO-3166 alpha-2.
  pattern: ^[A-Z]{2}$
- valuenumber
  Customs value in the destination's currency; defaults to a notional value.
  ≥ 0
- datestring
  Entry date the rates apply on; defaults to effectiveDate, else today.
  pattern: ^\d{4}-\d{2}-\d{2}$
- metalsobject
  Section 232 metal content, as a percentage of the article's value.
  3 fields
  steelnumber
  ≥ 0≤ 100
  aluminumnumber
  ≥ 0≤ 100
  coppernumber
  ≥ 0≤ 100
- usContentPercentagenumber
  ≥ 0≤ 100
- steelCountryOfMeltstring
  pattern: ^[A-Z]{2}$
- aluminumCountryOfSmeltstring
  pattern: ^[A-Z]{2}$
- uomQuantitiesmap<string, number>
  Quantities per unit of measure the code reports in, e.g. { "kg": 120 }.
- appliedExclusionsstring[]
  Chapter 99 exclusion numbers claimed on the line.
- chosenSpiCodesstring[]
  Special program indicators claimed on the line.
- setKindstring
  Set provisions: the article theory the set is rated under.
  One ofsinglecomposite_3beo_nomine_highesteo_nomine_eachensemblegri3bgri3cnamed_setassortment
- componentsobject[]
  Set provisions: the components the set is rated from, each at its own code.
  max items 50
  4 fields per item
  codestringrequired
  The component's 10-digit code as if imported alone (dots tolerated).
  min length 8max length 13
  descriptionstring
  valueSharenumber
  Fraction of the set's customs value, 0..1.
  ≥ 0≤ 1
  quantitynumber
  ≥ 0
effectiveDatestring
Default entry date for every line without its own date.
pattern: ^\d{4}-\d{2}-\d{2}$
loadingDatestring
Date the goods were loaded; drives in-transit rules.
pattern: ^\d{4}-\d{2}-\d{2}$
modeOfTransportstring
One ofoceanairtruckrail
dryRunboolean
Price the request at the organization's card and reserve nothing; answers 200 with the estimate.

Responses

202Queued (or, for dryRun, priced with 200)

application/json

object | object

Any of

1.object

jobIdstringrequired
The job id: poll GET /tariff-rates/{jobId}.
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
status"queued"required
ratesQueuednumberrequired
messagestringrequired

2.object

dryRuntruerequired
estimatedCreditsnumberrequired
linesobject[]required
3 fields per item
- actionstringrequired
  One of 16 values
  rate_lookupadcvd_screenpga_applicabilitycode_classifiedexport_controlorigin_determinationentry_filedentry_prepareddocument_ocrdocument_extractdocument_sortproduct_enrichentry_reviewrationale_documentaudit_parsedata_export
- unitsnumberrequired
- creditsnumberrequired
balancenumberrequired
unitstringrequired
One oftokencredit
notestring

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

402Not enough credits

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: PAYMENT_REQUIRED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

409The first request with this Idempotency-Key is still filing

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: CONFLICT
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /tariff-rates

curl -X POST "https://api.tarifflo.com/api/v2/tariff-rates" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rates": [
      {
        "htsCode": "8471.30.0100",
        "origin": "CN",
        "destination": "US"
      }
    ]
  }'

Response · 202

JSON

{
  "jobId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "credits": {
    "action": "rate_lookup",
    "reserved": 2,
    "used": 0,
    "refunded": 0
  },
  "status": "queued",
  "ratesQueued": 1,
  "message": "string"
}

Get a duty-rate job

gethttps://api.tarifflo.com/api/v2/tariff-rates/{jobId}

The job's status and progress; once complete, data is the tariff_rate.completed webhook's data. Requires the API key scope tariff_rates.

AuthApiKeyorBearer

Path parameters

jobIdstringrequired

Responses

200Successful response

application/json

object | object | object

Any of

1.object

jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
status"failed"required
errorobjectrequired
2 fields
- code"RUN_FAILED"required
- messagestringrequired

2.object

jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
status"complete"required
event"tariff_rate.completed"required
dataobjectrequired
{ results: [...] }, one entry per rate in request order, exactly the webhook's data.

3.object

jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
statusstringrequired
Lines are still being rated.
One ofqueuedprocessing
ratesQueuednumberrequired
ratesCompletednumberrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /tariff-rates/{jobId}

curl "https://api.tarifflo.com/api/v2/tariff-rates/01a19e37-837d-7c16-9a5d-3bef820fcff7" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "jobId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "credits": {
    "action": "rate_lookup",
    "reserved": 2,
    "used": 0,
    "refunded": 0
  },
  "status": "failed",
  "error": {
    "code": "RUN_FAILED",
    "message": "string"
  }
}

Look up duty rates and wait for the result

posthttps://api.tarifflo.com/api/v2/tariff-rates/wait

Starts a lookup like POST /tariff-rates, then waits up to 40 s for it. Answers the finished job, or the job still running with its jobId to poll at GET /tariff-rates/{jobId}. Country codes are accepted in either case. Requires the API key scope tariff_rates.

AuthApiKeyorBearer

Headers

Idempotency-Keystring
Repeats of the same request with the same key answer the first result (72 hours) with Idempotent-Replayed: true.
max length 255

Request body

application/json

object

ratesobject[]required
min items 1max items 50
14 fields per item
- htsCodestringrequired
  HTS code, 4 to 10 digits; dots tolerated.
  min length 4max length 20
- originstringrequired
  Country of origin, ISO-3166 alpha-2.
  pattern: ^[A-Za-z]{2}$
- destinationstringrequired
  Import country, ISO-3166 alpha-2.
  pattern: ^[A-Za-z]{2}$
- valuenumber
  Customs value in the destination's currency; defaults to a notional value.
  ≥ 0
- datestring
  Entry date the rates apply on; defaults to effectiveDate, else today.
  pattern: ^\d{4}-\d{2}-\d{2}$
- metalsobject
  Section 232 metal content, as a percentage of the article's value.
  3 fields
  steelnumber
  ≥ 0≤ 100
  aluminumnumber
  ≥ 0≤ 100
  coppernumber
  ≥ 0≤ 100
- usContentPercentagenumber
  ≥ 0≤ 100
- steelCountryOfMeltstring
  pattern: ^[A-Z]{2}$
- aluminumCountryOfSmeltstring
  pattern: ^[A-Z]{2}$
- uomQuantitiesmap<string, number>
  Quantities per unit of measure the code reports in, e.g. { "kg": 120 }.
- appliedExclusionsstring[]
  Chapter 99 exclusion numbers claimed on the line.
- chosenSpiCodesstring[]
  Special program indicators claimed on the line.
- setKindstring
  Set provisions: the article theory the set is rated under.
  One ofsinglecomposite_3beo_nomine_highesteo_nomine_eachensemblegri3bgri3cnamed_setassortment
- componentsobject[]
  Set provisions: the components the set is rated from, each at its own code.
  max items 50
  4 fields per item
  codestringrequired
  The component's 10-digit code as if imported alone (dots tolerated).
  min length 8max length 13
  descriptionstring
  valueSharenumber
  Fraction of the set's customs value, 0..1.
  ≥ 0≤ 1
  quantitynumber
  ≥ 0
effectiveDatestring
Default entry date for every line without its own date.
pattern: ^\d{4}-\d{2}-\d{2}$
loadingDatestring
Date the goods were loaded; drives in-transit rules.
pattern: ^\d{4}-\d{2}-\d{2}$
modeOfTransportstring
One ofoceanairtruckrail

Responses

200Successful response

application/json

object | object | object

Where the job stands. complete: data.results has one entry per rate line, in request order. queued / processing: still running; call wait_for_work with jobType "rate" and this jobId. failed: error.message says why; tell the user.

Any of

1.object

jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
status"failed"required
errorobjectrequired
2 fields
- code"RUN_FAILED"required
- messagestringrequired

2.object

jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
status"complete"required
event"tariff_rate.completed"required
dataobjectrequired
{ results: [...] }, one entry per rate in request order, exactly the webhook's data.

3.object

jobIdstringrequired
creditsobjectrequired
What the job has reserved, used and refunded so far, in credits.
4 fields
- actionstring | nullrequired
- reservednumberrequired
- usednumberrequired
- refundednumberrequired
statusstringrequired
Lines are still being rated.
One ofqueuedprocessing
ratesQueuednumberrequired
ratesCompletednumberrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

402Not enough credits

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: PAYMENT_REQUIRED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

409The first request with this Idempotency-Key is still filing

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: CONFLICT
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /tariff-rates/wait

curl -X POST "https://api.tarifflo.com/api/v2/tariff-rates/wait" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rates": [
      {
        "htsCode": "8471.30.0100",
        "origin": "CN",
        "destination": "US"
      }
    ]
  }'

Response · 200

JSON

{
  "jobId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "credits": {
    "action": "rate_lookup",
    "reserved": 2,
    "used": 0,
    "refunded": 0
  },
  "status": "failed",
  "error": {
    "code": "RUN_FAILED",
    "message": "string"
  }
}

1 endpoint

Organizations

The organization a call acts in, and the others it can use

gethttps://api.tarifflo.com/api/v2/organizations

Requires the API key scope filing.

AuthApiKeyorBearer

Responses

200Successful response

application/json

object

activeOrganizationIdstringrequired
The organization this call acts in.
switchablebooleanrequired
True: call use_organization to act in another. False: this API key is bound to its organization.
organizationsobject[]required
3 fields per item
- idstringrequired
- namestringrequired
- activebooleanrequired
  The one acting now (a live twin shows as its root).

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /organizations

curl "https://api.tarifflo.com/api/v2/organizations" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "activeOrganizationId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "switchable": true,
  "organizations": [
    {
      "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "name": "Example",
      "active": true
    }
  ]
}

8 endpoints

CBP queries

Ask CBP directly: AD/CVD cases, manufacturer IDs, quota, currency, entry summaries, bonds.

Query CBP AD/CVD cases

posthttps://api.tarifflo.com/api/v2/cbp-queries/adcvd-rates

Requires the API key scope filing.

AuthApiKeyorBearer

Request body

application/json

object

midstring
htsCodestring
caseNumberstring
countryCodestring
companyCaseStatusstring
customDatestring
certificationScenariostring

Responses

200Successful response

application/json

object

shortJobIdstringrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /cbp-queries/adcvd-rates

curl -X POST "https://api.tarifflo.com/api/v2/cbp-queries/adcvd-rates" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mid": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "htsCode": "8471.30.0100",
    "caseNumber": "string",
    "countryCode": "US",
    "companyCaseStatus": "string",
    "customDate": "2026-01-15",
    "certificationScenario": "string"
  }'

Response · 200

JSON

{
  "shortJobId": "01a19e37-837d-7c16-9a5d-3bef820fcff7"
}

Query CBP for a manufacturer (MID)

posthttps://api.tarifflo.com/api/v2/cbp-queries/manufacturer

Requires the API key scope filing.

AuthApiKeyorBearer

Request body

application/json

object

manufacturerIdstring
documentIdstring
dedupeKeystring

Responses

200Successful response

application/json

object

shortJobIdstringrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /cbp-queries/manufacturer

curl -X POST "https://api.tarifflo.com/api/v2/cbp-queries/manufacturer" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "manufacturerId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "documentId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "dedupeKey": "string"
  }'

Response · 200

JSON

{
  "shortJobId": "01a19e37-837d-7c16-9a5d-3bef820fcff7"
}

Query CBP census warnings for entries

posthttps://api.tarifflo.com/api/v2/cbp-queries/census-warnings

Requires the API key scope filing.

AuthApiKeyorBearer

Request body

application/json

object

blockHeaderParamsobjectrequired
3 fields
- processingPortCodestring
- processingFilerCodestring
- appIdCodestringrequired
  One of 35 values
  AEEQSECQREDENEHAHBADAHCWCJCBECFTFZGEKITPSFWPQP$IMACAAAMOQAPESUTERMFQFI
requestedFromDatestring
requestedToDatestring
entryNumbersstring[]required

Responses

200Successful response

application/json

object

shortJobIdstringrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /cbp-queries/census-warnings

curl -X POST "https://api.tarifflo.com/api/v2/cbp-queries/census-warnings" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "blockHeaderParams": {
      "appIdCode": "AE"
    },
    "entryNumbers": [
      "string"
    ]
  }'

Response · 200

JSON

{
  "shortJobId": "01a19e37-837d-7c16-9a5d-3bef820fcff7"
}

Query CBP currency conversion

posthttps://api.tarifflo.com/api/v2/cbp-queries/currency-conversion

Requires the API key scope filing.

AuthApiKeyorBearer

Request body

application/json

object

blockHeaderParamsobjectrequired
1 field
- appIdCodestringrequired
  One of 35 values
  AEEQSECQREDENEHAHBADAHCWCJCBECFTFZGEKITPSFWPQP$IMACAAAMOQAPESUTERMFQFI
countryCodestringrequired
min length 2max length 2
currencyCodestringrequired
min length 3max length 3
exchangeRateDatestringrequired
foreignAmountnumberrequired
> 0

Responses

200Successful response

application/json

object

shortJobIdstringrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /cbp-queries/currency-conversion

curl -X POST "https://api.tarifflo.com/api/v2/cbp-queries/currency-conversion" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "blockHeaderParams": {
      "appIdCode": "AE"
    },
    "countryCode": "US",
    "currencyCode": "USD",
    "exchangeRateDate": "2026-01-15",
    "foreignAmount": 100
  }'

Response · 200

JSON

{
  "shortJobId": "01a19e37-837d-7c16-9a5d-3bef820fcff7"
}

Query CBP quota status

posthttps://api.tarifflo.com/api/v2/cbp-queries/quota-rates

Requires the API key scope filing.

AuthApiKeyorBearer

Request body

application/json

object

queriesobject[]required
min items 1max items 99
3 fields per item
- queryIdstringrequired
  min length 1
- secondTariffNumberstring
- countryCodestringrequired
  min length 1
certificationScenariostring

Responses

200Successful response

application/json

object

shortJobIdstringrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /cbp-queries/quota-rates

curl -X POST "https://api.tarifflo.com/api/v2/cbp-queries/quota-rates" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      {
        "queryId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
        "countryCode": "US"
      }
    ]
  }'

Response · 200

JSON

{
  "shortJobId": "01a19e37-837d-7c16-9a5d-3bef820fcff7"
}

Query CBP entry summaries

posthttps://api.tarifflo.com/api/v2/cbp-queries/entry-summary

Requires the API key scope filing.

AuthApiKeyorBearer

Request body

application/json

object

queryTypestringrequired
One ofJ1J2
includeDetailboolean
entriesobject[]
2 fields per item
- filerCodestringrequired
  min length 3max length 3
- entryNumberstringrequired
  min length 1max length 8
criteriaQueryTypeCodestring
One ofAIIDOCRCNPSCLIQNLQEES
requestedFromDateTimestring
pattern: ^\d{2}\d{2}\d{2}\d{2}\d{2}\d{2}(AM|PM)$
requestedToDateTimestring
pattern: ^\d{2}\d{2}\d{2}\d{2}\d{2}\d{2}(AM|PM)$
entrySummariesFlag"Y"
ftaReconSummariesFlag"Y"
otherReconSummariesFlag"Y"
drawbackSummariesFlag"Y"
dutyDeferralSummariesFlag"Y"
collectionBillInfoCodestring
One of123456
certificationScenariostring

Responses

200Successful response

application/json

object

shortJobIdstringrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /cbp-queries/entry-summary

curl -X POST "https://api.tarifflo.com/api/v2/cbp-queries/entry-summary" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queryType": "J1"
  }'

Response · 200

JSON

{
  "shortJobId": "01a19e37-837d-7c16-9a5d-3bef820fcff7"
}

Query CBP importer and bond records

posthttps://api.tarifflo.com/api/v2/cbp-queries/importer-bond

Requires the API key scope filing.

AuthApiKeyorBearer

Request body

application/json

object

importerOfRecordstringrequired
min length 1
importerProfileIdstring

Responses

200Successful response

application/json

object

shortJobIdstringrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /cbp-queries/importer-bond

curl -X POST "https://api.tarifflo.com/api/v2/cbp-queries/importer-bond" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "importerOfRecord": "string"
  }'

Response · 200

JSON

{
  "shortJobId": "01a19e37-837d-7c16-9a5d-3bef820fcff7"
}

Ask CBP to generate a manufacturer ID

posthttps://api.tarifflo.com/api/v2/cbp-queries/mid

Requires the API key scope filing.

AuthApiKeyorBearer

Request body

application/json

object

legalNamestringrequired
addressstringrequired
cityNamestringrequired
countryCodestringrequired
postalCodestringrequired
documentIdstring

Responses

200Successful response

application/json

object

shortJobIdstringrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /cbp-queries/mid

curl -X POST "https://api.tarifflo.com/api/v2/cbp-queries/mid" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "legalName": "Example",
    "address": "string",
    "cityName": "Example",
    "countryCode": "US",
    "postalCode": "string"
  }'

Response · 200

JSON

{
  "shortJobId": "01a19e37-837d-7c16-9a5d-3bef820fcff7"
}

1 endpoint

Census warnings

Page through the organization's census warning overrides

posthttps://api.tarifflo.com/api/v2/census-warning-overrides/search

Requires the API key scope filing.

AuthApiKeyorBearer

Request body

application/json

object

startRowintegerrequired
First row of the page (0-based).
≥ 0≤ 9007199254740991
endRowintegerrequired
Row after the last one of the page.
≥ 0≤ 9007199254740991
filterModelobject
1 field
- statusobject
  2 fields
  filterTypestring
  valuesstring[]
  Keep only overrides in these statuses.

Responses

200Successful response

application/json

object[]

idstringrequired
entryNumbernumber | stringrequired
The entry number, or "No entry number provided".
lineItemsnumber | null[] | nullrequired
Line numbers the override covers; null when it has no overrides list.
statusstringrequired
The stored status: DRAFT, SUBMITTED, APPROVED or DENIED.
messagestring | null
createdAtstring | nullrequired
updatedAtstring | nullrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /census-warning-overrides/search

curl -X POST "https://api.tarifflo.com/api/v2/census-warning-overrides/search" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "startRow": 1,
    "endRow": 1
  }'

Response · 200

JSON

[
  {
    "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "entryNumber": 1,
    "lineItems": [
      100
    ],
    "status": "string",
    "message": "string",
    "createdAt": "string",
    "updatedAt": "2026-01-15"
  }
]

7 endpoints

Parties

Your filers, importer profiles, manufacturers and other trade parties.

List the organization's importer profiles

gethttps://api.tarifflo.com/api/v2/importer-profiles

Requires the API key scope filing.

AuthApiKeyorBearer

Responses

200Successful response

application/json

object[]

idstringrequired
importerNamestring
importerOfRecordstring
statusstringrequired
One ofDRAFTAWAITING CBPAPPROVEDDENIEDCBP INACTIVECBP VOIDED

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /importer-profiles

curl "https://api.tarifflo.com/api/v2/importer-profiles" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

[
  {
    "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "importerName": "Example",
    "importerOfRecord": "string",
    "status": "DRAFT"
  }
]

Get one of the organization's filers

gethttps://api.tarifflo.com/api/v2/filers/{id}

Requires the API key scope filing.

AuthApiKeyorBearer

Path parameters

idstringrequired

Responses

200Successful response

application/json

object

namestring
filerCodestring
portCodestring
startingEntryNumbernumber
checkDigitOffsetnumber
nationalPermitboolean
isBrokerboolean
brokerLicenseNumberstring
qualifyingBrokerNamestring
disPocNamestring
disPocEmailstring
disPocPhonestring
idstring

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /filers/{id}

curl "https://api.tarifflo.com/api/v2/filers/01a19e37-837d-7c16-9a5d-3bef820fcff7" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

{
  "name": "Example",
  "filerCode": "string",
  "portCode": "string",
  "startingEntryNumber": 1,
  "checkDigitOffset": 100,
  "nationalPermit": true,
  "isBroker": true,
  "brokerLicenseNumber": "string",
  "qualifyingBrokerName": "Example",
  "disPocName": "Example",
  "disPocEmail": "ops@example.com",
  "disPocPhone": "string",
  "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7"
}

List the organization's filers

gethttps://api.tarifflo.com/api/v2/filers

Requires the API key scope filing.

AuthApiKeyorBearer

Responses

200Successful response

application/json

object[]

idstringrequired
namestring
filerCodestring
portCodestring
isBrokerboolean
startingEntryNumbernumber
checkDigitOffsetnumber

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /filers

curl "https://api.tarifflo.com/api/v2/filers" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

[
  {
    "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "name": "Example",
    "filerCode": "string",
    "portCode": "string",
    "isBroker": true,
    "startingEntryNumber": 1,
    "checkDigitOffset": 100
  }
]

List the organization's manufacturers

gethttps://api.tarifflo.com/api/v2/trade-parties/manufacturers

Requires the API key scope filing.

AuthApiKeyorBearer

Responses

200Successful response

application/json

object[]

idstringrequired
legalNamestring
countryCodestringrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

404Not found

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: NOT_FOUND
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

GET /trade-parties/manufacturers

curl "https://api.tarifflo.com/api/v2/trade-parties/manufacturers" \
  -H "X-API-Key: $TARIFFLO_API_KEY"

Response · 200

JSON

[
  {
    "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "legalName": "Example",
    "countryCode": "US"
  }
]

Page through the organization's trade parties

posthttps://api.tarifflo.com/api/v2/trade-parties/search

Requires the API key scope filing.

AuthApiKeyorBearer

Request body

application/json

object

startRownumberrequired
endRownumberrequired
searchTextstring

Responses

200Successful response

application/json

object

rowDataobject[]required
6 fields per item
- idstringrequired
- legalNamestringrequired
- phonestringrequired
- addressstringrequired
- errorstring
- individualContactsobject[]
  4 fields per item
  namestring
  phonestring
  emailstring
  rolestring
rowCountnumberrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /trade-parties/search

curl -X POST "https://api.tarifflo.com/api/v2/trade-parties/search" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "startRow": 100,
    "endRow": 100
  }'

Response · 200

JSON

{
  "rowData": [
    {
      "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "legalName": "Example",
      "phone": "string",
      "address": "string",
      "error": "string",
      "individualContacts": [
        {
          "name": "Example",
          "phone": "string",
          "email": "ops@example.com",
          "role": "string"
        }
      ]
    }
  ],
  "rowCount": 1
}

Find trade parties by their fields

posthttps://api.tarifflo.com/api/v2/trade-parties/match

Requires the API key scope filing.

AuthApiKeyorBearer

Request body

application/json

object

filtermap<string, object>required
Trade-party fields to match, e.g. { legalName, countryCode }. Must not be empty.

Responses

200Successful response

application/json

object

totalMatchednumberrequired
Every match, not just those returned. 0 = no trade party matches: if the documents name this party, create it with create_entity. Do NOT invent one. More than results holds = the filter is too broad.
resultsobject[]required
At most 25 matches; use a match's id.
18 fields per item
- legalNamestringrequired
- abbreviatedNamestringrequired
- hasGbibooleanrequired
- identifierstringrequired
- identifierQualifierstringrequired
- manufacturerIdentifierstringrequired
- individualContactsobject[]required
  4 fields per item
  namestringrequired
  phonestringrequired
  emailstringrequired
  rolestringrequired
- notesstringrequired
- gbiInfoobject[]required
  3 fields per item
  identifierstringrequired
  identifierQualifierstringrequired
  partyTypeDescriptionstringrequired
- addressstringrequired
- cityNamestringrequired
- countrySubEntityCodestringrequired
- postalCodestringrequired
- countryCodestringrequired
- dunsNumberstringrequired
- feiNumberstringrequired
- deaRegistrationNumberstringrequired
- idstringrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /trade-parties/match

curl -X POST "https://api.tarifflo.com/api/v2/trade-parties/match" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "key": {}
    }
  }'

Response · 200

JSON

{
  "totalMatched": 1,
  "results": [
    {
      "legalName": "Example",
      "abbreviatedName": "Example",
      "hasGbi": true,
      "identifier": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "identifierQualifier": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "manufacturerIdentifier": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "individualContacts": [
        {
          "name": "Example",
          "phone": "string",
          "email": "ops@example.com",
          "role": "string"
        }
      ],
      "notes": "string",
      "gbiInfo": [
        {
          "identifier": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
          "identifierQualifier": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
          "partyTypeDescription": "Laptop computer, 14 inch"
        }
      ],
      "address": "string",
      "cityName": "Example",
      "countrySubEntityCode": "US",
      "postalCode": "string",
      "countryCode": "US",
      "dunsNumber": "string",
      "feiNumber": "string",
      "deaRegistrationNumber": "string",
      "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7"
    }
  ]
}

Create or update a trade party

posthttps://api.tarifflo.com/api/v2/trade-parties

Requires the API key scope filing.

AuthApiKeyorBearer

Request body

application/json

object

idstring
An existing trade party's id, to update it.
partymap<string, object>required
Trade-party fields: legalName, abbreviatedName (≤35, required on name-reporting slots when legalName is longer), address, city, postalCode, countryCode, manufacturerIdentifier, …
isManufacturerboolean
Create only. True when this party manufactures the goods.

Responses

200Successful response

application/json

object

idstringrequired
legalNamestringrequired
createdbooleanrequired
Without id: true = created; false = the party already exists under this id and was NOT changed — use that id, or pass it as id to update it. With id: always false (updated).

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /trade-parties

curl -X POST "https://api.tarifflo.com/api/v2/trade-parties" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "party": {
      "key": {}
    }
  }'

Response · 200

JSON

{
  "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
  "legalName": "Example",
  "created": true
}

1 endpoint

TIB extensions

Page through the organization's TIB groups

posthttps://api.tarifflo.com/api/v2/tib-extensions/search

Requires the API key scope filing.

AuthApiKeyorBearer

Request body

application/json

object

startRowintegerrequired
First row of the page (0-based).
≥ 0≤ 9007199254740991
endRowintegerrequired
Row after the last one of the page.
≥ 0≤ 9007199254740991
filterModelobject
2 fields
- statusobject
  2 fields
  filterTypestring
  valuesstring[]
  Keep only TIBs whose latest request is in these statuses.
- entryNumberobject
  3 fields
  filterTypestring
  typestring
  filterstring | number | null
  Keep only TIBs whose entry number starts with this.
sortModelobject[]
The first entry sorts the rows; default is newest update first.
2 fields per item
- colIdstringrequired
  One ofentryNumberstatuscreatedAtupdatedAtexpirationDate
- sortstringrequired
  One ofascdesc

Responses

200Successful response

application/json

object

rowsobject[]required
15 fields per item
- acceptedExtensionsnumberrequired
- closureAcceptedbooleanrequired
- extensionDeniedbooleanrequired
- openRequestIdstring
  The request id of the group's unfinished request, if it has one.
- canExtendbooleanrequired
- canClosebooleanrequired
- idstringrequired
- filerCodestringrequired
- entryNumbernumberrequired
- entryVersionIdstring
- expirationDatestring
- extensionCountnumber
- createdAtstring
- updatedAtstring
- latestobject
  11 fields
  idstringrequired
  rowIdstringrequired
  versionnumberrequired
  Send attempts: a rejected request fixed and resent is a new version.
  kindstring
  1 = extension, 2 = closure.
  One of12
  portOfEntrystring
  statusstringrequired
  One ofDRAFTAPPROVEDAWAITING CBPDENIEDWARNINGINFOINTERNAL ERRORUNKNOWNTIB DENIED
  messagestring
  submittedAtstring
  createdAtstring
  updatedAtstring
  conditionsCountnumberrequired
totalnumberrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /tib-extensions/search

curl -X POST "https://api.tarifflo.com/api/v2/tib-extensions/search" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "startRow": 1,
    "endRow": 1
  }'

Response · 200

JSON

{
  "rows": [
    {
      "acceptedExtensions": 100,
      "closureAccepted": true,
      "extensionDenied": true,
      "openRequestId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "canExtend": true,
      "canClose": true,
      "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "filerCode": "string",
      "entryNumber": 1,
      "entryVersionId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "expirationDate": "2026-01-15",
      "extensionCount": 1,
      "createdAt": "string",
      "updatedAt": "2026-01-15",
      "latest": {
        "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
        "rowId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
        "version": 100,
        "kind": "1",
        "portOfEntry": "string",
        "status": "DRAFT",
        "message": "string",
        "submittedAt": "string",
        "createdAt": "string",
        "updatedAt": "2026-01-15",
        "conditionsCount": 1
      }
    }
  ],
  "total": 1
}

1 endpoint

In-bonds

Page through the organization's in-bonds

posthttps://api.tarifflo.com/api/v2/in-bonds/search

Requires the API key scope filing.

AuthApiKeyorBearer

Request body

application/json

object

startRowintegerrequired
≥ 0≤ 9007199254740991
endRowintegerrequired
≥ 0≤ 9007199254740991
filterModelobject
2 fields
- statusobject
  2 fields
  filterTypestring
  valuesstring[]
- inBondNumberobject
  3 fields
  filterTypestring
  typestring
  filterstring | number | null
sortModelobject[]
2 fields per item
- colIdstringrequired
  One ofinBondNumberstatuscreatedAtupdatedAtsubmittedAt
- sortstringrequired
  One ofascdesc

Responses

200Successful response

application/json

object

rowsobject[]required
15 fields per item
- idstringrequired
- rowIdstringrequired
- versionnumberrequired
- statusstringrequired
  One ofDRAFTAWAITING CBPACCEPTEDWARNINGPARTIALREJECTEDDELETEDUNKNOWNINTERNAL ERROR
- onFilebooleanrequired
- inBondNumberstring
- inBondTypestring
- usPortOfDestinationstring
- inBondCarrierCodestring
- billCountnumberrequired
- filerCodestring
- shipmentIdstringrequired
- submittedAtstring
- createdAtstring
- updatedAtstring
totalnumberrequired

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /in-bonds/search

curl -X POST "https://api.tarifflo.com/api/v2/in-bonds/search" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "startRow": 1,
    "endRow": 1
  }'

Response · 200

JSON

{
  "rows": [
    {
      "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "rowId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "version": 100,
      "status": "DRAFT",
      "onFile": true,
      "inBondNumber": "string",
      "inBondType": "string",
      "usPortOfDestination": "US",
      "inBondCarrierCode": "string",
      "billCount": 1,
      "filerCode": "string",
      "shipmentId": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
      "submittedAt": "string",
      "createdAt": "string",
      "updatedAt": "2026-01-15"
    }
  ],
  "total": 1
}

1 endpoint

Cargo release

Page through the organization's cargo releases

posthttps://api.tarifflo.com/api/v2/cargo-releases/search

Requires the API key scope filing.

AuthApiKeyorBearer

Request body

application/json

object

startRowintegerrequired
First row of the page (0-based).
≥ 0≤ 9007199254740991
endRowintegerrequired
Row after the last one of the page.
≥ 0≤ 9007199254740991
filterModelobject
1 field
- statusobject
  2 fields
  filterTypestring
  valuesstring[]
  Keep only cargo releases in these statuses.

Responses

200Successful response

application/json

object[]

idstringrequired
The cargo release's id.
entryFilerCodestring
entryNumberstring
entryTypestring
modeOfTransportationstring
statusstringrequired
One ofDRAFTAWAITING CBPAPPROVEDDENIEDWARNINGINFOINTERNAL ERROR
estimatedEntryValuenumber
createdAtstring
ISO timestamp.

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: INTERNAL_SERVER_ERROR
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

POST /cargo-releases/search

curl -X POST "https://api.tarifflo.com/api/v2/cargo-releases/search" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "startRow": 1,
    "endRow": 1
  }'

Response · 200

JSON

[
  {
    "id": "01a19e37-837d-7c16-9a5d-3bef820fcff7",
    "entryFilerCode": "string",
    "entryNumber": "string",
    "entryType": "string",
    "modeOfTransportation": "string",
    "status": "DRAFT",
    "estimatedEntryValue": 1000,
    "createdAt": "string"
  }
]

1 endpoint

Shipments

Page through the organization's shipments

posthttps://api.tarifflo.com/api/v2/shipments/search

Requires the API key scope filing.

AuthApiKeyorBearer

Request body

application/json

object

startRowintegerrequired
≥ 0≤ 9007199254740991
endRowintegerrequired
≥ 1≤ 500
entryNumberstring
max length 64

Responses

200Successful response

application/json

object

rowsobject[]required
5 fields per item
- idstringrequired
- createdAtstringrequired
- entryobject
  12 fields
  kind"entrySummary"required
  idstringrequired
  statusstringrequired
  datestringrequired
  headerIdstringrequired
  entryNumberstring
  entryFilerCodestring
  entryTypestring
  importerNamestring
  numActionItemsnumberrequired
  cbpSourcedbooleanrequired
  hasEntryDatebooleanrequired
- countsobjectrequired
  7 fields
  entrySummarynumberrequired
  isfnumberrequired
  cargoReleasenumberrequired
  tibExtensionnumberrequired
  censusWarningOverridenumberrequired
  inBondnumberrequired
  inBondEventnumberrequired
- lastActivityAtstringrequired
totalnumber

400Invalid input data

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: BAD_REQUEST
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

401Authorization not provided

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: UNAUTHORIZED
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

403Insufficient access

application/json

errorobjectrequired
7 fields
- codestringrequired
  example: FORBIDDEN
- messagestringrequired
- issuesobject[]
  Input validation issues (400 only)
  3 fields per item
  codestring
  messagestringrequired
  pathany[]
- errorsobject[]
  Entry validation errors, by path in the request's entry
  2 fields per item
  pathstringrequired
  example: lineItems[3].tariffRows[0].htsNumber
  messagestringrequired
- efidstring
  The entry the request wrote before it failed
- fieldstring
  The field CBP now requires or rejects (cbp_requirement only)
- effectiveDatestring
  When that CBP rule takes effect (cbp_requirement only)

500Internal server error

application/json