> ## Documentation Index > Fetch the complete documentation index at: https://docs.bahnexpress.fi/llms.txt > Use this file to discover all available pages before exploring further. # Create a file upload > Creates a file identifier and a temporary direct-upload request. Send a multipart form POST to the returned URL. Add each returned field to the form. Add the file as the final form field with the name `file`. Use the file identifier in an order request after the upload succeeds. ## OpenAPI ````yaml /openapi.yaml post /v2/files openapi: 3.1.2 info: title: Bahn Customer API version: 2.0.0-draft summary: Create and follow vehicle transport orders. description: | Create vehicle transport orders and read their current state. contact: name: Bahn API support email: support@bahnexpress.com license: name: Proprietary identifier: LicenseRef-Proprietary servers: - url: https://sandbox.api.bahnexpress.fi description: Customer sandbox - url: https://api.bahnexpress.fi description: Production security: - oauth2: - orders:read - orders:write tags: - name: Authentication description: Create an access token for the selected environment. - name: Prices description: Check the current price for a route. - name: Orders description: Create, read, change, and cancel orders. - name: Files description: Upload and read order files. - name: Inspections description: Get vehicle inspection reports. - name: Tracking description: Get the current location for each order item. - name: Reports description: Get order report rows. - name: Sandbox description: Apply deterministic scenarios in the customer sandbox. - name: Webhooks description: Receive order change events from Bahn. paths: /v2/files: post: tags: - Files summary: Create a file upload description: | Creates a file identifier and a temporary direct-upload request. Send a multipart form POST to the returned URL. Add each returned field to the form. Add the file as the final form field with the name `file`. Use the file identifier in an order request after the upload succeeds. operationId: createFileUpload parameters: - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/RequestId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/FileUploadRequest' example: description: Pickup release document for this vehicle. name: pickup-release-document.pdf category: customer_document media_type: application/pdf size_bytes: 48211 responses: '201': description: The upload request is ready. content: application/json: schema: $ref: '#/components/schemas/FileUpload' example: file_id: file_01k1a2b3c4d5e6f7g8h9j0k1m2 upload: method: POST url: https://upload.example.invalid/customer-file fields: key: customer-api/example/file Content-Type: application/pdf expires_at: '2026-07-30T14:15:00Z' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '413': description: The file or request body is too large. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '500': $ref: '#/components/responses/ServerError' '503': $ref: '#/components/responses/ServerError' security: - oauth2: - orders:write components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: true description: A unique key for this logical write. schema: type: string minLength: 8 maxLength: 255 RequestId: name: X-Request-Id in: header required: false description: A caller-supplied request identifier for support. schema: type: string minLength: 1 maxLength: 255 schemas: FileUploadRequest: description: Metadata used to create a temporary direct-upload form. type: object additionalProperties: false required: - name - category - media_type - size_bytes properties: description: type: string minLength: 1 description: Customer-facing explanation of what the uploaded document contains. name: type: string minLength: 1 maxLength: 255 description: Original file name shown with the uploaded document. category: type: string description: >- Use power_of_attorney only for a power of attorney. Use customer_document for other files, including pickup release documents. enum: - power_of_attorney - customer_document media_type: type: string description: MIME type of the file that will be uploaded. enum: - application/pdf - image/jpeg - image/png size_bytes: type: integer minimum: 1 maximum: 12582912 description: Exact file size in bytes. The maximum is 12 MiB. FileUpload: description: File ID and temporary multipart form for direct upload. type: object additionalProperties: false required: - file_id - upload properties: file_id: $ref: '#/components/schemas/FileId' description: ID to add to an order after the upload succeeds. upload: type: object description: Temporary form that accepts the file contents. additionalProperties: false required: - method - url - fields - expires_at properties: method: const: POST description: HTTP method required by the upload form. url: type: string format: uri description: Temporary URL that receives the multipart form. fields: type: object description: Form fields to send unchanged before the final file field. additionalProperties: type: string expires_at: type: string format: date-time description: Time after which this upload form no longer accepts the file. Problem: description: A machine-readable API error in RFC 9457 problem-details format. type: object additionalProperties: false required: - type - title - status - code - instance - request_id properties: type: type: string format: uri description: A stable URI for the problem type. title: type: string description: A short problem summary. status: type: integer minimum: 400 maximum: 599 description: The HTTP status code returned with this problem. code: $ref: '#/components/schemas/ProblemCode' description: Stable code for application logic and retry decisions. detail: type: string description: A human-readable explanation of this occurrence. instance: type: string description: The request path that produced the problem. request_id: type: string description: Request identifier to include when you contact Bahn support. errors: type: array description: >- Field-level validation errors, when the problem concerns request input. items: $ref: '#/components/schemas/FieldError' FileId: type: string pattern: ^file_[a-z0-9]+$ description: Stable identifier for an uploaded or published order file. ProblemCode: type: string description: A stable machine code for client decisions. enum: - validation_error - authentication_failed - permission_denied - resource_not_found - idempotency_conflict - revision_conflict - order_not_cancellable - order_not_updateable - business_rule_violation - ordered_for_required - ordered_for_not_allowed - ordered_for_customer_not_found - file_too_large - request_too_large - scenario_not_allowed - internal_error FieldError: description: One invalid request field. type: object additionalProperties: false required: - path - code - message properties: path: type: string description: Dot-separated path to the invalid field. code: type: string description: Stable validation code for this field error. message: type: string description: Human-readable reason why the field is invalid. responses: BadRequest: description: The request syntax or shape is invalid. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://api.bahnexpress.fi/problems/validation-error title: The request is invalid. status: 400 code: validation_error detail: One or more fields are invalid. instance: /v2/orders request_id: req_01k1a2b3c4d5e6f7g8h9j0k1m2 errors: - path: items.0.vin code: invalid_length message: The VIN must contain 17 characters. Unauthorized: description: Authentication failed. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' Forbidden: description: The token lacks the required scope or customer access. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' Conflict: description: The request conflicts with the current resource state. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' ServerError: description: Bahn could not complete the request. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' securitySchemes: oauth2: type: oauth2 description: OAuth 2.0 client credentials. flows: clientCredentials: tokenUrl: /oauth2/token scopes: orders:read: Read customer orders. orders:write: Check prices, upload files, and change customer orders. reports:read: Read customer order reports. test:write: Apply customer sandbox scenarios. ````