Transaction Attachments

Last Updated: 2026-05-13
Version: 1.0

Expense transactions can include receipts, invoices, and other supporting files. Attachments are uploaded first, then linked to an expense transaction by ID.

Flow

1. Upload each file to POST /transaction-attachments.
2. Read the returned attachment id.
3. Pass the IDs in attachmentIds on POST /transactions or PUT /transactions/{id}.

Only expense transactions support attachments. Deposits and transfers reject a non-empty attachmentIds array.

Upload

Send a multipart/form-data request with a file part.

curl 'https://api.vrplatform.app/transaction-attachments' \
  -H 'x-team-id: team_123' \
  -F 'file=@invoice.pdf' \
  -F 'isOwnerAccessible=true'

Optional fields:

Example response:

{
  "id": "1a3a5a1f-9c33-49bd-91c7-02bd0f3f5a92",
  "transactionId": null,
  "filename": "invoice.pdf",
  "contentType": "application/pdf",
  "byteSize": 48213,
  "isOwnerAccessible": true
}

Attach On Create

Pass the uploaded IDs in attachmentIds when creating an expense transaction.

POST /transactions
{
  "type": "expense",
  "date": "2024-06-15",
  "description": "HVAC Repair - Beach House",
  "attachmentIds": ["1a3a5a1f-9c33-49bd-91c7-02bd0f3f5a92"],
  "lines": [
    {
      "accountId": "account-repairs",
      "listingId": "listing-123",
      "amount": 25000,
      "description": "AC compressor replacement"
    }
  ]
}

Attach On Update

PUT /transactions/{id} treats attachmentIds as the complete desired set:

• Omit attachmentIds to keep current attachments unchanged
• Send attachmentIds: [] to remove all attachments
• Send the full list to add, keep, or remove attachments

PUT /transactions/txn-123
{
  "attachmentIds": [
    "1a3a5a1f-9c33-49bd-91c7-02bd0f3f5a92",
    "5f778740-d84e-4a4f-8215-52b9c5f1a741"
  ]
}

Visibility And Download

Use PATCH /transaction-attachments/{attachmentId} to update isOwnerAccessible. Owner-accessible files appear in owner statement details for owners who can access the linked listing.

Use GET /transaction-attachments/{attachmentId}/download to download the file.

Endpoint Reference

• POST /transaction-attachments uploads a staged attachment
• PATCH /transaction-attachments/{attachmentId} updates owner visibility
• GET /transaction-attachments/{attachmentId}/download downloads a file
• DELETE /transaction-attachments/{attachmentId} deletes an attachment
• POST /transactions creates an expense with attachmentIds
• PUT /transactions/{id} replaces the attached set when attachmentIds is present