> This page is for version V1 (default). > For other versions, use one of these documentation indexes: > - V1 (default): https://docs.ottimate.com/v-1/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ottimate.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ottimate.com/_mcp/server. # Extraction Overview 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`](/api-reference/api-reference/invoices/post-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 | > **Warn** > > **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 > **Note** > > **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`](/api-reference/api-reference/invoices/get-invoices-uploads) endpoint. This returns a list of uploads that have been submitted but not yet fully processed. **`Check upload status`** ```bash title="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`** ```json title="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/" } ] } ``` | 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 | > **Info** > > **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 > **Warn** > > **`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