Declaration Lifecycle API

The Declaration Lifecycle API provides endpoints for managing declarations throughout their lifecycle: submission, XML generation, invalidation, control responses, and status management.

Required Scope: declarations:submit (for submission actions), declarations:write (for lifecycle management)

Submit to Customs

Submit a validated declaration to customs authorities.


curl -X POST "https://app.borderbolt.com/api/v1/declarations/12345/submit" \
  -H "Authorization: Bearer your-access-token" \
  -H "Accept: application/json"

Prerequisites: Declaration must be in DRF (draft) status and pass all validations.

Response


{
  "id": 12345,
  "reference": "IMP-2026-003",
  "status": "NEW",
  "submitted_at": "2026-03-25T15:30:00.000000Z",
  "message": "Declaration submitted successfully to customs"
}

Send Advance Notification

Send the advance notification for an advance declaration (variants D, E, F) after the goods have physically arrived at the declared location. Dutch Customs processes the declaration as if it had just been submitted.

This endpoint is also used for warehouse entry declarations with chain procedures enabled.


curl -X POST "https://app.borderbolt.com/api/v1/declarations/12345/send-presentation" \
  -H "Authorization: Bearer your-access-token" \
  -H "Accept: application/json"

Prerequisites: Declaration must be accepted and the advance notification must not have been sent yet. Only applies to variants D, E, and F.

Warehouse Operations: For warehouse entry with chain procedures, see Warehouse & Chain Procedures.

Response


{
  "success": true,
  "id": 12345,
  "reference": "IMP-2026-003",
  "presentation_sent_at": "2026-03-25T15:45:00.000000Z",
  "message": "Advance notification sent to Dutch Customs"
}

Errors

HTTP Status	Error	Description
422	`invalid_variant`	Declaration is not an advance variant (`D`, `E`, `F`)
422	`not_accepted`	Declaration has not been accepted by Dutch Customs yet
422	`already_sent`	Advance notification has already been sent for this declaration

Send Supplementary Declaration

Send the supplementary declaration for an incomplete declaration (variants B, C, E, F). Must be sent within one month of acceptance.


curl -X POST "https://app.borderbolt.com/api/v1/declarations/12345/send-supplementary" \
  -H "Authorization: Bearer your-access-token" \
  -H "Accept: application/json"

Prerequisites: Declaration must be accepted. For variants E and F, the advance notification must have been accepted by Dutch Customs before the supplementary declaration can be sent.

Response


{
  "success": true,
  "id": 12345,
  "reference": "IMP-2026-003",
  "supplementary_sent_at": "2026-03-25T16:00:00.000000Z",
  "additional_declaration_type": "Y",
  "message": "Supplementary declaration sent to Dutch Customs"
}

The additional_declaration_type field indicates which supplementary type was sent:

X — Supplementary for an incomplete declaration (B, C)
Y — Supplementary for an incomplete advance declaration (E, F)

Errors

HTTP Status	Error	Description
422	`invalid_variant`	Declaration is not an incomplete variant (`B`, `C`, `E`, `F`)
422	`not_accepted`	Declaration has not been accepted by Dutch Customs yet
422	`advance_notification_pending`	Advance notification must be accepted first (variants `E`, `F`)
422	`already_sent`	Supplementary declaration has already been sent
422	`deadline_passed`	One-month deadline has passed; contact Dutch Customs directly

Generate XML

Generate customs XML without submitting the declaration.


curl -X POST "https://app.borderbolt.com/api/v1/declarations/12345/generate-xml" \
  -H "Authorization: Bearer your-access-token" \
  -H "Accept: application/json"

Response


{
  "xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Declaration>...</Declaration>",
  "format": "IE315A",
  "generated_at": "2026-03-25T15:35:00.000000Z"
}

Preview XML

Get an HTML-formatted preview of the customs XML.


curl -X GET "https://app.borderbolt.com/api/v1/declarations/12345/xml-preview" \
  -H "Authorization: Bearer your-access-token" \
  -H "Accept: text/html"

Returns syntax-highlighted XML in an HTML response.

Request Invalidation

Request invalidation of an accepted declaration.


curl -X POST "https://app.borderbolt.com/api/v1/declarations/12345/invalidate" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "reason": "Incorrect consignee details",
    "justification": "Customer provided updated information after submission"
  }'

Request Body

Field	Required	Type	Description
`reason`	Yes	string	Invalidation reason
`justification`	No	string	Additional justification details

Response


{
  "id": 12345,
  "status": "INV_PENDING",
  "invalidation_requested_at": "2026-03-25T16:00:00.000000Z",
  "message": "Invalidation request submitted to customs"
}

Respond to Control

Submit a response to a customs control notification.


curl -X POST "https://app.borderbolt.com/api/v1/declarations/12345/control-response" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "response_type": "document_provided",
    "documents": [
      {
        "type": "certificate_of_origin",
        "reference": "COO-2026-12345",
        "notes": "Original certificate attached"
      }
    ],
    "remarks": "All requested documents provided"
  }'

Request Body

Field	Required	Type	Description
`response_type`	Yes	string	`document_provided`, `goods_presented`, `remarks_only`
`documents`	No	array	Supporting documents
`remarks`	No	string	Additional remarks for customs

Alternative Proof of Export (APE)

Submit alternative proof of export for released goods.


curl -X POST "https://app.borderbolt.com/api/v1/declarations/12345/ape" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "proof_type": "cmr",
    "reference": "CMR-2026-001",
    "exit_date": "2026-03-25",
    "exit_office": "NLRTM",
    "notes": "Goods crossed border at Rotterdam"
  }'

Request Body

Field	Required	Type	Description
`proof_type`	Yes	string	`cmr`, `bill_of_lading`, `airway_bill`, `other`
`reference`	Yes	string	Document reference number
`exit_date`	Yes	date	Date goods left customs territory (YYYY-MM-DD)
`exit_office`	Yes	string	Exit customs office
`notes`	No	string	Additional notes

Duty Estimate

Calculate estimated import duties and taxes for a declaration.


curl -X GET "https://app.borderbolt.com/api/v1/declarations/12345/duty-estimate" \
  -H "Authorization: Bearer your-access-token" \
  -H "Accept: application/json"

Response


{
  "declaration_id": 12345,
  "currency": "EUR",
  "total_invoice_value": 15000.00,
  "total_customs_value": 15750.00,
  "duties": [
    {
      "type": "customs_duty",
      "rate": "3.5%",
      "base": 15750.00,
      "amount": 551.25
    },
    {
      "type": "vat",
      "rate": "21%",
      "base": 16301.25,
      "amount": 3423.26
    }
  ],
  "total_duties": 3974.51,
  "total_payable": 19724.51,
  "calculated_at": "2026-03-25T16:15:00.000000Z",
  "disclaimer": "Estimated duties for reference only. Final duties determined by customs."
}

Estimates Only: Duty calculations are estimates based on declared values and standard rates. Final duties are determined by customs authorities.

Mark as Verified

Mark a declaration as manually verified by the customs broker.


curl -X POST "https://app.borderbolt.com/api/v1/declarations/12345/mark-verified" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "verified_by": "John Doe",
    "verification_notes": "All documents checked and validated"
  }'

Set Manual Status

Override declaration status manually (admin function).


curl -X POST "https://app.borderbolt.com/api/v1/declarations/12345/set-status" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "status": "REL",
    "reason": "Manual release after phone approval from customs",
    "notes": "Officer badge #12345, phone approval at 16:30"
  }'

Use with Caution: Manual status changes should only be used in exceptional cases and with proper authorization.

View Timeline

Get a complete event timeline for a declaration.


curl -X GET "https://app.borderbolt.com/api/v1/declarations/12345/timeline" \
  -H "Authorization: Bearer your-access-token" \
  -H "Accept: application/json"

Response


{
  "declaration_id": 12345,
  "reference": "IMP-2026-003",
  "events": [
    {
      "event": "created",
      "status": "DRF",
      "timestamp": "2026-03-25T10:00:00.000000Z",
      "user": "API Client",
      "details": "Declaration created via API"
    },
    {
      "event": "submitted",
      "status": "NEW",
      "timestamp": "2026-03-25T15:30:00.000000Z",
      "user": "API Client",
      "details": "Submitted to customs"
    },
    {
      "event": "accepted",
      "status": "ACC",
      "timestamp": "2026-03-25T15:32:15.000000Z",
      "user": "Customs",
      "details": "Declaration accepted",
      "mrn": "26NL123456789012345"
    },
    {
      "event": "released",
      "status": "REL",
      "timestamp": "2026-03-25T16:00:00.000000Z",
      "user": "Customs",
      "details": "Goods released for free circulation"
    }
  ]
}

Copy Declaration

Create a copy of an existing declaration.


curl -X POST "https://app.borderbolt.com/api/v1/declarations/12345/copy" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "reference": "IMP-2026-004",
    "copy_lines": true,
    "reset_status": true
  }'

Request Body

Field	Required	Type	Description
`reference`	No	string	New reference (auto-generated if omitted)
`copy_lines`	No	boolean	Copy declaration lines (default: true)
`reset_status`	No	boolean	Reset to draft status (default: true)

Response


{
  "id": 12348,
  "reference": "IMP-2026-004",
  "status": "DRF",
  "copied_from": 12345,
  "created_at": "2026-03-25T16:30:00.000000Z"
}

Distribute Transport Costs

Distribute transport costs across declaration lines proportionally.


curl -X POST "https://app.borderbolt.com/api/v1/declarations/12345/distribute-transport-costs" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "total_transport_cost": 500.00,
    "distribution_method": "by_value"
  }'

Request Body

Field	Required	Type	Description
`total_transport_cost`	Yes	number	Total transport cost to distribute
`distribution_method`	No	string	`by_value` (default), `by_weight`, `equal`

Save as Draft

Convert a submitted declaration back to draft status (if allowed by customs).


curl -X POST "https://app.borderbolt.com/api/v1/declarations/12345/save-as-draft" \
  -H "Authorization: Bearer your-access-token" \
  -H "Accept: application/json"

Pre-Submission Overview

Get a summary of the declaration before submission for final review.


curl -X GET "https://app.borderbolt.com/api/v1/declarations/12345/submit-overview" \
  -H "Authorization: Bearer your-access-token" \
  -H "Accept: application/json"

Response


{
  "declaration_id": 12345,
  "reference": "IMP-2026-003",
  "validation": {
    "valid": true,
    "errors": []
  },
  "summary": {
    "total_items": 3,
    "total_gross_mass": 1250.50,
    "total_invoice_value": 15000.00,
    "currency": "EUR",
    "estimated_duties": 3974.51
  },
  "warnings": [
    "Line 2: High-value item may trigger control"
  ],
  "ready_to_submit": true
}

Next Steps

Declarations API - CRUD operations
Declaration Submit API - Create and validate declarations
Warehouse & Chain Procedures - Warehouse operations and chain procedures
Webhooks - Receive status updates