---
title: "Upload files to existing collection"
method: POST
path: "/v1/documents/collections/{collection_id}/upload/"
tags: ["Document Collections"]
---

# Upload files to existing collection

`POST /v1/documents/collections/{collection_id}/upload/`

The endpoint uploads additional files to an existing collection. Documents are provided as base64-encoded content in JSON format. Each uploaded file is automatically validated and queued for AI-powered categorization.

## Request body

- object
  - `documents` DocumentUploadData[], required
    - `filename` string, required
    - `mime_type` 'application/pdf' | 'image/jpeg' | 'image/png' | 'image/tiff' | 'image/webp' | 'image/x-ms-bmp' | 'image/heic' | 'image/heif', required
    - `content` string, byte, required — Base64-encoded file content. Maximum file size: 10 MB (10,000,000 bytes). Minimum file size: 1 KB (1,000 bytes). Note: maxLength accounts for base64 encoding overhead (4/3 ratio).
    - `user_id` string, nullable — Truv user ID to assign this document to (optional, mutually exclusive with external_user_id). Setting it binds every document recognized in this file to that user and skips automatic matching for them. Omit it to let Truv match documents to the collection's users using the name and SSN it extracts.
    - `external_user_id` string, nullable — External system user ID to assign this document to (optional, mutually exclusive with user_id). Setting it binds every document recognized in this file to that user and skips automatic matching for them. Omit it to let Truv match documents to the collection's users using the name and SSN it extracts.

## Response `201`

- DocumentCollectionUploadResponse
  - `collection_id` string, required
  - `uploaded_files` UploadedFileBasic[], required
    - `file_id` string, required
    - `filename` string, required
    - `mime_type` 'application/pdf' | 'image/jpeg' | 'image/png' | 'image/tiff' | 'image/webp' | 'image/x-ms-bmp' | 'image/heic' | 'image/heif', required
    - `validations` object, nullable
      - `is_viable_size` boolean, nullable — Whether the file size is within acceptable limits
      - `is_supported_type` boolean, nullable — Whether the file type is supported
      - `is_accessible` boolean, nullable — Whether the file is accessible
      - `is_valid` boolean, nullable — Overall validation status
      - `is_readable` boolean, nullable — Whether the file can be read
      - `is_unique` boolean, nullable — Whether the file is unique (not a duplicate)
    - `status` 'pending' | 'validating' | 'validated' | 'invalid' | 'duplicate' | 'processing' | 'successful' | 'failed', required
    - `user_id` string, nullable — Truv user ID associated with this file
    - `external_user_id` string, nullable — External system user ID associated with this file
  - `documents` RecognizedDocumentBasic[], required
    - `document_id` string, required
    - `file_id` string, required
    - `document_type` 'PAYSTUB' | 'W2' | 'F1099' | 'F1040' | 'BANK_STATEMENT' | 'PASSPORT' | 'GREEN_CARD' | 'DRIVER_LICENSE' | 'LETTER_OF_VERIFICATION' | 'UTILITY_BILL' | 'LEASE_AGREEMENT' | 'INSURANCE_HOME_POLICY' | 'INSURANCE_AUTO_POLICY' | 'VOLUNTEER_LETTER' | 'OTHER', required
    - `document_subtype` 'F1099_MISC' | 'F1099_NEC' | 'F1099_DIV' | 'F1099_INT' | 'F1099_G' | 'F1099_R' | 'F_SSA1099' | 'VOL_TRANSCRIPT' | 'VOL_HOURS_LOG' | 'null', nullable
    - `status` 'successful' | 'failed' | 'rejected', required
    - `first_name` string, nullable
    - `last_name` string, nullable
    - `user_id` string, nullable — Truv user ID associated with this document
    - `external_user_id` string, nullable — External system user ID associated with this document
    - `start_page` integer, nullable, required
    - `end_page` integer, nullable, required
  - `users` CollectionUserResponse[], required
    - `id` string, required — Truv user ID
    - `external_user_id` string, nullable, required — External system user ID
    - `first_name` string, nullable, required — User's first name
    - `last_name` string, nullable, required — User's last name

## Other responses

- `400` — HTTP 400 Bad Request
- `401` — HTTP 401 Unauthorized
- `403` — HTTP 403 Forbidden
- `404` — HTTP 404 Not Found

---

[API](https://skmtc.net/truv/apis/truv-api.md) · [All operations](https://skmtc.net/truv/apis/truv-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/truv/truv-api/versions/b92671dcb52d/schema)