Case: API Integration & Workflow Guide

Welcome to the developer integration guide for Docsumo. This document outlines how to programmatically interact with Docsumo's case APIs to manage document processing cases, search files, retrieve artifacts, update workflow stages, and capture real-time updates.

🔑 Authentication & Headers

All API calls to the Docsumo platform require authentication. You must pass your private credentials in the request headers.

[!WARNING]
Never expose your API keys in frontend code, public repositories, or client-side environments. Always proxy Docsumo API requests through a secure backend service.

📁 1. Case & Document Management

Docsumo organizes document extraction around Cases and Case Types. You can upload multiple files to initiate a case, list active cases, append documents to existing cases, or update case attributes.

A. Create a New Case & Upload Files

To submit new documents for extraction and create a new case container simultaneously, use this endpoint.

• Endpoint: POST https://app.docsumo.com/api/v1/upload-service/agents/casetype/case
• Content-Type: multipart/form-data
• Official Reference: 🔗 Upload Case

Request Parameters

cURL Example

curl --request POST \
  --url https://app.docsumo.com/api/v1/upload-service/agents/casetype/case \
  --header 'accept: application/json' \
  --header 'content-type: multipart/form-data' \
  --header 'x-api-key: YOUR_SECURE_API_KEY' \
  --form 'trigger_workflow=false' \
  --form 'casetype_id=casetype__d1t5b' \
  --form 'files=@/path/to/invoice_1.pdf' \
  --form 'files=@/path/to/invoice_2.pdf'

Sample Response

{
  "status": "success",
  "status_code": 200,
  "message": "File upload successful",
  "data": {
    "case_id": "case__06c93accde6d445286518079268d45a3",
    "casetype_id": "casetype__d1t5b",
    "documents": [
      {
        "doc_id": "doc__71a76c8c",
        "filename": "invoice_1.pdf",
        "status": "uploaded"
      },
      {
        "doc_id": "doc__a4b3d82f",
        "filename": "invoice_2.pdf",
        "status": "uploaded"
      }
    ]
  }
}

B. List All Cases

Retrieve lists of cases to monitor status, extraction results, and ingest timelines.

• Endpoint: GET https://app.docsumo.com/api/v1/external/agents/{casetype_id}/cases
• Authentication Header: x-api-key (or apikey)
• Official Reference: 🔗 Docsumo API Support - Get Cases List

Path Parameters

• casetype_id (string, required): The unique identifier of the case type (e.g., casetype__d1t5b).

Query Parameters

cURL Example

curl --request GET \
  --url 'https://app.docsumo.com/api/v1/external/agents/casetype__d1t5b/cases?limit=5&sort_by=created_date.desc' \
  --header 'accept: application/json' \
  --header 'x-api-key: YOUR_SECURE_API_KEY'

Sample Response

{
  "status": "success",
  "status_code": 200,
  "data": {
    "cases": [
      {
        "case_id": "case__06c93accde6d445286518079268d45a3",
        "case_name": "Invoice Batch A",
        "stage_id": "stage__extraction",
        "status": "processing",
        "created_date": "2026-05-20T10:15:00Z",
        "modified_date": "2026-05-20T10:16:30Z",
        "assigned_to": "user__982bc"
      }
    ],
    "total_count": 142
  }
}

C. Upload Document to a Case Already Present

To add supplementary files or new document versions to a case that has already been created, use the same upload endpoint but include the case_id form field parameter.

• Endpoint: POST https://app.docsumo.com/api/v1/upload-service/agents/casetype/case
• Content-Type: multipart/form-data
• Official Reference: 🔗 Docsumo API Support - Upload to Case

Request Parameters

cURL Example

curl --request POST \
  --url https://app.docsumo.com/api/v1/upload-service/agents/casetype/case \
  --header 'accept: application/json' \
  --header 'content-type: multipart/form-data' \
  --header 'x-api-key: YOUR_SECURE_API_KEY' \
  --form 'casetype_id=casetype__d1t5b' \
  --form 'case_id=case__06c93accde6d445286518079268d45a3' \
  --form 'files=@/path/to/additional_document.pdf'

Sample Response

{
  "status": "success",
  "status_code": 200,
  "message": "File successfully appended to case",
  "data": {
    "case_id": "case__06c93accde6d445286518079268d45a3",
    "casetype_id": "casetype__d1t5b",
    "documents": [
      {
        "doc_id": "doc__bf38c21a",
        "filename": "additional_document.pdf",
        "status": "uploaded"
      }
    ]
  }
}

D. Update Case Status & Properties

To modify the attributes of an existing case—such as assigning it to a new workflow stage, modifying the assignee, or changing the display name—send a PATCH request.

• Endpoint: PATCH https://app.docsumo.com/api/v1/external/agents/{casetype_id}/case/{case_id}
• Content-Type: application/json
• Official Reference: 🔗 Docsumo API Support - Update Case Status

Path Parameters

• casetype_id (string, required): The unique identifier of the case type (e.g., casetype__d1t5b).
• case_id (string, required): The unique identifier of the case (e.g., case__06c93accde6d445286518079268d45a3).

Request Body Schema (JSON)

cURL Example

curl --request PATCH \
  --url https://app.docsumo.com/api/v1/external/agents/casetype__d1t5b/case/case__06c93accde6d445286518079268d45a3 \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_SECURE_API_KEY' \
  --data '{
    "stage_id": "stage__review",
    "assigned_to": "user__081ad",
    "case_name": "Updated Invoice Batch A"
  }'

Sample Response

{
  "status": "success",
  "status_code": 200,
  "message": "Case updated successfully",
  "data": {
    "case_id": "case__06c93accde6d445286518079268d45a3",
    "casetype_id": "casetype__d1t5b",
    "case_name": "Updated Invoice Batch A",
    "stage_id": "stage__review",
    "assigned_to": "user__081ad",
    "modified_date": "2026-05-20T10:22:15Z"
  }
}

⚡ 2. The Artifact & File Download Flow (Multi-Step)

Retrieving completed files or extracted text artifacts from cases is structured as a robust three-step process to ensure secure, queryable, and authenticated access.

sequenceDiagram
    autonumber
    participant Client as Integration Client
    participant Docsumo as Docsumo Server (app.docsumo.com)
    participant CloudStorage as Secure Cloud Storage
    
    Client->>Docsumo: 1. Search Files in Case<br/>(GET /cases/{case_id}/files?q=email)
    Docsumo-->>Client: Returns list of file IDs & metadata
    
    Client->>Docsumo: 2. Request Download URL<br/>(GET /cases/{case_id}/chat/artifacts/{file_id}/url?download=true)
    Docsumo-->>Client: Returns secure Signed URL & filename
    
    Client->>CloudStorage: 3. Download File<br/>(GET to Secure Cloud Storage)
    CloudStorage-->>Client: Streams file content (.pdf, .json, etc.)

Step 1: Query and Find the File

Search inside a specific case to find the exact artifact or file you wish to download. You can filter artifacts using search queries (e.g., querying for "email.pdf").

• Endpoint: GET https://app.docsumo.com/api/v1/chatot/cases/{case_id}/files?q={query}
• Example: GET https://app.docsumo.com/api/v1/chatot/cases/case__06c93accde6d445286518079268d45a3/files?q=email

Response Shape

[
  {
    "id": "6a0cd728051fa766f81f5b7d",
    "filename": "email.pdf",
    "status": "processed",
    "created_at": "2026-05-20T10:15:00Z"
  }
]

(Extract the specific file id from this response payload to proceed to Step 2.)

Step 2: Generate the Download URL

Use the Case ID and the File ID retrieved in Step 1 to request a secure, temporary download URL.

• Endpoint: GET https://app.docsumo.com/api/v1/chatot/cases/{case_id}/chat/artifacts/{file_id}/url?download=true
• Example: GET https://app.docsumo.com/api/v1/chatot/cases/case__06c93accde6d445286518079268d45a3/chat/artifacts/6a0cd728051fa766f81f5b7d/url?download=true

Response Shape

{
    "status": "success",
    "status_code": 200,
    "message": "Download URL generated",
    "data": {
        "filename": "email.pdf",
        "url": "https://storage.googleapis.com/docsumo-cases-testing/662a769a7eb2d66ce4a101fc/case__06c93accde6d445286518079268d45a3/artifacts//d5dddf43_email.pdf"
    }
}

Step 3: Stream and Save the File

Perform an HTTP GET request to the exact URL returned in the "url" field from Step 2's JSON response to download the actual raw file.

Bash/cURL Example

curl -o "email.pdf" "https://storage.googleapis.com/docsumo-cases-testing/662a769a7eb2d66ce4a101fc/case__06c93accde6d445286518079268d45a3/artifacts//d5dddf43_email.pdf"

Node.js / Javascript Code Example

const fs = require('fs');
const https = require('https');

function downloadFile(url, destPath) {
  const file = fs.createWriteStream(destPath);
  https.get(url, (response) => {
    response.pipe(file);
    file.on('finish', () => {
      file.close();
      console.log(`Download completed successfully: ${destPath}`);
    });
  }).on('error', (err) => {
    fs.unlink(destPath, () => {});
    console.error(`Error downloading file: ${err.message}`);
  });
}

🪝 3. Webhooks & Real-time Synchronization

To avoid polling Docsumo APIs for file or data updates, you can register Webhooks to capture events instantly.

Whenever a user manually interacts with or changes case stage in ui or when Docsumo's workflow finalize changes, a webhook notification is automatically pushed to your registered endpoint.

How Webhooks Work

1. User action/System update: An operator change status inside the Docsumo UI , or background data processing changes.
2. Payload Delivery: Docsumo pushes a JSON payload containing the updated metadata, case ID, state changes, and related documents.
3. Immediate Download: You can use the incoming webhook payload to automatically trigger the Artifact & File Download Flow (detailed in Section 2) to download the freshly generated file and keep your downstream systems fully in sync.

[!TIP]
Key Integration Flow: When your webhook listener receives a payload indicating a file update or state of change:

1. Read the case_id from the payload.
2. Query the files endpoint (Step 1).
3. Generate a download URL (Step 2).
4. Fetch the document (Step 3) to update your local databases or document stores.