Transit API

The Transit API provides full CRUD operations for NCTS5 transit declarations, including departure (T1/T2), arrival, amendments, and enquiry responses.

Required Scope: transit:read, transit:write, transit:delete

List Transit Declarations

Retrieve a paginated list of transit declarations with optional filters.


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

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status (DRF, NEW, ACC, REJ, ARR, etc.)
`type`	string	Filter by type (departure, arrival)
`mrn`	string	Filter by Movement Reference Number
`lrn`	string	Filter by Local Reference Number
`customer_code`	string	Filter by customer code
`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": 5001,
      "lrn": "26NL00001234567890123",
      "mrn": "26NL12345678901234567",
      "type": "departure",
      "status": "ACC",
      "transit_type": "T1",
      "customer_code": "CUST001",
      "office_of_departure": "NL000396",
      "office_of_destination": "BE123456",
      "total_items": 2,
      "total_gross_mass": 850.00,
      "total_packages": 45,
      "created_at": "2026-03-25T09:00:00.000000Z",
      "submitted_at": "2026-03-25T09:15:00.000000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 120
  }
}

Get Single Transit

Retrieve a single transit declaration with all items.


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

Response


{
  "id": 5001,
  "lrn": "26NL00001234567890123",
  "mrn": "26NL12345678901234567",
  "type": "departure",
  "status": "ACC",
  "transit_type": "T1",
  "customer_code": "CUST001",
  "office_of_departure": "NL000396",
  "office_of_destination": "BE123456",
  "guarantee": {
    "type": "0",
    "reference": "26NL00001234567",
    "amount": 5000.00,
    "currency": "EUR"
  },
  "parties": {
    "principal": {
      "name": "Transport B.V.",
      "eori": "NL987654321012"
    },
    "consignor": {
      "name": "Example B.V.",
      "eori": "NL123456789012"
    },
    "consignee": {
      "name": "BE Receiver SA",
      "address": "Rue de la Loi 1",
      "city": "Brussels",
      "postal_code": "1000",
      "country": "BE"
    }
  },
  "total_items": 2,
  "total_gross_mass": 850.00,
  "total_packages": 45,
  "items": [
    {
      "id": 10001,
      "item_number": 1,
      "description": "Electronic Equipment",
      "hs_code": "85176290",
      "gross_mass": 500.00,
      "packages": 20,
      "package_type": "CT",
      "marks": "LOT-2026-A"
    }
  ],
  "created_at": "2026-03-25T09:00:00.000000Z",
  "submitted_at": "2026-03-25T09:15:00.000000Z"
}

Create Departure Declaration

Create a new transit departure declaration (T1/T2).


curl -X POST "https://app.borderbolt.com/api/v1/transit/departure" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "lrn": "26NL00001234567890124",
    "transit_type": "T1",
    "customer_code": "CUST001",
    "office_of_departure": "NL000396",
    "office_of_destination": "BE123456",
    "guarantee": {
      "type": "0",
      "reference": "26NL00001234567"
    },
    "parties": {
      "principal": {
        "name": "Transport B.V.",
        "eori": "NL987654321012"
      },
      "consignor": {
        "name": "Example B.V.",
        "eori": "NL123456789012"
      },
      "consignee": {
        "name": "BE Receiver SA",
        "address": "Rue de la Loi 1",
        "city": "Brussels",
        "postal_code": "1000",
        "country": "BE"
      }
    },
    "items": [
      {
        "item_number": 1,
        "description": "Electronic Equipment",
        "hs_code": "85176290",
        "gross_mass": 500.00,
        "packages": 20,
        "package_type": "CT"
      }
    ]
  }'

Request Body

Field	Required	Type	Description
`lrn`	No	string	Local Reference Number (auto-generated if omitted)
`transit_type`	Yes	string	T1 (external), T2 (internal), T2F (internal with special fiscal)
`customer_code`	Yes	string	Customer code
`office_of_departure`	Yes	string	Departure customs office
`office_of_destination`	Yes	string	Destination customs office
`guarantee`	Yes	object	Guarantee details (type, reference)
`parties`	Yes	object	Principal, consignor, consignee
`items`	Yes	array	Transit items

Create Arrival Declaration

Create an arrival declaration for an existing transit.


curl -X POST "https://app.borderbolt.com/api/v1/transit/arrival" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "mrn": "26NL12345678901234567",
    "arrival_date": "2026-03-26T14:30:00",
    "office_of_destination": "BE123456",
    "unloading_remarks": "All packages intact, no discrepancies"
  }'

Create Arrival from MRN

Create an arrival by looking up the departure MRN.


curl -X POST "https://app.borderbolt.com/api/v1/transit/arrival-from-mrn" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "mrn": "26NL12345678901234567",
    "arrival_date": "2026-03-26T14:30:00",
    "unloading_remarks": "All packages intact"
  }'

Update Transit

Update a draft transit declaration.


curl -X PUT "https://app.borderbolt.com/api/v1/transit/5001" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "office_of_destination": "FR123456"
  }'

Status Restriction: Only draft (DRF) transit declarations can be updated.

Delete Transit

Delete a draft transit declaration.


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

Submit Departure

Submit a departure declaration to customs.


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

Response


{
  "id": 5001,
  "status": "NEW",
  "submitted_at": "2026-03-25T09:15:00.000000Z",
  "message": "Transit departure submitted successfully"
}

Submit Arrival

Submit an arrival notification to customs.


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

Submit Amendment

Amend an accepted transit declaration.


curl -X POST "https://app.borderbolt.com/api/v1/transit/5001/amend" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "reason": "Incorrect destination office",
    "changes": {
      "office_of_destination": "FR789012"
    }
  }'

Request Invalidation

Request invalidation of a transit declaration.


curl -X POST "https://app.borderbolt.com/api/v1/transit/5001/invalidate" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "reason": "Shipment cancelled by customer"
  }'

Enquiry Response

Respond to a customs enquiry (IE140).


curl -X POST "https://app.borderbolt.com/api/v1/transit/5001/enquiry-response" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "response": "Goods are currently at warehouse in Brussels awaiting final delivery",
    "supporting_documents": [
      {
        "type": "warehouse_receipt",
        "reference": "WH-2026-001"
      }
    ]
  }'

Unloading Remarks

Submit unloading remarks for an arrival.


curl -X POST "https://app.borderbolt.com/api/v1/transit/5001/unloading-remarks" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "remarks": "All 45 packages received intact, no discrepancies",
    "unloading_completed": true
  }'

Copy Transit

Create a copy of an existing transit declaration.


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

View Timeline

Get the complete event timeline for a transit declaration.


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

Response


{
  "transit_id": 5001,
  "lrn": "26NL00001234567890123",
  "events": [
    {
      "event": "created",
      "status": "DRF",
      "timestamp": "2026-03-25T09:00:00.000000Z",
      "user": "API Client"
    },
    {
      "event": "submitted",
      "status": "NEW",
      "timestamp": "2026-03-25T09:15:00.000000Z",
      "user": "API Client",
      "message_type": "IE015"
    },
    {
      "event": "accepted",
      "status": "ACC",
      "timestamp": "2026-03-25T09:17:30.000000Z",
      "user": "Customs",
      "message_type": "IE029",
      "mrn": "26NL12345678901234567"
    },
    {
      "event": "arrival_submitted",
      "status": "ARR",
      "timestamp": "2026-03-26T14:35:00.000000Z",
      "user": "API Client",
      "message_type": "IE007"
    }
  ]
}

Get Available Actions

Get available actions for a transit declaration based on its current status.


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

Response


{
  "transit_id": 5001,
  "status": "ACC",
  "actions": [
    "submit_arrival",
    "amend",
    "invalidate",
    "copy"
  ]
}

Transit Items

Add Item


curl -X POST "https://app.borderbolt.com/api/v1/transit/5001/items" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "item_number": 3,
    "description": "Machinery Parts",
    "hs_code": "84799090",
    "gross_mass": 300.00,
    "packages": 15,
    "package_type": "PX"
  }'

Update Item


curl -X PUT "https://app.borderbolt.com/api/v1/transit/5001/items/10001" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "gross_mass": 520.00
  }'

Delete Item


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

Status Codes

Status	Description
`DRF`	Draft - not yet submitted
`NEW`	Submitted, awaiting customs response
`ACC`	Accepted by customs (MRN assigned)
`REJ`	Rejected by customs
`ARR`	Arrival submitted
`CMP`	Completed (arrival accepted)
`INV`	Invalidated
`ENQ`	Enquiry received

Next Steps

Guarantees API - Check DVA guarantee balances
Risks API - Monitor non-closure risks
Webhooks - Receive transit status updates