Vexless API

Overview

Vexless is a headless system of record for bookkeeping, built for software companies whose customers run a business. Your customers use your software. Their books are kept in Vexless without them, or you, doing any accounting.

You never choose accounts, compute VAT or post to a ledger. You send an origin: a sales invoice you issued, a bill your user wants paid, a bank transaction. Vexless interprets it, posts it, matches money against it, and reports back through statuses and webhooks.

Anything a model is unsure about is handled by an accountant in a separate Vexless control surface. You do not build for it. What it produces reaches you as the same statuses and events.

First jurisdiction: Finland. The OpenAPI document is the contract; every response is typed there and enforced by the server. The endpoint reference at the end of this page is generated from it.

https://api.vexless.io/v1             # base URL of the service; reserved, not live yet
https://docs.vexless.io/              # this reference
https://docs.vexless.io/openapi.json  # OpenAPI 3.1, fully typed responses; also /openapi.yaml
https://docs.vexless.io/llms.txt      # for agents; /llms-full.txt has the whole reference as text

Getting started

Six requests take one customer from nothing to a paid invoice. All of them work on a sandbox company with no real bank involved.

1. Get an API key

Vexless issues your organisation, a partner, an API key. It starts with vx_ and is shown once. Every request carries it as a bearer token.

2. Create the customer's company

POST /v1/companies
Authorization: Bearer vx_…
X-Actor: agent:onboarding@1.0
Idempotency-Key: company-asiakas-oy
Content-Type: application/json

{ "name": "Asiakas Oy", "businessIdentifier": "1234567-8", "jurisdiction": "FI", "sandbox": true }

201
{ "id": "cmp_06g6…", "name": "Asiakas Oy", "currency": "EUR", "sandbox": true, "lockDate": null, "createdAt": "2026-09-03T09:12:03.120Z",
  "connections": [ { "kind": "PARTNER_API", … }, { "kind": "EINVOICE", … }, { "kind": "AUTHORITY", … }, { "kind": "BANK", "provider": "sandbox", "status": "ACTIVE", … } ],
  "externalAccounts": [ { "kind": "BANK", "externalId": "FI0000000000000000", "accountNumber": "1910", … } ],
  "fiscalYears": [ { "id": "fy_…", "startDate": "2026-01-01", "endDate": "2026-12-31", "closedAt": null, … } ] }

The company arrives with the Finnish chart of accounts, tax codes, an e-invoice and an authority connection, and, because it is a sandbox, a simulated bank account. Your partner is granted the standard scopes on it. GET /v1/companies lists every company you hold a grant on.

3. Subscribe to events

POST /v1/companies/cmp_06g6…/webhooks
{ "url": "https://your.app/vexless", "events": ["origin.posted", "origin.settled", "origin.needs_review", "payment.executed", "payment.rejected"] }

201
{ "id": "whk_…", "secret": "…" }        # keep the secret; it signs every delivery

4. Issue a sales invoice

POST /v1/companies/cmp_06g6…/origins
Idempotency-Key: inv-2026-000117

{
  "type": "SALES_INVOICE",
  "externalReference": "2026-000117",
  "buyer": { "businessId": "7654321-1", "name": "Ostaja Oy", "externalId": "cust-42" },
  "dueDate": "2026-09-17",
  "lines": [ { "description": "Consulting, August 2026", "net": 100000, "hint": "consulting" } ]
}

201
{ "id": "org_06g6…", "type": "SALES_INVOICE", "status": "POSTED",
  "invoiceNumber": 1, "paymentReference": "RF74000001",
  "total": { "amount": 125500, "currency": "EUR" },
  "settlement": { "state": "unpaid", "paid": 0, "remaining": 125500, "paidAt": null, "paidBy": [], "currency": "EUR" },
  "delivery": { "channel": "PDF_EMAIL", "status": "PENDING_PROVIDER" },
  "currentInterpretationId": "int_…", "confidence": 1,
  "entries": [ { "number": 1, "version": 1, "date": "2026-09-03", "postings": [
      { "accountNumber": "1700", "accountName": "Myyntisaamiset", "amount": 125500, "partyId": "pty_…", "remaining": 125500, … },
      { "accountNumber": "3010", "accountName": "Palvelumyynti", "amount": -100000, "taxCode": "FI_SALE_25_5", … },
      { "accountNumber": "2939", "accountName": "Arvonlisäverovelka", "amount": -25500, "taxCode": "FI_SALE_25_5", … } ] } ], … }

You sent net lines and a business id. Vexless resolved the buyer, applied 25.5 % VAT, assigned the invoice number and RF reference, and posted the entry.

5. Show what is open

GET /v1/companies/cmp_06g6…/open-items?direction=receivable

200
{ "items": [ { "originId": "org_06g6…", "partyName": "Ostaja Oy", "partyExternalId": "cust-42", "direction": "receivable",
               "amount": { "amount": 125500, "currency": "EUR" }, "remaining": { "amount": 125500, "currency": "EUR" },
               "externalReference": "2026-000117", "paymentReference": "RF74000001", "dueDate": "2026-09-17", … } ],
  "next": null }

6. The customer pays

In production the bank connection delivers the transaction. In the sandbox, and for any bank feed you operate yourself, you send it:

POST /v1/companies/cmp_06g6…/origins
{ "type": "BANK_TRANSACTION", "externalId": "bank-tx-8812", "iban": "FI0000000000000000",
  "amount": 125500, "bookingDate": "2026-09-15", "reference": "RF74000001",
  "counterparty": { "name": "OSTAJA OY", "iban": "FI2112345600000785" } }

201  → status POSTED; postings 1910 +125500, 1700 −125500, allocated to the invoice by reference

Your webhook receives origin.settled for the invoice with your external reference. Its status is now SETTLED. That is the whole loop.

Authentication and access

Every request carries Authorization: Bearer vx_…. The key identifies your partner. What you may do on a company is decided by the grant your partner holds on it.

Creating a company grants the creating partner these scopes: origins:write, ledger:read, settlements:write, payments:write, connections:manage, grants:manage. With grants:manage you can give another partner, an accounting office for instance, or yourself, further scopes:

POST /v1/companies/{companyId}/grants
{ "granteeKind": "OFFICE", "granteeId": "ptn_…", "scopes": ["review:write", "accounts:manage", "close:manage"] }

A request without a valid key answers 401 UNAUTHENTICATED. A request on a company your partner has no grant on answers 404 COMPANY_NOT_FOUND. A missing scope answers 403 SCOPE_MISSING.

Headers on every write

Money, dates, ids, paging

Errors

Every refused request answers with the rule it broke, a message for a person, and a JSON pointer into the request when one applies. Extra keys carry context.

{ "rule": "ORIGIN_DUPLICATE", "message": "An origin with externalReference 2026-000117 already exists",
  "path": "/externalReference", "existingId": "org_06g6…" }

Companies

One per customer of yours. Created with the jurisdiction's chart of accounts, tax codes, an e-invoice connection, an authority connection and a calendar fiscal year.

POST /v1/companies
{ "name": "Asiakas Oy", "businessIdentifier": "1234567-8", "jurisdiction": "FI",
  "sandbox": true,                      # optional; enables the simulated bank and sandbox endpoints
  "fiscalYearStart": "2026-01-01" }     # optional; defaults to 1 January of the current year

GET  /v1/companies?cursor=&limit=       # every company your partner holds a grant on
GET  /v1/companies/{companyId}          # connections, externalAccounts, fiscalYears, lockDate
GET  /v1/companies/{companyId}/accounts # { items: [{ id, number, name, type, openItems, status, reportingCode }] }
GET  /v1/companies/{companyId}/fiscal-years
GET  /v1/tax-codes?jurisdiction=FI      # { items: [{ code, name, kind, rateBps, validFrom, validTo, returnLine }] }

Every account carries a reportingCode, the statutory report line it rolls up to. The reports group by it.

Auto-accept policy

Per origin type, the company decides what posts without an accountant: a minimum confidence, an optional maximum amount, and whether the counterparty must already be known. Defaults: 0.9 for sales invoices, purchase invoices and bank transactions; purchase invoices additionally require a known supplier. This is why a supplier's first bill always goes to review, however good your hint. An accountant with accounts:manage can change it:

GET /v1/companies/{companyId}/policies/auto-accept
PUT /v1/companies/{companyId}/policies/auto-accept/PURCHASE_INVOICE
{ "minConfidence": 0.8, "maxAmount": 500000, "knownPartyOnly": false }

Bank connections

Sandbox companies come with an active simulated bank whose account is FI0000000000000000, mapped to ledger account 1910. For a real bank:

POST /v1/companies/{companyId}/connections
{ "kind": "BANK", "provider": "op" }
201 → { "id": "con_…", "status": "NEEDS_AUTH", "consentUrl": "https://…" }   # send your user there

Real bank providers are not connected in this version; the connection stays in NEEDS_AUTH. Bank transactions can always be sent through the origins endpoint.

Dimensions

Your own labels for reporting: Location, Project, Team. A line carries at most one dimension per category. They never change how anything is posted.

POST /v1/companies/{companyId}/dimensions
{ "category": "Location", "name": "Helsinki" }          # creates the category on first use
201 → { "id": "dim_…", "categoryId": "dcat_…" }
GET  /v1/companies/{companyId}/dimensions               # { items: [{ id, name, requiredOnAccounts, dimensions: [{ id, name }] }] }

Origins

The document behind every entry. One endpoint, four types, discriminated by type. The response is always the origin, already interpreted and, when policy allows, posted.

POST /v1/companies/{companyId}/origins            # 201, or 409 ORIGIN_DUPLICATE
POST /v1/companies/{companyId}/origins?dryRun=true # 200; runs the whole pipeline and rolls back; response carries "dryRun": true
GET  /v1/companies/{companyId}/origins/{originId}?explain=true
GET  /v1/companies/{companyId}/origins?type=&status=&partyId=&from=&to=&externalReference=&settlementState=&cursor=&limit=
POST /v1/companies/{companyId}/origins/{originId}/reverse   # undo a posted origin you delivered; see below

Naming a party

Wherever a party is expected, send any one identifier. Vexless resolves it or creates the party. Identifiers learned on one company recognise the same legal party on another, which is why matching works from day one. What you get back is always your own view of the party: the name you gave, or the identifier you gave when you gave no name, and only the identifiers your company supplied. Nothing another company knows about the party is shown to you.

Lines

SALES_INVOICE

An invoice you issued to your customer's customer. Vexless assigns invoiceNumber and the RF paymentReference. Delivery goes by e-invoice when the buyer has an e-invoice address, otherwise as a PDF.

A credit note is a sales invoice with negative lines.

PURCHASE_INVOICE

A bill your customer received. In production most arrive through the e-invoice connection. You send the ones you capture yourself.

BANK_TRANSACTION

One line of a bank statement. Vexless posts the bank side and decides the counter side by matching against open items, then by the counterparty's default account, otherwise to a suspense account for review.

MANUAL

Explicit postings, for the rare case your software knows exactly what to book. Must balance. Postings on receivables, payables or other open-item accounts need a party.

{ "type": "MANUAL", "description": "Bank fee", "documentDate": "2026-09-05",
  "postings": [ { "accountNumber": "6900", "amount": 500 }, { "accountNumber": "1910", "amount": -500 } ] }

Reversing an origin

A bank feed can push the same transaction twice under different ids, or a captured bill can be simply wrong. POST …/origins/{originId}/reverse books a new entry with the postings negated, clears the original's open items against it, and sets the origin to REVERSED. The original entry stays as history and both entries appear on the origin. With origins:write you may reverse origins your own partner delivered; review:write may reverse any. An invoice that already has payments allocated to it cannot be reversed: issue a credit note or have a reviewer correct it.

The origin response

Returned by every origin endpoint, and carried in part by every origin event.

Attachments

The PDF, XML or photo behind an origin. Vexless stores it, keeps it for the statutory retention period, and deduplicates by content.

POST /v1/companies/{companyId}/origins/{originId}/attachments
{ "filename": "receipt.jpg", "mediaType": "image/jpeg", "contentBase64": "…" }     # at most 10 MB decoded
201 → { "id": "att_…", "originId": "org_…", "filename": "receipt.jpg", "mediaType": "image/jpeg", "size": 48213,
        "hash": "sha256…", "retentionUntil": "2032-12-31", "createdBy": "user:mikko", "createdAt": "…" }

GET /v1/companies/{companyId}/origins/{originId}/attachments                       # { items, next }
GET /v1/companies/{companyId}/origins/{originId}/attachments/{attachmentId}        # the bytes, with Content-Type and X-Vexless-Sha256

Sending the same content twice returns the existing attachment. Retention is six years from the end of the document's year.

Parties

GET /v1/companies/{companyId}/parties?externalId=&cursor=&limit=
200
{ "items": [ { "id": "prl_…", "partyId": "pty_…", "name": "Toimittaja Oy", "roles": ["SUPPLIER"], "externalId": "sup-88",
               "defaultAccountNumber": "6000", "defaultTaxCode": "FI_PURCHASE_25_5",
               "identifiers": [ { "scheme": "BUSINESS_ID", "value": "1111111-1", "source": "DOCUMENT" }, { "scheme": "IBAN", … } ], … } ],
  "next": null }

PATCH /v1/companies/{companyId}/parties/{partyId}
{ "name": "Our Supplier", "externalId": "sup-88", "iban": "FI4250001510000023" }   # origins:write
{ "defaultAccountNumber": "6000", "defaultTaxCode": "FI_PURCHASE_25_5" }            # accounts:manage

The defaults are what the interpreter uses for that supplier's bills. They are learned automatically when an accountant accepts or corrects a bill, and can be set directly with accounts:manage. An IBAN you add here is one Vexless may pay to.

Ledger reads and reports

You never write to the ledger. These are the reads a product needs.

GET /v1/companies/{companyId}/open-items?direction=receivable|payable&partyId=&dueBefore=&account=&cursor=&limit=
→ { items: [{ id, postingId, originId, originType, entryId, accountNumber, partyId, partyName, partyExternalId, direction,
              amount, remaining, externalReference, paymentReference, invoiceNumber, documentDate, dueDate }], next }

GET /v1/companies/{companyId}/balances?asOf=2026-08-31&accounts=1910,1700&dimensionId=
→ { asOf, from: null, currency, accounts: [{ accountId, number, name, type, reportingCode, balance }] }
   every active account, zero included; balance is cumulative at asOf, signed

GET /v1/companies/{companyId}/balances?from=2026-08-01&asOf=2026-08-31
GET /v1/companies/{companyId}/balances?fiscalYearId=fy_…
→ with from (or a fiscal year), balance is the movement within the range

GET /v1/companies/{companyId}/reports/income-statement?from=&to=        # or ?fiscalYearId=
→ { from, to, currency, lines: [{ code, label, amount }], result }     revenue positive, expenses negative

GET /v1/companies/{companyId}/reports/balance-sheet?asOf=
→ { asOf, currency, assets: [...], equityAndLiabilities: [...], totals }   the current-year result line includes the not-yet-closed profit

GET /v1/companies/{companyId}/entries?from=&to=&account=&cursor=&limit=
GET /v1/companies/{companyId}/entries/{entryId}
GET /v1/companies/{companyId}/entries/{entryId}/versions      # { items } — history after corrections

Report lines are the statutory small-company layouts, grouped by each account's reportingCode. Both totals of the balance sheet agree at any date.

Settlements

Most allocation happens automatically. Use these when your software knows the link better than the matcher, for example from a card processor's payout report. The simplest form is settles on the bank transaction itself. The explicit form works on posting ids from open items:

POST /v1/companies/{companyId}/settlements
{ "allocations": [ { "debitPostingId": "pst_invoice…", "creditPostingId": "pst_payment…", "amount": 125500 } ] }
201 → { id, accountNumber, status: OPEN | CLOSED, allocations: [{ debitPostingId, creditPostingId, amount, basis, actor }] }

GET /v1/companies/{companyId}/settlements/{settlementId}

Both postings must be on the same open-item account, one debit and one credit, and the amount cannot exceed either remaining. Overpayments stay as an open credit on the payer. Closing a settlement that does not net to zero, with a write-off, fee or FX difference, is an accountant action.

Payments

Vexless pays purchase invoices. Approval is your workflow: the POST is the approval, and the actor on it is recorded as the approver. Nothing is posted when a payment is sent; the ledger moves when the bank transaction arrives, and the payment links the two.

POST /v1/companies/{companyId}/payments
X-Actor: user:mikko
{ "originId": "org_bill…", "executeOn": "2026-09-30", "amount": 50200 }   # amount defaults to remaining; executeOn to the due date

201
{ "id": "pay_…", "originId": "org_bill…", "status": "CREATED",
  "amount": { "amount": 50200, "currency": "EUR" }, "executeOn": "2026-09-30",
  "payeeIban": "FI4250001510000023", "paymentReference": null, "bankReference": null, "bankTransactionOriginId": null, … }

GET  /v1/companies/{companyId}/payments/{paymentId}
POST /v1/companies/{companyId}/payments/{paymentId}/cancel     # while CREATED

Status moves CREATED → SENT → ACCEPTED → EXECUTED, or REJECTED with a rejectReason, or CANCELLED. The payee IBAN must be one your company supplied for the seller; without one the call answers PAYMENT_NO_PAYEE_IBAN. A payment on a bill still in review is accepted and held until the bill is posted.

Webhooks and events

POST   /v1/companies/{companyId}/webhooks    { "url": "https://…", "events": ["origin.settled", …], "secret": "optional, ≥16 chars" }
201 → { "id": "whk_…", "secret": "…" }
GET    /v1/companies/{companyId}/webhooks    # { items, next }
DELETE /v1/companies/{companyId}/webhooks/{webhookId}

Delivery

Each event is POSTed as JSON to every active webhook subscribed to its type. Delivery is at least once, with retries at 30 seconds, 2 minutes, 10 minutes, 1 hour and then every 6 hours after a non-2xx response or a timeout of 10 seconds. Order is not guaranteed. Answer 2xx quickly and do the work asynchronously.

POST https://your.app/vexless
Content-Type: application/json
X-Vexless-Event: origin.settled
X-Vexless-Event-Id: evt_…
X-Vexless-Signature: t=1757000000,v1=<hex hmac-sha256(secret, t + "." + rawBody)>

{ "id": "evt_…", "type": "origin.settled", "companyId": "cmp_…", "occurredAt": "2026-09-15T09:12:03.120Z",
  "originId": "org_…", "externalReference": "2026-000117", "paidAt": "2026-09-15",
  "paid": { "amount": 125500, "currency": "EUR" }, "paidBy": ["org_banktx…"] }

Verify by recomputing the HMAC over t, a dot, and the raw body, and comparing with v1 in constant time.

Events

Sandbox

A company created with "sandbox": true behaves exactly like a live one, with a simulated bank instead of a real one. Use it to build and test the whole loop.

• The company's bank account is FI0000000000000000 on ledger account 1910. Send incoming payments as BANK_TRANSACTION origins on that IBAN.
• Outgoing payments are simulated on request. Execution books today, or on executeOn when that date has already passed; pass bookingDate to choose.

POST /v1/companies/{companyId}/sandbox/payments/{paymentId}/execute   { "bookingDate": "2026-09-30" }   # body optional
POST /v1/companies/{companyId}/sandbox/payments/{paymentId}/reject    { "reason": "insufficient funds" }

Sandbox endpoints on a live company answer 403 COMPANY_NOT_SANDBOX.

How an origin is processed

Confidence is mechanical. A sales invoice from net lines is 1.0. An unmapped hint costs 0.1. An unknown supplier costs 0.2, and a bill with neither a supplier default nor a hint costs 0.4 more. A bank transaction matched by reference is 1.0; matched by party and amount 0.85 or lower; parked on suspense 0.3.

Matching a bank transaction, in order: the RF or Finnish reference; an invoice number or the supplier's invoice number in the message; the recognised party with exactly one open item of that amount; the oldest due when several open items share the amount; the recognised party with several items summing to it. Your settles list overrides all of it.

Learning without machine learning: when an accountant accepts or corrects a bill, the chosen account and tax code become that supplier's defaults, so the next bill posts on its own.

The accounting side

These happen in Vexless without you. An accountant does them in a Vexless control surface, or through the same API with accountant scopes. You observe the results.

• Review. Origins outside the policy are accepted, corrected or rejected. You see origin.needs_review, then origin.posted or origin.rejected. A correction is applied and accepted in one call; there is no second step.
• Corrections. An entry is replaced by a new version with the same number. origin.posted fires again.
• Lock. The lock date moves forward, usually monthly. company.locked. An origin dated inside the locked range posts on the first open date; its document date is kept.
• Year-end close. Revenue and expense accounts are zeroed into the result account on the last day of the year and the result moves to retained earnings on the first day of the next. The year locks. fiscal_year.closed. After it, period figures for that year still come from balances?fiscalYearId= and the income statement, while the balance sheet carries the result in equity.
• Residuals. Settlements that cannot reach zero are closed with a write-off, fee or FX difference booked as a system origin.

Endpoint reference

Generated from the OpenAPI document at build time: every operation with its parameters, request body and response schema, then the named schemas the responses refer to.

Companies and access

Origins and attachments

Ledger reads and reports

Settlements

Payments

Parties

Chart, tax codes, dimensions, policies

Connections

Webhooks

Review (accountant scopes)

Close (accountant scopes)

Sandbox

Meta

Schemas

Named objects the responses refer to. Every field is present in every response; nullable fields are marked.

Current limits

• Invoice delivery is recorded but not performed: delivery.status stays PENDING_PROVIDER. Render and send invoices yourself for now; the number and RF reference are in the response.
• Real bank and e-invoice providers are not connected. Send bank transactions and captured bills through the origins endpoint. Payments execute only in the sandbox.
• Foreign-currency origins need an explicit fxRate; there is no rate source yet.
• Finland only. The chart of accounts is a minimal one that covers these flows; the statutory report layouts are abbreviated to its lines.

Everything else on this page is implemented, typed in the OpenAPI document, and covered by end-to-end tests.