> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truv.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload a sandbox document

> Adds a file to your sandbox document library. A payroll scenario references the returned `id` as a paystub's or W-2's `document_id`; every W-2 requires one.

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.



## OpenAPI

````yaml POST /v1/sandbox/documents/
openapi: 3.0.1
info:
  title: Truv API
  description: Truv API Documentation
  termsOfService: https://www.truv.com/legal/terms-of-use
  contact:
    email: support@truv.com
  version: v1
servers:
  - url: https://prod.truv.com
security:
  - ClientID: []
    AccessKey: []
tags:
  - name: Users
  - name: Bridge Token
  - name: Companies and Data Providers
  - name: Key Management
  - name: Account Links
  - name: Data Refresh
  - name: Customization Templates
  - name: Webhooks
  - name: Orders
  - name: Tasks
  - name: VOIE Reports
  - name: VOA Reports
  - name: Income Insights Reports
  - name: DDS Reports
  - name: Employment
  - name: Identity
  - name: Benefit Letters
  - name: Shifts
  - name: Pay Statements
  - name: Tax Documents
  - name: Parsed Documents
  - name: Reports
  - name: Uploaded Documents
  - name: Bank Accounts
  - name: Bank Statements
  - name: Deposit Switch Reports
  - name: Insurance Reports
  - name: Income Report
  - name: Scoring Attributes
  - name: Accounts
  - name: Transactions
  - name: Recurring Transactions
  - name: Document Collections
  - name: Sandbox
paths:
  /v1/sandbox/documents/:
    parameters: []
    post:
      tags:
        - Sandbox
      summary: Upload a sandbox document
      description: >-
        Adds a file to your sandbox document library. A payroll scenario
        references the returned `id` as a paystub's or W-2's `document_id`;
        every W-2 requires one.


        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.
      operationId: v1_sandbox_documents_create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SandboxDocumentCreate'
        required: true
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxDocument'
        '400':
          description: >-
            The filename is taken or reserved, the bytes are missing or not
            valid base64, or a storage quota would be exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxError400'
        '401':
          description: HTTP 401 Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: The key is not a sandbox key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxError403'
        '429':
          description: HTTP 429 Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error429'
components:
  schemas:
    SandboxDocumentCreate:
      description: >-
        A library upload 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.
      type: object
      required:
        - filename
        - content
      properties:
        filename:
          description: >-
            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.
          type: string
          maxLength: 255
          example: acme-w2-2025.pdf
        content:
          description: The file bytes, base64-encoded.
          type: string
          example: JVBERi0xLjQKJc...
        documents:
          description: >-
            Test metadata describing the documents in the file. Omitting it
            declares one paystub for John Doe at Acme Inc., so a document-upload
            flow resolves the file without the entry having to describe it. A
            payroll scenario only needs the file itself, so it can be left out.
          type: array
          items:
            $ref: '#/components/schemas/SandboxRecognizedDocument'
    SandboxDocument:
      description: >-
        One file in your sandbox document library, plus the test metadata
        describing it.
      type: object
      properties:
        id:
          description: >-
            Unique identifier of the library entry. This is the value a scenario
            payload references as `document_id`.
          type: string
          readOnly: true
          maxLength: 64
          example: 3f1c8a90b7d2416e9a5c0e4f2b8d6a17
        uploaded_file:
          $ref: '#/components/schemas/SandboxUploadedFile'
        documents:
          description: >-
            Test metadata describing the documents in the file, used by
            document-upload scenarios.
          type: array
          items:
            $ref: '#/components/schemas/SandboxRecognizedDocument'
        created_at:
          description: Time when the entry was created.
          type: string
          format: date-time
          readOnly: true
          example: '2026-09-17T10:11:02.104882Z'
        updated_at:
          description: Time when the entry was last updated.
          type: string
          format: date-time
          readOnly: true
          example: '2026-09-17T10:11:02.104901Z'
    SandboxError400:
      description: A sandbox configuration error.
      type: object
      properties:
        error:
          description: ''
          type: object
          properties:
            code:
              description: >-
                `data_source_required` when the matching fields fit more than
                one data source, `unsupported_data_source` when one of them is
                not accepted by the source, `reserved_credential` when a login
                or filename collides with one of Truv's own documented sandbox
                credentials, `sandbox_limit_exceeded` when a quota would be
                exceeded, and `incorrect_parameters` for any other field
                validation failure.
              type: string
              enum:
                - data_source_required
                - unsupported_data_source
                - reserved_credential
                - sandbox_limit_exceeded
                - incorrect_parameters
              example: reserved_credential
            message:
              description: ''
              type: string
              example: >-
                Username 'goodlogin' is reserved for Truv's documented sandbox
                logins.
    Error401:
      description: ''
      type: object
      properties:
        error:
          description: ''
          type: object
          properties:
            code:
              description: ''
              type: string
              example: authentication_failed
            message:
              description: ''
              type: string
              example: No such token
    SandboxError403:
      description: The request authenticated with a key that is not a sandbox key.
      type: object
      properties:
        error:
          description: ''
          type: object
          properties:
            code:
              description: ''
              type: string
              enum:
                - env_not_sandbox
              example: env_not_sandbox
            message:
              description: ''
              type: string
              example: >-
                Sandbox configuration requires a sandbox key; this key is
                'prod'.
    Error429:
      description: ''
      type: object
      properties:
        error:
          description: ''
          type: object
          properties:
            code:
              description: ''
              type: string
              example: throttled
            message:
              description: ''
              type: string
              example: Request was throttled.
    SandboxRecognizedDocument:
      description: >-
        Test metadata for one document in a library file. You configure it; Truv
        does not extract it from the file.
      type: object
      required:
        - document_type
      properties:
        document_type:
          description: >-
            Type of the document. Accepted case-insensitively and returned
            lowercase.
          type: string
          maxLength: 64
          example: paystub
        document_subtype:
          description: >-
            Subtype of the document, accepted case-insensitively. Only some
            document types carry one.
          type: string
          nullable: true
          maxLength: 64
          example: null
        identity:
          $ref: '#/components/schemas/SandboxRecognizedDocumentIdentity'
        company_name:
          description: Employer named on the document.
          type: string
          nullable: true
          maxLength: 255
          example: Acme Inc.
        start_page:
          description: First page of the document inside the file.
          type: integer
          nullable: true
          minimum: 1
          example: 1
        end_page:
          description: Last page of the document inside the file.
          type: integer
          nullable: true
          minimum: 1
          example: 2
    SandboxUploadedFile:
      description: The file half of a library entry.
      type: object
      properties:
        file_id:
          description: Unique identifier of the file.
          type: string
          readOnly: true
          maxLength: 64
          example: 3f1c8a90b7d2416e9a5c0e4f2b8d6a17
        filename:
          description: Name the entry is addressed by.
          type: string
          readOnly: true
          maxLength: 255
          example: acme-w2-2025.pdf
        mime_type:
          description: Mimetype detected from the uploaded bytes.
          type: string
          readOnly: true
          enum:
            - application/pdf
            - image/jpeg
            - image/png
            - image/tiff
            - image/webp
            - image/x-ms-bmp
            - image/heic
            - image/heif
          example: application/pdf
        size:
          description: Size of the stored file in bytes.
          type: integer
          readOnly: true
          example: 48219
        md5:
          description: MD5 hash of the file bytes.
          type: string
          readOnly: true
          example: 9f2b1c0d4e6a8b3f5c7d9e1a2b4c6d8e
        file:
          description: >-
            Short-lived pre-signed URL over the stored file, minted fresh on
            every read.
          type: string
          format: uri
          readOnly: true
          nullable: true
          example: https://s3.amazonaws.com/...
        status:
          description: File-level processing outcome the entry declares.
          type: string
          enum:
            - successful
            - invalid
            - duplicate
            - failed
          default: successful
          example: successful
        validations:
          description: Per-check validation results the entry declares.
          type: object
          additionalProperties:
            type: boolean
            nullable: true
          example:
            is_viable_size: true
            is_supported_type: true
            is_accessible: true
            is_valid: true
            is_readable: true
            is_unique: true
        last_error:
          description: Message surfaced for a failed file.
          type: string
          maxLength: 500
          example: ''
    SandboxRecognizedDocumentIdentity:
      description: The identity the document metadata declares.
      type: object
      properties:
        full_name:
          description: Full name on the document.
          type: string
          nullable: true
          maxLength: 255
          example: John Doe
        first_name:
          description: First name on the document.
          type: string
          nullable: true
          maxLength: 50
          example: John
        last_name:
          description: Last name on the document.
          type: string
          nullable: true
          maxLength: 50
          example: Doe
        ssn:
          description: >-
            SSN on the document. Must be synthetic, with an area number of
            900-999.
          type: string
          nullable: true
          maxLength: 11
          example: 991-91-9991
  securitySchemes:
    ClientID:
      type: apiKey
      description: Client ID
      name: X-Access-Client-Id
      in: header
    AccessKey:
      type: apiKey
      description: Client Access Key
      name: X-Access-Secret
      in: header

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.