TRtruv
Sandbox

Upload a sandbox document

Changed on

Adds a file to your sandbox document library. A scenario references the returned id as a record's document_id: a payroll or document-upload paystub, W-2, 1099 or 1040, a volunteer letter, a PCS order, a bank statement, or an insurance policy document. A document-upload scenario also selects on the entry's filename, and a Document Collections upload of that filename takes the entry's status, validations, last_error and documents as its result.

The documented body is the JSON form, carrying the bytes as base64 content. The same endpoint also accepts multipart/form-data with a file part and the same metadata, where documents is sent as a JSON-encoded string.

filename is unique per client, compared without regard to case, and is also the join key a document-upload scenario matches on.

post/v1/sandbox/documents/

Request

  • Base URL
    https://prod.truv.com
  • URL
    https://prod.truv.com/v1/sandbox/documents/
  • Auth
    API key in header X-Access-Client-Id and API key in header X-Access-Secret

Request body

filenamestring required

Name the entry is addressed by. Unique per client, compared without regard to case, and refused when it is one of Truv's own documented sandbox filenames.

contentstring required

The file bytes, base64-encoded.

Example request

{
  "filename": "acme-w2-2025.pdf",
  "content": "JVBERi0xLjQKJc...",
  "documents": [
    {
      "document_type": "PAYSTUB",
      "identity": {
        "full_name": "John Doe",
        "first_name": "John",
        "last_name": "Doe",
        "ssn": "991-91-9991"
      },
      "company_name": "Acme Inc.",
      "start_page": 1,
      "end_page": 2
    }
  ]
}

Response

idstring

Unique identifier of the library entry. This is the value a scenario payload references as document_id.

created_atstring date-time

Time when the entry was created.

updated_atstring date-time

Time when the entry was last updated.

Example response

{
  "id": "3f1c8a90b7d2416e9a5c0e4f2b8d6a17",
  "uploaded_file": {
    "file_id": "3f1c8a90b7d2416e9a5c0e4f2b8d6a17",
    "filename": "acme-w2-2025.pdf",
    "mime_type": "application/pdf",
    "size": 48219,
    "md5": "9f2b1c0d4e6a8b3f5c7d9e1a2b4c6d8e",
    "file": "https://s3.amazonaws.com/...",
    "status": "successful",
    "validations": {
      "is_viable_size": true,
      "is_supported_type": true,
      "is_accessible": true,
      "is_valid": true,
      "is_readable": true,
      "is_unique": true
    }
  },
  "documents": [
    {
      "document_type": "PAYSTUB",
      "identity": {
        "full_name": "John Doe",
        "first_name": "John",
        "last_name": "Doe",
        "ssn": "991-91-9991"
      },
      "company_name": "Acme Inc.",
      "start_page": 1,
      "end_page": 2
    }
  ],
  "created_at": "2026-09-17T10:11:02.104882Z",
  "updated_at": "2026-09-17T10:11:02.104901Z"
}

Changes