API reference

Bills (households)

For Invoist Personal. A household's key reaches only these endpoints, and a business key never does. Create a household key in Settings, then AI assistants.

List bills

GET

The household's bills. Unpaid bills come soonest due first; otherwise newest first. A reminder or collection letter is folded into the bill it is about (see letter). Requires bills:read.

Query parameters

6 fields

paidboolean
true for paid bills only, false for unpaid only. Omit for both.
monthstring
Only bills due in this month, as YYYY-MM.
senderstring
Only this sender's bills, by name.
qstring
Words to search for: sender, bill number, or reference.
limitinteger
Max results. Default 50, at most 200.
offsetinteger
Number of results to skip.
curl "https://api.invoi.st/v1/bills?paid=false&month=2026-11" \
  -H "Authorization: Bearer $INVOIST_API_KEY"
Response · 200
{
  "bills": [
    {
      "id": "01a1f0c2-3b44-7d10-9a51-6f0e2c1b8a90",
      "source": "email",
      "original_filename": "arve-4471.pdf",
      "content_type": "application/pdf",
      "byte_size": 48213,
      "status": "done",
      "vendor_name": "Elektrum",
      "invoice_number": "4471",
      "reference_number": "9003311",
      "total_cents": 6420,
      "currency": "EUR",
      "due_date": "2026-11-06",
      "kind": null,
      "bill": { "paid_at": null, "paid_by": null, "assigned_to": null },
      "related": { "document_id": null, "link": "" },
      "letter": null,
      "logo": "elektrum.ee",
      "pending_review": false,
      "flagged": false,
      "created_at": "2026-10-21T07:02:11Z",
      "updated_at": "2026-10-21T07:02:15Z"
    }
  ]
}

Get a bill

GET

One bill with everything read from it: who to pay, the account and reference, the amount and due date, each line, any warning to check before paying (review_queue), and any reminder about it. Requires bills:read.

curl "https://api.invoi.st/v1/bills/01a01663-6802-7707-a847-13323ffab41e" \
  -H "Authorization: Bearer $INVOIST_API_KEY"
Response · 200
{
  "document": { "id": "01a1f0c2-3b44-7d10-9a51-6f0e2c1b8a90", "status": "done", "original_filename": "arve-4471.pdf" },
  "extraction": {
    "vendor_name": "Elektrum",
    "vendor_iban": "EE47 1010 2200 3428 2015",
    "reference_number": "9003311",
    "total_cents": 6420,
    "currency": "EUR",
    "due_date": "2026-11-06",
    "line_items": [{ "description": "Electricity, October", "amount_cents": 6420 }]
  },
  "review_queue": [],
  "bill": { "paid_at": null, "paid_by": null, "assigned_to": null },
  "related": { "document_id": null, "link": "" },
  "logo": "elektrum.ee"
}

Download a bill's file

GET

The PDF or photo the bill was read from, with its own content type. Requires bills:read.

curl "https://api.invoi.st/v1/bills/01a01663-6802-7707-a847-13323ffab41e/file" \
  -H "Authorization: Bearer $INVOIST_API_KEY" \
  -o bill.pdf
Response · 200
(the file's bytes)

Bills to pay

GET

How many bills are unpaid and overdue, and what is due within the next days, per currency. Requires bills:read.

Query parameters

2 fields

daysinteger
How many days ahead counts as due soon. Default 30.
todaystring
The household's today, as YYYY-MM-DD. Defaults to the server's date.
curl "https://api.invoi.st/v1/bills/summary?days=14" \
  -H "Authorization: Bearer $INVOIST_API_KEY"
Response · 200
{
  "unpaid": 3,
  "overdue": 0,
  "due_soon": [{ "currency": "EUR", "count": 3, "total_cents": 13529 }],
  "days": 30,
  "today": "2026-11-01"
}

Monthly totals

GET

One month at a glance: what the bills came to and how much is paid, the twelve months up to it, and the biggest senders. Receipts and credit notes are not counted as spending. Requires bills:read.

Query parameters

2 fields

monthstring
The month as YYYY-MM. Default this month.
senderstring
Only this sender's bills.
curl "https://api.invoi.st/v1/bills/stats?month=2026-11" \
  -H "Authorization: Bearer $INVOIST_API_KEY"
Response · 200
{
  "month": "2026-10",
  "totals": [{ "currency": "EUR", "count": 6, "paid_count": 6, "total_cents": 31240, "paid_cents": 31240 }],
  "trend": [{ "month": "2026-10", "currency": "EUR", "count": 6, "total_cents": 31240 }],
  "top_senders": [{ "name": "Elektrum", "currency": "EUR", "count": 1, "total_cents": 7180, "logo": "elektrum.ee" }],
  "senders": [{ "name": "Elektrum", "count": 12 }]
}

Mark a bill as paid

POST

Records that the bill is paid, by whoever created the key or approved the assistant. Invoist never pays anything itself. DELETE on the same path marks it as not paid again. Requires bills:write.

curl -X POST "https://api.invoi.st/v1/bills/01a01663-6802-7707-a847-13323ffab41e/paid" \
  -H "Authorization: Bearer $INVOIST_API_KEY"
Response · 200
{
  "bill": {
    "paid_at": "2026-11-01T18:20:04Z",
    "paid_by": "0199c7a4-5e21-7b3f-8f10-2d4c8e6a1b23",
    "assigned_to": null
  }
}

List emails waiting for approval

GET

Emails forwarded to the household from a sender nobody has approved yet, with why each one waits and when it would be deleted. Approving a sender is done in the Invoist app. Requires bills:read.

curl "https://api.invoi.st/v1/held-emails" \
  -H "Authorization: Bearer $INVOIST_API_KEY"
Response · 200
{
  "held_emails": [
    {
      "id": "01a2b7e0-9c1d-7f42-8b3e-5a6d4c2f1e07",
      "from_email": "[email protected]",
      "sender": "telia.ee",
      "subject": "Your Telia bill for October",
      "status": "held",
      "hold_reason": "new_sender",
      "held_until": "2026-11-15T07:00:00Z",
      "created_at": "2026-11-01T07:00:00Z",
      "files": [{ "id": "…", "filename": "telia-oct.pdf", "content_type": "application/pdf", "size_bytes": 51200 }]
    }
  ]
}