Documents API

Upload, process, and manage documents through the API.

Upload Document

Upload a document for processing.

POST /documents

Request Body

{
  "file": "base64-encoded-file-content",
  "filename": "invoice.pdf",
  "contentType": "application/pdf",
  "type": "invoice|bol|packing_list|commercial_invoice|customs_declaration",
  "metadata": {
    "customer_id": "12345",
    "po_number": "PO-2024-001"
  },
  "webhookUrl": "https://your-app.com/webhook",
  "priority": "low|normal|high",
  "templateId": "tpl_abc123"
}

Response

{
  "success": true,
  "data": {
    "id": "doc_abc123",
    "filename": "invoice.pdf",
    "type": "invoice",
    "status": "processing",
    "fileSize": 245760,
    "pages": 3,
    "language": "en",
    "uploadedBy": "user@company.com",
    "priority": "normal",
    "metadata": {
      "customer_id": "12345",
      "po_number": "PO-2024-001"
    },
    "processingStartedAt": "2024-01-15T10:30:00Z",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Get Document

Retrieve document details and extracted data.

GET /documents/{id}

Query Parameters

Parameter	Type	Description
`include`	string	Additional data to include (metadata, permissions, history)

Response

{
  "success": true,
  "data": {
    "id": "doc_abc123",
    "filename": "invoice.pdf",
    "type": "invoice",
    "status": "completed",
    "fileSize": 245760,
    "pages": 3,
    "language": "en",
    "confidence": 0.94,
    "templateId": "tpl_invoice_001",
    "templateName": "Standard Invoice Template",
    "extractedData": {
      "invoice_number": "INV-2024-001",
      "invoice_date": "2024-01-15",
      "due_date": "2024-02-15",
      "total_amount": 15000.00,
      "tax_amount": 1500.00,
      "currency": "USD",
      "vendor": {
        "name": "ABC Logistics",
        "address": "123 Main St, New York, NY 10001",
        "email": "billing@abclogistics.com"
      },
      "customer": {
        "name": "Acme Corp",
        "address": "456 Oak Ave, Los Angeles, CA 90001"
      },
      "line_items": [
        {
          "description": "Ocean Freight - Container #ABCD123456",
          "quantity": 1,
          "unit_price": 12000.00,
          "total": 12000.00
        },
        {
          "description": "Documentation Fee",
          "quantity": 1,
          "unit_price": 3000.00,
          "total": 3000.00
        }
      ]
    },
    "confidenceScores": {
      "overall": 0.94,
      "fields": {
        "invoice_number": 0.99,
        "total_amount": 0.91,
        "vendor_name": 0.96,
        "line_items": 0.89
      }
    },
    "processingTime": "2.3s",
    "metadata": {
      "customer_id": "12345",
      "po_number": "PO-2024-001"
    },
    "uploadedBy": "user@company.com",
    "createdAt": "2024-01-15T10:30:00Z",
    "completedAt": "2024-01-15T10:31:00Z",
    "updatedAt": "2024-01-15T10:31:00Z"
  }
}

List Documents

Retrieve documents with filtering and pagination.

GET /documents

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status (processing, completed, failed, review_required)
`type`	string	Filter by document type
`templateId`	string	Filter by template ID
`uploadedBy`	string	Filter by uploader email
`fromDate`	string	Filter documents created after this date (ISO 8601)
`toDate`	string	Filter documents created before this date (ISO 8601)
`confidence`	number	Minimum confidence score (0.0 - 1.0)
`hasErrors`	boolean	Filter documents with/without errors
`search`	string	Search in filename or extracted text
`sortBy`	string	Sort by field (createdAt, updatedAt, confidence, filename)
`sortOrder`	string	Sort order (asc, desc)
`limit`	integer	Number of results (max 100)
`offset`	integer	Pagination offset

Response

{
  "success": true,
  "data": {
    "documents": [
      {
        "id": "doc_abc123",
        "filename": "invoice.pdf",
        "type": "invoice",
        "status": "completed",
        "confidence": 0.94,
        "templateName": "Standard Invoice Template",
        "extractedFields": 8,
        "processingTime": "2.3s",
        "uploadedBy": "user@company.com",
        "createdAt": "2024-01-15T10:30:00Z",
        "completedAt": "2024-01-15T10:31:00Z"
      },
      {
        "id": "doc_xyz789",
        "filename": "bol_container.pdf",
        "type": "bol",
        "status": "review_required",
        "confidence": 0.76,
        "templateName": "Ocean BOL Template",
        "extractedFields": 12,
        "processingTime": "3.1s",
        "reviewReason": "Low confidence on container numbers",
        "uploadedBy": "ops@company.com",
        "createdAt": "2024-01-14T15:45:00Z",
        "completedAt": "2024-01-14T15:48:00Z"
      }
    ],
    "pagination": {
      "limit": 10,
      "offset": 0,
      "total": 42,
      "totalPages": 5
    },
    "summary": {
      "totalDocuments": 42,
      "completed": 38,
      "processing": 2,
      "reviewRequired": 2,
      "failed": 0,
      "averageConfidence": 0.91
    }
  }
}

Update Document

Update document metadata or reprocess.

PATCH /documents/{id}

Request Body

{
  "type": "commercial_invoice",
  "templateId": "tpl_def456",
  "metadata": {
    "customer_id": "67890",
    "po_number": "PO-2024-100",
    "priority": "urgent"
  },
  "reprocess": true,
  "forceTemplate": false
}

Response

{
  "success": true,
  "data": {
    "id": "doc_abc123",
    "status": "processing",
    "type": "commercial_invoice",
    "templateId": "tpl_def456",
    "metadata": {
      "customer_id": "67890",
      "po_number": "PO-2024-100",
      "priority": "urgent"
    },
    "reprocessingStartedAt": "2024-01-15T11:00:00Z",
    "updatedAt": "2024-01-15T11:00:00Z"
  }
}

Delete Document

Permanently delete a document and its data.

DELETE /documents/{id}

Query Parameters

Parameter	Type	Description
`reason`	string	Reason for deletion (optional)

Response

{
  "success": true,
  "message": "Document deleted successfully",
  "data": {
    "id": "doc_abc123",
    "filename": "invoice.pdf",
    "deletedBy": "admin@company.com",
    "deletedAt": "2024-01-15T11:30:00Z",
    "reason": "Customer request"
  }
}

Download Document

Get the original document file or processed version.

GET /documents/{id}/download

Query Parameters

Parameter	Type	Description
`version`	string	Version to download (original, processed, annotated)
`format`	string	Output format (pdf, json, csv, xlsx)

Response

{
  "success": true,
  "data": {
    "downloadUrl": "https://files.flint.com/documents/doc_abc123/original.pdf?token=xyz789",
    "filename": "invoice.pdf",
    "contentType": "application/pdf",
    "fileSize": 245760,
    "expiresAt": "2024-01-15T12:30:00Z"
  }
}

Get Document History

Retrieve processing and modification history.

GET /documents/{id}/history

Response

{
  "success": true,
  "data": {
    "documentId": "doc_abc123",
    "events": [
      {
        "id": "evt_001",
        "type": "document.uploaded",
        "user": "user@company.com",
        "timestamp": "2024-01-15T10:30:00Z",
        "details": {
          "filename": "invoice.pdf",
          "fileSize": 245760
        }
      },
      {
        "id": "evt_002",
        "type": "processing.started",
        "templateId": "tpl_abc123",
        "templateName": "Standard Invoice Template",
        "timestamp": "2024-01-15T10:30:15Z"
      },
      {
        "id": "evt_003",
        "type": "processing.completed",
        "confidence": 0.94,
        "extractedFields": 8,
        "processingTime": "2.3s",
        "timestamp": "2024-01-15T10:31:00Z"
      },
      {
        "id": "evt_004",
        "type": "document.reviewed",
        "user": "reviewer@company.com",
        "action": "approved",
        "timestamp": "2024-01-15T14:20:00Z",
        "notes": "All data verified and approved"
      }
    ]
  }
}

Batch Upload

Upload multiple documents at once.

POST /documents/batch

Request Body

{
  "documents": [
    {
      "filename": "invoice1.pdf",
      "file": "base64-encoded-content",
      "type": "invoice",
      "metadata": {"customer_id": "123"}
    },
    {
      "filename": "bol1.pdf",
      "file": "base64-encoded-content",
      "type": "bol",
      "metadata": {"shipment_id": "SHIP001"}
    }
  ],
  "webhookUrl": "https://your-app.com/webhook",
  "priority": "normal"
}

Response

{
  "success": true,
  "data": {
    "batchId": "batch_xyz789",
    "status": "processing",
    "documentsCount": 2,
    "documents": [
      {
        "id": "doc_abc123",
        "filename": "invoice1.pdf",
        "status": "processing"
      },
      {
        "id": "doc_def456",
        "filename": "bol1.pdf",
        "status": "processing"
      }
    ],
    "submittedAt": "2024-01-15T10:30:00Z",
    "estimatedCompletion": "2024-01-15T10:33:00Z"
  }
}

Get Batch Status

Check status of batch upload.

GET /documents/batch/{batchId}

Response

{
  "success": true,
  "data": {
    "batchId": "batch_xyz789",
    "status": "completed",
    "documentsCount": 2,
    "completedCount": 2,
    "failedCount": 0,
    "processingTime": "2m 45s",
    "documents": [
      {
        "id": "doc_abc123",
        "filename": "invoice1.pdf",
        "status": "completed",
        "confidence": 0.95,
        "processingTime": "2.1s"
      },
      {
        "id": "doc_def456",
        "filename": "bol1.pdf",
        "status": "completed",
        "confidence": 0.89,
        "processingTime": "3.2s"
      }
    ],
    "submittedAt": "2024-01-15T10:30:00Z",
    "completedAt": "2024-01-15T10:32:45Z"
  }
}

Search Documents

Advanced search across document content.

POST /documents/search

Request Body

{
  "query": "Acme Corp invoice amount > 1000",
  "filters": {
    "type": ["invoice", "commercial_invoice"],
    "status": ["completed"],
    "dateRange": {
      "from": "2024-01-01",
      "to": "2024-01-31"
    },
    "confidence": {
      "min": 0.8
    }
  },
  "sortBy": "relevance",
  "limit": 20,
  "offset": 0
}

Response

{
  "success": true,
  "data": {
    "results": [
      {
        "id": "doc_abc123",
        "filename": "acme_invoice_001.pdf",
        "type": "invoice",
        "relevanceScore": 0.95,
        "matchedFields": ["vendor_name", "total_amount"],
        "highlights": {
          "vendor_name": "**Acme Corp**",
          "total_amount": "**$15,000.00**"
        },
        "extractedData": {
          "vendor_name": "Acme Corp",
          "total_amount": 15000.00
        },
        "createdAt": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "limit": 20,
      "offset": 0,
      "total": 5
    },
    "aggregations": {
      "totalAmount": 75000.00,
      "averageAmount": 15000.00,
      "documentTypes": {
        "invoice": 4,
        "commercial_invoice": 1
      }
    }
  }
}

Document Analytics

Get analytics for document processing.

GET /documents/analytics

Query Parameters

Parameter	Type	Description
`period`	string	Time period (7d, 30d, 90d, 1y)
`type`	string	Filter by document type
`groupBy`	string	Group results by (day, week, month, type, user)

Response

{
  "success": true,
  "data": {
    "period": "30d",
    "summary": {
      "totalDocuments": 1250,
      "averageConfidence": 0.91,
      "averageProcessingTime": "2.4s",
      "successRate": 0.94,
      "reviewRate": 0.06
    },
    "trends": {
      "documentsPerDay": [
        {"date": "2024-01-15", "count": 45, "avgConfidence": 0.92},
        {"date": "2024-01-14", "count": 38, "avgConfidence": 0.89}
      ]
    },
    "breakdown": {
      "byType": {
        "invoice": {"count": 650, "percentage": 52.0, "avgConfidence": 0.94},
        "bol": {"count": 400, "percentage": 32.0, "avgConfidence": 0.88},
        "commercial_invoice": {"count": 200, "percentage": 16.0, "avgConfidence": 0.91}
      },
      "byStatus": {
        "completed": {"count": 1175, "percentage": 94.0},
        "review_required": {"count": 75, "percentage": 6.0}
      }
    },
    "performance": {
      "processingTimes": {
        "p50": "1.8s",
        "p95": "6.2s",
        "p99": "15.4s"
      },
      "confidenceDistribution": {
        "high": {"range": "0.9-1.0", "count": 875, "percentage": 70.0},
        "medium": {"range": "0.7-0.9", "count": 300, "percentage": 24.0},
        "low": {"range": "0.0-0.7", "count": 75, "percentage": 6.0}
      }
    }
  }
}

Document Status Values

uploading - File being uploaded
processing - OCR and extraction in progress
completed - Processing finished successfully
review_required - Manual review needed
approved - Reviewed and approved
rejected - Reviewed and rejected
failed - Processing failed due to error

Document Types

invoice - Commercial invoices
bol - Bills of lading
packing_list - Packing lists
commercial_invoice - Commercial invoices for customs
customs_declaration - Customs declarations
certificate - Certificates and permits
contract - Contracts and agreements

Error Codes

Code	Description
`DOCUMENT_NOT_FOUND`	Document ID doesn't exist
`INVALID_DOCUMENT_TYPE`	Unsupported document type
`FILE_TOO_LARGE`	Document exceeds size limit (50MB)
`INVALID_FILE_FORMAT`	Unsupported file format
`PROCESSING_ERROR`	Error during document processing
`TEMPLATE_NOT_APPLICABLE`	Template cannot be used for this document
`INSUFFICIENT_PERMISSIONS`	No permission to access document
`DOCUMENT_LOCKED`	Document is being processed or reviewed
`BATCH_NOT_FOUND`	Batch ID doesn't exist
`SEARCH_QUERY_INVALID`	Invalid search query format

Documents API

On this page