Upload API

PreviousNext

Programmatically upload documents for AI extraction via the Doc-Vision REST API - supports PDF, images, and spreadsheets

Overview

DocVision provides a webhook endpoint that allows you to programmatically upload documents via HTTP POST requests. This is ideal for integrating with external systems, automated workflows, or custom applications.

How It Works

When you send a document to your webhook URL:

  1. Authentication - Request is validated using your webhook secret (if configured)
  2. File Upload - Document is uploaded to secure storage
  3. Pre-processing - Spreadsheet files (Excel, CSV) are automatically converted to CSV text format
  4. Document Processing - The document goes through the standard pipeline:
    • Classification
    • Folder assignment
    • Data extraction
    • Indexing for search

Webhook URL Format

POST https://app.doc-vision.com/api/webhook/{webhookId}/document/upload

Where {webhookId} is your unique webhook identifier.

Example:

POST https://app.doc-vision.com/api/webhook/abc123xyz/document/upload

API Reference

Endpoint

POST /api/webhook/{webhookId}/document/upload

Authentication

If a webhook secret is configured, include it in the Authorization header:

Authorization: {your-webhook-secret}

Request Formats

You can send documents in three ways:

Fetch files from a remote URL. The system will download the file automatically. This is the recommended method for better reliability.

curl -X POST https://app.doc-vision.com/api/webhook/{webhookId}/document/upload \
  -H "Authorization: {your-webhook-secret}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/documents/invoice.pdf"
  }'

Request Parameters:

FieldTypeRequiredDescription
urlStringYesHTTP/HTTPS URL to fetch file from
fileNameStringNoFilename (inferred from URL or Content-Disposition header if not provided)
contentTypeStringNoMIME type (inferred from extension or Content-Type header if not provided)

Response Format

Success Response (200):

{
  "success": true,
  "message": "Document uploaded successfully",
  "documentId": "doc_abc123xyz"
}

Error Responses:

  • 401 Unauthorized - Invalid or missing webhook secret
  • 404 Not Found - Invalid webhook ID
  • 400 Bad Request - Missing or invalid file data, unsupported file type, or unable to determine content type

Example Error Response:

{
  "success": false,
  "error": "Unable to determine content type. Please provide 'contentType' in the request body or ensure the file has a recognized extension."
}

Supported File Types

  • PDF documents - Invoices, receipts, bank statements, etc.
  • Image files - JPG, JPEG, PNG, GIF, WebP, TIFF
  • Spreadsheet files - Excel (XLS, XLSX, XLSM) and CSV files (automatically converted to CSV text)

Code Examples

async function uploadDocumentFromUrl(
  url: string,
  webhookId: string,
  secret: string
) {
  const response = await fetch(
    `https://app.doc-vision.com/api/webhook/${webhookId}/document/upload`,
    {
      method: 'POST',
      headers: {
        'Authorization': secret,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        url: url,
      }),
    }
  );

  const result = await response.json();
  return result.documentId;
}

Troubleshooting

401 Unauthorized

  • Verify your webhook secret matches the one in Organization Settings
  • Ensure the Authorization header is included in the request
  • Check that the secret doesn't have extra spaces or characters

404 Not Found

  • Verify the webhook ID in your URL matches the one in Organization Settings
  • Ensure you're using the correct endpoint path: /api/webhook/{webhookId}/document/upload
  • Check that you're using the correct base URL (https://app.doc-vision.com)

400 Bad Request

  • Verify the file is a supported format (PDF, image, or spreadsheet)
  • Check that the file data is properly formatted
  • Ensure required fields (file or url) are included
  • If using JSON, verify the base64 encoding is correct
  • Check that the URL is accessible and returns a valid file (for URL-based uploads)
  • Ensure content type can be determined (provide contentType if needed)

Upload + Polling Pattern

After uploading a document, you'll need to poll the Get API to check when processing is complete and retrieve the extracted data. See the Upload + Polling Example for complete implementation details and code examples.

Frequently Asked Questions

What file size limits apply?

URL-based uploads support files up to 50MB. For multipart uploads, the limit is the same. If you need to process larger files, split multi-page PDFs into smaller batches.

How long does processing take?

Average processing time is 30 seconds per page. The upload endpoint returns immediately with a documentId - extraction happens asynchronously in the background.

Which upload method should I use?

URL uploads (recommended) are the most reliable. The server fetches the file directly, avoiding client-side timeouts for large files. Use multipart for direct file uploads from forms or file systems. Use base64 only when you need to embed file data in a JSON payload.

Can I specify the document type on upload?

The AI automatically classifies uploaded documents based on your configured Extraction Templates. You don't need to specify the document type - the system determines it automatically.

What happens if I upload a duplicate?

Each upload creates a new document with a unique ID. The system does not deduplicate automatically. Implement duplicate detection in your application if needed.

Next Steps