Dossiers API

The Dossiers API provides full CRUD operations for managing customs dossiers, which group related declarations and transits, track purchase costs, and generate revenue for invoicing.

Required Scope: dossiers:read, dossiers:write, dossiers:delete

List Dossiers

Retrieve a paginated list of dossiers with optional filters.


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

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status (open, complete, invoiced, closed)
`customer_code`	string	Filter by customer code
`dossier_number`	string	Filter by dossier number (partial match)
`customer_reference`	string	Filter by customer reference (partial match)
`search`	string	Search across dossier number, AWB/BL numbers, customer reference
`created_from`	date	Filter by creation date (from, YYYY-MM-DD)
`created_to`	date	Filter by creation date (to, YYYY-MM-DD)
`page`	integer	Page number (default: 1)
`per_page`	integer	Results per page (default: 25, max: 100)

Response


{
  "data": [
    {
      "id": 3001,
      "reference": "DOS-2026-001",
      "customer_code": "CUST001",
      "customer_name": "Example B.V.",
      "status": "open",
      "total_declarations": 5,
      "total_transits": 2,
      "total_purchase_costs": 1250.00,
      "total_revenue": 2500.00,
      "margin": 1250.00,
      "margin_percentage": 50.00,
      "created_at": "2026-03-20T10:00:00.000000Z",
      "updated_at": "2026-03-25T14:30:00.000000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 45
  }
}

Get Single Dossier

Retrieve a single dossier with all linked items and costs.


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

Response


{
  "id": 3001,
  "reference": "DOS-2026-001",
  "customer_code": "CUST001",
  "customer_name": "Example B.V.",
  "status": "open",
  "description": "Monthly import declarations - March 2026",
  "declarations": [
    {
      "id": 12345,
      "reference": "IMP-2026-001",
      "mrn": "26NL123456789012345",
      "status": "REL"
    }
  ],
  "transits": [
    {
      "id": 5001,
      "lrn": "26NL00001234567890123",
      "mrn": "26NL12345678901234567",
      "status": "CMP"
    }
  ],
  "purchase_lines": [
    {
      "id": 101,
      "description": "Customs clearance fee",
      "quantity": 5,
      "unit_price": 50.00,
      "total": 250.00
    }
  ],
  "invoice_lines": [
    {
      "id": 201,
      "description": "Customs clearance service",
      "quantity": 5,
      "unit_price": 100.00,
      "total": 500.00
    }
  ],
  "total_purchase_costs": 1250.00,
  "total_revenue": 2500.00,
  "margin": 1250.00,
  "margin_percentage": 50.00,
  "created_at": "2026-03-20T10:00:00.000000Z",
  "updated_at": "2026-03-25T14:30:00.000000Z"
}

Create Dossier

Create a new dossier.


curl -X POST "https://app.borderbolt.com/api/v1/dossiers" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "customer_code": "CUST001",
    "dossier_number": "DOS-2026-002",
    "customer_reference": "Q1-2026",
    "transport_mode": "air",
    "master_airwaybill": "123-45678901",
    "eta": "2026-04-01"
  }'

Request Body

Field	Required	Type	Description
`customer_code`	Yes	string	Customer code (max 50 chars)
`dossier_number`	No	string	Unique dossier number (auto-generated if omitted)
`invoice_to_customer_id`	No	integer	Override the invoice-to customer
`transport_mode`	No	string	Transport mode (e.g. `air`, `sea`, `road`)
`master_airwaybill`	No	string	Master AWB number
`house_airwaybill`	No	string	House AWB number
`master_bill_of_lading`	No	string	Master BL number
`house_bill_of_lading`	No	string	House BL number
`vessel_name`	No	string	Vessel name
`voyage_number`	No	string	Voyage number
`carrier_name`	No	string	Carrier name
`carrier_eori`	No	string	Carrier EORI number
`eta`	No	date	Estimated time of arrival (`YYYY-MM-DD`)
`etd`	No	date	Estimated time of departure (`YYYY-MM-DD`)
`customer_reference`	No	string	Customer’s own reference
`internal_notes`	No	string	Internal notes
`invoice_frequency`	No	string	`immediate`, `delayed`, `weekly`, `monthly`

Update Dossier

Update an existing dossier.


curl -X PUT "https://app.borderbolt.com/api/v1/dossiers/3001" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "description": "Updated description",
    "status": "complete"
  }'

Delete Dossier

Delete a dossier. Only empty dossiers with no linked declarations or transits can be deleted.


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

Link Declaration

Link a declaration to a dossier.


curl -X POST "https://app.borderbolt.com/api/v1/dossiers/3001/link-declaration" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "declaration_id": 12345
  }'

Unlink Declaration

Remove a declaration from a dossier.


curl -X POST "https://app.borderbolt.com/api/v1/dossiers/3001/unlink-declaration" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "declaration_id": 12345
  }'

Link Transit

Link a transit declaration to a dossier.


curl -X POST "https://app.borderbolt.com/api/v1/dossiers/3001/link-transit" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "transit_id": 5001
  }'

Unlink Transit

Remove a transit from a dossier.


curl -X POST "https://app.borderbolt.com/api/v1/dossiers/3001/unlink-transit" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "transit_id": 5001
  }'

Purchase Lines (Costs)

List Purchase Lines


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

Add Purchase Line


curl -X POST "https://app.borderbolt.com/api/v1/dossiers/3001/purchase-lines" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "description": "Transport costs",
    "quantity": 1,
    "unit_price": 500.00,
    "vat_rate": 21.00
  }'

Update Purchase Line


curl -X PUT "https://app.borderbolt.com/api/v1/dossiers/3001/purchase-lines/101" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "unit_price": 550.00
  }'

Delete Purchase Line


curl -X DELETE "https://app.borderbolt.com/api/v1/dossiers/3001/purchase-lines/101" \
  -H "Authorization: Bearer your-access-token" \
  -H "Accept: application/json"

Invoice Lines (Revenue)

List Invoice Lines


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

Add Invoice Line


curl -X POST "https://app.borderbolt.com/api/v1/dossiers/3001/invoice-lines" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "description": "Customs clearance service",
    "quantity": 5,
    "unit_price": 100.00,
    "vat_rate": 21.00
  }'

Update Invoice Line


curl -X PUT "https://app.borderbolt.com/api/v1/dossiers/3001/invoice-lines/201" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "unit_price": 110.00
  }'

Delete Invoice Line


curl -X DELETE "https://app.borderbolt.com/api/v1/dossiers/3001/invoice-lines/201" \
  -H "Authorization: Bearer your-access-token" \
  -H "Accept: application/json"

Recalculate Revenue

Recalculate total revenue based on current invoice lines.


curl -X POST "https://app.borderbolt.com/api/v1/dossiers/3001/recalculate-revenue" \
  -H "Authorization: Bearer your-access-token" \
  -H "Accept: application/json"

Response


{
  "dossier_id": 3001,
  "total_revenue": 2750.00,
  "total_purchase_costs": 1250.00,
  "margin": 1500.00,
  "margin_percentage": 54.55
}

Update Status

Transition a dossier to a new status. Not all transitions are allowed — see the workflow table below.


POST /api/v1/dossiers/{id}/update-status

Request Body

Field	Required	Type	Description
`status`	Yes	string	Target status: `open`, `complete`, `invoiced`, or `closed`


curl -X POST "https://app.borderbolt.com/api/v1/dossiers/3001/update-status" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "complete"
  }'

Example Response


{
  "data": {
    "old_status": "open",
    "new_status": "complete",
    "dossier": {
      "id": 3001,
      "status": "complete"
    }
  },
  "message": "Dossier status updated to complete"
}

HTTP 422 is returned for invalid transitions.

Status Workflow

Status	Description	Next Actions
`open`	Active dossier	mark-complete
`complete`	Work done, ready to invoice	mark-invoiced, reopen
`invoiced`	Invoice generated	mark-closed, reopen
`closed`	Paid and archived	reopen

Next Steps

Invoices API - Generate invoices from dossiers
Declarations API - Link declarations to dossiers
Transit API - Link transit to dossiers