Cases - Document Collections

Cases are a powerful feature that allows you to organize related documents into collections for better management and processing. Think of a case as a folder that can contain multiple documents that belong together - like all documents for a specific customer, project, or business process.

What are Cases?

A Case is a logical container for grouping related documents. Each case has:

• Name: A descriptive identifier for the case
• Description: Optional detailed information about the case purpose
• Organization Scope: Cases belong to your organization
• User Scope: Cases can be user-specific or organization-wide
• Documents: Multiple documents can be uploaded to each case
• Metadata: Rich metadata and processing status for each document

When to Use Cases

Cases are ideal for scenarios where you need to:

• Process multiple documents together (invoices from the same vendor, contract amendments, etc.)
• Organize documents by project (real estate transaction, insurance claim, etc.)
• Track processing status across multiple related documents
• Maintain document relationships and context
• Batch process documents that share similar characteristics

Common Use Cases

• Invoice Processing: Group all invoices from a specific vendor or time period
• Contract Management: Organize contract, amendments, and related documents
• Insurance Claims: Collect all documents related to a single claim
• Real Estate Transactions: Group property documents, inspections, and contracts
• Compliance Audits: Organize documents required for regulatory compliance

Case Management

Creating Cases

cURL

curl -X POST https://api.docudevs.ai/cases \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q4 2024 Vendor Invoices",
    "description": "All invoices from vendors for Q4 2024 processing"
  }'

Python SDK

from docudevs.docudevs_client import DocuDevsClient
from docudevs.models import CasesControllerCreateCaseRequest
import os

# Initialize the client

client = DocuDevsClient(token=os.getenv('API_KEY'))

# Create a new case using the request model

case_request = CasesControllerCreateCaseRequest(
    name="Q4 2024 Vendor Invoices",
    description="All invoices from vendors for Q4 2024 processing"
)

response = await client.create_case(case_request)
case = response.parsed
print(f"Created case ID: {case.id}")

CLI

docudevs cases create \
  --name "Q4 2024 Vendor Invoices" \
  --description "All invoices from vendors for Q4 2024 processing"

Listing Cases

cURL

curl -X GET https://api.docudevs.ai/cases \
  -H "Authorization: Bearer $API_KEY"

Python SDK

# List all cases for your organization
response = await client.list_cases()
cases = response.parsed

for case in cases:
    print(f"Case {case.id}: {case.name}")
    if case.description:
        print(f"  Description: {case.description}")
    print(f"  Created: {case.created_at}")

CLI

docudevs cases list

Getting Case Details

cURL

curl -X GET https://api.docudevs.ai/cases/{case_id} \
  -H "Authorization: Bearer $API_KEY"

Python SDK

# Get specific case details
case_id = 123
response = await client.get_case(case_id)
case = response.parsed

print(f"Case: {case.name}")
print(f"Description: {case.description}")
print(f"Created: {case.created_at}")
print(f"Organization ID: {case.organization_id}")

CLI

docudevs cases get 123

Updating Cases

cURL

curl -X PUT https://api.docudevs.ai/cases/{case_id} \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q4 2024 Vendor Invoices - Updated",
    "description": "Updated description with additional context"
  }'

Python SDK

from docudevs.models import CasesControllerUpdateCaseRequest

# Update case details

case_id = 123
update_request = CasesControllerUpdateCaseRequest(
    name="Q4 2024 Vendor Invoices - Updated",
    description="Updated description with additional context"
)

response = await client.update_case(case_id, update_request)
updated_case = response.parsed
print(f"Updated case: {updated_case.name}")

CLI

docudevs cases update 123 \
  --name "Q4 2024 Vendor Invoices - Updated" \
  --description "Updated description with additional context"

Deleting Cases

cURL

curl -X DELETE https://api.docudevs.ai/cases/{case_id} \
  -H "Authorization: Bearer $API_KEY"

Python SDK

# Delete a case (this will also delete all associated documents)
case_id = 123
response = await client.delete_case(case_id)

if response.status_code == 204:
    print("Case deleted successfully")

CLI

docudevs cases delete 123

warning

Deleting a case will also delete all documents associated with that case. This action cannot be undone.

Document Management within Cases

Uploading Documents to Cases

cURL

curl -X POST https://api.docudevs.ai/cases/{case_id}/documents \
  -H "Authorization: Bearer $API_KEY" \
  -F "document=@invoice_001.pdf"

Python SDK

from docudevs.models import UploadCaseDocumentBody
from docudevs.types import File

# First, create a case (required before uploading documents)

from docudevs.models import CasesControllerCreateCaseRequest

case_request = CasesControllerCreateCaseRequest(
    name="My Invoice Case",
    description="Documents for invoice processing"
)
case_response = await client.create_case(case_request)
case = case_response.parsed
case_id = case.id
print(f"Created case ID: {case_id}")

# Now upload a document to the case

with open("invoice_001.pdf", "rb") as f:
    file_data = f.read()

body = UploadCaseDocumentBody(
    document=File(payload=file_data, file_name="invoice_001.pdf")
)
response = await client.upload_case_document(case_id=case_id, body=body)

document = response.parsed
print(f"Uploaded document {document.document_id} to case {case_id}")
print(f"Status: {document.processing_status}")

CLI

docudevs cases upload-document 123 invoice_001.pdf

Listing Documents in a Case

cURL

# List documents with pagination
curl -X GET "https://api.docudevs.ai/cases/{case_id}/documents?page=0&size=20" \
  -H "Authorization: Bearer $API_KEY"

Python SDK

# List all documents in a case with pagination
case_id = 123
page = 0
size = 20

response = await client.list_case_documents(
    case_id=case_id,
    page=page,
    size=size
)

documents_page = response.parsed
print(f"Total documents: {documents_page.total_elements}")
print(f"Current page: {documents_page.number}/{documents_page.total_pages}")

for document in documents_page.content:
    print(f"Document: {document.filename}")
    print(f"  ID: {document.document_id}")
    print(f"  Status: {document.processing_status}")
    print(f"  Size: {document.size_bytes} bytes")
    print(f"  Uploaded: {document.created_at}")

CLI

docudevs cases list-documents 123 --page 0 --size 20

Getting Document Details

cURL

curl -X GET https://api.docudevs.ai/cases/{case_id}/documents/{document_id} \
  -H "Authorization: Bearer $API_KEY"

Python SDK

# Get specific document details
case_id = 123
document_id = "doc-uuid-here"

response = await client.get_case_document(case_id, document_id)
document = response.parsed

print(f"Document: {document.filename}")
print(f"Content Type: {document.content_type}")
print(f"Processing Status: {document.processing_status}")
print(f"Metadata: {document.metadata}")

CLI

docudevs cases get-document 123 doc-uuid-here

Deleting Documents from Cases

cURL

curl -X DELETE https://api.docudevs.ai/cases/{case_id}/documents/{document_id} \
  -H "Authorization: Bearer $API_KEY"

Python SDK

# Delete a document from a case
case_id = 123
document_id = "doc-uuid-here"

response = await client.delete_case_document(case_id, document_id)

if response.status_code == 204:
    print("Document deleted successfully")

CLI

docudevs cases delete-document 123 doc-uuid-here

User vs Organization Scope

Cases support two levels of scope:

Organization-wide Cases

• Created by: Any user in the organization
• Visible to: All users in the organization
• Use case: Shared projects, company-wide document processing

User-specific Cases

• Created by: A specific user
• Visible to: Only the creating user (and organization admins)
• Use case: Personal projects, user-specific workflows

The scope is automatically determined based on your API key and user context when creating cases.

Processing Status Tracking

Each document in a case tracks its processing status:

• PENDING: Document uploaded, waiting to be processed
• PROCESSING: Document is currently being processed
• COMPLETED: Processing completed successfully
• FAILED: Processing failed due to an error

You can monitor processing progress by checking the processing_status field when listing documents.

Integration with Document Processing

Documents uploaded to cases can be processed just like standalone documents:

from docudevs.models import CasesControllerCreateCaseRequest, UploadCaseDocumentBody
from docudevs.types import File
import json

# Step 1: Create a case first
case_request = CasesControllerCreateCaseRequest(
    name="Contract Review",
    description="Contract documents for review"
)
case_response = await client.create_case(case_request)
case = case_response.parsed
case_id = case.id

# Step 2: Upload document to case
with open("contract.pdf", "rb") as f:
    document_data = f.read()

upload_body = UploadCaseDocumentBody(
    document=File(payload=document_data, file_name="contract.pdf")
)
upload_response = await client.upload_case_document(case_id=case_id, body=upload_body)
document = upload_response.parsed

print(f"Uploaded document {document.document_id} to case {case_id}")

note

Case documents are stored and organized within the case. To process them with AI extraction, you would process them separately using the standard document processing API with submit_and_process_document().

Best Practices

Case Organization

• Use descriptive names that clearly indicate the case purpose
• Include relevant dates in case names (e.g., "Q4 2024 Invoices")
• Add detailed descriptions for complex cases
• Use consistent naming conventions across your organization

Document Management

• Upload documents immediately when they become available
• Check processing status regularly for large batches
• Use meaningful filenames that help identify document contents
• Include metadata in document uploads when relevant

Performance Optimization

• Batch upload multiple documents to the same case when possible
• Monitor processing status to avoid overwhelming the system
• Use pagination when listing large numbers of documents
• Delete unnecessary cases to keep your workspace organized

Error Handling

Always implement proper error handling when working with cases:

try:
    response = await client.create_case(case_data)
    case = response.parsed
    print(f"Created case: {case.id}")
except Exception as e:
    print(f"Error creating case: {e}")
    # Handle error appropriately

try:
    response = await client.upload_case_document(case_id, document_data, filename)
    document = response.parsed
    print(f"Uploaded document: {document.document_id}")
except Exception as e:
    print(f"Error uploading document: {e}")
    # Handle error appropriately

What's Next?

• Learn about Job Management for cleanup and data retention
• Learn about Operations for advanced document processing workflows
• Explore Named Configurations for consistent processing settings
• Check out Use Cases for real-world implementation examples
• Review Best Practices for production deployment guidelines