Menu
Getting started
Cookbooks
API reference
- Overview
- Companies
- Capabilities
- Measures
- Packages
- Unexplained
- Liquidity forecast
- Portfolio
- Customers
- Invoices
- Collections
- Articles
- Set-offs
- Suppliers
- Supplier invoices
- Supplier payment files
- Bank payments
- Expense claims
- Transactions
- Reconciliation
- Bank accounts
- POS sales
- Webshop orders
- Journal entries
- Voucher gap explanations
- Fiscal periods
- Accounts
- Accrual schedules
- Agreements and commitments
- Tax loss carry-forwards
- Fixed assets
- Documents
- Signing requests
- Company registers
- Capital events
- Owner tax
- Inbox items
- Dimensions
- Employees
- Salary runs
- Reports
- Budgets
- Imports
- Compliance check
- Deadlines
- Skatteverket
- Peppol
- Webhooks
- Operations
- Pending operations
- Health
- API key
- Service accounts
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: List invoice-inbox items (Underlag) with a summary of what was read from each.GET/api/v1/companies/:companyId/inbox-items/:id: Read one inbox item with its full reading and e-mail text.GET/api/v1/companies/:companyId/inbox-items/removed: List the inbox items deleted most recently that can still be put back.POST/api/v1/companies/:companyId/inbox-items: Deliver a supplier invoice or receipt into the Inkorg for a person to book.POST/api/v1/companies/:companyId/inbox-items/:id/convert: Register a supplier invoice from an inbox item, with its document as underlag.POST/api/v1/companies/:companyId/inbox-items/:id/match-supplier: Set which supplier an inbox item comes from.POST/api/v1/companies/:companyId/inbox-items/:id/match-transaction: Pair an inbox item with the bank transaction it documents.POST/api/v1/companies/:companyId/inbox-items/:id/restore: Put a deleted inbox item back in the inbox, as it was deleted.POST/api/v1/companies/:companyId/inbox-items/:id/stamp: Mark an inbox item as consumed by a journal entry.POST/api/v1/companies/:companyId/inbox-items/:id/unmatch-transaction: Release an inbox item's bank transaction match.PATCH/api/v1/companies/:companyId/inbox-items/:id: Correct fields of an inbox item's reading (supplier, invoice, totals).PUT/api/v1/companies/:companyId/inbox-items/:id/purchase-category: Set, or clear, what an inbox item bought (its purchase category).DELETE/api/v1/companies/:companyId/inbox-items/:id: Discard an inbox item that was never converted or booked.
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
| Name | Type | Required | Description |
|---|---|---|---|
status | "received" | "error" | no | error = extraction failed. |
unprocessed_only | "true" | "false" | no | true = only open items: no link, not in Arkiv, and no verifikat holds the document. |
cursor | string | no | next_cursor from the previous page. Omit for the first page. |
limit | number | no | Page size, 1-100 (default 50). |
Response fields
| Name | Type |
|---|---|
inbox_items | object[] |
next_cursor | string | 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
| Name | Type | Required | Description |
|---|---|---|---|
include | "reading" | no | reading = add the one reading of the document: every field with its source and evidence level. |
Response fields
| Name | Type | Description |
|---|---|---|
inbox_item_id | string | |
handle | string (optional) | Typed handle of this inbox item: inbx_ plus its id as 32 lowercase hex. Accepted wherever the id is. |
status | string | received or error (extraction failed). |
source | string | How it arrived: email, upload, api, whatsapp, ... |
created_at | string | |
document_id | string | null | |
kind_hint | string | null | Declared kind: a +lev / +ver address tag, the type Arkiv queued it as, or a person's type in Dokument. |
vendor_name | string | null | Supplier name as read from the document. |
amount | number | null | Total as read from the document, in its currency. |
currency | string | null | |
invoice_date | string | null | |
processed | boolean | True 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_id | string | null | |
matched_transaction_id | string | null | |
matched_transaction_journal_entry_id | string | null | The verifikat that booked the matched transaction, when it is booked. |
created_supplier_invoice_id | string | null | |
created_journal_entry_id | string | null | |
underlag_status | "anchored" | "unlinked" | "unlinked_locked" | "anchored_elsewhere" | "unknown" | null | For a matched item whose transaction is booked: whether THIS item's document reached that verifikat (anchored) or not. Null otherwise. |
email_from | string | null | |
email_subject | string | null | |
email_received_at | string | null | |
error_message | string | null | |
extracted_data | object | null | |
purchase_category | object | null | What the underlag bought, computed when read; null when the evidence is ambiguous. Not a booking: the account stays the booking's. |
extraction_skipped | boolean | |
email_body_text | string | null | |
file_name | string | null | |
updated_at | string | |
intake_source | "intake_email" | "mailbox" | "whatsapp" | "upload" | "peppol" | "partner_api" | "mcp" | "migration" | "system" | "bank_feed" | "bank_file" | "sie" | "billo" | "kivra" | "paypal" | "portal" | null | The 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). |
reading | object (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_match | object | null | A 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
| Name | Type | Description |
|---|---|---|
removed_items[].inbox_item_id | string | The item's own id, the one to put back. |
removed_items[].document_id | string | The document it carried, still in the archive. |
removed_items[].file_name | string | null | |
removed_items[].vendor_name | string | null | Supplier name as read from the document. |
removed_items[].amount | number | null | Total as read from the document, in its currency. |
removed_items[].currency | string | null | |
removed_items[].email_from | string | null | |
removed_items[].email_subject | string | null | |
removed_items[].removed_at | string | When it was deleted. |
removed_items[].removed_by | object | Who 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
| Name | Type | Required | Description |
|---|---|---|---|
kind_hint | "supplier_invoice" | "receipt" | no | What the sender says it is. Shown in the Inkorg ahead of what extraction reads. |
external_ref | string | no | Your own id for this delivery (1-200 chars). A repeat answers the first delivery's item. |
sender_name | string | no | Who sent the document to you, shown as its sender. |
sender_org_number | string | no | The sender's organisationsnummer, as you have it. |
subject | string | no | A subject line, shown when no supplier name was read. |
message | string | no | A short text that came with the document. Kept with the arrival, not on the item. |
received_at | string | no | ISO timestamp you received it. Defaults to now. |
file | unknown | no |
Response fields
| Name | Type | Description |
|---|---|---|
inbox_item_id | string | The item in the Inkorg. Read it with GET /inbox-items/{id}. |
document_id | string | The archived document (BFL 7 kap retention). |
deduplicated | boolean | True when nothing new was filed: the same external_ref, or the same file, was already in the Inkorg and that item is returned. |
arrival_id | string | null | The 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
| Name | Type | Required | Description |
|---|---|---|---|
dry_run | string | no | true (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits. |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
supplier_id | string | yes | The supplier (supplier_id from GET /suppliers). |
supplier_invoice_number | string | yes | |
invoice_date | string | yes | |
due_date | string | no | |
delivery_date | string | "" | no | |
currency | "SEK" | "EUR" | "USD" | "GBP" | "NOK" | "DKK" | "CHF" | "CAD" | no | |
exchange_rate | number | no | |
vat_treatment | "standard_25" | "reduced_12" | "reduced_6" | "reverse_charge" | "export" | "exempt" | no | |
reverse_charge | boolean | no | |
reverse_charge_kind | "eu_goods" | "eu_services" | no | |
payment_reference | string | no | |
notes | string | no | |
default_dimensions | object | no | Tags for every line {"<sie_dim_no>":"<code>"}, e.g. {"1":"KS01","6":"P001"}: kostnadsställe 1, projekt 6, codes from GET /dimensions. |
vat_breakdown | object[] | no | The 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. |
items | object[] | yes |
Response fields
| Name | Type | Description |
|---|---|---|
supplier_invoice_id | string | |
arrival_number | number | null | Ankomstnummer. |
status | string | |
currency | string | |
total | number | |
total_sek | number | null | |
registration_journal_entry_id | string | null | The registration verifikat, or null when the company defers booking. |
inbox_item_id | string |
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
| Name | Type | Required | Description |
|---|---|---|---|
dry_run | string | no | true (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits. |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
supplier_id | string | yes | The supplier id (from GET /suppliers). |
Response fields
| Name | Type |
|---|---|
inbox_item_id | string |
matched_supplier_id | string |
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
| Name | Type | Required | Description |
|---|---|---|---|
dry_run | string | no | true (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits. |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
transaction_id | string | yes | The bank transaction id (from GET /transactions). |
mismatch_reason | string | no | After DOC_ROW_MISMATCH: why it belongs here |
Response fields
| Name | Type |
|---|---|
inbox_item_id | string |
matched_transaction_id | string |
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
| Name | Type | Required | Description |
|---|---|---|---|
dry_run | string | no | true (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits. |
Response fields
| Name | Type |
|---|---|
inbox_item_id | string |
document_id | string |
restored | true |
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
| Name | Type | Required |
|---|---|---|
journal_entry_id | string | yes |
Response fields
| Name | Type | Description |
|---|---|---|
id | string | |
handle | string (optional) | Typed handle of this inbox item: inbx_ plus its id as 32 lowercase hex. Accepted wherever the id is. |
created_journal_entry_id | string |
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
| Name | Type | Required | Description |
|---|---|---|---|
dry_run | string | no | true (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits. |
stage | string | no | true 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
| Name | Type |
|---|---|
inbox_item_id | string |
matched_transaction_id | unknown |
released_transaction_id | string | 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
| Name | Type | Required | Description |
|---|---|---|---|
dry_run | string | no | true (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits. |
Request body
| Name | Type | Required |
|---|---|---|
documentKind | "receipt" | "supplier_invoice" | "credit_note" | "government_letter" | "other" | null | no |
supplier | object | no |
invoice | object | no |
totals | object | no |
Response fields
| Name | Type | Description |
|---|---|---|
inbox_item_id | string | |
handle | string (optional) | Typed handle of this inbox item: inbx_ plus its id as 32 lowercase hex. Accepted wherever the id is. |
extracted_data | object |
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
| Name | Type | Required | Description |
|---|---|---|---|
dry_run | string | no | true (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits. |
stage | string | no | true 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
| Name | Type | Required | Description |
|---|---|---|---|
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" | null | yes | A purchase-category code (e.g. "expense.software.saas"), or null to clear the choice and read the proposal again. |
every_time | boolean | no | true: 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_id | string | no | Precondition: 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
| Name | Type | Description |
|---|---|---|
inbox_item_id | string | |
purchase_category | object | null | What 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
| Name | Type | Required | Description |
|---|---|---|---|
dry_run | string | no | true (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits. |
stage | string | no | true 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
| Name | Type |
|---|---|
inbox_item_id | string |
deleted | true |
Example response
{
"data": {
"inbox_item_id": "1b2c…",
"deleted": true
},
"meta": {
"request_id": "req_…",
"api_version": "2026-05-12"
}
}