Tariff & Codebook API

The Tariff & Codebook API provides read-only access to the EU customs tariff and the Dutch customs codebook. Use these endpoints to validate HS codes, look up applicable measures and document requirements per commodity, and retrieve the valid option lists for every declaration field.

Required Scope: Any valid API token — no specific scope required. These endpoints are read-only reference data available to all authenticated callers.

HS Code Validation

Validate whether an HS code is declarable in the EU customs tariff on a given date.

The EU tariff distinguishes between import and export declarability:

Import — requires a 10-digit code (8-digit CN code + 2-digit TARIC subheading, e.g. 0101210000)
Export — requires an 8-digit CN code (e.g. 01012100); the last two digits are always 00

Always pass trade_direction so the endpoint validates against the correct digit level for your declaration type.


GET /api/v1/tariff/validate?hs_code=0101210000&trade_direction=import

Query Parameters

Parameter	Type	Required	Description
`hs_code`	string	Yes	6–10 digit HS code (dots and spaces are stripped)
`trade_direction`	string	No	`import` or `export`. When omitted, either digit level is accepted.
`date`	date	No	Validation date (default: today). Format: `YYYY-MM-DD`

Example — Import validation


curl https://app.borderbolt.com/api/v1/tariff/validate \
  -H "Authorization: Bearer {token}" \
  -G \
  --data-urlencode "hs_code=0101210000" \
  --data-urlencode "trade_direction=import"


{
  "hs_code": "0101210000",
  "date": "2026-05-04",
  "trade_direction": "import",
  "valid": true,
  "digit_level": 10,
  "message": null
}

Example — Export validation


curl https://app.borderbolt.com/api/v1/tariff/validate \
  -H "Authorization: Bearer {token}" \
  -G \
  --data-urlencode "hs_code=01012100" \
  --data-urlencode "trade_direction=export"


{
  "hs_code": "01012100",
  "date": "2026-05-04",
  "trade_direction": "export",
  "valid": true,
  "digit_level": 8,
  "message": null
}

Response Fields

Field	Type	Description
`valid`	boolean	`true` if the code is declarable for the given trade direction and date
`digit_level`	integer\|null	`10` for an import-declarable code, `8` for an export-declarable code, `null` if invalid
`message`	string\|null	Error description when `valid` is `false`

Invalid — wrong digit level

A 10-digit code submitted for export, or an 8-digit code for import, is rejected with 422:


{
  "hs_code": "0101210000",
  "date": "2026-05-04",
  "trade_direction": "export",
  "valid": false,
  "digit_level": null,
  "message": "HS code 0101210000 is not declarable for export on 2026-05-04 (8-digit code required)"
}

HTTP 422 is returned for invalid or non-declarable codes.

Additional Codes

Retrieve TARIC and national additional codes. These are the codes entered in the additional_taric1 / additional_taric2 fields on a declaration line.

To find which additional codes apply to a specific HS code, use Additional References — that endpoint returns measures with their linked certificate and additional code requirements per commodity and country.


GET /api/v1/tariff/additional-codes

Query Parameters

Parameter	Type	Required	Description
`type`	string	No	Filter by additional code type prefix (e.g. `4`, `A`, `B`, `C`, `D`, `F`, `P`)
`lang`	string	No	Response language: `nl` (default) or `en`

Common Additional Code Types

Type	Description
`4`	CITES / wildlife trade (e.g. `4001` Bluefin tuna)
`A`	Agri additional codes
`B`	Pharmaceutical additional codes
`C`	Chemical additional codes
`D`	Dual-use / export control
`F`	Food safety
`P`	Plant health
`Q`, `V`, `U`	National (NL) additional codes

Example Request


curl https://app.borderbolt.com/api/v1/tariff/additional-codes \
  -H "Authorization: Bearer {token}" \
  -G \
  --data-urlencode "type=4" \
  --data-urlencode "lang=en"

Example Response


{
  "type": "4",
  "lang": "en",
  "count": 278,
  "additional_codes": [
    {
      "type": "4",
      "code": "001",
      "description": "Bluefin tunas (Thunnus thynnus)",
      "date_start": "2003-11-14"
    },
    {
      "type": "4",
      "code": "002",
      "description": "Swordfish (Xiphias gladius)",
      "date_start": "2003-11-14"
    }
  ]
}

Additional References

Retrieve the applicable measures for an HS code, country, and trade direction. Each measure lists the document or certificate requirements that must be declared in additional_references on the declaration line.


GET /api/v1/tariff/additional-references

Query Parameters

Parameter	Type	Required	Description
`hs_code`	string	Yes	6–10 digit HS code
`country_code`	string	Yes	2-letter ISO country code of origin / destination
`trade_direction`	string	Yes	`import` or `export`
`taric_code`	string	No	4-character TARIC additional code to narrow results

Example Request


curl https://app.borderbolt.com/api/v1/tariff/additional-references \
  -H "Authorization: Bearer {token}" \
  -G \
  --data-urlencode "hs_code=0302110000" \
  --data-urlencode "country_code=NO" \
  --data-urlencode "trade_direction=import"

Example Response


{
  "hs_code": "0302110000",
  "country_code": "NO",
  "trade_direction": "import",
  "taric_code": null,
  "count": 3,
  "measures": [
    {
      "measure_type": "750",
      "description": "Import control of fishery products",
      "geographical_area": "1011",
      "condition_groups": [
        {
          "condition_code": "L",
          "description": "Reference to document issued by competent authority",
          "certificates": [
            {
              "code": "L001",
              "type": "Certificate",
              "description": "Common Health Entry Document for Products (CHED-P)"
            }
          ]
        }
      ]
    }
  ]
}

Codebook Index

List all available codebook table aliases with their table numbers and descriptions.


GET /api/v1/codebook

Example Request


curl https://app.borderbolt.com/api/v1/codebook \
  -H "Authorization: Bearer {token}"

Example Response (excerpt)


{
  "description": "Use GET /api/v1/codebook/{table} to retrieve codebook entries. {table} can be a numeric table number or one of the aliases below.",
  "aliases": {
    "transport_modes":        { "table": "018", "description": "Transport mode codes (VERVOERSWIJZE)" },
    "countries":              { "table": "008", "description": "All country codes" },
    "currencies":             { "table": "352", "description": "Currency codes (MUNTSOORT)" },
    "incoterms":              { "table": "090", "description": "Incoterms delivery conditions" },
    "procedures_current":     { "table": "092", "description": "Current procedure codes (GEVRAAGDE REG)" },
    "procedures_previous":    { "table": "093", "description": "Previous procedure codes (VOORAFG REG)" },
    "document_types_support": { "table": "213", "description": "Supporting document types (BIJLAG DOC)" }
  }
}

Codebook Lookup

Retrieve all valid codes for a specific customs codebook table. Use a numeric table number (e.g. 018) or one of the named aliases.


GET /api/v1/codebook/{table}

Path Parameter

{table} — a numeric table number or one of the aliases from /api/v1/codebook.

Query Parameters

Parameter	Type	Required	Description
`date`	date	No	Validity date (default: today). Codes valid on this date are returned.
`lang`	string	No	`nl` (Dutch, default) or `en` (English)

Field → Codebook Mapping

Every dropdown in a declaration maps to a specific codebook table. Use the alias or table number directly.

Header Fields

Field	Alias	Table
Declaration type (A–F)	`declaration_types`	042
Declaration symbol (IM/EX/CO)	`declaration_symbols`	231
Current procedure	`procedures_current`	092
Previous procedure	`procedures_previous`	093
Special procedure	`special_procedures`	102
Customs office	`customs_offices`	141
Office of exit	`offices_of_exit`	294
Incoterms	`incoterms`	090
Transport mode (border/arrival/departure)	`transport_modes`	018
Transport identification type	`transport_id_types`	750
Country (all fields)	`countries`	008
Destination country (export)	`export_countries`	207
Goods location type	`location_types`	347
Warehouse licence type	`licence_types`	099
Guarantee type	`guarantee_types`	251
Surety type	`surety_types`	100
Authorisation type	`authorisation_types`	T03
Fiscal party role	`fiscal_party_roles`	149
Currency	`currencies`	352
Transaction nature	`transaction_natures`	091

Line Fields

Field	Alias	Table
Packaging type	`packaging`	017
Valuation method	`valuation_methods`	604
Duty regime / preference	`duty_regimes`	603
Supporting document type	`document_types_support`	213
Previous document type	`document_types_previous`	214
Transport document type	`document_types_transport`	754
Additional information code	`additional_info`	239
Additional reference type	`additional_references`	380
Charge/deduction code	`charge_deductions`	791
Duty/tax/fee type	`duty_tax_fee_types`	098
Tax base unit	`tax_base_units`	349

Example — Transport Modes


curl https://app.borderbolt.com/api/v1/codebook/transport_modes \
  -H "Authorization: Bearer {token}" \
  -G \
  --data-urlencode "lang=en"


{
  "table": "018",
  "alias": "transport_modes",
  "table_name": "VERVOERSWIJZE",
  "date": "2026-05-04",
  "lang": "en",
  "count": 9,
  "codes": [
    { "code": "1", "description": "Sea transport",        "description_en": "Sea transport",        "description_nl": "ZEEVERVOER",   "legal_reference": null },
    { "code": "2", "description": "Rail transport",       "description_en": "Rail transport",       "description_nl": "SPOORVERVOER", "legal_reference": null },
    { "code": "3", "description": "Road transport",       "description_en": "Road transport",       "description_nl": "WEGVERVOER",   "legal_reference": null },
    { "code": "4", "description": "Air transport",        "description_en": "Air transport",        "description_nl": "LUCHTVERVOER", "legal_reference": null },
    { "code": "7", "description": "Fixed transport installations", "description_en": "Fixed transport installations", "description_nl": "VASTE INSTALLATIES", "legal_reference": null },
    { "code": "8", "description": "Inland waterway transport", "description_en": "Inland waterway transport", "description_nl": "BINNENVAART", "legal_reference": null },
    { "code": "9", "description": "Own propulsion",      "description_en": "Own propulsion",       "description_nl": "EIGEN VOORTDRIJVING", "legal_reference": null }
  ]
}

Example — Procedure Codes (Current)


curl https://app.borderbolt.com/api/v1/codebook/procedures_current \
  -H "Authorization: Bearer {token}"


{
  "table": "092",
  "alias": "procedures_current",
  "table_name": "GEVRAAGDE REG",
  "date": "2026-05-04",
  "lang": "nl",
  "count": 42,
  "codes": [
    { "code": "0700", "description": "Vrijstelling douanerechten (artikel 23 Douanewet)", "description_en": null, "description_nl": "...", "legal_reference": null },
    { "code": "4000", "description": "Invoer in het vrije verkeer", "description_en": "Release for free circulation", "description_nl": "Invoer in het vrije verkeer", "legal_reference": null },
    { "code": "4200", "description": "Invoer met vrijstelling BTW", "description_en": "Simultaneous release for free circulation and home use of goods subject to VAT exemption", "description_nl": "...", "legal_reference": null }
  ]
}

Example — Supporting Document Types


curl https://app.borderbolt.com/api/v1/codebook/document_types_support \
  -H "Authorization: Bearer {token}"


{
  "table": "213",
  "alias": "document_types_support",
  "table_name": "BIJLAG DOC",
  "date": "2026-05-04",
  "lang": "nl",
  "count": 156,
  "codes": [
    { "code": "C400", "description": "Douanevergunning actieve veredeling", "description_en": "Customs authorisation for inward processing", "description_nl": "...", "legal_reference": null },
    { "code": "C505", "description": "ATA-carnet", "description_en": "ATA carnet", "description_nl": "ATA-carnet", "legal_reference": null },
    { "code": "N830", "description": "Factuur", "description_en": "Invoice", "description_nl": "Factuur", "legal_reference": null },
    { "code": "N935", "description": "Oorsprongscertificaat Form A", "description_en": "Certificate of origin Form A", "description_nl": "...", "legal_reference": null }
  ]
}

Not Found

If the table alias or number does not exist, HTTP 404 is returned:


{
  "error": "codebook_not_found",
  "message": "Codebook table 'xyz' not found. Use a valid table number or alias.",
  "aliases": ["transport_modes", "countries", "currencies", "..."]
}