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

# Upload a single invoice (API key, one-step)

> Creates the invoice, stores the file, debits credits, and enqueues extraction in one call. Prefer init + attach for clearer client progress when uploading large files. Poll `statusUrl` until `ready` is true, then read `data` for extracted JSON. If the extraction queue is down, credits are refunded and the call returns 503.



## OpenAPI

````yaml /openapi/programmatic.json post /api/v1/invoices/upload
openapi: 3.0.0
info:
  title: SnapIt Programmatic API
  description: >-
    Public API-key endpoints for invoice upload, extracted JSON, credit balance,
    and top-up. Authenticate with `Authorization: Bearer sk_live_…`. Full
    operator Swagger (including admin/JWT routes) remains at `/api/docs` on the
    API host.
  version: '1.0'
  contact: {}
servers:
  - url: https://api.trysnapit.com
    description: Production
  - url: http://localhost:3000
    description: Local development
security:
  - api-key: []
tags:
  - name: programmatic
    description: API-key authenticated upload, invoice JSON, balance, and credit top-up
paths:
  /api/v1/invoices/upload:
    post:
      tags:
        - programmatic
      summary: Upload a single invoice (API key, one-step)
      description: >-
        Creates the invoice, stores the file, debits credits, and enqueues
        extraction in one call. Prefer init + attach for clearer client progress
        when uploading large files. Poll `statusUrl` until `ready` is true, then
        read `data` for extracted JSON. If the extraction queue is down, credits
        are refunded and the call returns 503.
      operationId: uploadSingle
      parameters:
        - name: vendorId
          required: false
          in: query
          description: Optional vendor UUID (alternative to form field)
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: Invoice PDF or image (JPG, JPEG, PNG, PDF)
                vendorId:
                  type: string
                  description: Optional vendor UUID to prefer Tier 1 template extraction
      responses:
        '202':
          description: Upload accepted; extraction queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadAcceptedResponseDto'
        '400':
          description: Unsupported file type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseDto'
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseDto'
        '402':
          description: Insufficient credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseDto'
        '404':
          description: Invoice slot not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseDto'
        '503':
          description: Extraction queue unavailable (credits refunded)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseDto'
      security:
        - api-key: []
components:
  schemas:
    UploadAcceptedResponseDto:
      type: object
      properties:
        invoice:
          $ref: '#/components/schemas/ProgrammaticInvoiceSummaryDto'
        fileId:
          type: string
          format: uuid
          description: Stored file id; download via JWT /api/files/:fileId in the web app
        statusUrl:
          type: string
          example: /api/v1/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890
          description: >-
            Relative path — prepend your API host (e.g.
            https://api.trysnapit.com). Poll until `ready` is true, then read
            `data` for extracted JSON.
      required:
        - invoice
        - fileId
        - statusUrl
    ApiErrorResponseDto:
      type: object
      properties:
        statusCode:
          type: number
          example: 401
        message:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          example: Invalid or missing API key
        error:
          type: string
          example: Unauthorized
      required:
        - statusCode
        - message
    ProgrammaticInvoiceSummaryDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - pending
            - processing
            - extracted
            - reviewed
            - approved
            - rejected
            - duplicate
          example: pending
        processingStatus:
          type: string
          enum:
            - queued
            - processing
            - completed
            - failed
            - needs_review
          example: queued
        tenantId:
          type: string
          format: uuid
        vendorId:
          type: string
          format: uuid
          nullable: true
        invoiceNumber:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - status
        - processingStatus
        - createdAt
        - updatedAt
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: Authorization
      description: Bearer sk_live_… (include the Bearer prefix)
      x-default: Bearer sk_live_…

````

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