Menu

Inbox items

The invoice inbox: list and read items, correct the extracted fields, convert an item to a supplier invoice, unmatch a transaction, stamp or delete an item.

Endpoints


GET /api/v1/companies/:companyId/inbox-items

inbox-items.list · scope documents:read

List invoice-inbox items (Underlag) with a summary of what was read from each.

Returns inbox items newest first: how each arrived, the document, the vendor, total, currency and date read from it, and its links (transaction match, supplier invoice, verifikat). processed is true once the item is not open: any link, Arkiv took it, or a verifikat holds its document; unprocessed_only=true returns only the open items, so a page can run short with a next_cursor. Cursor pagination: pass next_cursor back as cursor; null on the last page. The full reading and the e-mail text are on GET /inbox-items/{id}.

Use when: You work the inbox: receipts and invoices waiting to be matched, converted or booked.

Don't use for: The document archive as a whole (GET /documents) or supplier invoices already registered (GET /supplier-invoices).

Pitfalls

  • amount is in the document's currency: compare with a transaction's amount only after converting.
  • A matched item whose transaction is booked can still have underlag_status unlinked: the document did not reach the verifikat.
  • The page is in data.inbox_items with data.next_cursor; a cursor that no longer decodes starts from the first page.

Risk: low · Idempotent: yes · Reversible: no · Dry-run supported: no

Query parameters

NameTypeRequiredDescription
status"received" | "error"noerror = extraction failed.
unprocessed_only"true" | "false"notrue = only open items: no link, not in Arkiv, and no verifikat holds the document.
cursorstringnonext_cursor from the previous page. Omit for the first page.
limitnumbernoPage size, 1-100 (default 50).

Response fields

NameType
inbox_itemsobject[]
next_cursorstring | null

Example response

{
  "data": {
    "inbox_items": [
      {
        "inbox_item_id": "1b2c…",
        "status": "received",
        "source": "email",
        "created_at": "2026-09-02T07:41:10Z",
        "document_id": "4f1c…",
        "kind_hint": null,
        "vendor_name": "Clas Ohlson AB",
        "amount": 499,
        "currency": "SEK",
        "invoice_date": "2026-09-01",
        "processed": false,
        "matched_supplier_id": null,
        "matched_transaction_id": null,
        "matched_transaction_journal_entry_id": null,
        "created_supplier_invoice_id": null,
        "created_journal_entry_id": null,
        "underlag_status": null,
        "email_from": "kvitto@clasohlson.se",
        "email_subject": "Ditt kvitto",
        "email_received_at": "2026-09-02T07:41:02Z",
        "error_message": null
      }
    ],
    "next_cursor": null
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

GET /api/v1/companies/:companyId/inbox-items/:id

inbox-items.get · scope documents:read

Read one inbox item with its full reading and e-mail text.

Returns the item's summary plus the complete extracted_data (supplier, invoice, totals, line items, VAT breakdown), the e-mail body text and the document's file name. When the item has no reading of its own, the document's reading stands in. include=reading adds the one reading: each field under its EN 16931 name with its source (xml, vision, text, door, person) and evidence (exakt, stark, trolig, ditt_val). bank_match is the bank transaction the item looks already paid by (match on arrival), or null: a proposal, never a booking or a link.

Use when: You are about to correct the reading, convert the item to a supplier invoice or match it, and need every field.

Don't use for: Scanning the queue (GET /inbox-items) or downloading the file (GET /documents/{id}/download).

Pitfalls

  • extracted_data is what was read, not what was booked: check it against the document before converting.
  • extracted_data.sellerIsOwnCompany true (with documentKind other and an empty supplier) means the seller on the document is the company itself: its own sales invoice, not a purchase. Never convert it to a supplier invoice or book a cost from it; link it to the payment it brought in, or leave it. If the reading got it wrong and the document is a purchase, say so through PATCH /inbox-items/{id}: the seller it really names and its documentKind.
  • email_body_text can carry personal data: do not copy it into notes or descriptions.
  • An id from another company answers 404 INBOX_ITEM_NOT_FOUND.
  • reading.fields holds only fields something read; evidence is never the model's own confidence, and a value a person cleared is null with source person.
  • bank_match is only a proposal, re-checked on every read (the bank transaction still unbooked and claimed by nothing else). To accept it for a receipt, pair it (POST /inbox-items/{id}/match-transaction) and book the transaction; for a supplier invoice, convert it (POST /inbox-items/{id}/convert), then POST /transactions/{bank_match.transaction_id}/match-supplier-invoice.

Risk: low · Idempotent: yes · Reversible: no · Dry-run supported: no

Query parameters

NameTypeRequiredDescription
include"reading"noreading = add the one reading of the document: every field with its source and evidence level.

Response fields

NameTypeDescription
inbox_item_idstring
handlestring (optional)Typed handle of this inbox item: inbx_ plus its id as 32 lowercase hex. Accepted wherever the id is.
statusstringreceived or error (extraction failed).
sourcestringHow it arrived: email, upload, api, whatsapp, ...
created_atstring
document_idstring | null
kind_hintstring | nullDeclared kind: a +lev / +ver address tag, the type Arkiv queued it as, or a person's type in Dokument.
vendor_namestring | nullSupplier name as read from the document.
amountnumber | nullTotal as read from the document, in its currency.
currencystring | null
invoice_datestring | null
processedbooleanTrue once the item is not open: a transaction match, a supplier invoice or a verifikat, Arkiv took it, or a verifikat holds its document.
matched_supplier_idstring | null
matched_transaction_idstring | null
matched_transaction_journal_entry_idstring | nullThe verifikat that booked the matched transaction, when it is booked.
created_supplier_invoice_idstring | null
created_journal_entry_idstring | null
underlag_status"anchored" | "unlinked" | "unlinked_locked" | "anchored_elsewhere" | "unknown" | nullFor a matched item whose transaction is booked: whether THIS item's document reached that verifikat (anchored) or not. Null otherwise.
email_fromstring | null
email_subjectstring | null
email_received_atstring | null
error_messagestring | null
extracted_dataobject | null
purchase_categoryobject | nullWhat the underlag bought, computed when read; null when the evidence is ambiguous. Not a booking: the account stays the booking's.
extraction_skippedboolean
email_body_textstring | null
file_namestring | null
updated_atstring
intake_source"intake_email" | "mailbox" | "whatsapp" | "upload" | "peppol" | "partner_api" | "mcp" | "migration" | "system" | "bank_feed" | "bank_file" | "sie" | "billo" | "kivra" | "paypal" | "portal" | nullThe door it came through, one id across every channel: intake_email, mailbox, whatsapp, upload, peppol, partner_api, mcp, migration, system, ... source keeps the legacy value (upload covers several doors).
readingobject (optional)One reading of the document. Precedence per field: person > xml > model > door. evidence: exakt (structured source), stark (machine reading something agrees with), trolig (machine reading alone), ditt_val (a person chose it).
bank_matchobject | nullA proposal, never a booking: the item looks already paid by this bank row.

Example response

{
  "data": {
    "inbox_item_id": "1b2c…",
    "status": "received",
    "source": "email",
    "created_at": "2026-09-02T07:41:10Z",
    "document_id": "4f1c…",
    "kind_hint": null,
    "vendor_name": "Clas Ohlson AB",
    "amount": 499,
    "currency": "SEK",
    "invoice_date": "2026-09-01",
    "processed": false,
    "matched_supplier_id": null,
    "matched_transaction_id": null,
    "matched_transaction_journal_entry_id": null,
    "created_supplier_invoice_id": null,
    "created_journal_entry_id": null,
    "underlag_status": null,
    "email_from": "kvitto@clasohlson.se",
    "email_subject": "Ditt kvitto",
    "email_received_at": "2026-09-02T07:41:02Z",
    "error_message": null,
    "extracted_data": {
      "supplier": {
        "name": "Clas Ohlson AB"
      },
      "invoice": {
        "invoiceDate": "2026-09-01",
        "currency": "SEK"
      },
      "totals": {
        "total": 499
      }
    },
    "purchase_category": {
      "code": "expense.office.supplies",
      "source": "counterparty",
      "level": "Stark",
      "version": "pc-2026-10"
    },
    "extraction_skipped": false,
    "email_body_text": null,
    "file_name": "kvitto.pdf",
    "updated_at": "2026-09-02T07:41:30Z",
    "intake_source": "intake_email",
    "bank_match": {
      "transaction_id": "7d3a…",
      "date": "2026-09-01",
      "amount": -499,
      "currency": "SEK",
      "counterparty": "CLAS OHLSON",
      "basis": "rule_amount_date",
      "evidence_level": "trolig"
    }
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

GET /api/v1/companies/:companyId/inbox-items/removed

inbox-items.list-removed · scope documents:read

List the inbox items deleted most recently that can still be put back.

Returns at most 20 deleted inbox items, newest deletion first, one per document: the file name, the vendor, total and currency of its reading, its e-mail sender and subject, when it was deleted and by whom. Only items that can be put back are listed: one that is in the inbox again, or whose document has since been booked or become the underlag of a supplier invoice, an expense claim or a bank transaction, is left out.

Use when: An inbox item was deleted by mistake and you need its id to put it back.

Don't use for: The inbox itself (GET /inbox-items) or the document archive (GET /documents).

Pitfalls

  • Not a history of every deletion: an item deleted before deleted items were kept, one that carried no document and one whose document was deleted from the archive are never listed.
  • The list is read from the newest deletions only, so it can be shorter than the limit after many items were put back.

Risk: low · Idempotent: yes · Reversible: no · Dry-run supported: no

Response fields

NameTypeDescription
removed_items[].inbox_item_idstringThe item's own id, the one to put back.
removed_items[].document_idstringThe document it carried, still in the archive.
removed_items[].file_namestring | null
removed_items[].vendor_namestring | nullSupplier name as read from the document.
removed_items[].amountnumber | nullTotal as read from the document, in its currency.
removed_items[].currencystring | null
removed_items[].email_fromstring | null
removed_items[].email_subjectstring | null
removed_items[].removed_atstringWhen it was deleted.
removed_items[].removed_byobjectWho deleted it.

Example response

{
  "data": {
    "removed_items": [
      {
        "inbox_item_id": "1b2c…",
        "document_id": "4f1c…",
        "file_name": "kvitto.pdf",
        "vendor_name": "Clas Ohlson AB",
        "amount": 499,
        "currency": "SEK",
        "email_from": "kvitto@clasohlson.se",
        "email_subject": "Ditt kvitto",
        "removed_at": "2026-11-16T09:12:44Z",
        "removed_by": {
          "actor_type": "user",
          "user_id": "8a3e…"
        }
      }
    ]
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

POST /api/v1/companies/:companyId/inbox-items

inbox-items.deliver · scope documents:write

Deliver a supplier invoice or receipt into the Inkorg for a person to book.

Multipart delivery of one document (PDF, JPEG, PNG, HEIC or WebP, at most 10 MB) into the company's Inkorg. It takes the same path as a person's upload: the file is archived under BFL 7 kap (deduplicated on content), read by extraction, and waits among the Inkorg's open items as an inbox item with source "upload", until a person, or an agent the owner has granted it to, books it. Nothing is booked here: no supplier invoice, no verifikat. Answers 201 with the new inbox_item_id and document_id, or 200 with deduplicated=true when the same external_ref or the same file was already delivered. For a mailbox partner (Billo and the like): deliver each document here instead of POST /supplier-invoices. That endpoint registers and books the invoice on arrival, past the Inkorg and its duplicate check; this one hands it to the company to review. Send your own id as external_ref, the sender as sender_name and sender_org_number, and kind_hint when you know what the document is. Booking without a person will come back later as a grant the owner switches on, not as a partner call.

Use when: You deliver documents to a company on its behalf (a digital mailbox, a scanning service, a portal) and the company should review and book them in Accounted.

Don't use for: Booking (convert the item with POST /inbox-items/{id}/convert, or book it from the Inkorg). Archiving a document that already belongs to a verifikat (POST /documents with journal_entry_id). Several files at once: one file per call.

Pitfalls

  • This files into the Inkorg for a person or a granted agent to book; it does not book. No supplier invoice and no verifikat exist until someone books the item.
  • Idempotency-Key is mandatory; a resend with the same key and the same parts replays the first answer. external_ref is the business key on top: a repeat with the same external_ref returns the first delivery's item (200, deduplicated=true) even under a new key.
  • The same external_ref with a different file answers 409 INBOX_DELIVERY_REF_CONFLICT: give each document its own external_ref.
  • external_ref is unique per company across every partner delivering to it: prefix it with something of your own (billo-123, not 123).
  • Do not send the same delivery twice concurrently: wait for the answer (or a timeout) before resending, or both requests may file.
  • Only PDF, JPEG, PNG, HEIC and WebP up to 10 MB: INBOX_UPLOAD_UNSUPPORTED_TYPE, INBOX_UPLOAD_TOO_LARGE, or DOC_UPLOAD_INVALID_CONTENT for bytes that do not match the declared type. On the hosted service the platform refuses a request body over 4.5 MB before it reaches Accounted (a plain-text 413, no error envelope), so keep files there under 4 MB.
  • The Inkorg takes at most 30 deliveries a minute and 500 a day per company, a person's uploads included: 429 RATE_LIMITED with Retry-After. Resend after it with the same Idempotency-Key.
  • Extraction runs after the answer: GET /inbox-items/{id} shows status "processing" until the reading is in.
  • Not dry-runnable: test keys are refused with TEST_KEY_WRITE_BLOCKED.

Risk: low · Idempotent: yes · Reversible: no · Dry-run supported: no

Request body

NameTypeRequiredDescription
kind_hint"supplier_invoice" | "receipt"noWhat the sender says it is. Shown in the Inkorg ahead of what extraction reads.
external_refstringnoYour own id for this delivery (1-200 chars). A repeat answers the first delivery's item.
sender_namestringnoWho sent the document to you, shown as its sender.
sender_org_numberstringnoThe sender's organisationsnummer, as you have it.
subjectstringnoA subject line, shown when no supplier name was read.
messagestringnoA short text that came with the document. Kept with the arrival, not on the item.
received_atstringnoISO timestamp you received it. Defaults to now.
fileunknownno

Response fields

NameTypeDescription
inbox_item_idstringThe item in the Inkorg. Read it with GET /inbox-items/{id}.
document_idstringThe archived document (BFL 7 kap retention).
deduplicatedbooleanTrue when nothing new was filed: the same external_ref, or the same file, was already in the Inkorg and that item is returned.
arrival_idstring | nullThe recorded delivery (how it came in, by whom). Null when it could not be recorded; the item is filed regardless.

Example request

{
  "file": "<binary>",
  "kind_hint": "supplier_invoice",
  "external_ref": "billo-8f2c1a",
  "sender_name": "Leverantören AB",
  "sender_org_number": "556677-8899",
  "subject": "Faktura 1001",
  "received_at": "2026-10-15T08:00:00Z"
}

Example response

{
  "data": {
    "inbox_item_id": "1b2c…",
    "document_id": "4f1c…",
    "deduplicated": false,
    "arrival_id": "9a0d…"
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

POST /api/v1/companies/:companyId/inbox-items/:id/convert

inbox-items.convert-to-supplier-invoice · scope suppliers:write

Register a supplier invoice from an inbox item, with its document as underlag.

Registers a supplier invoice (status registered, next ankomstnummer) from the given lines, attaches the item's document as underlag and marks the item converted. A company that books on registration gets the registration verifikat at once (cost and 2641 against 2440, with periodisering and särskild löneskatt where the lines ask); a company that defers booking gets none until the invoice is booked. A non-SEK invoice without exchange_rate gets Riksbanken's rate for invoice_date. Idempotent. Dry-runnable: the preview computes the invoice without an ankomstnummer.

Use when: An inbox item is a supplier invoice the company will pay later (leverantörsskuld).

Don't use for: A receipt the company already paid (book it against the bank transaction), a purchase paid privately (POST /expense-claims), a supplier credit note (credit the invoice it references: POST /supplier-invoices/{id}/credit with inbox_item_id), or registering an invoice without an inbox item (POST /supplier-invoices).

Pitfalls

  • An item already converted returns 409 INBOX_ITEM_ALREADY_CONVERTED; a supplier invoice number the supplier already has returns 409 SI_CREATE_DUPLICATE_INVOICE_NUMBER with details.existing.
  • Where registering posts a verifikat, an item a live verifikat books already, by its stamp or because that verifikat holds its document, returns 409 INBOX_ITEM_ALREADY_BOOKED with details.journal_entry_id: a second verifikat would book the purchase twice.
  • A credit note (read as one, or with a negative net or VAT) returns 409 INBOX_ITEM_IS_CREDIT_NOTE with details.credit_target: the invoice it credits, or the candidates to choose from.
  • amount is per line EXCLUDING VAT. VAT is booked per rate as the document states it: on the summed base of each rate, or the figure in vat_breakdown when it is within half an öre per line of that (else 400 VAT_BREAKDOWN_MISMATCH), spread over the lines. items[].vat_amount books a line's own VAT as given. Private-payment fields are not accepted here.
  • Reverse charge follows POST /supplier-invoices: an EU or non-EU supplier without reverse_charge defaults to it, vat_treatment follows the flag, the payable is the net, and a line with a vat_rate other than 0 returns 400 VALIDATION_ERROR. Send reverse_charge: false for a foreign supplier that charged its own or no VAT. Goods from an EU supplier take reverse_charge_kind: "eu_goods" (basis 4515, ruta 20); omitted books services (4535, ruta 21).
  • With dimensions enabled, an unknown or archived code in default_dimensions or items[].dimensions returns DIMENSION_VALIDATION_FAILED and registers nothing when the company books on registration; a company that defers booking meets it when the invoice is booked.
  • No fiscal year for invoice_date returns SI_CREATE_NO_FISCAL_PERIOD and registers nothing.
  • account_number is a STRING ("6110"), never a number.

Risk: medium · Idempotent: yes · Reversible: no · Dry-run supported: yes

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.

Request body

NameTypeRequiredDescription
supplier_idstringyesThe supplier (supplier_id from GET /suppliers).
supplier_invoice_numberstringyes
invoice_datestringyes
due_datestringno
delivery_datestring | ""no
currency"SEK" | "EUR" | "USD" | "GBP" | "NOK" | "DKK" | "CHF" | "CAD"no
exchange_ratenumberno
vat_treatment"standard_25" | "reduced_12" | "reduced_6" | "reverse_charge" | "export" | "exempt"no
reverse_chargebooleanno
reverse_charge_kind"eu_goods" | "eu_services"no
payment_referencestringno
notesstringno
default_dimensionsobjectnoTags for every line {"<sie_dim_no>":"<code>"}, e.g. {"1":"KS01","6":"P001"}: kostnadsställe 1, projekt 6, codes from GET /dimensions.
vat_breakdownobject[]noThe VAT per rate the document states, e.g. [{"vat_rate":0.25,"vat_amount":3864.11}]. Omitted: the VAT on the summed base per rate.
itemsobject[]yes

Response fields

NameTypeDescription
supplier_invoice_idstring
arrival_numbernumber | nullAnkomstnummer.
statusstring
currencystring
totalnumber
total_seknumber | null
registration_journal_entry_idstring | nullThe registration verifikat, or null when the company defers booking.
inbox_item_idstring

Example request

{
  "supplier_id": "7c1d…",
  "supplier_invoice_number": "F-2026-118",
  "invoice_date": "2026-09-01",
  "due_date": "2026-09-30",
  "items": [
    {
      "description": "Kontorsmaterial",
      "amount": 399.2,
      "account_number": "6110",
      "vat_rate": 0.25
    }
  ]
}

Example response

{
  "data": {
    "supplier_invoice_id": "a9e0…",
    "arrival_number": 118,
    "status": "registered",
    "currency": "SEK",
    "total": 499,
    "total_sek": 499,
    "registration_journal_entry_id": "9c1e…",
    "inbox_item_id": "1b2c…"
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

POST /api/v1/companies/:companyId/inbox-items/:id/match-supplier

inbox-items.match-supplier · scope documents:write

Set which supplier an inbox item comes from.

Sets the item's matched supplier, the supplier the conversion to a supplier invoice (POST /inbox-items/{id}/convert) uses when the request names none. A hint only: nothing is registered or booked. Picking another supplier later replaces it. Idempotent. Dry-runnable.

Use when: The reading named the supplier ambiguously or not at all, and the right supplier exists in the register (GET /suppliers).

Don't use for: Creating a supplier (POST /suppliers) or registering the invoice (POST /inbox-items/{id}/convert, which also accepts supplier_id directly).

Pitfalls

  • The supplier must belong to the same company: otherwise 404 SUPPLIER_NOT_FOUND.
  • An item already converted keeps the supplier its supplier invoice has; this only changes the item's hint.

Risk: low · Idempotent: yes · Reversible: yes · Dry-run supported: yes

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.

Request body

NameTypeRequiredDescription
supplier_idstringyesThe supplier id (from GET /suppliers).

Response fields

NameType
inbox_item_idstring
matched_supplier_idstring

Example request

{
  "supplier_id": "8a9b…"
}

Example response

{
  "data": {
    "inbox_item_id": "1b2c…",
    "matched_supplier_id": "8a9b…"
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

POST /api/v1/companies/:companyId/inbox-items/:id/match-transaction

inbox-items.match-transaction · scope documents:write

Pair an inbox item with the bank transaction it documents.

Sets the item's matched transaction and, when the transaction has no document yet, pins the item's document on it (an existing pin is never replaced). When the transaction is already booked, the item is completed against that verifikat: the document becomes its underlag. Release with POST /inbox-items/{id}/unmatch-transaction. Idempotent. Dry-runnable.

Use when: A receipt or invoice in the inbox belongs to a bank transaction (typically a card purchase) and should travel with it to booking.

Don't use for: Registering a supplier invoice from the item (POST /inbox-items/{id}/convert) or attaching an arbitrary document to a transaction (POST /transactions/{id}/attach-document).

Pitfalls

  • The transaction must belong to the same company: otherwise 404 TX_CATEGORIZE_TX_NOT_FOUND.
  • A document that asks for more than the transaction paid AND names another seller, or that names its seller and whose money goes the other way (a purchase on money in, a refund or credit note on money out), returns 409 DOC_ROW_MISMATCH with both sides in details; send mismatch_reason when it belongs anyway.
  • A transaction that already carries another document keeps it (details in the dry run: transaction_has_other_document).
  • Matching a booked transaction in a locked period links the document best-effort; check the verifikat afterwards.

Risk: low · Idempotent: yes · Reversible: yes · Dry-run supported: yes

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.

Request body

NameTypeRequiredDescription
transaction_idstringyesThe bank transaction id (from GET /transactions).
mismatch_reasonstringnoAfter DOC_ROW_MISMATCH: why it belongs here

Response fields

NameType
inbox_item_idstring
matched_transaction_idstring

Example request

{
  "transaction_id": "1f2e…"
}

Example response

{
  "data": {
    "inbox_item_id": "1b2c…",
    "matched_transaction_id": "1f2e…"
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

POST /api/v1/companies/:companyId/inbox-items/:id/restore

inbox-items.restore · scope documents:write

Put a deleted inbox item back in the inbox, as it was deleted.

Re-creates the item under its own id with the reading, e-mail fields, source and arrival time it had when it was deleted: nothing is read again and no new usage is counted. It comes back open: a bank transaction it was matched to is not matched again. Works once per deletion. Refused when the item or its document is in the inbox again, when the document is on a verifikat or is the underlag of a supplier invoice, an expense claim or a bank transaction, and when a byte-identical copy is queued or booked. Dry-runnable.

Use when: An inbox item was deleted by mistake (DELETE /inbox-items/{id}) and should be worked after all.

Don't use for: Queueing an archive document that never was an inbox item (upload it: POST /inbox-items) or undoing a supplier invoice or verifikat.

Pitfalls

  • The id is the deleted item's own inbox_item_id (GET /inbox-items/removed lists them), not the document id.
  • A second call answers 409 INBOX_ITEM_RESTORE_IN_INBOX: read the inbox instead of retrying.
  • 404 INBOX_ITEM_RESTORE_NOT_FOUND also covers an id from another company and an item whose document was deleted from the archive.

Risk: low · Idempotent: yes · Reversible: yes · Dry-run supported: yes

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.

Response fields

NameType
inbox_item_idstring
document_idstring
restoredtrue

Example response

{
  "data": {
    "inbox_item_id": "1b2c…",
    "document_id": "4f1c…",
    "restored": true
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

POST /api/v1/companies/:companyId/inbox-items/:id/stamp

inbox-items.stamp · scope documents:write

Mark an inbox item as consumed by a journal entry.

Sets created_journal_entry_id on an invoice_inbox_items row so the item drops out of the active inbox todo list. Use when the document was linked to a JE via a separate call and you need to close the inbox item independently.

Use when: An inbox document has already been attached to a verifikation (via documents link) but the inbox item itself was not stamped at link time: e.g. when using the v1 link endpoint without inbox_item_id.

Don't use for: Creating a new journal entry from an inbox item: use the invoice-inbox extension book-direct route for that.

Pitfalls

  • Idempotency-Key is mandatory.
  • The inbox item and journal_entry_id must both belong to the caller's company.
  • Stamping with a different journal_entry_id than the one already set returns CONFLICT: the item is already resolved.

Risk: low · Idempotent: yes · Reversible: no · Dry-run supported: no

Request body

NameTypeRequired
journal_entry_idstringyes

Response fields

NameTypeDescription
idstring
handlestring (optional)Typed handle of this inbox item: inbx_ plus its id as 32 lowercase hex. Accepted wherever the id is.
created_journal_entry_idstring

Example request

{
  "journal_entry_id": "0d1d0000-0000-4000-8000-000000000004"
}

Example response

{
  "data": {
    "id": "4d2fcdbb-13b3-4ff3-911f-a4cc82f1f6db",
    "created_journal_entry_id": "0d1d0000-0000-4000-8000-000000000004"
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

POST /api/v1/companies/:companyId/inbox-items/:id/unmatch-transaction

inbox-items.unmatch-transaction · scope documents:write

Release an inbox item's bank transaction match.

Clears the item's matched transaction, and the transaction's document pin when it is still this item's document (a document from another source stays). Answers the released transaction. The item returns to the work queue. Idempotent. Dry-runnable.

Use when: The item was paired with the wrong bank transaction, or should be paired again.

Don't use for: Taking a document off a transaction directly (POST /transactions/{id}/detach-document) or undoing a booked verifikat (storno).

Pitfalls

  • Once the transaction is booked with this document as underlag, the transaction pin cannot be cleared (the document is räkenskapsinformation); the item's own match is released regardless.
  • An item with no match answers success with released_transaction_id null.

Risk: low · Idempotent: yes · Reversible: yes · Dry-run supported: yes · Stage for approval: yes (?stage=true)

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.
stagestringnotrue stages the write for approval instead of committing it: 202 with the pending operation to approve via POST /pending-operations/{id}/approve. Absent or false commits; other values are 400. A reason in the body (why you propose it, at most 500 characters) is shown to the approver as agent_reason and kept with the decision.

Response fields

NameType
inbox_item_idstring
matched_transaction_idunknown
released_transaction_idstring | null

Example response

{
  "data": {
    "inbox_item_id": "1b2c…",
    "matched_transaction_id": null,
    "released_transaction_id": "1f2e…"
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

PATCH /api/v1/companies/:companyId/inbox-items/:id

inbox-items.update-extracted-data · scope documents:write

Correct fields of an inbox item's reading (supplier, invoice, totals).

Merges the given fields into the item's extracted_data: documentKind (what the document is), supplier (name, orgNumber, vatNumber, address, bankgiro, plusgiro), invoice (invoiceNumber, invoiceDate, dueDate, paymentReference, currency, creditedInvoiceNumber) and totals (subtotal, vatAmount, total). Fields not named are kept, line items and the VAT breakdown included; null clears a field. A hand-set total becomes a verified total. Answers the merged reading. Idempotent. Dry-runnable.

Use when: The reading got a field wrong (total, date, invoice number) before the item is converted or matched.

Don't use for: Replacing the whole reading from your own extraction pipeline (MCP gnubok_set_inbox_extracted_data), or changing a registered supplier invoice.

Pitfalls

  • An item already converted to a supplier invoice returns 409 INBOX_ITEM_EDIT_LOCKED.
  • A concurrent edit returns 409 INBOX_ITEM_EDIT_CONFLICT: read the item again and retry.
  • Dates are YYYY-MM-DD; currency is a 3-letter ISO 4217 code.
  • A supplier_invoice whose subtotal or vatAmount is negative still counts as a credit note: correct the totals, not only documentKind.
  • An enskild firma's orgNumber is a personnummer: only send it when it is on the document.

Risk: low · Idempotent: yes · Reversible: yes · Dry-run supported: yes

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.

Request body

NameTypeRequired
documentKind"receipt" | "supplier_invoice" | "credit_note" | "government_letter" | "other" | nullno
supplierobjectno
invoiceobjectno
totalsobjectno

Response fields

NameTypeDescription
inbox_item_idstring
handlestring (optional)Typed handle of this inbox item: inbx_ plus its id as 32 lowercase hex. Accepted wherever the id is.
extracted_dataobject

Example request

{
  "totals": {
    "total": 499
  },
  "invoice": {
    "invoiceDate": "2026-09-01"
  }
}

Example response

{
  "data": {
    "inbox_item_id": "1b2c…",
    "extracted_data": {
      "totals": {
        "total": 499
      },
      "invoice": {
        "invoiceDate": "2026-09-01"
      }
    }
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

PUT /api/v1/companies/:companyId/inbox-items/:id/purchase-category

inbox-items.set-purchase-category · scope documents:write

Set, or clear, what an inbox item bought (its purchase category).

Stores the given purchase-category code on the item as a person's choice, which the item then reads as purchase_category with source person and level "Ditt val". code null clears the choice, and the item reads the computed proposal again. every_time true also makes it the instruction for the item's matched supplier: later items from that supplier read it as source instruction, level "Ditt val", under any choice made on a single item and over the learned proposal (with code null it removes the instruction). Answers what the item reads after the write. Books nothing: the account stays the booking's. Idempotent. Dry-runnable.

Use when: The proposed purchase category is wrong or missing, and the person says what was bought; with every_time, when they say it holds for everything from that supplier.

Don't use for: Choosing the account a purchase is booked on (that is the booking), or correcting the reading's fields (PATCH /inbox-items/{id}).

Pitfalls

  • An item already converted to a supplier invoice returns 409 INBOX_ITEM_EDIT_LOCKED.
  • An item with no reading of its own yet returns 409 INBOX_ITEM_NO_READING.
  • every_time on an item without a matched supplier returns 409 INBOX_ITEM_NO_SUPPLIER and writes nothing.
  • A concurrent edit returns 409 INBOX_ITEM_EDIT_CONFLICT: read the item again and retry.
  • expected_supplier_id given and the item now matched to another supplier (or none) returns 409 INBOX_ITEM_SUPPLIER_CHANGED and writes nothing.
  • Codes are the purchase-category taxonomy's (e.g. "expense.software.saas", "expense.equipment.furniture"); anything else is 400.

Risk: low · Idempotent: yes · Reversible: yes · Dry-run supported: yes · Stage for approval: yes (?stage=true)

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.
stagestringnotrue stages the write for approval instead of committing it: 202 with the pending operation to approve via POST /pending-operations/{id}/approve. Absent or false commits; other values are 400. A reason in the body (why you propose it, at most 500 characters) is shown to the approver as agent_reason and kept with the decision.

Request body

NameTypeRequiredDescription
code"expense.software.saas" | "expense.software.licence" | "expense.software.cloud_hosting" | "expense.software.domains" | "expense.software.services" | "expense.telecom.mobile" | "expense.telecom.landline" | "expense.telecom.internet" | "expense.office.supplies" | "expense.office.printing" | "expense.office.postage" | "expense.premises.rent" | "expense.premises.electricity" | "expense.premises.heating" | "expense.premises.water" | "expense.premises.cleaning" | "expense.premises.repairs" | "expense.premises.alarm" | "expense.equipment.hardware" | "expense.equipment.furniture" | "expense.equipment.tools" | "expense.equipment.machinery" | "expense.equipment.rental" | "expense.equipment.repairs" | "expense.consumables.operating_supplies" | "expense.vehicle.fuel" | "expense.vehicle.parking" | "expense.vehicle.repairs" | "expense.vehicle.leasing" | "expense.vehicle.insurance_tax" | "expense.vehicle.congestion_tax" | "expense.vehicle.accessories" | "expense.travel.flight" | "expense.travel.train" | "expense.travel.taxi" | "expense.travel.hotel" | "expense.travel.car_rental" | "expense.travel.meals" | "expense.travel.other" | "expense.representation.client" | "expense.representation.staff" | "expense.marketing.ads" | "expense.marketing.print" | "expense.marketing.events" | "expense.marketing.gifts" | "expense.marketing.sponsorship" | "expense.marketing.agency" | "expense.professional_services.accounting" | "expense.professional_services.audit" | "expense.professional_services.legal" | "expense.professional_services.tax_advice" | "expense.professional_services.consulting" | "expense.professional_services.technical" | "expense.professional_services.staffing" | "expense.goods.resale" | "expense.goods.materials" | "expense.goods.subcontracting" | "expense.goods.packaging" | "expense.goods.freight" | "expense.goods.customs" | "expense.personnel.health" | "expense.personnel.wellness" | "expense.personnel.recruitment" | "expense.personnel.workwear" | "expense.personnel.gifts" | "expense.personnel.refreshments" | "expense.education.training" | "expense.education.literature" | "expense.insurance.business" | "expense.insurance.credit" | "expense.insurance.deductible" | "expense.bank_fees.fees" | "expense.bank_fees.factoring" | "expense.card_fees.payment_fees" | "expense.fees.authorities" | "expense.fees.memberships" | "expense.fees.collection" | "expense.fees.royalties" | "expense.fees.patents_trademarks" | nullyesA purchase-category code (e.g. "expense.software.saas"), or null to clear the choice and read the proposal again.
every_timebooleannotrue: also make it the instruction for the item's matched supplier, so later items from that supplier are proposed this category as "Ditt val" (null removes the instruction). Never changes a choice made on another single item. Omitted or false: this item only.
expected_supplier_idstringnoPrecondition: the supplier the item must still be matched to (matched_supplier_id). Any other match refuses with INBOX_ITEM_SUPPLIER_CHANGED and writes nothing. A staged every_time pins it.

Response fields

NameTypeDescription
inbox_item_idstring
purchase_categoryobject | nullWhat the underlag bought, computed when read; null when the evidence is ambiguous. Not a booking: the account stays the booking's.

Example request

{
  "code": "expense.equipment.furniture",
  "every_time": true
}

Example response

{
  "data": {
    "inbox_item_id": "1b2c…",
    "purchase_category": {
      "code": "expense.equipment.furniture",
      "source": "person",
      "level": "Ditt val",
      "version": "pc-2026-10"
    }
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

DELETE /api/v1/companies/:companyId/inbox-items/:id

inbox-items.delete · scope documents:write

Discard an inbox item that was never converted or booked.

Takes the item out of the inbox. A document it carried stays in the archive with its own deletion rule (DELETE /documents/{id}), and the item as it was (its reading and e-mail fields) is kept with that document, so it can be put back (POST /inbox-items/{id}/restore) when the dry run's preview answers can_be_put_back true. Refused once the item became a supplier invoice or was booked. Idempotent. Dry-runnable.

Use when: Spam, a duplicate delivery or a non-accounting e-mail landed in the inbox.

Don't use for: Deleting the document itself (DELETE /documents/{id}) or undoing a supplier invoice or verifikat.

Pitfalls

  • A converted item returns 409 INBOX_ITEM_DELETE_CONVERTED; a booked one 409 INBOX_ITEM_DELETE_BOOKED.
  • Not every removal can be undone: an item that carried no document (a mail without a readable attachment) keeps nothing, and one matched to a bank transaction, or whose document a verifikat holds, is not put back. The dry run's preview says which: can_be_put_back.
  • Deleting the document afterwards (DELETE /documents/{id}) removes the kept item with it: then nothing can be put back.

Risk: medium · Idempotent: yes · Reversible: yes · Dry-run supported: yes · Stage for approval: yes (?stage=true)

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.
stagestringnotrue stages the write for approval instead of committing it: 202 with the pending operation to approve via POST /pending-operations/{id}/approve. Absent or false commits; other values are 400. A reason in the body (why you propose it, at most 500 characters) is shown to the approver as agent_reason and kept with the decision.

Response fields

NameType
inbox_item_idstring
deletedtrue

Example response

{
  "data": {
    "inbox_item_id": "1b2c…",
    "deleted": true
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}