Extraction Overview | Ottimate Developer Documentation

Document extraction is the foundation of Ottimate’s invoice automation platform. Ottimate uses a proprietary AI model trained specifically on invoices and purchase documents to extract structured data from uploaded files. This enables downstream automation including coding, approvals, and ERP synchronization.

How extraction works

The extraction pipeline begins when a document is uploaded to Ottimate. Documents can be uploaded via:

Email forwarding - Send invoices to your dedicated Ottimate inbox
Desktop Upload - Upload invoices to an Ottimate Location via the Dashboard UI
API upload - Upload files programmatically using the POST /v1/invoices/upload endpoint

Supported file formats

Ottimate accepts the following file types:

PDF
JPG / JPEG
PNG

Size limits

Upload path	Limit
`multipart/form-data` (sending the file itself)	10 MiB (10,485,760 bytes) for the whole request body, including form-field overhead
`image_url` (Ottimate downloads the file)	50 MB per file

The 10 MiB multipart limit is enforced at the API gateway, before your request reaches Ottimate. Exceeding it returns a 413 whose body is plain text, not JSON — it does not use Ottimate’s usual error envelope:

HTTP content length exceeded 10485760 bytes.

Do not try to parse this response as JSON. To ingest a file larger than 10 MiB, host it and pass image_url instead of file, which raises the effective limit to 50 MB because only the URL travels in the request body.

Uploads vs. invoices

Understanding the distinction between uploads and invoices is critical when working with the Ottimate API.

When you upload a document to Ottimate, it creates an upload record, not an invoice. The upload represents the raw file awaiting extraction. An invoice is only created after extraction completes and structured data has been captured from the document.

This means:

An upload exists immediately after you submit a file
An invoice only exists after successful extraction
You should poll for upload status to track extraction progress
Once extraction completes, you can retrieve the invoice using the invoice ID

Extraction processing

Extraction is asynchronous. When you upload a document, Ottimate queues it for processing and returns immediately with an upload ID. The actual extraction happens in the background.

Depending on your account configuration during onboarding, uploaded files are processed through one of two pipelines:

AI extraction - Fully automated extraction using Ottimate’s proprietary model. This is the faster option and is suitable for most standard invoice formats.
Human-in-the-loop extraction - A quality-focused pipeline where trained operators verify and correct AI-extracted data. This option provides higher accuracy for complex or non-standard documents but has longer processing times.

Your account’s extraction pipeline is configured during onboarding based on the account tier.

Checking extraction status

To monitor the progress of your uploads, call the GET /v1/invoices/uploads endpoint. This returns a list of uploads that have been submitted but not yet fully processed.

Check upload status

curl -X GET "https://api.ottimate.com/v1/invoices/uploads" \
  -H "X-Api-Key: your-api-key-here" \
  -H "X-API-Version: 1.0.0"

The response includes the status of each upload:

Response

{
  "version": "1.0.0",
  "count": 1,
  "page": 1,
  "limit": 20,
  "results": [
    {
      "id": "cf_64EFeQ3Y41UY6",
      "reference_id": "IC_4a818bace9464bf694c7043aca294136",
      "filename": "invoice-abc.pdf",
      "status": "grouped",
      "date": "2025-10-10T12:00:00.000000-07:00",
      "no_of_pages": 1,
      "ottimate_location_name": "Downtown Location",
      "preview_url": "https://app.ottimate.com/#/capture/<token>"
    }
  ]
}

Field	Description
`id`	Ottimate’s upload identifier
`reference_id`	The Instant Capture service’s own reference for this upload
`filename`	Original filename as submitted
`status`	Where the upload sits in the extraction pipeline
`date`	When the upload was created
`no_of_pages`	Page count of the uploaded file
`ottimate_location_name`	Name of the location the upload belongs to
`preview_url`	Signed link into the Ottimate capture UI

The endpoint is paginated — pass page and limit, and filter to a single location with ottimate_location_id.

Upload status values

status is passed through from Ottimate’s extraction service and moves roughly in the order below:

Status	Description
`new`	The upload has been accepted and is queued for processing
`splitting`	Ottimate is determining page boundaries within the file
`split`	The uploaded file contains multiple pages that require manual review to confirm whether they belong to the same invoice or should be separated into distinct invoices
`digitizing`	Extraction is in progress
`grouped`	Page grouping has been confirmed and the upload is ready for extraction
`ready_to_create`	Extraction is complete and the upload is ready to become an invoice

Treat this list as non-exhaustive. status is relayed verbatim from the extraction service, so new values can appear without an API version change. Handle an unrecognised status as “still in progress” rather than failing. Uploads that have already become invoices drop out of this endpoint entirely, so you will not normally see a terminal status here.

Using the preview URL

The preview_url field provides a direct link to the Ottimate extraction UI where users can:

Review extracted data and make corrections
Confirm page groupings for multi-page uploads
Manually export the invoice once review is complete

preview_url expires about 60 minutes after it is generated. The link carries a short-lived signed token, and a new one is minted every time you call GET /v1/invoices/uploads. Do not store these URLs or embed them in emails or tickets — fetch the upload again to get a fresh link.

Once an upload no longer appears in this list, extraction has completed and the invoice is available through the invoices API.

What you can do with extraction

Upload invoice files - Submit PDF, image, or scanned documents for extraction
Track upload progress - Monitor the status of documents in the extraction queue
Automate intake workflows - Build integrations that automatically submit invoices from email, vendor portals, or other sources