Konto Agent API (1.0.0)

Send the user's browser here. They sign in to Konto, review the requested scopes, and are redirected back to redirect_uri with a short-lived authorization code (10-minute TTL) and your state.

PKCE: if you send a code_challenge, only S256 is accepted. Public clients (no client_secret) must send one. redirect_uri must match the value registered for the client exactly.

Exchange an authorization code (with grant_type=authorization_code) or a refresh_token (with grant_type=refresh_token) for an access token. Refresh tokens rotate — persist the new refresh_token from every response. Refresh does not require redirect_uri.

Create an agent client and receive a client_id + client_secret (the secret is shown once). In practice Konto often provisions clients — especially shared app clients (one client many merchants authorize) — manually; contact Konto for onboarding.

Returns the connected company name, registration number (kennitala) and username. A plain object, not the status/result envelope.

The agent clients currently authorized on this account, with granted scopes. A plain object, not the status/result envelope.

Immediately invalidates that client's tokens. Irreversible. Revoking the client you are currently using cuts off your own access.

Recent actions taken by agent clients on this account, newest first. A plain object, not the status/result envelope.

Results include deactivated profiles — filter client-side if needed. Without limit, every customer is returned.

search matches the customer name only (substring). kennitala switches to a kennitala search; it is a substring match too, so check registration_no in the results when you need an exact hit.

Does not dedupe by kennitala — each call creates a new profile. To change an existing one, GET it then PUT. result is the new customer's guid.

On create, output_select is not read: the customer gets email delivery (3), or e-invoice (2) when trading_partner_id is sent. So email is always required here. For a PDF-only customer (4), create it and then PUT output_select: 4.

A refusal is HTTP 200 with status: false and one of: Please input validate kennitala, Name is required, Please input validate email, Trading partner is required, Language is required, Currency is required, or Data customer invalidate (missing or unreadable data).

Send the fields you want to change; the others keep their values. The whole record is then validated with the create rules, and here output_select can be set (4 makes email optional). result is the customer's guid. PUT bodies must be application/json.

Every catalogue item, inactive ones included. Without limit, all of them.

Catalogue product/service. description, uom and tax are required — there is no default VAT code (the Konto MCP server fills C62 / Z for you; the API does not). unit_price defaults to 0. The item number is assigned automatically. result is the new item's guid.

A refusal is HTTP 200 with status: false and Description is required, Unit of measure is required, Tax is required or Data item invalidate.

Includes the stock lots.

Send the fields to change — but always send unit_price: an update without it sets the price to 0. The other fields keep their values when omitted. result is the item's guid.

Recurring templates, group invoices and hidden invoices are not listed. Drafts are (status Draft). Outside sync mode, omitting limit returns every matching invoice, newest issue date first.

Send updated_since and/or cursor for sync mode: rows in a stable (updated, id) order, limit per page (default 100, max 500), has_more and next_cursor on the envelope. Pass next_cursor back as cursor until has_more is false. sort, page, date_filter, from_date and to_date are then ignored.

Creates and issues an invoice — Konto delivers it to the customer per their delivery setting. amount must equal Σ(line items) + VAT. For a credit note, send type: credit + ref_invoice_guid (the original is marked credited and its customer is inherited).

result is the new invoice's guid. With save: 1 the invoice is stored as a draft instead: nothing is sent, and the answer is the same 201 with the draft's guid.

Sending a catalogue line (guid) with your own description, uom, unit_price or tax also updates that catalogue item to those values.

A refusal is HTTP 200 with status: false, the reason in message — for example Amount is required, Currency is required, Customer is required, Settlement date is required, Issue date is smaller than now (issue date in the future), Settlement date is older than the due date, Type is required (invoice or credit), Item number is required, The calculated total amount of all item lines not equal to the total amount, an empty account balance, a used-up claim quota, or error_code claim_not_configured / customer_mismatch / feature_required.

Any of the account's invoices by guid, drafts, recurring templates and credit notes included.

Updates only the bookkeeping accounting status (and an optional message). It cannot edit amounts, dates, line items or the customer. Any of the four statuses can be set, in any order. result is the invoice's guid; a bad status is refused with Accounting status is required.

A template that auto-generates invoices on a schedule. Same amount, line-item and customer rules as a normal invoice, with two differences: for ISK each line's net amount and VAT are rounded to whole krónur before they are summed, and due_date must be at least 72 hours from now. result is the recurring schedule's guid.

The number of invoices matching the filters. Takes the filters of GET /api/v1/agent/invoices except paging and sorting.

The count covers every invoice record on the account, including recurring-invoice templates and grouped or hidden invoices that the list endpoint leaves out, so it can be higher than the number of invoices the list returns.

Known issue: with date_filter=created_date, to_date currently acts as a second lower bound rather than an upper bound. Filter on the issue date (the default) for reliable ranges.

Invoice counts and totals for a period, grouped by status and currency — the figures behind Konto's dashboard cards. Read from pre-computed monthly buckets, so the cost does not grow with invoice volume.

Pick one period mode (evaluated in this order):

Buckets are monthly, so a custom range is widened to whole months: from_date=2026-01-15&to_date=2026-04-15 covers 2026-01-01 – 2026-04-30 (see period in the response). Invoices are placed by issue date.

Statuses:

• paid — paid invoices. Credit notes are not counted here.
• sent — issued and unpaid, not past the settlement date (eindagi), no active collection case.
• overdue — issued and unpaid, past the settlement date, no active collection case.
• collection — issued and unpaid, with an active collection case.
• total — always the first entry: the sum of the four above.

Apart from total, only statuses with data are listed. Amounts include VAT, stay in the invoice currency (never converted), and are rounded to 0 decimals for ISK and 2 for other currencies. Credit notes count negative in sent, overdue and collection.

The response is not wrapped in result: period and summaries sit at the top level next to status.

Requires the dashboard_data feature on the account's plan; without it the reply is status: false with a "Subscription does not include the required feature" message.

Pages by default: 10 records per page unless you send limit (limit=0 returns everything). A paged reply also carries hasMore, limit, page and next_url (a legacy-API URL; build the next request yourself with page + 1). Newest issue date first unless you pass sort. Each record includes its file and xml base64, so keep pages small. Deleted records and records Cost AI is still reading are not listed.

Send updated_since and/or cursor for sync mode: rows in a stable (updated, id) order, limit per page (default 100, max 500), has_more and next_cursor on the envelope. Pass next_cursor back as cursor until has_more is false. sort and page are then ignored; the other filters still apply.

Upload a receipt/invoice image or PDF (multipart/form-data, max 5 MB; images are scaled down to 1028 px).

• Cost AI on (plan feature): Konto's AI reads amount, supplier, VAT, date and cost code. The answer carries queue: true; the record stays out of GET /costs until the AI is done, so poll GET /costs/{guid}. date is optional and description is not stored. Each upload counts against a monthly AI allowance (2 × the account's available credits); past it the answer is status: false with code: cost_limit_reached (HTTP 200).
• Cost AI off: date is required and the record is created at once with accounting status Created, holding just the file, date and description.

If you already have the numbers, use /costs/advanced instead. result is the new record's guid. Refusals are HTTP 200 with status: false: Field date is required and must be format Y-m-d, Field file is required, File must be jpg, jpeg, png, gif or pdf, File size must not exceed 5MB.

Record a cost from numbers you already have. Fields are sent flat at the top level (no data wrapper), as JSON — or as multipart/form-data to attach the receipt. For a credit note set credit_note: 1 and keep amount positive. The record may be approved at once if the account's auto-approve rules match. result is the new record's guid.

Refusals are HTTP 200 with status: false: Field date is required and must be format Y-m-d, Field amount is required and must be a positive number, Field how_paid is required, Field supplier_name is required, Field supplier_id is required, Field type is required (an unknown cost code), or a file error.

Takes the list's filters except paging and sorting. Unlike the list it also counts records Cost AI is still reading, so it can be higher than the number of records GET /costs returns.

For bookkeeping software: records what happened to an approved record. Only a record whose status is Created can be updated, and only to Posted, Skipped or Error — Created itself is set by Konto, and Posted is terminal. To edit a Created record's data, move it to New first, then re-approve. result is the record's guid.

Refusals (HTTP 200, status: false): Accounting status must be one of: Posted, Skipped, Error, Only costs with accounting_status Created can be updated via the API, No cost found, Data cost invalidate.

Moves the record to Konto's recycle bin: it disappears from the API at once, the user can restore it in Konto for 28 days, and then it is purged. Prefer status Skipped to exclude a record from bookkeeping. Refused (HTTP 200, status: false) for a Posted record (retryable: false) and while the record is being processed (retryable: true, retry_after seconds).

Moves an approved (Created), non-Posted cost back to New so it can be edited in Konto; re-approving regenerates its bookkeeping XML. result is the record's guid. Otherwise status: false with No cost found or This cost cannot be moved to New (only approved, non-Posted costs can be re-opened for editing).