Documents API

The Documents API provides endpoints for managing documents attached to customs declarations. You can list, view, download, upload, and update document metadata.

Required Scope: declarations:read (list, view, download), declarations:write (upload, update)

List Documents

Retrieve all documents for a declaration.


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

Response


{
  "data": [
    {
      "id": 101,
      "original_filename": "invoice-2026-001.pdf",
      "mime_type": "application/pdf",
      "file_size": 245760,
      "file_size_human": "240 KB",
      "document_type": "invoice",
      "description": "Commercial invoice for shipment",
      "created_at": "2026-03-25T10:30:00+00:00",
      "updated_at": "2026-03-25T10:30:00+00:00"
    },
    {
      "id": 102,
      "original_filename": "packing-list.pdf",
      "mime_type": "application/pdf",
      "file_size": 102400,
      "file_size_human": "100 KB",
      "document_type": "packing_list",
      "description": null,
      "created_at": "2026-03-25T10:35:00+00:00",
      "updated_at": "2026-03-25T10:35:00+00:00"
    }
  ],
  "meta": {
    "total": 2,
    "document_types": [
      "invoice",
      "packing_list",
      "bill_of_lading",
      "airway_bill",
      "cmr",
      "certificate_of_origin",
      "eur1",
      "atr",
      "health_certificate",
      "phytosanitary",
      "import_permit",
      "export_permit",
      "customs_valuation",
      "insurance",
      "contract",
      "correspondence",
      "utb",
      "emergency_procedure",
      "sad",
      "other"
    ]
  }
}

Get Single Document

Retrieve metadata for a specific document.


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

Response


{
  "data": {
    "id": 101,
    "original_filename": "invoice-2026-001.pdf",
    "mime_type": "application/pdf",
    "file_size": 245760,
    "file_size_human": "240 KB",
    "document_type": "invoice",
    "description": "Commercial invoice for shipment",
    "created_at": "2026-03-25T10:30:00+00:00",
    "updated_at": "2026-03-25T10:30:00+00:00"
  }
}

Download Document

Download the actual file content of a document.


curl -X GET "https://app.borderbolt.com/api/v1/declarations/12345/documents/101/download" \
  -H "Authorization: Bearer your-access-token" \
  --output invoice-2026-001.pdf

Response

Returns the file as a streamed download with the appropriate Content-Type and Content-Length headers.

Header	Description
`Content-Type`	MIME type of the file (e.g., `application/pdf`)
`Content-Length`	File size in bytes
`Content-Disposition`	Attachment with original filename

Upload Document

Upload a new document to a declaration.


curl -X POST "https://app.borderbolt.com/api/v1/declarations/12345/documents" \
  -H "Authorization: Bearer your-access-token" \
  -H "Accept: application/json" \
  -F "file=@/path/to/invoice.pdf" \
  -F "document_type=invoice" \
  -F "description=Commercial invoice for shipment"

Required Scope: declarations:write

Request Body (multipart/form-data)

Field	Required	Type	Description
`file`	Yes	file	The file to upload (max 50 MB)
`document_type`	No	string	Document type (see document types below)
`description`	No	string	Description of the document (max 500 characters)

Response


{
  "data": {
    "id": 103,
    "original_filename": "invoice.pdf",
    "mime_type": "application/pdf",
    "file_size": 245760,
    "file_size_human": "240 KB",
    "document_type": "invoice",
    "description": "Commercial invoice for shipment",
    "created_at": "2026-03-25T14:00:00+00:00"
  },
  "message": "Document uploaded successfully."
}

HTTP Status: 201 Created

File Restrictions

Max Size: 50 MB
Allowed Types: PDF, Word (.doc, .docx), Excel (.xls, .xlsx), Images (JPEG, PNG, GIF, WebP), Text, CSV, XML
Blocked Extensions: php, phtml, php3, php4, php5, exe, sh, bat, cmd, js, vbs

Update Document Metadata

Update the document type or description of an existing document.


curl -X PUT "https://app.borderbolt.com/api/v1/declarations/12345/documents/101" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "document_type": "customs_valuation",
    "description": "Updated: Customs valuation document"
  }'

Required Scope: declarations:write

Request Body

Field	Required	Type	Description
`document_type`	No	string	New document type
`description`	No	string	New description (max 500 characters)

Response


{
  "data": {
    "id": 101,
    "original_filename": "invoice-2026-001.pdf",
    "mime_type": "application/pdf",
    "file_size": 245760,
    "document_type": "customs_valuation",
    "description": "Updated: Customs valuation document",
    "updated_at": "2026-03-25T15:00:00+00:00"
  },
  "message": "Document updated successfully."
}

Note: You can only update metadata (document type and description). The file itself cannot be replaced. To change the file, upload a new document.

Document Types

The following document types are available:

Type	Description
`invoice`	Invoice
`packing_list`	Packing List
`bill_of_lading`	Bill of Lading (B/L)
`airway_bill`	Airway Bill (AWB)
`cmr`	CMR (International Consignment Note)
`certificate_of_origin`	Certificate of Origin
`eur1`	EUR.1 (Preferential Origin Certificate)
`atr`	A.TR (Turkey Movement Certificate)
`health_certificate`	Health Certificate
`phytosanitary`	Phytosanitary Certificate
`import_permit`	Import Permit
`export_permit`	Export Permit
`customs_valuation`	Customs Valuation Document
`insurance`	Insurance Document
`contract`	Contract
`correspondence`	Correspondence
`utb`	UTB (Invitation to Pay / Uitnodiging tot Betaling)
`emergency_procedure`	Emergency Procedure Document (Noodprocedure)
`sad`	SAD (Single Administrative Document)
`other`	Other

Error Responses

Declaration Not Found


{
  "error": "not_found",
  "message": "Declaration not found."
}

HTTP Status: 404

Document Not Found


{
  "error": "not_found",
  "message": "Document not found."
}

HTTP Status: 404

File Not Found in Storage


{
  "error": "not_found",
  "message": "File not found in storage."
}

HTTP Status: 404

Validation Error (Upload)


{
  "error": "validation_error",
  "message": "The given data was invalid.",
  "errors": {
    "file": ["The file field is required."],
    "document_type": ["The selected document type is invalid."]
  }
}

HTTP Status: 422

Next Steps

Declarations API - Declaration CRUD operations
Webhooks - Real-time event notifications
Error Reference - Error handling