---
title: "Create a new document collection"
method: POST
path: "/v1/documents/collections/"
tags: ["Document Collections"]
---

# Create a new document collection

`POST /v1/documents/collections/`

The endpoint creates a new document collection and uploads documents in a single request. Documents are provided as base64-encoded content in JSON format. The uploaded files are automatically validated and queued for AI-powered categorization.

## Request body

- DocumentCollectionCreate
  - `documents` DocumentUploadData[], required — Array of documents to upload (maximum 10 files per request)
    - `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.
  - `users` CollectionUser[] — Array of users to create/update in this collection (optional). Truv matches documents to these users automatically using the name and SSN it extracts. Assigning user_id or external_user_id on a document in the documents array overrides that matching for the whole file.
    - union — User information for collection. Either 'id' or 'external_user_id' must be provided, but not both.
      - object
        - `id` string, nullable, required — Truv user ID (optional, mutually exclusive with external_user_id)
        - `external_user_id` string, nullable — External system user ID (optional, mutually exclusive with id). Either id or external_user_id must be provided.
        - `full_name` string, nullable — Full name to parse into first_name and last_name (required if profile doesn't exist or has no names)
        - `ssn` string, nullable — Social Security Number - either 4 or 9 digits (optional)
      - object
        - `id` string, nullable — Truv user ID (optional, mutually exclusive with external_user_id)
        - `external_user_id` string, nullable, required — External system user ID (optional, mutually exclusive with id). Either id or external_user_id must be provided.
        - `full_name` string, nullable — Full name to parse into first_name and last_name (required if profile doesn't exist or has no names)
        - `ssn` string, nullable — Social Security Number - either 4 or 9 digits (optional)

## Response `201`

- DocumentCollectionCreateResponse
  - `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

---

[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)