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
  }'

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