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

# 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:

python prepare_request.py mydocument.pdf
curl -X POST https://prod.truv.com/v1/documents/collections/ \
     -H "Content-Type: application/json" \
     -d @request.json

User matching

Truv assigns each recognized document to a user on the collection by matching the name and SSN it extracts from the document. Omit user_id and external_user_id from your documents and let matching run.

Setting user_id or external_user_id on a document in create or upload binds that document to the user you name and skips automatic matching for it. Truv never reconciles that assignment against the extracted identity, so a wrong id stays wrong.

Binding applies per file, not per document. Every document recognized inside a file inherits that file’s user assignment. A single PDF holding pay statements for two users assigns both to the one you named. Set these fields only when you already know which user a file belongs to — for example, when your portal collected it under a specific user. Otherwise leave them out.

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.

Example responses

Collection detail response

{
  "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

{
  "users": [
    {
      "id": "a1b2c3d4e5f6478899aabbccddeeff00",
      "external_user_id": "ext_user_789",
      "links": [
        {
          "link_id": "c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9",
          "status": "done",
          "documents": [
            {
              "id": "d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6",
              "document_type": "PAYSTUB",
              "document_subtype": null
            }
          ]
        }
      ]
    }
  ]
}

API Reference

Platform

Income & Employment

Financial Accounts

Document Processing

Direct Deposit Switch

Insurance Verification

The Document Collections object

Quickstart

User matching

Collection Attributes

Uploaded File Attributes

Recognized Document Attributes

Finalization

Finalize request attributes

User Object

Link Object

Document Object (in Finalize Response)

Endpoints

Example responses

Collection detail response

Finalization response

​Quickstart

​User matching

​Collection Attributes

​Uploaded File Attributes

​Recognized Document Attributes

​Finalization

​Finalize request attributes

​User Object

​Link Object

​Document Object (in Finalize Response)

​Endpoints

​Example responses

​Collection detail response

​Finalization response

Quickstart

User matching

Collection Attributes

Uploaded File Attributes

Recognized Document Attributes

Finalization

Finalize request attributes

User Object

Link Object

Document Object (in Finalize Response)

Endpoints

Example responses

Collection detail response

Finalization response