Skip to main content

Upload Management API

The Upload Management API allows you to submit documents for processing. An upload represents a batch of files, while tasks represent the individual documents that get processed.

How Uploads and Tasks Work Together​

Simple Example​

When you upload a single PDF invoice, you get:

  • 1 Upload - The submission containing your invoice
  • 1 Task - The processing of that specific invoice

Complex Example​

When you upload an email with 3 PDF attachments, you get:

  • 1 Upload - The email submission
  • 4 Tasks - One for the email body + one for each PDF attachment

Real-World Example​

Upload: "Monthly Invoice Batch - March 2024"
├── Task 1: "invoice_001.pdf" (Status: COMPLETED)
├── Task 2: "invoice_002.pdf" (Status: REVIEWING)
├── Task 3: "invoice_003.pdf" (Status: PROCESSING)
└── Task 4: "receipt_001.jpg" (Status: FAILED)

Key Concepts​

  • Upload = The container for your submission
  • Task = Individual document processing work
  • Each file becomes a separate task that moves through your processing pipeline
  • You manage uploads for batch operations, tasks for individual control

Available Operations​

OperationEndpointPurpose
Create UploadPOST /uploadSubmit files for processing
Get UploadGET /upload/{id}Check status and view all tasks
Move UploadPUT /upload/{id}/moveChange project or organization

Upload Status​

Uploads automatically aggregate their task statuses:

  • PROCESSING - Some tasks are still being processed
  • REVIEWING - Tasks are ready for review
  • COMPLETED - All tasks finished successfully
  • PARTIAL - Mixed results (some completed, some failed)
  • FAILED - Critical processing errors

Common Workflows​

1. Batch Processing​

# Submit documents
POST /upload (with multiple files)

# Check overall progress
GET /upload/{id}

# Handle individual tasks as needed
GET /task/{task_id}
POST /task/{task_id}/complete

2. Quality Review​

# Submit documents
POST /upload

# See which tasks need review
GET /upload/{id}

# Review individual tasks
POST /task/{task_id}/complete
POST /task/{task_id}/discard

Best Practices​

Organize Your Uploads​

  • Group related documents together - "Q1 Invoices", "Contract Batch #5"
  • Use descriptive names - Include dates, departments, or document types
  • Keep reasonable batch sizes - 10-100 documents work well

Monitor Progress​

  • Check upload status for overall progress
  • Use the Task Management API for detailed control
  • Handle failed tasks individually rather than resubmitting entire uploads

Handle Mixed Results​

  • Uploads often have mixed outcomes (some tasks succeed, others need review)
  • Use GET /upload/{id} to see which tasks need attention
  • Complete successful tasks, review or discard problematic ones

Authentication​

All endpoints require an API key with appropriate permissions:

  • upload.create - Create new uploads
  • upload.read - View upload information
  • upload.edit - Move or modify uploads

Next Steps​