Declaration Submit API

The Declaration Submit API lets you create import and export declarations with full customs data and optionally submit them directly to Dutch Customs (DMS 4.0 and 4.1).

Required Scopes: declarations:write to create declarations, declarations:submit to auto-submit to customs.

Endpoints

Method	Endpoint	Description
`POST`	`/api/v1/declarations/create`	Create (and optionally submit) an import or export declaration
`POST`	`/api/v1/declarations/create/validate`	Validate a declaration without saving

Set declaration.imex to "IM" for import or "EX" for export.

Customer Master Lookup

For any party block (importer, exporter, buyer, seller, consignor, consignee), you can provide only a customer_code instead of repeating the full name, address, and EORI. Borderbolt will look up the party details from the Customer Master automatically.


"importer": { "customer_code": "ACME-NL" }

Any fields you provide explicitly always take precedence over the Customer Master values. If the customer_code is not found, a warning is logged and the inline fields are used as-is.

Submit Import Declaration


POST /api/v1/declarations/submit

Full Request Example — Import 40 00


{
  "reference": "IMP-2026-00124",
  "application_reference": "APP-IMP-00124",
  "submit_when_valid": false,
  "representation_type": "2",
  "applyChainProcedure": false,
  "daysDelayBeforeSubmit": 0,
  "declaration": {
    "office": "NL000012",
    "language": "NL",
    "symbol": "A",
    "imex": "IM",
    "procedure": {
      "current": "40",
      "previous": "00",
      "special": null
    },
 
    "importer": {
      "customer_code": "ACME-NL",
      "eori": "NL123456789B01",
      "name": "Acme Netherlands B.V.",
      "address": {
        "street": "Havenstraat 42",
        "city": "Rotterdam",
        "postal_code": "3011 AA",
        "country": "NL"
      }
    },
    "exporter": {
      "eori": "CN987654321",
      "name": "Shenzhen Goods Co. Ltd.",
      "address": {
        "street": "Industrial Zone 8, Longhua",
        "city": "Shenzhen",
        "postal_code": "518000",
        "country": "CN"
      }
    },
    "buyer": {
      "customer_code": "ACME-NL",
      "eori": "NL123456789B01",
      "name": "Acme Netherlands B.V.",
      "address": {
        "street": "Havenstraat 42",
        "city": "Rotterdam",
        "postal_code": "3011 AA",
        "country": "NL"
      }
    },
    "seller": {
      "eori": "CN987654321",
      "name": "Shenzhen Goods Co. Ltd.",
      "address": {
        "street": "Industrial Zone 8, Longhua",
        "city": "Shenzhen",
        "postal_code": "518000",
        "country": "CN"
      }
    },
 
    "transport": {
      "border": {
        "mode": "1",
        "nationality": "NL",
        "identification": "MSCZOE123456",
        "identification_type": "41"
      },
      "containers": [
        { "number": "MSCU1234567", "seals": ["SEAL001", "SEAL002"] }
      ]
    },
 
    "goods_location": {
      "type": "A",
      "identification_type": "U",
      "country": "NL",
      "postal_code": "3011 AA",
      "city": "Rotterdam",
      "address": null,
      "house_number": null
    },
 
    "incoterms": {
      "code": "CIF",
      "country": "NL",
      "location": "Rotterdam"
    },
 
    "transaction_nature": 11,
    "total_packages": 36,
    "total_invoice_value": 18500.00,
    "total_invoice_currency": "USD",
 
    "warehouse": {
      "licence": null,
      "licence_type": null
    },
 
    "authorizations": [
      { "type_code": "CGU", "id": "NL-CGU-2026-00042" },
      { "type_code": "C506", "id": "NLDPONL000568-2024-D-UZH140607" }
    ],
 
    "domestic_duty_tax_party": {
      "id": null,
      "role": null
    },
 
    "items": [
      {
        "sequence": 1,
        "description": "Electronic control units, programmable",
        "sku": "ECU-PRG-001",
        "hs_code": "85371099",
        "taric": "00",
        "additional_taric1": "4099",
        "additional_taric2": null,
        "country_of_origin": "CN",
        "preferential_country_of_origin": null,
        "gross_weight": 320.50,
        "net_weight": 295.00,
        "supplementary_quantity": 150,
        "invoice_value": 12000.00,
        "invoice_currency": "USD",
        "statistical_value": 13200.00,
        "previous_code": "00",
        "duty_regime": "100",
        "valuation": {
          "method": "1",
          "charge_deductions": [
            { "code": "AK", "currency": "USD", "amount": 1.84 },
            { "code": "AH", "currency": "USD", "amount": 3.91 }
          ]
        },
        "packaging": [
          { "type": "CT", "quantity": 12, "marks": "ACME/2026/001-012" }
        ],
        "containers": [
          { "number": "MSCU1234567" }
        ],
        "supporting_documents": [
          {
            "type": "N271",
            "id": "INV-2026-SZ-0042",
            "line": 1,
            "expiry_date": null,
            "value": 12000.00,
            "currency": "USD",
            "quantity": null,
            "uom": null
          },
          {
            "type": "N705",
            "id": "BL-MSCROT2026001",
            "line": null,
            "expiry_date": null,
            "value": null,
            "currency": null,
            "quantity": null,
            "uom": null
          },
          {
            "type": "C644",
            "id": "CERT-CONF-2026-001",
            "line": 1,
            "expiry_date": "2026-12-31",
            "value": null,
            "currency": null,
            "quantity": 150,
            "uom": "NAR"
          }
        ],
        "additional_references": [
          { "type": "Y900", "value": "LIC-NL-2026-0042" },
          { "type": "GRN",  "value": "26NL0000000000001A1" }
        ],
        "previous_documents": [
          { "type": "355", "id": "MRN2500001NL000012", "line": 1 }
        ],
        "sku_details": [
          {
            "sku": "ECU-PRG-001-A",
            "description": "ECU variant A",
            "quantity": 100,
            "unit_value": 75.00,
            "unit_value_currency": "USD",
            "unit_gross_weight": 2.10,
            "unit_net_weight": 1.95,
            "country_of_origin": "CN"
          },
          {
            "sku": "ECU-PRG-001-B",
            "description": "ECU variant B",
            "quantity": 50,
            "unit_value": 90.00,
            "unit_value_currency": "USD",
            "unit_gross_weight": 2.20,
            "unit_net_weight": 2.00,
            "country_of_origin": "CN"
          }
        ]
      },
      {
        "sequence": 2,
        "description": "Cable harnesses for automotive use",
        "sku": "CBL-AUTO-022",
        "hs_code": "85443010",
        "taric": "00",
        "additional_taric1": null,
        "additional_taric2": null,
        "country_of_origin": "CN",
        "preferential_country_of_origin": null,
        "gross_weight": 180.00,
        "net_weight": 168.00,
        "supplementary_quantity": null,
        "invoice_value": 6500.00,
        "invoice_currency": "USD",
        "statistical_value": 7150.00,
        "previous_code": "00",
        "duty_regime": "100",
        "valuation": { "method": "1" },
        "packaging": [
          { "type": "BX", "quantity": 24, "marks": "ACME/2026/013-036" }
        ],
        "containers": [
          { "number": "MSCU1234567" }
        ],
        "supporting_documents": [
          {
            "type": "N271",
            "id": "INV-2026-SZ-0042",
            "line": 2,
            "expiry_date": null,
            "value": 6500.00,
            "currency": "USD",
            "quantity": null,
            "uom": null
          },
          {
            "type": "N705",
            "id": "BL-MSCROT2026001",
            "line": null,
            "expiry_date": null,
            "value": null,
            "currency": null,
            "quantity": null,
            "uom": null
          }
        ],
        "additional_references": [
          { "type": "Y900", "value": "LIC-NL-2026-0043" }
        ],
        "previous_documents": [
          { "type": "355", "id": "MRN2500001NL000012", "line": 2 }
        ],
        "sku_details": []
      }
    ]
  }
}

Submit Export Declaration


POST /api/v1/declarations/submit

Full Request Example — Export 10 00


{
  "reference": "EXP-2026-00456",
  "application_reference": "APP-EXP-00456",
  "submit_when_valid": false,
  "representation_type": "2",
  "declaration": {
    "office": "NL000510",
    "exit_office": "NL000834",
    "language": "NL",
    "symbol": "A",
    "imex": "EX",
    "procedure": {
      "current": "10",
      "previous": "00",
      "special": null
    },
 
    "consignor": {
      "customer_code": "ACME-NL",
      "eori": "NL123456789B01",
      "name": "Acme Netherlands B.V.",
      "address": {
        "street": "Havenstraat 42",
        "city": "Rotterdam",
        "postal_code": "3011 AA",
        "country": "NL"
      }
    },
    "consignee": {
      "eori": "US123456789",
      "name": "Acme North America Inc.",
      "address": {
        "street": "500 Commerce Drive",
        "city": "Chicago",
        "postal_code": "60601",
        "country": "US"
      }
    },
    "seller": {
      "customer_code": "ACME-NL",
      "eori": "NL123456789B01",
      "name": "Acme Netherlands B.V.",
      "address": {
        "street": "Havenstraat 42",
        "city": "Rotterdam",
        "postal_code": "3011 AA",
        "country": "NL"
      }
    },
    "buyer": {
      "eori": "US123456789",
      "name": "Acme North America Inc.",
      "address": {
        "street": "500 Commerce Drive",
        "city": "Chicago",
        "postal_code": "60601",
        "country": "US"
      }
    },
 
    "transport": {
      "border": {
        "mode": "1",
        "nationality": "PA",
        "identification": "EVERGREEN999",
        "identification_type": "41"
      },
      "departure": {
        "mode": "3",
        "nationality": "NL",
        "identification": "AB-12-CD",
        "identification_type": "11"
      },
      "containers": [
        { "number": "EVGU8765432", "seals": ["SEAL100"] }
      ]
    },
 
    "goods_location": {
      "type": "A",
      "identification_type": "U",
      "country": "NL",
      "postal_code": "3011 AA",
      "city": "Rotterdam",
      "address": null,
      "house_number": null
    },
 
    "incoterms": {
      "code": "FOB",
      "country": "NL",
      "location": "Rotterdam"
    },
 
    "destination_country": "US",
    "export_country": "NL",
    "transaction_nature": 11,
    "total_packages": 18,
    "total_invoice_value": 22400.00,
    "total_invoice_currency": "EUR",
 
    "warehouse": {
      "licence": null,
      "licence_type": null
    },
 
    "authorizations": [
      { "type_code": "CWP", "id": "NL-CWP-2026-00099" }
    ],
 
    "domestic_duty_tax_party": {
      "id": null,
      "role": null
    },
 
    "items": [
      {
        "sequence": 1,
        "description": "Industrial hydraulic pumps, max 350 bar",
        "sku": "HYD-PUMP-350",
        "hs_code": "84135020",
        "taric": "00",
        "additional_taric1": null,
        "additional_taric2": null,
        "country_of_origin": "NL",
        "preferential_country_of_origin": null,
        "gross_weight": 840.00,
        "net_weight": 790.00,
        "supplementary_quantity": 12,
        "invoice_value": 14400.00,
        "invoice_currency": "EUR",
        "statistical_value": 14400.00,
        "previous_code": "00",
        "duty_regime": "100",
        "valuation": { "method": "1" },
        "packaging": [
          { "type": "CR", "quantity": 12, "marks": "PUMP/EXP/2026/001-012" }
        ],
        "containers": [
          { "number": "EVGU8765432" }
        ],
        "supporting_documents": [
          {
            "type": "N380",
            "id": "INV-2026-EXP-0099",
            "line": 1,
            "expiry_date": null,
            "value": 14400.00,
            "currency": "EUR",
            "quantity": null,
            "uom": null
          },
          {
            "type": "N703",
            "id": "PL-2026-EXP-0099",
            "line": null,
            "expiry_date": null,
            "value": null,
            "currency": null,
            "quantity": 12,
            "uom": "NAR"
          },
          {
            "type": "N935",
            "id": "EXA-2026-NL-00099",
            "line": 1,
            "expiry_date": "2027-06-30",
            "value": 14400.00,
            "currency": "EUR",
            "quantity": 12,
            "uom": "NAR"
          }
        ],
        "additional_references": [
          { "type": "Y023", "value": "NL-DGA-2026-AUTH-001" }
        ],
        "previous_documents": [],
        "sku_details": [
          {
            "sku": "HYD-PUMP-350-STD",
            "description": "Hydraulic pump 350 bar standard",
            "quantity": 12,
            "unit_value": 1200.00,
            "unit_value_currency": "EUR",
            "unit_gross_weight": 70.00,
            "unit_net_weight": 65.83,
            "country_of_origin": "NL"
          }
        ]
      },
      {
        "sequence": 2,
        "description": "Spare parts kit for hydraulic pumps",
        "sku": "HYD-PARTS-KIT",
        "hs_code": "84139100",
        "taric": "00",
        "additional_taric1": null,
        "additional_taric2": null,
        "country_of_origin": "NL",
        "preferential_country_of_origin": null,
        "gross_weight": 120.00,
        "net_weight": 112.00,
        "supplementary_quantity": null,
        "invoice_value": 8000.00,
        "invoice_currency": "EUR",
        "statistical_value": 8000.00,
        "previous_code": "00",
        "duty_regime": "100",
        "valuation": { "method": "1" },
        "packaging": [
          { "type": "BX", "quantity": 6, "marks": "PARTS/EXP/2026/001-006" }
        ],
        "containers": [
          { "number": "EVGU8765432" }
        ],
        "supporting_documents": [
          {
            "type": "N380",
            "id": "INV-2026-EXP-0099",
            "line": 2,
            "expiry_date": null,
            "value": 8000.00,
            "currency": "EUR",
            "quantity": null,
            "uom": null
          }
        ],
        "additional_references": [],
        "previous_documents": [],
        "sku_details": []
      }
    ]
  }
}

Field Reference

Top-Level Fields

Field	Required	Type	Max	Description
`dms_version`	Yes	string	—	DMS version: `4.0` or `4.1`.
`reference`	No	string	255	Your internal reference. Auto-generated if omitted.
`application_reference`	No	string	50	Application-level tracking reference.
`submit_when_valid`	No	boolean	—	If `true`, automatically submits to customs when validation passes. Default: `false`.
`representation_type`	No	string	—	`2` = Direct representation, `3` = Indirect representation. Default: `2`.

`declaration` — Header Fields

Field	Required	Type	Allowed values / Max	Description
`office`	Yes	string	20	Customs office of lodgement (e.g. `NL000012`).
`exit_office`	No	string	20	Office of exit. Export only.
`language`	No	string	`NL` `EN` `DE` `PL`	Declaration language.
`imex`	No	string	`IM` `EX`	Direction: `IM` for import (default), `EX` for export.
`symbol`	No	string	`A` `B` `C` `D` `E` `F` `Z`	Declaration variant — see Declaration Variants. Defaults to `A`.
`procedure.current`	Yes	string	2	Current procedure code (e.g. `40`, `10`).
`procedure.previous`	Yes	string	2	Previous procedure code (e.g. `00`, `71`).
`procedure.special`	No	string	3	Special procedure code (e.g. `F01`).
`transaction_nature`	No	integer	—	Nature of transaction code (e.g. `11` = outright purchase/sale).
`total_packages`	No	integer	—	Total number of packages in the shipment.
`total_invoice_value`	No	number	—	Total invoice value. Overrides the sum of line values.
`total_invoice_currency`	No	string	3	ISO 4217 currency code (e.g. `EUR`, `USD`).
`destination_country`	No	string	2	ISO country code of final destination. Export only.
`export_country`	No	string	2	ISO country code goods are dispatched from. Export only.

Declaration Variants

`symbol`	Variant	Description
`A`	Standard	Single-step: submit → accepted → released.
`B`	Incomplete — incidental	Submit incomplete → accepted → send supplementary within 1 month.
`C`	Incomplete — regular (authorised)	As `B`, under standing authorisation.
`D`	Advance (pre-lodged)	Submit before goods arrive → send advance notification on arrival.
`E`	Incomplete advance — incidental	Advance notification required before supplementary can be sent.
`F`	Incomplete advance — regular (authorised)	As `E`, under standing authorisation.
`Z`	IIAA (Entry in Declarant’s Records)	DMS 4.1 only. Entry registered in declarant’s own records.

Variants B through F require follow-up calls after initial submission. See the Declaration Lifecycle API.

Party Blocks

Each party block supports a customer_code shorthand. When provided, Borderbolt looks up the party details from the Customer Master. Explicit fields always override Customer Master values.

Import uses importer, exporter, buyer, seller. Export uses consignor, consignee, buyer, seller.

Field	Required	Type	Max	Description
`customer_code`	No	string	100	Customer Master code. Hydrates name, address, and EORI automatically.
`eori`	No	string	20	EORI number (e.g. `NL123456789B01`).
`name`	No*	string	255	Party name. *Required if `customer_code` is not provided.
`address.street`	No	string	255	Street address.
`address.city`	No	string	100	City.
`address.postal_code`	No	string	20	Postal/ZIP code.
`address.country`	No	string	2	ISO country code.

Import party roles:

Block	Customs role	Commercial role
`importer`	Customs declarant / importer of record	—
`exporter`	Foreign supplier	—
`buyer`	—	Commercial buyer (Box 8)
`seller`	—	Commercial seller (Box 2)

Export party roles:

Block	Customs role	Commercial role
`consignor`	Exporter of record (must have EORI)	—
`consignee`	Foreign receiver	—
`seller`	—	Commercial seller (Box 2)
`buyer`	—	Commercial buyer (Box 8)

buyer and seller are the commercial transaction parties (SAD boxes 2 and 8). They are separate from the customs importer/consignor and exporter/consignee. If the commercial and customs parties are the same entity, you can use customer_code on both blocks to avoid duplication.

`transport`

The border block describes the active means of transport at the EU external border — the sea vessel, aircraft, or train. Used for both import and export.

The departure block describes the inland means of transport:

Import: the truck or vehicle that collects the goods from the port/airport and delivers them inland (“Vervoermiddel bij aankomst”).
Export: the truck or vehicle that moves the goods from the premises to the port or airport of exit.

Field	Required	Type	Max	Description
`transport.border.mode`	No	string	2	Transport mode at the EU border: `1`=Sea, `2`=Rail, `3`=Road, `4`=Air, `7`=Pipeline, `9`=Own propulsion.
`transport.border.nationality`	No	string	2	ISO country code of the flag/registration of the means of transport at the border.
`transport.border.identification`	No	string	35	Vessel name, flight number, vehicle registration, etc.
`transport.border.identification_type`	No	string	2	`10`=IMO ship no., `11`=Vehicle reg., `20`=IATA flight no., `30`=Rail car no., `41`=Container no., `80`=EORI, `99`=Unknown.
`transport.departure.mode`	No	string	2	Inland transport mode. Import: arrival truck at port. Export: departure truck to port. Same values as border mode.
`transport.departure.nationality`	No	string	2	Nationality of the inland means of transport.
`transport.departure.identification`	No	string	35	Identification of the inland means of transport (e.g. truck licence plate).
`transport.departure.identification_type`	No	string	2	Type code for the inland transport identification.
`transport.containers`	No	array	—	Containers at header level. If only one container is provided, it is automatically assigned to all lines.
`transport.containers[].number`	Yes*	string	17	Container number (e.g. `MSCU1234567`). *Required per container entry.
`transport.containers[].seals`	No	array	—	List of seal numbers (strings, max 20 chars each).

`goods_location`

Field	Required	Type	Max	Description
`goods_location.type`	No	string	1	Location type: `A`=Designated location, `B`=Authorised place, `C`=Approved place, `D`=Other.
`goods_location.identification_type`	No	string	1	Identification qualifier: `U`=UN/LOCODE, `Y`=Authorisation no., `Z`=Free text.
`goods_location.country`	No	string	2	ISO country code.
`goods_location.postal_code`	No	string	20	Postal code of the goods location.
`goods_location.city`	No	string	100	City of the goods location.
`goods_location.address`	No	string	255	Street address of the goods location.
`goods_location.house_number`	No	string	20	House/building number.

`incoterms`

Field	Required	Type	Max	Description
`incoterms.code`	No	string	3	Incoterms code: `EXW`, `FCA`, `FAS`, `FOB`, `CFR`, `CIF`, `CPT`, `CIP`, `DAP`, `DPU`, `DDP`.
`incoterms.country`	No	string	2	ISO country code of the delivery point.
`incoterms.location`	No	string	35	Named place of delivery (e.g. `Rotterdam`).

`authorizations`

Customs authorisations held by the declarant that apply to this declaration (e.g. CGU for comprehensive guarantee, CWP for customs warehouse, C506 for deferred payment, C521 for chain procedure).

Field	Required	Type	Max	Description
`authorizations[].type_code`	Yes*	string	4	Authorisation type code (e.g. `CGU`, `CWP`, `C506`, `C521`). *Required per entry.
`authorizations[].id`	Yes*	string	35	Authorisation reference number (decision reference). *Required per entry.
`authorizations[].holder_id`	No	string	35	EORI of the authorisation holder if different from the declarant.

`applyChainProcedure` / `daysDelayBeforeSubmit`

Top-level fields (not inside declaration) that control the Ketenregeling (chain procedure) settings for EIDR declarations.

Field	Required	Type	Description
`applyChainProcedure`	No	boolean	Set to `true` to apply the chain procedure (Ketenregeling). Requires a `C521` authorisation.
`daysDelayBeforeSubmit`	No	integer	Number of days delay before the supplementary declaration is submitted. Default: `0`.

`warehouse`

Field	Required	Type	Max	Description
`warehouse.licence`	No	string	35	Customs warehouse licence number. Required for procedures involving warehousing (e.g. `71 00`, `78 71`).
`warehouse.licence_type`	No	string	1	Warehouse type code (e.g. `U` for public warehouse, `R` for private).

`domestic_duty_tax_party`

Import only. Not applicable for export declarations.

The party responsible for payment of import duties when different from the importer — for example, a fiscal representative acting on behalf of a non-EU importer.

Field	Required	Type	Description
`domestic_duty_tax_party.id`	No	string	EORI or identifier of the duty tax party.
`domestic_duty_tax_party.role`	No	string	Role code (e.g. `FR` for fiscal representative).

Item Fields

Field	Required	Type	Max	Description
`sequence`	No	integer	—	Line sequence number. Auto-incremented if omitted.
`description`	Yes	string	500	Goods description.
`sku`	No	string	100	Your internal article/SKU code.
`hs_code`	Yes	string	8	8-digit Harmonized System (GN/CN) code (e.g. `85371099`).
`taric_subheading`	No	string	2	2-digit TARIC subheading appended after the 8-digit HS code (e.g. `00`).
`additional_taric1`	No	string	4	First additional TARIC code (e.g. `4099`).
`additional_taric2`	No	string	4	Second additional TARIC code.
`country_of_origin`	Yes (import)	string	2	ISO country code of origin.
`preferential_country_of_origin`	No	string	2	ISO country code when claiming preferential origin.
`gross_weight`	Yes	number	—	Gross weight in kg.
`net_weight`	Yes	number	—	Net weight in kg.
`supplementary_quantity`	No	number	—	Quantity in supplementary units (required for certain HS codes).
`invoice_value`	Yes (import)	number	—	Invoice value for this line.
`invoice_currency`	No	string	3	ISO 4217 currency. Defaults to header currency.
`statistical_value`	No	number	—	Statistical (CIF) value at NL border. Defaults to `invoice_value`.
`previous_code`	No	string	2	Previous procedure code at line level (e.g. `00`).
`duty_regime`	No	string	3	Tax calculation regime code (e.g. `100`).
`valuation.method`	No	string	1	WTO customs valuation method: `1`=Transaction value, `2`=Identical goods, `3`=Similar goods, `4`=Deductive, `5`=Computed, `6`=Fall-back.
`valuation.charge_deductions`	No	array	—	List of valuation adjustments (additions/deductions to customs value).
`valuation.charge_deductions[].code`	Yes*	string	2	Adjustment type code (e.g. `AK`=freight, `AH`=insurance). *Required per entry.
`valuation.charge_deductions[].currency`	No	string	3	ISO 4217 currency of the adjustment amount.
`valuation.charge_deductions[].amount`	No	number	—	Adjustment amount.

Item — `packaging`

Field	Required	Type	Max	Description
`type`	No	string	2	Package type code (e.g. `CT`=Carton, `BX`=Box, `CR`=Crate, `PL`=Pallet). Also accepted: `soort`.
`quantity`	No	integer	—	Number of packages. Also accepted: `aantal`.
`marks`	No	string	512	Shipping marks and numbers. Also accepted: `merk`.

Item — `containers`

Line-level container assignment. If the header has exactly one container, it is automatically assigned to all lines — you can omit this field.

Field	Required	Type	Max	Description
`containers[].number`	Yes*	string	17	Container number. *Required per entry.

Item — `supporting_documents`

Supporting documents (N-codes, C-codes) associated with the declaration line.

Field	Required	Type	Max	Description
`type`	Yes	string	5	Document type code (e.g. `N271`=Commercial invoice, `N705`=Bill of lading, `N380`=Commercial invoice export, `N703`=Packing list, `N935`=Export accompanying document, `C644`=Certificate).
`id`	No	string	70	Document reference number. Also accepted: `reference`.
`line`	No	integer	—	Line number within the referenced document. Also accepted: `lineNumber`.
`expiry_date`	No	date	—	Document expiry date (`YYYY-MM-DD`). Used for licences and certificates. Also accepted: `expiryDate`.
`value`	No	number	—	Written-off value amount (amount consumed from a licence or quota).
`currency`	No	string	3	ISO 4217 currency for the written-off value.
`quantity`	No	number	—	Written-off quantity.
`uom`	No	string	5	Unit of measure for the written-off quantity (e.g. `KGM`, `NAR`, `LTR`). Also accepted: `unit_of_measure`.

Item — `additional_references`

Y-codes and Z-codes referencing licences, guarantees, or other authorisations.

Field	Required	Type	Max	Description
`type`	Yes	string	4	Reference type code (e.g. `Y900`=Licence, `GRN`=Guarantee reference).
`value`	No	string	70	Reference number or identifier.

Item — `previous_documents`

Prior customs documents that this declaration draws from (e.g. a preceding T1 transit, customs warehouse entry, or previous MRN).

Field	Required	Type	Max	Description
`type`	Yes	string	4	Document type code (e.g. `355`=MRN, `720`=T1, `740`=T2, `825`=Summary declaration, `NCLE`=Warehouse entry).
`id`	No	string	70	Reference number of the previous document.
`line`	No	integer	—	Line number within the previous document.

Item — `sku_details` (Mode B)

Per-SKU breakdown within a single declaration line. Use this when one customs line covers multiple SKUs that need to be tracked individually.

Field	Required	Type	Max	Description
`sku`	Yes	string	100	SKU / article code.
`description`	No	string	500	SKU description.
`quantity`	Yes	integer	—	Number of units of this SKU.
`unit_value`	No	number	—	Value per unit.
`unit_value_currency`	No	string	3	ISO 4217 currency. Defaults to `EUR`.
`unit_gross_weight`	No	number	—	Gross weight per unit in kg.
`unit_net_weight`	No	number	—	Net weight per unit in kg.
`country_of_origin`	No	string	2	ISO country code of origin for this SKU.

SKU Consolidation (Mode A)

Instead of specifying items manually, you can pass a list of SKU codes from the Item Master. Borderbolt resolves all customs details (HS code, description, origin, weights, values) automatically.


{
  "reference": "IMP-2026-00125",
  "declaration": {
    "office": "NL000012",
    "imex": "IM",
    "procedure": { "current": "40", "previous": "00" },
    "importer": { "customer_code": "ACME-NL" },
    "skus": [
      { "sku": "ECU-PRG-001", "quantity": 150 },
      { "sku": "CBL-AUTO-022", "quantity": 48 }
    ]
  }
}

When skus is provided, the items array is not required.

Response

Created (HTTP 201)


{
  "success": true,
  "declaration": {
    "id": 12347,
    "reference": "IMP-2026-00124",
    "application_reference": "APP-IMP-00124",
    "status": "DRF",
    "workflow": "import",
    "declaration_type": "H1",
    "mrn": null,
    "validation": {
      "valid": true,
      "errors": []
    },
    "submitted": false,
    "created_at": "2026-05-04T09:15:00.000000Z"
  }
}

When submit_when_valid: true and validation passes, status becomes NEW and submitted is true:


{
  "success": true,
  "declaration": {
    "id": 12347,
    "reference": "IMP-2026-00124",
    "status": "NEW",
    "submitted": true,
    "submitted_at": "2026-05-04T09:15:01.000000Z",
    "mrn": null,
    "validation": {
      "valid": true,
      "errors": []
    },
    "created_at": "2026-05-04T09:15:00.000000Z"
  }
}

The MRN is assigned by Dutch Customs after acceptance and delivered via webhook. See Webhooks.

Validation Errors (HTTP 422)


{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Request validation failed"
  },
  "validation": {
    "valid": false,
    "errors": [
      {
        "field": "declaration.office",
        "message": "The declaration.office field is required.",
        "rule": "REQUEST_VALIDATION"
      },
      {
        "field": "declaration.items.0.hs_code",
        "message": "The declaration.items.0.hs_code field is required.",
        "rule": "REQUEST_VALIDATION"
      },
      {
        "field": "declaration.items.0.country_of_origin",
        "message": "The declaration.items.0.country_of_origin must be 2 characters.",
        "rule": "REQUEST_VALIDATION"
      }
    ]
  }
}

Validate Without Saving

Use the validate endpoint to check a payload without creating a declaration or submitting to customs:


POST /api/v1/declarations/validate

Same request body as /declarations/submit. Response:


{
  "valid": true,
  "errors": []
}

Or when invalid:


{
  "valid": false,
  "errors": [
    {
      "field": "declaration.procedure.current",
      "message": "The declaration.procedure.current field is required.",
      "rule": "REQUEST_VALIDATION"
    }
  ]
}

Next Steps

Declaration Lifecycle API — Submit, invalidate, supplement, and advance notifications
Declarations API — Read and update existing declarations
Item Master API — Manage your SKU catalogue for Mode A consolidation
Webhooks — Receive real-time status updates (MRN assignment, acceptance, release)