Reports API

The Reports API provides access to saved reports with filtering, pagination, and CSV export capabilities.

Required Scope: reports:read, reports:export

List Saved Reports

Retrieve all available saved reports.


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

Response


{
  "data": [
    {
      "id": "dms-import",
      "name": "Import Declarations",
      "description": "All import declarations submitted to customs",
      "type": "declaration",
      "default_columns": [
        "reference",
        "mrn",
        "status",
        "customer_name",
        "consignee_name",
        "total_invoice_value",
        "submitted_at"
      ]
    },
    {
      "id": "dms-export",
      "name": "Export Declarations",
      "description": "All export declarations submitted to customs",
      "type": "declaration",
      "default_columns": [
        "reference",
        "mrn",
        "status",
        "customer_name",
        "consignor_name",
        "destination_country",
        "submitted_at"
      ]
    },
    {
      "id": "dva-departure",
      "name": "DVA Transit Departures",
      "description": "All transit departure declarations (T1/T2)",
      "type": "transit",
      "default_columns": [
        "lrn",
        "mrn",
        "status",
        "customer_name",
        "office_of_destination",
        "guarantee_reference",
        "submitted_at"
      ]
    },
    {
      "id": "dva-arrival",
      "name": "DVA Transit Arrivals",
      "description": "All transit arrival notifications",
      "type": "transit",
      "default_columns": [
        "lrn",
        "mrn",
        "status",
        "office_of_destination",
        "arrival_date"
      ]
    }
  ]
}

Run Report

Execute a saved report with filters and pagination.


curl -X POST "https://app.borderbolt.com/api/v1/reports/dms-import/run" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "filters": {
      "date_from": "2026-03-01",
      "date_to": "2026-03-07",
      "status": "REL",
      "customer_code": "CUST001"
    },
    "page": 1,
    "per_page": 50
  }'

Request Body

Field	Required	Type	Description
`filters`	Yes	object	Report filters (see below)
`page`	No	integer	Page number (default: 1)
`per_page`	No	integer	Results per page (default: 25, max: 100)

Common Filters

Filter	Type	Description
`date_from`	date	Start date (YYYY-MM-DD) - required
`date_to`	date	End date (YYYY-MM-DD) - required
`status`	string	Filter by status (ACC, REL, etc.)
`customer_code`	string	Filter by customer code
`mrn`	string	Filter by MRN
`reference`	string	Filter by reference/LRN

Date Range Limit: Maximum 7 days per request to ensure performance. For longer periods, make multiple requests.

Response


{
  "report_id": "dms-import",
  "report_name": "Import Declarations",
  "filters": {
    "date_from": "2026-03-01",
    "date_to": "2026-03-07",
    "status": "REL",
    "customer_code": "CUST001"
  },
  "data": [
    {
      "id": 12345,
      "reference": "IMP-2026-001",
      "mrn": "26NL123456789012345",
      "status": "REL",
      "customer_code": "CUST001",
      "customer_name": "Example B.V.",
      "consignee_name": "Example B.V.",
      "total_invoice_value": 15000.00,
      "currency": "EUR",
      "submitted_at": "2026-03-25T11:00:00.000000Z",
      "released_at": "2026-03-25T16:00:00.000000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 50,
    "total": 120
  }
}

Export Report as CSV

Export a report to CSV format.


curl -X POST "https://app.borderbolt.com/api/v1/reports/dms-import/export" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: text/csv" \
  -d '{
    "filters": {
      "date_from": "2026-03-01",
      "date_to": "2026-03-07"
    },
    "format": "csv"
  }' \
  --output dms-import-2026-03.csv

Required Scope: reports:export

Request Body

Field	Required	Type	Description
`filters`	Yes	object	Same filters as “Run Report”
`format`	No	string	Export format: `csv` (default) or `json`

CSV Format

Delimiter: Semicolon (;)
Encoding: UTF-8 with BOM
Headers: Column names in first row
Date format: ISO 8601 (YYYY-MM-DD HH:MM:SS)

Example CSV:


Reference;MRN;Status;Customer Code;Customer Name;Invoice Value;Currency;Submitted At
IMP-2026-001;26NL123456789012345;REL;CUST001;Example B.V.;15000.00;EUR;2026-03-25 11:00:00
IMP-2026-002;26NL123456789012346;REL;CUST001;Example B.V.;8500.00;EUR;2026-03-26 09:30:00

Export as JSON

Export a report as JSON (no pagination).


curl -X POST "https://app.borderbolt.com/api/v1/reports/dms-import/export" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "filters": {
      "date_from": "2026-03-01",
      "date_to": "2026-03-07"
    },
    "format": "json"
  }' \
  --output dms-import-2026-03.json

Returns all matching records as a JSON array (no pagination, up to 10,000 records).

Default Reports

Import Declarations

ID: dms-import

All import declarations submitted to customs.

Columns:

reference - Internal reference/LRN
mrn - Movement Reference Number
status - Current status (NEW, ACC, REL, etc.)
declaration_type - Declaration type
customer_code - Customer code
customer_name - Customer name
consignee_name - Consignee name
consignee_eori - Consignee EORI
total_items - Number of line items
total_gross_mass - Total gross mass (kg)
total_invoice_value - Total invoice value
currency - Currency code
submitted_at - Submission timestamp
accepted_at - Acceptance timestamp
released_at - Release timestamp

Export Declarations

ID: dms-export

All export declarations submitted to customs.

Columns:

reference - Internal reference/LRN
mrn - Movement Reference Number
status - Current status
declaration_type - Declaration type
customer_code - Customer code
customer_name - Customer name
consignor_name - Consignor name (exporter)
consignor_eori - Consignor EORI
destination_country - Final destination country
total_items - Number of line items
total_gross_mass - Total gross mass (kg)
total_invoice_value - Total invoice value
currency - Currency code
submitted_at - Submission timestamp
accepted_at - Acceptance timestamp

DVA Transit Departures

ID: dva-departure

Transit departure declarations (T1/T2) submitted to DVA/NCTS5.

Columns:

lrn - Local Reference Number
mrn - Movement Reference Number
status - Current status
transit_type - T1, T2, T2F
customer_code - Customer code
customer_name - Customer name
office_of_departure - Departure customs office
office_of_destination - Destination customs office
guarantee_type - Guarantee type (0-9)
guarantee_reference - Guarantee reference/GRN
total_items - Number of items
total_gross_mass - Total gross mass (kg)
total_packages - Total number of packages
submitted_at - Submission timestamp
accepted_at - Acceptance timestamp (MRN assigned)

DVA Transit Arrivals

ID: dva-arrival

Transit arrival notifications submitted to DVA/NCTS5.

Columns:

lrn - Local Reference Number (from departure)
mrn - Movement Reference Number
status - Current status
office_of_destination - Destination customs office
arrival_date - Arrival date/time
unloading_remarks - Unloading remarks
submitted_at - Arrival submission timestamp

Performance Notes

Reports are optimized for 7-day date ranges
CSV exports include all records (no pagination)
JSON exports limited to 10,000 records
Large exports may take several seconds

Error Responses

Date Range Too Large


{
  "error": "validation_error",
  "error_description": "Date range exceeds maximum of 7 days",
  "errors": {
    "date_to": [
      "Date range must not exceed 7 days. Please use a shorter date range."
    ]
  }
}

HTTP Status: 422 Unprocessable Entity

Missing Required Dates


{
  "error": "validation_error",
  "error_description": "The given data was invalid.",
  "errors": {
    "filters.date_from": ["The date from field is required."],
    "filters.date_to": ["The date to field is required."]
  }
}

HTTP Status: 422 Unprocessable Entity

Next Steps

Declarations API - Declaration data source
Transit API - Transit data source
Error Reference - Error handling