> ## Documentation Index > Fetch the complete documentation index at: https://docs.truv.com/llms.txt > Use this file to discover all available pages before exploring further. # The Document Collections object > Find more information about document collections API. Document Collections provide a way to upload, process, and manage multiple documents in a single workflow. Documents are automatically validated and processed using AI-powered categorization to identify document types such as paystubs, W2s, 1099s, and more. # Quickstart We recommend using Python (works on all platforms): ```python theme={null} # save as prepare_request.py import base64, json, sys with open(sys.argv[1], 'rb') as f: content = base64.b64encode(f.read()).decode() json.dump({ "documents": [{ "mime_type": "application/pdf", "content": content, "filename": sys.argv[1] }] }, open('request.json', 'w')) ``` Run it: ```bash theme={null} python prepare_request.py mydocument.pdf curl -X POST https://prod.truv.com/v1/documents/collections/ \ -H "Content-Type: application/json" \ -d @request.json ``` # Collection Attributes The table below covers the attributes returned when listing document collections. | Attribute | Type | Description | | :--------------- | :-------- | :------------------------------------------------- | | collection\_id | string | Unique identifier for the collection | | created\_at | date-time | Date and time when the collection was created | | updated\_at | date-time | Date and time when the collection was last updated | | files\_count | integer | Number of uploaded files in the collection | | documents\_count | integer | Number of recognized documents in the collection | | users\_count | integer | Number of users associated with the collection | # Uploaded File Attributes The table below covers the attributes for uploaded files within a collection. | Attribute | Type | Description | | :----------------- | :----------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | | file\_id | string | Unique identifier for the uploaded file | | filename | string | Name of the uploaded file | | mime\_type | string | MIME type of the file, valid values: `application/pdf`, `image/jpeg`, `image/png`, `image/tiff`, `image/webp`, `image/x-ms-bmp`, `image/heic`, `image/heif` | | status | string | Processing status of the file, valid values: `pending`, `validating`, `validated`, `invalid`, `duplicate`, `processing`, `successful`, `failed` | | validations | object, null | File validation results containing `is_viable_size`, `is_supported_type`, `is_accessible`, `is_valid`, `is_readable`, `is_unique` | | user\_id | string, null | Truv user ID associated with this file | | external\_user\_id | string, null | External system user ID associated with this file | # Recognized Document Attributes The table below covers the attributes for documents recognized within uploaded files. | Attribute | Type | Description | | :----------------- | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | document\_id | string | Unique identifier for the recognized document | | file\_id | string | ID of the uploaded file containing this document | | document\_type | string | Type of the document, valid values: `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` | | document\_subtype | string, null | Subtype of the document, valid values: `F1099_MISC`, `F1099_NEC`, `F1099_DIV`, `F1099_INT`, `F1099_G`, `F1099_R`, `F_SSA1099`, `VOL_TRANSCRIPT`, `VOL_HOURS_LOG` | | status | string | Processing status of the document, valid values: `successful`, `failed`, `rejected` | | first\_name | string, null | First name extracted from the document | | last\_name | string, null | Last name extracted from the document | | user\_id | string, null | Truv user ID associated with this document | | external\_user\_id | string, null | External system user ID associated with this document | | start\_page | integer | Starting page number of the document within the file | | end\_page | integer | Ending page number of the document within the file | # Finalization After documents in a collection have been processed and categorized, use the finalize endpoint to create links for the recognized documents. This step converts the pre-processed documents into usable Truv links for retrieving income and employment data. ## Finalize request attributes The finalize endpoint returns a response containing users with their associated links and documents. ### User Object | Attribute | Type | Description | | :----------------- | :----------- | :--------------------------------------------- | | id | string | Truv user ID | | external\_user\_id | string, null | External system user ID (optional) | | links | array | List of links created or updated for this user | ### Link Object | Attribute | Type | Description | | :-------- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | link\_id | string | Truv link ID | | status | string | Current status of the link, valid values: `new`, `parse`, `full_parse`, `done`, `no_data`, `config_error`, `error`, `unavailable`. Final statuses (processing complete): `done`, `no_data`, `config_error`, `error`, `unavailable` | | documents | array | List of documents associated with this link | ### Document Object (in Finalize Response) | Attribute | Type | Description | | :---------------- | :----------- | :------------------------------------------------------ | | id | string | Recognized document ID | | document\_type | string | Type of the document (uppercase), e.g., `PAYSTUB`, `W2` | | document\_subtype | string, null | Subtype of the document (uppercase, optional) | # Endpoints Use the endpoints below to manage document collections. * [List all document collections](/api-reference/document-collections/collections_list) * [Create a new document collection](/api-reference/document-collections/collections_create) * [Get document collection details](/api-reference/document-collections/collections_retrieve) * [Delete a document collection](/api-reference/document-collections/collections_delete) * [Upload files to existing collection](/api-reference/document-collections/collections_upload) * [Get uploaded file details](/api-reference/document-collections/collections_uploaded_file_retrieve) * [Delete an uploaded file](/api-reference/document-collections/collections_uploaded_file_delete) * [Finalize a collection](/api-reference/document-collections/collections_finalize_create) * [Get collection finalization results](/api-reference/document-collections/collections_finalize_retrieve) # Example responses *** ## Collection detail response ```json theme={null} { "collection_id": "a1b2c3d4e5f6478899aabbccddeeff00", "created_at": "2025-11-11T10:00:00Z", "updated_at": "2025-11-11T10:05:00Z", "uploaded_files": [ { "file_id": "f1234567890abcdef1234567890abcde", "filename": "paystub.pdf", "mime_type": "application/pdf", "status": "successful", "validations": { "is_viable_size": true, "is_supported_type": true, "is_accessible": true, "is_valid": true, "is_readable": true, "is_unique": true }, "user_id": "a1b2c3d4e5f6478899aabbccddeeff00", "external_user_id": null } ], "documents": [ { "document_id": "d0c1234567890abcdef1234567890abc", "file_id": "f1234567890abcdef1234567890abcde", "document_type": "PAYSTUB", "document_subtype": null, "status": "successful", "first_name": "John", "last_name": "Doe", "user_id": "a1b2c3d4e5f6478899aabbccddeeff00", "external_user_id": null, "start_page": 1, "end_page": 2 } ], "users": [ { "id": "a1b2c3d4e5f6478899aabbccddeeff00", "external_user_id": "ext_user_789", "first_name": "John", "last_name": "Doe" } ] } ``` *** ## Finalization response ```json theme={null} { "users": [ { "id": "a1b2c3d4e5f6478899aabbccddeeff00", "external_user_id": "ext_user_789", "links": [ { "link_id": "c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9", "status": "done", "documents": [ { "id": "d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6", "document_type": "PAYSTUB", "document_subtype": null } ] } ] } ] } ```