Documentation Index
Fetch the complete documentation index at: https://truv.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
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'))
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
}
]
}
]
}
]
}
