Files and inspections

An order can collect customer uploads, handover photos, transport documents, condition summaries, and a full inspection report. These records answer different questions, so keep their meaning distinct in your system.

Upload a customer document

You cannot attach a file by URL. Upload it first, then add its ID to an order:

Call POST /v2/files with the file name, category, media type, and byte size.
Submit every returned form field to the returned upload URL.
Add the file as the final multipart field with the name file.
Add the returned file_id to the order file_ids field.

Do not rename or remove fields from the upload form. The temporary upload request accepts PDF, JPEG, and PNG files up to 12 MiB. Use power_of_attorney or customer_document as the category. The optional description is visible with the attached file and should tell a user what the document contains. Use customer_document for a pickup release document. Give the file a clear name, such as pickup-release-document.pdf, and add its ID to the order. You can leave pickup.release_code empty when the document contains the release authorization. A successful upload does not attach the file by itself. The file appears on the order only after its ID is included in order creation or an order update.

Complete upload example

This Node.js example needs a valid BAHN_ACCESS_TOKEN, a PDF at ./pickup-release-document.pdf, and one BAHN_UPLOAD_KEY for this logical upload. Generate the key once, then retain it for retries.

import { readFile } from "node:fs/promises"

const bytes = await readFile("./pickup-release-document.pdf")
const reservationResponse = await fetch("https://sandbox.api.bahnexpress.fi/v2/files", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BAHN_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": process.env.BAHN_UPLOAD_KEY,
  },
  body: JSON.stringify({
    name: "pickup-release-document.pdf",
    category: "customer_document",
    media_type: "application/pdf",
    size_bytes: bytes.byteLength,
  }),
})
if (!reservationResponse.ok) throw new Error(await reservationResponse.text())
const reservation = await reservationResponse.json()

const form = new FormData()
for (const [name, value] of Object.entries(reservation.upload.fields)) {
  form.append(name, value)
}
form.append("file", new Blob([bytes], { type: "application/pdf" }), "pickup-release-document.pdf")

const uploadResponse = await fetch(reservation.upload.url, { method: "POST", body: form })
if (!uploadResponse.ok) throw new Error(`Upload failed: ${uploadResponse.status}`)
console.log(reservation.file_id)

Let FormData set the multipart content type and boundary. Send the returned form to the upload URL without the API Bearer header. Use the form before upload.expires_at. Before attaching the file, retrying POST /v2/files with the same key and metadata returns the same file ID with a fresh form. Attach that ID when creating the order, or send this order-update body with a new write key and the current quoted revision:

{
  "file_ids": ["file_01k1a2b3c4d5e6f7g8h9j0k1m2"]
}

Replace the example ID with the actual returned ID. file_ids adds files to the order. It does not replace the existing file list.

Build the order file list

Call GET /v2/orders/{order_id}/files to read all available order files. Use the fields together rather than relying on the file name:

Field	Use in your system
`id`	Stable file identity.
`kind`	Render the file as an `image` or `document`.
`category`	Label the content, such as vehicle, odometer, VIN, or CMR.
`stage`	Group the file under pickup or delivery. It can be `null`.
`evidence_for`	Mark evidence for damage, inspection, both, or neither.
`item_id`	Associate the file with the primary or trade-in vehicle.

The file id is stable. The content_url is not. Use the URL before content_url_expires_at, then read the file list again when you need a fresh URL. Submitted provider pickup and delivery photos appear when they are available to the customer. The order status can change after the upload. Use stage to group files. Do not use it to decide if a file is available. The customer file list does not include vehicle key photos. Read CMR recipients when the document recipient needs to differ from the physical destination. After delivery, the list also contains a generated CMR PDF with category: cmr. The generated document has a stable file ID. Its content_url is valid for a short time. Its size_bytes value is null because the server creates the PDF when you open the URL.

Show vehicle condition

Each order item has a pickup_condition and delivery_condition. These summaries contain the recorded condition, odometer value, notes, and related evidence_file_ids when available. Use those file IDs to find the photos in the order file list. A photo alone does not tell you whether Bahn recorded damage or accepted a condition result.

Show a full inspection

A full inspection is a structured report for the primary vehicle. It is separate from the condition summary and the general file list. Call GET /v2/orders/{order_id}/inspection-report and handle its status:

Status	Interpretation
`not_required`	This order does not require a full inspection.
`pending`	The inspection is not yet available.
`available`	Read the inspection time, findings, category results, and evidence.

Each category has an ok or issue status, optional findings, and its own evidence files. Use those fields to build the report. Do not label a normal handover photo as an inspection result.

Delete a customer upload

The can_delete field tells you whether the current credential can delete a file. When it is true, call DELETE /v2/orders/{order_id}/files/{file_id}. Deletion is available only while the order allows changes and only for files uploaded by the same customer account. Use can_delete as the deletion rule instead of deriving access from the file category.

Get started

Create and manage orders

Follow the transport

Reliability and production

Platform ordering

Automation

Upload a customer document

Complete upload example

Build the order file list

Show vehicle condition

Show a full inspection

Delete a customer upload

​Upload a customer document

​Complete upload example

​Build the order file list

​Show vehicle condition

​Show a full inspection

​Delete a customer upload

Upload a customer document

Complete upload example

Build the order file list

Show vehicle condition

Show a full inspection

Delete a customer upload