---
title: "Prepare an expense attachment upload reference"
method: POST
path: "/v1/expenses/attachments/uploads"
tags: ["Expenses"]
---

# Prepare an expense attachment upload reference

`POST /v1/expenses/attachments/uploads`

## Request

- Base URL: `https://api.frihet.io`
- URL: `https://api.frihet.io/v1/expenses/attachments/uploads`
- Auth: API key in header `X-API-Key`

Prepare a metadata-only attachment reference for an expense receipt.
This endpoint does not accept raw bytes, local file paths, signed URLs,
or secrets. It returns an opaque fileReferenceId plus limits that a full
MCP/API client can use before linking the uploaded file to an expense.

## Request body

- FileAttachmentUploadCreate
  - `fileName` string, required: Filename only; local paths are rejected.
  - `contentType` 'application/pdf' | 'image/jpeg' | 'image/jpg' | 'image/png' | 'image/webp' | 'image/heic' | 'image/heif' | 'image/tiff', required
  - `sizeBytes` integer, required
  - `expenseId` string: Optional expense ID to scope the upload reference to.
  - `checksumSha256` string

## Response `200`

Attachment upload reference prepared

- object
  - `data` FileAttachmentUpload
    - `uploadId` string
    - `fileReferenceId` string: Opaque backend-issued file reference to pass to attachExpenseFileReference.
    - `fileId` string: Backward-compatible alias for fileReferenceId.
    - `fileName` string
    - `originalName` string
    - `contentType` string
    - `sizeBytes` integer
    - `size` integer
    - `maxSizeBytes` integer
    - `expiresAt` string, date-time
    - `status` string
    - `attach` object
      - `expenseId` string, nullable
      - `endpoint` string
      - `body` object

## Other responses

- `400`: Bad request - invalid parameters or request body
- `401`: Authentication required or invalid API key
- `404`: Resource not found
- `429`: Rate limit exceeded (100 requests per minute)
- `500`: Internal server error

---

[API](https://skmtc.dev/frihet/apis/frihet-api.md) · [All operations](https://skmtc.dev/frihet/apis/frihet-api/llms.txt) · [OpenAPI document](https://skmtc.dev/frihet/apis/frihet-api/revisions/3dd37f6a72d1?raw)