Declarations API

The Declarations API provides CRUD operations for managing customs declarations (import, export, and simplified import).

Required Scope: declarations:read, declarations:write, declarations:delete

List Declarations

Retrieve a paginated list of declarations with optional filters.


curl -X GET "https://app.borderbolt.com/api/v1/declarations?status=ACC&page=1&per_page=25" \
  -H "Authorization: Bearer your-access-token" \
  -H "Accept: application/json"

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status (NEW, ACC, REJ, REL, ERR, etc.)
`workflow`	string	Filter by workflow (import, export, transit)
`mrn`	string	Filter by Movement Reference Number
`reference`	string	Filter by internal reference/LRN
`customer_code`	string	Filter by customer code
`created_from`	date	Filter by creation date (from, format: YYYY-MM-DD)
`created_to`	date	Filter by creation date (to, format: YYYY-MM-DD)
`page`	integer	Page number (default: 1)
`per_page`	integer	Results per page (default: 25, max: 100)

Response


{
  "data": [
    {
      "id": 12345,
      "reference": "IMP-2026-001",
      "mrn": "26NL123456789012345",
      "status": "ACC",
      "workflow": "import",
      "declaration_type": "H1",
      "customer_code": "CUST001",
      "customer_name": "Example B.V.",
      "total_items": 3,
      "total_gross_mass": 1250.50,
      "total_invoice_value": 15000.00,
      "currency": "EUR",
      "office_of_lodgement": "NL000396",
      "created_at": "2026-03-25T10:30:00.000000Z",
      "updated_at": "2026-03-25T11:45:00.000000Z",
      "submitted_at": "2026-03-25T11:00:00.000000Z"
    }
  ],
  "links": {
    "first": "https://app.borderbolt.com/api/v1/declarations?page=1",
    "last": "https://app.borderbolt.com/api/v1/declarations?page=10",
    "prev": null,
    "next": "https://app.borderbolt.com/api/v1/declarations?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 10,
    "per_page": 25,
    "to": 25,
    "total": 250
  }
}

Get Single Declaration

Retrieve a single declaration with all its lines.


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

Response


{
  "id": 12345,
  "reference": "IMP-2026-001",
  "mrn": "26NL123456789012345",
  "status": "ACC",
  "workflow": "import",
  "declaration_type": "H1",
  "representation_type": "2",
  "customer_code": "CUST001",
  "customer_name": "Example B.V.",
  "consignor": {
    "name": "Foreign Supplier Inc",
    "address": "123 Main St",
    "city": "New York",
    "postal_code": "10001",
    "country": "US",
    "eori": null
  },
  "consignee": {
    "name": "Example B.V.",
    "address": "Hoofdstraat 1",
    "city": "Amsterdam",
    "postal_code": "1012AB",
    "country": "NL",
    "eori": "NL123456789012"
  },
  "office_of_lodgement": "NL000396",
  "goods_location": "NLAMS",
  "transport_mode": "3",
  "transport_nationality": "NL",
  "incoterms": "CIF",
  "total_items": 3,
  "total_gross_mass": 1250.50,
  "total_invoice_value": 15000.00,
  "currency": "EUR",
  "created_at": "2026-03-25T10:30:00.000000Z",
  "updated_at": "2026-03-25T11:45:00.000000Z",
  "submitted_at": "2026-03-25T11:00:00.000000Z",
  "lines": [
    {
      "id": 1001,
      "item_number": 1,
      "description": "Electronic Components",
      "hs_code": "85423190",
      "origin_country": "CN",
      "quantity": 500,
      "gross_mass": 450.00,
      "net_mass": 420.00,
      "invoice_value": 5000.00,
      "statistical_value": 5200.00,
      "procedure": "4000",
      "previous_procedure": null,
      "quota_number": null,
      "preference_code": "100",
      "created_at": "2026-03-25T10:35:00.000000Z",
      "updated_at": "2026-03-25T10:35:00.000000Z"
    }
  ]
}

Create Declaration

Create a new declaration in draft status.


curl -X POST "https://app.borderbolt.com/api/v1/declarations" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "reference": "IMP-2026-002",
    "workflow": "import",
    "declaration_type": "H1",
    "representation_type": "2",
    "customer_code": "CUST001",
    "office_of_lodgement": "NL000396",
    "goods_location": "NLAMS",
    "transport_mode": "3",
    "transport_nationality": "NL",
    "incoterms": "CIF",
    "currency": "EUR",
    "consignor": {
      "name": "Foreign Supplier Inc",
      "address": "123 Main St",
      "city": "New York",
      "postal_code": "10001",
      "country": "US"
    },
    "consignee": {
      "name": "Example B.V.",
      "address": "Hoofdstraat 1",
      "city": "Amsterdam",
      "postal_code": "1012AB",
      "country": "NL",
      "eori": "NL123456789012"
    }
  }'

Request Body

Field	Required	Type	Description
`reference`	No	string	Internal reference/LRN (auto-generated if omitted)
`workflow`	Yes	string	`import`, `export`, or `transit`
`declaration_type`	Yes	string	Import, export, or simplified import type
`representation_type`	No	string	2 (direct), 3 (indirect) - default: 2
`customer_code`	Yes	string	Customer code from customer master
`office_of_lodgement`	Yes	string	Customs office code (e.g., NL000396)
`goods_location`	Yes	string	Goods location code (e.g., NLAMS)
`transport_mode`	No	string	1=Sea, 2=Rail, 3=Road, 4=Air, 5=Mail, 7=Fixed, 8=Inland waterway
`transport_nationality`	No	string	ISO country code
`incoterms`	No	string	Incoterms code (CIF, FOB, etc.)
`currency`	Yes	string	ISO currency code (EUR, USD, etc.)
`consignor`	Yes	object	Consignor details (name, address, city, postal_code, country)
`consignee`	Yes	object	Consignee details (name, address, city, postal_code, country, eori)

Response

Returns the created declaration with status: "DRF" (draft).


{
  "id": 12346,
  "reference": "IMP-2026-002",
  "status": "DRF",
  "workflow": "import",
  "declaration_type": "H1",
  "created_at": "2026-03-25T14:00:00.000000Z"
}

Update Declaration

Update an existing declaration. Only declarations with status DRF (draft) or ERR (error) can be updated.


curl -X PUT "https://app.borderbolt.com/api/v1/declarations/12346" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "reference": "IMP-2026-002-UPDATED",
    "goods_location": "NLRTM"
  }'

Status Restriction: Only draft (DRF) or error (ERR) declarations can be updated. Submitted declarations cannot be modified.

Delete Declaration

Delete a draft declaration. Only declarations with status DRF can be deleted.


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

Required Scope: declarations:delete

Response:


{
  "message": "Declaration deleted successfully"
}

Declaration Lines

List Lines

Retrieve all lines for a declaration.


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

Get Single Line


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

Add Line

Add a new line to a declaration.


curl -X POST "https://app.borderbolt.com/api/v1/declarations/12345/lines" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "description": "Electronic Components",
    "hs_code": "85423190",
    "origin_country": "CN",
    "quantity": 500,
    "gross_mass": 450.00,
    "net_mass": 420.00,
    "invoice_value": 5000.00,
    "statistical_value": 5200.00,
    "procedure": "4000",
    "preference_code": "100"
  }'

Update Line


curl -X PUT "https://app.borderbolt.com/api/v1/declarations/12345/lines/1001" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "quantity": 550,
    "invoice_value": 5500.00
  }'

Line authorisations

A line can carry its own authorisations, for example a binding tariff or origin decision, or a permit for goods with a special destination. Send them in the optional authorisations list when updating a line:


curl -X PUT "https://app.borderbolt.com/api/v1/declarations/12345/lines/1001" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "authorisations": [
      {
        "identification": "NLBTI2026000123",
        "type_code": "<authorisation type>",
        "sequence": 1
      }
    ]
  }'

Field	Type	Required	Description
`authorisations`	array	No	The line’s authorisations. Sending the list replaces the line’s existing authorisations; send an empty list (`[]`) to remove them all. Leave the field out to keep them unchanged.
`authorisations[].identification`	string (max 35)	Yes, per entry	The reference number of the decision or permit.
`authorisations[].type_code`	string (max 4)	No	The kind of authorisation, as the code used in the declaration line screen’s Authorisations section.
`authorisations[].sequence`	integer	No	The entry’s position in the list.

The line response (from the get and update line endpoints) includes the line’s authorisations. Like other line changes, authorisations can only be updated while the declaration can still be edited.

Delete Line


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

Duplicate Line

Create a copy of an existing line.


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

Response:


{
  "id": 1002,
  "item_number": 2,
  "description": "Electronic Components",
  "hs_code": "85423190",
  "created_at": "2026-03-25T14:30:00.000000Z"
}

Status Codes

Status	Description
`DRF`	Draft - not yet submitted
`NEW`	Submitted, awaiting customs response
`ACC`	Accepted by customs
`REJ`	Rejected by customs
`REL`	Released by customs
`HLD`	Held for control
`CTL`	Control notification received
`ERR`	Submission error
`INV`	Invalidated

Next Steps

Declaration Submit API - Submit declarations to customs
Declaration Lifecycle API - Manage declaration lifecycle events