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

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
            }
          ]
        }
      ]
    }
  ]
}

​Quickstart

​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