Upload, manage, and organize documents within your Well organization with comprehensive metadata and AI-powered processing capabilities.

​
Getting Started

The Documents API allows you to upload files, manage document metadata, and integrate with AI processing workflows for data extraction and analysis.

Upload your first Document

Start by uploading a document with metadata

​
How Document Management Works

  1. Upload documents: Send files with metadata to create document records
  2. Organize content: Add descriptions, categories, and custom metadata
  3. AI Processing: Leverage AI capabilities for content extraction and analysis
  4. Access control: Documents are scoped to your organization for security
  5. Lifecycle management: Track creation, updates, and deletion events

​
Supported File Types

The Well Core API supports various document formats:
  • PDF Documents: .pdf - Ideal for reports, contracts, and formal documents
  • Images: .jpg, .jpeg, .png, .gif - Photos, screenshots, and visual content
  • Office Documents: .docx, .xlsx, .pptx - Microsoft Office files
  • Text Files: .txt, .md, .csv - Plain text and structured data
  • Archives: .zip, .tar - Compressed file collections

​
Quick Start Examples

// Upload a document with metadata
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('data', JSON.stringify({
  type: 'document',
  attributes: {
    name: 'Q4 Financial Report',
    description: 'Quarterly financial analysis and projections',
    category: 'finance',
    tags: ['quarterly', 'finance', '2024']
  }
}));

const uploadResponse = await fetch('https://api.well.com/v1/documents', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`
  },
  body: formData
});

const document = await uploadResponse.json();
console.log('Document uploaded:', document.data.id);

// Get document details  
const getResponse = await fetch(`https://api.well.com/v1/documents/${document.data.id}`, {
  headers: {
    'Authorization': `Bearer ${apiKey}`
  }
});

// List all documents with pagination
const listResponse = await fetch('https://api.well.com/v1/documents?page=1&limit=10', {
  headers: {
    'Authorization': `Bearer ${apiKey}`
  }
});

​
Document Management

Upload Document

Upload files with comprehensive metadata

Get Document

Retrieve specific document details and metadata

List Documents

Browse all documents with pagination and filtering

Delete Document

Remove documents you no longer need

​
Document Response Structure

​
Single Document Response

{
  "data": {
    "type": "document",
    "id": "doc_12345",
    "attributes": {
      "name": "Q4 Financial Report",
      "description": "Quarterly financial analysis and projections",
      "filename": "q4_report.pdf",
      "content_type": "application/pdf",
      "size": 2048576,
      "category": "finance",
      "tags": ["quarterly", "finance", "2024"],
      "upload_url": "https://storage.well.com/documents/doc_12345.pdf",
      "organisation_id": "org_67890",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  }
}

​
Document List Response

{
  "data": [
    {
      "type": "document",
      "id": "doc_12345",
      "attributes": {
        "name": "Q4 Financial Report",
        "filename": "q4_report.pdf",
        "size": 2048576,
        "created_at": "2024-01-15T10:30:00Z"
      }
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 25,
    "total_pages": 3
  }
}

​
AI Integration

Documents can be processed with AI for data extraction and analysis: 
// After uploading a document, process it with AI
const aiResponse = await fetch('https://api.well.com/v1/ai', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${firebaseToken}` // Note: AI uses Firebase auth
  },
  body: JSON.stringify({
    data: {
      type: 'ai-request',
      attributes: {
        html: documentContent,
        mode: 'EXTRACT_DOCUMENT_DATA',
        flow: 'DOCUMENT_PROCESSING',
        flow_id: document.data.id
      }
    }
  })
});

​
Storage & Security

  • Secure Storage: All documents are stored with encryption at rest
  • Access Control: Documents are scoped to your organization
  • Size Limits: Maximum file size is 50MB per document
  • Retention: Documents are retained according to your organization’s policy
  • HTTPS Only: All document URLs use secure HTTPS protocol

​
Webhook Events

Documents trigger webhook events for real-time notifications:
  • document.uploaded - When a new document is successfully uploaded
  • document.processed - When AI processing completes
  • document.updated - When document metadata is modified
  • document.deleted - When a document is permanently removed

​
Best Practices

  1. Use descriptive names to make documents easily searchable
  2. Add comprehensive metadata including categories and tags
  3. Implement pagination when listing large document collections
  4. Handle file size limits by checking before upload
  5. Set up webhooks to track document lifecycle events
  6. Use appropriate file formats for your use case
  7. Store document IDs for future reference and updates