API reference

Extraction

The endpoint everything else is built on: send an invoice file, get a document and a pending extraction back.

Extract an invoice

POST

Upload an invoice as multipart form data in the file field. Accepts PDF, PNG, and JPEG up to 20 MB. The response comes back immediately with the document and a pending extraction; processing runs in the background, so poll the document until the extraction status is done or failed.

Headers

1 field

Idempotency-Keystring
A key you generate per logical request. Reusing it with the same file replays the first response (Idempotency-Replayed: true, no new document, no new charge). Reusing it with a different file is rejected with 422. Keys expire after 24 hours.

Body

1 field

filefilerequired
The invoice. PDF, PNG, or JPEG, at most 20 MB.
curl -X POST "https://api.invoi.st/v1/extract" \
  -H "Authorization: Bearer $INVOIST_API_KEY" \
  -H "Idempotency-Key: order-1042" \
  -F "[email protected]"
Response · 201
{
  "document": {
    "id": "01a01663-6802-7707-a847-13323ffab41e",
    "source": "api",
    "original_filename": "invoice.pdf",
    "content_type": "application/pdf",
    "byte_size": 182044,
    "status": "processing",
    "created_at": "2026-08-19T09:14:08Z",
    "updated_at": "2026-08-19T09:14:08Z"
  },
  "extraction": {
    "id": "01a01663-6807-7549-8391-b2be347960cf",
    "document_id": "01a01663-6802-7707-a847-13323ffab41e",
    "engine": "invoist-extraction-v1",
    "status": "pending",
    "invoice_number": null,
    "vendor_name": null,
    "total_cents": null,
    "confidence": null,
    "line_items": null,
    "error_message": null,
    "created_at": "2026-08-19T09:14:08Z",
    "updated_at": "2026-08-19T09:14:08Z"
  }
}

Extract up to 10 invoices in one call

POST

Multipart form data, one or more files under the field name files (repeat the field for each one), up to 10 per request. Each file goes through the same pipeline as POST /v1/extract — same duplicate detection, same document.created webhook per new document. Always answers 200: one bad file doesn't fail the others, each entry in results carries its own outcome in the order the files were sent. Idempotency-Key is not supported here.

Body

1 field

filesfile[]required
One to ten invoices. PDF, PNG, or JPEG, each at most 20 MB.
curl -X POST "https://api.invoi.st/v1/extract/batch" \
  -H "Authorization: Bearer $INVOIST_API_KEY" \
  -F "[email protected]" \
  -F "[email protected]"
Response · 200
{
  "results": [
    {
      "filename": "invoice-1.pdf",
      "document_id": "01a01663-6802-7707-a847-13323ffab41e",
      "extraction_id": "01a01663-6807-7549-8391-b2be347960cf",
      "status": "processing",
      "duplicate": false
    },
    {
      "filename": "invoice-2.pdf",
      "error": {
        "code": "upload_type",
        "message": "use a PDF, PNG or JPEG file"
      }
    }
  ],
  "accepted": 1,
  "rejected": 1
}