Uploading Documents

Sources are the entry point for all data in Talonic. Every document belongs to a source — whether uploaded manually, synced from Google Drive, or ingested via the public API. A source acts as a container that groups related documents together and tracks their ingestion method, processing status, and connection credentials. Manual uploads land in your workspace's upload source automatically, while connectors and dedicated-key API sources each keep their own source so you can tell channels apart.

Uploads happen on the Documents page: open Documents in the sidebar and drop files onto the upload zone at the top of the list. You can upload individual files, multiple files, or entire folders. ZIP archives are unpacked recursively — nested ZIPs are also extracted, so deeply packaged archives are handled automatically. When uploading folders, the original file path is preserved as a data field (source_file_path) on each document — available for downstream processing and export.

Files are deduplicated via SHA-256 hashing — uploading the same file twice won't create duplicates. The hash is computed from the raw file bytes before any processing begins, so identical files are caught regardless of filename or upload method. Processing runs asynchronously so you can continue working while documents flow through OCR, classification, and extraction in the background.

When uploading folders or ZIP archives, the original directory structure is preserved as a source_file_path metadata field on each document (e.g., contracts/2026/lease.pdf). This field is available for filtering, export, and schema mapping — just like any AI-extracted field. It provides a natural way to organize and trace documents back to their original location in your file system.

Upload Workflow

1. Open Documents in the sidebar. The upload zone sits at the top of the document list.
2. Optionally type one or more tags into the small Tag this upload composer in the zone's top-right corner. Every file in the upload carries those tags.
3. Drag files, folders, or ZIP archives onto the zone, or click browse to pick them.
4. Watch the progress line and the Status dot on each new row: gray for queued, a pulsing purple for processing, green for done, amber for partial, red for failed. Hover a dot to see the full legend.
5. Once processing completes, each document shows its classification pills and extracted fields. Open a row to see the document detail view.

The Sources sidebar entry is retired. Connectors, dedicated-key API sources, and their access rules now open from the Sources button in the Documents page header, and the /sources route still works if you have it bookmarked. Reference data has its own Reference Data tab beside the document list, so lookup tables you check documents against live next to the documents themselves. Upload tags are ordinary document tags: they appear in the Tags column and in the filter bar's tag cloud, which makes them a quick way to find one upload again later.

Large uploads (100+ files) are throttled to avoid overloading the pipeline, but you can monitor progress from the Documents list where each document shows its current processing stage. For very large ingestion jobs, consider using batch processing mode which defers AI extraction to run at 50% cost. You can also combine manual uploads with source connectors — for example, uploading a backlog of historical files manually while connecting Google Drive for ongoing ingestion.

Uploading via API

For automated ingestion pipelines, you can upload documents programmatically through the REST API. The upload endpoint accepts multipart form data with the file and optional metadata. Each uploaded document flows through the same processing pipeline as manual uploads — OCR, classification, and extraction run automatically. You can optionally set processing_mode=batch to defer extraction at 50% cost for non-urgent documents.

curl -X POST https://api.talonic.com/v1/sources/src_abc123/documents \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -F "file=@invoice.pdf" \
  -F "processing_mode=realtime"

{
  "document_id": "doc_7f3a1b2c",
  "filename": "invoice.pdf",
  "status": "queued",
  "processing_mode": "realtime",
  "source_id": "src_abc123"
}

curl https://api.talonic.com/v1/documents?source_id=src_abc123 \
  -H "Authorization: Bearer $TALONIC_API_KEY"

When integrating with external systems, a common pattern is to upload documents via the API and then configure a webhook to receive notifications when extraction completes. This avoids the need to poll for status updates and lets your downstream system react immediately when structured data is available. The document.extracted webhook signal fires as soon as all fields have been captured and the document status transitions to completed.

For batch ingestion scenarios, set processing_mode=batch when uploading to defer AI extraction and process at 50% cost. Batch mode runs OCR and classification immediately but queues the extraction step for deferred processing with a 48-hour delivery window. This is ideal for historical document backlogs where immediate results are not required. You can mix batch and realtime uploads within the same source — each document's processing mode is independent.