Integrating Invofox

The core integration — the happy path, from upload to JSON.

Invofox is one API to extract structured data from PDFs and images — send any document (invoices, receipts, bank statements, delivery notes, contracts and many more, including custom document types) and get back clean, structured JSON. Under the hood it’s an intelligent document processing (IDP) platform: OCR + AI that classify each document and extract its fields automatically — no templates, no manual data entry.

This page is the core integration — the happy path, from upload to JSON. For use cases, accuracy and pricing, see invofox.com →

Using an AI coding agent? Connect to the Invofox MCP server so your agent can search these docs in real time. Integrate with an AI agent →

Step 1 — Get your API key

API keys are scoped to an environment. To create one:

  1. Log in to app.invofox.com and open your environment — create a free account if you don’t have one yet.
  2. Click API and Webhooks in the left menu.
  3. Create a new API key and copy it.

Step 2 — Upload a document

Send your file as multipart/form-data with an info JSON field. The response returns a documentId — that’s all you need. Full API reference →

POSThttps://api.invofox.com/v1/ingest/uploads
$curl -s -X POST "https://api.invofox.com/v1/ingest/uploads" \
>  -H "x-api-key: $INVOFOX_API_KEY" \
>  -F "files=@invoice.pdf" \
>  -F 'info={"type":"<TYPE_ID>","clientData":{"internalId":"inv-1234"}}'

The info field

FieldTypeRequiredDescription
typestringRequiredThe Document Type to extract — its id or alias. Find it in Invofox → Document Types. *
clientDataobjectOptionalAny JSON object you want Invofox to store and return alongside the document — in both the GET response and webhook payload. Useful for carrying your own identifiers: {"internalId": "inv-1234"}.
Where to find Document Type IDs
  • Open Document Types in the left menu of Invofox.
  • Each Document Type shows a card with its id and alias.
  • Use the alias if it has one; otherwise use the id.
  • Need a Document Type that isn’t there? Invofox can define custom Document Types for your use case — contact support@invofox.com.

Upload response

The upload returns immediately with a documentId — not the extracted data. Invofox processes the document asynchronously. Save the documentId from files[0] and use it in Step 3 to retrieve the results.

Upload response
1{
2  "accountId": "666839c78ea472012a9b8875",
3  "environmentId": "6a338e5239207f9311eccd36",
4  "importId": "6a34a304f55a9cdc5e6d1c76",
5  "files": [
6    {
7      "id": "6a34a304f55a9cdc5e6d1c79",
8      "filename": "invoice.pdf",
9      "documentId": "6a34a304f55a9cdc5e6d1c7a"   // ← save this
10    }
11  ]
12}

Step 3 — Get the extracted data

Processing is asynchronous. Webhooks are the recommended approach; polling is fine for quick tests and prototyping.

Option A · Webhooks (Recommended)

Invofox pushes a document.processed event to your server when extraction is complete. Event-driven, no polling overhead. Recommended for all production integrations.

Option B · Polling

No infrastructure needed — great for prototyping and quick tests. Not recommended for production.

Option A · Webhooks (recommended for production)

In Invofox, open your environment and go to API and Webhooks → Webhooks to add your endpoint URL. Your server will then receive a document.processed event the moment extraction finishes.

For the complete list of events and their payload schemas (plus signing and verification), see the Webhooks Reference →. The example below shows a document.processed payload.

document.processed payload
1{
2  "type": "document.processed",
3  "version": "1.2",
4  "timestamp": 1781834535319,
5  "url": "",
6  "data": {                                // ← the document lives here (not under "result" like the GET); no permission flags
7    "_id": "6a34a304f55a9cdc5e6d1c7a",
8    "clientData": { "internalId": "inv-1234" },   // ← same clientData you sent on upload
9    "type": "6a338ee0fdcde8d97ac96784",           // ← the Document Type's id (or its alias, if it has one)
10    "name": "invoice.pdf",
11    "publicState": "approved",
12    "confidence": "high",
13    "pageCount": 1,
14    "images": [
15      "https://storage.invofox.com/documents/6a34a304f55a9cdc5e6d1c7a/page-1.jpeg?token=..."
16    ],
17    "original": "https://storage.invofox.com/documents/6a34a304f55a9cdc5e6d1c7a/original.pdf?token=...",
18    "data": {                              // ← extracted fields at data.data.<field>
19      "receiptNumber":  { "value": "A16030202" },
20      "issueDate":      { "value": "2023-12-04" },
21      "subtotalAmount": { "value": 31.32 },
22      "taxAmount":      { "value": 0 },
23      "totalAmount":    { "value": 31.32 },
24      "paymentMethod":  { "value": "Transferencia bancaria" },
25      "merchant":       { "name": { "value": "Invofox Inc" } },
26      "items": [
27        { "description": { "value": "Permanente Sharpie" }, "quantity": { "value": 1 }, "unitPrice": { "value": 2.1 }, "totalAmount": { "value": 2.1 } }
28      ]
29    }
30  }
31}

A file can also fail before producing any document (password-protected, corrupt, unsupported format). Listen for the file.rejected webhook so you don’t wait forever for a document that never arrives — this applies whether you use webhooks or polling. See Rejected files.

Option B · Polling

Poll GET /documents/{documentId} using exponential backoff (start at 5 s, double each retry). The endpoint may return 404 for the first several seconds — that’s expected, keep polling. Stop when you get a 200 with publicState set to approved, pendingCorrection, or discarded.

GEThttps://api.invofox.com/documents/{documentId}

Final response fields live under result.data. The example below is illustrative.

The set of fields is defined by the Document Type configured in your environment — it is not fixed. The structure is always the same: every field is a { "value": ... } object, which can be nested, with arrays for line items. To see the exact fields for your Document Type, check Document Types in the dashboard or process a sample document.

GET /documents/{documentId}
1{
2  "canEdit": true, "canComment": false, "canLock": true, "canAction": true,   // ← permission flags (not in the webhook)
3  "result": {
4    "_id": "6a34a304f55a9cdc5e6d1c7a",
5    "clientData": { "internalId": "inv-1234" },   // ← your clientData, returned untouched
6    "type": "6a338ee0fdcde8d97ac96784",           // ← the Document Type's id (or its alias, if it has one)
7    "name": "invoice.pdf",
8    "publicState": "approved",
9    "confidence": "high",
10    "pageCount": 1,
11    "images": [
12      "https://storage.invofox.com/documents/6a34a304f55a9cdc5e6d1c7a/page-1.jpeg?token=..."
13    ],
14    "original": "https://storage.invofox.com/documents/6a34a304f55a9cdc5e6d1c7a/original.pdf?token=...",
15    "data": {                              // ← extracted fields at result.data.<field>
16      "receiptNumber":  { "value": "A16030202" },
17      "issueDate":      { "value": "2023-12-04" },
18      "subtotalAmount": { "value": 31.32 },
19      "taxAmount":      { "value": 0 },
20      "totalAmount":    { "value": 31.32 },
21      "paymentMethod":  { "value": "Transferencia bancaria" },
22      "merchant":       { "name": { "value": "Invofox Inc" } },
23      "items": [
24        { "description": { "value": "Permanente Sharpie" }, "quantity": { "value": 1 }, "unitPrice": { "value": 2.1 }, "totalAmount": { "value": 2.1 } }
25      ]
26    }
27  }
28}

Further optional steps

Give feedback on extracted values

If an extracted value is missing or incorrect, you can send the right value back via PUT /documents/{id}. Every correction feeds directly into model training, improving extraction accuracy over time — automatically, with no extra configuration. See the Feedback loop page for the full reference.

Additional Features

The core integration is complete. These features are available if your use case requires them:

Feedback loop

Feed human corrections back into the API to close the human review loop.

Splitter

Upload a PDF that contains several documents and get each one back separately, automatically.

Classifier

Skip specifying the document type — Invofox detects it automatically.