Skip to main content
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.
AttributeTypeDescription
collection_idstringUnique identifier for the collection
created_atdate-timeDate and time when the collection was created
updated_atdate-timeDate and time when the collection was last updated
files_countintegerNumber of uploaded files in the collection
documents_countintegerNumber of recognized documents in the collection
users_countintegerNumber of users associated with the collection

​
Uploaded File Attributes

The table below covers the attributes for uploaded files within a collection.
AttributeTypeDescription
file_idstringUnique identifier for the uploaded file
filenamestringName of the uploaded file
mime_typestringMIME type of the file, valid values: application/pdf, image/jpeg, image/png, image/tiff, image/webp, image/x-ms-bmp, image/heic, image/heif
statusstringProcessing status of the file, valid values: pending, validating, validated, invalid, duplicate, processing, successful, failed
validationsobject, nullFile validation results containing is_viable_size, is_supported_type, is_accessible, is_valid, is_readable, is_unique
user_idstring, nullTruv user ID associated with this file
external_user_idstring, nullExternal system user ID associated with this file

​
Recognized Document Attributes

The table below covers the attributes for documents recognized within uploaded files.
AttributeTypeDescription
document_idstringUnique identifier for the recognized document
file_idstringID of the uploaded file containing this document
document_typestringType 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_subtypestring, nullSubtype of the document, valid values: F1099_MISC, F1099_NEC, F1099_DIV, F1099_INT, F1099_G, F1099_R, F_SSA1099, VOL_TRANSCRIPT, VOL_HOURS_LOG
statusstringProcessing status of the document, valid values: successful, failed, rejected
first_namestring, nullFirst name extracted from the document
last_namestring, nullLast name extracted from the document
user_idstring, nullTruv user ID associated with this document
external_user_idstring, nullExternal system user ID associated with this document
start_pageintegerStarting page number of the document within the file
end_pageintegerEnding 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

AttributeTypeDescription
idstringTruv user ID
external_user_idstring, nullExternal system user ID (optional)
linksarrayList of links created or updated for this user
AttributeTypeDescription
link_idstringTruv link ID
statusstringCurrent 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
documentsarrayList of documents associated with this link

​
Document Object (in Finalize Response)

AttributeTypeDescription
idstringRecognized document ID
document_typestringType of the document (uppercase), e.g., PAYSTUB, W2
document_subtypestring, nullSubtype 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
            }
          ]
        }
      ]
    }
  ]
}