Looking for the ePost APIs? developer.epost.ch

KLARA API documentation

Integrate accounting, articles, customers, payroll and time tracking directly with KLARA business software. Everything on this site is about KLARA only.

114Endpoints
5Domains
RESTover HTTPS
↓ klara-openapi.json114 operations, 1.1 MB, OpenAPI 3.0.3
Getting started From API key to your first response in under 15 minutes. Authentication API key or token flow, and when to use which. Common integration flows Eight worked examples across invoicing, bookings and master data. Sending documents Let KLARA pick the delivery channel automatically. Payroll data New: submit variable salary items to a payslip. API reference All 114 integration endpoints, grouped by domain.

Getting started

  1. Prerequisites

    An active KLARA account with a company set up, a user role that allows managing users, and an HTTP client. HTTP/1.0 is no longer supported, so use HTTP/1.1 or HTTP/2.

  2. Create an API key in KLARA

    Go to Benutzer, add a new API key, give it a name and assign at least one KLARA user role. Suggested naming convention: integration-payroll-prod.

  3. Choose roles and permissions

    Assign only the roles your use case needs. Any user holding that role can authenticate with the key, and the role cannot be changed afterwards, so pick it deliberately. See Roles & permissions.

    Which role does this guide need?

    The calls below require ARTICLE_READ_ONLY. These roles carry it: Zeit- und Materialrapporte, Online Terminbuchung, Mitarbeiter und Lohn, Kundenbeziehungen, Administrator, External user.

    Zeit- und Materialrapporte is the narrowest of them, so it is the least privilege choice for working through this page. Watch out for one that sounds right but is not: Accountant does not hold ARTICLE_READ_ONLY, so it cannot run the first call.

  4. Set up authentication

    Send the key as an X-API-KEY header, or obtain a bearer token via the token flow. See Authentication.

  5. Make your first API call

    List your articles. This is a read-only request that touches no data.

    curl -X GET "https://api.klara.ch/core/latest/articles" \
  -H "X-API-KEY: $KLARA_API_KEY" \
  -H "Accept: application/json"

    A successful call returns 200 with a JSON array. If you get 401, check the header name and that the key is assigned to a role. See Authentication.

    This example only reads, which is deliberate: there is no separate test environment, so every call works on your live data. See Environments.

  6. Where to go next

    Browse the reference by domain, or read the guides on errors, pagination and versioning.

API basics

Everything you need once, so you never have to guess again.

API routes

All endpoints live on https://api.klara.ch. Paths in this reference are relative and must be combined with the host:

GET /core/v1/invoices/42
→ https://api.klara.ch/core/v1/invoices/42

Three prefixes are in use. /core/v1 holds accounting, finance and payroll, /core/v2 holds company and individual profiles, and /core/latest still holds articles, customers and authentication.

Path prefixes and what is current

Three prefixes are in use. /core/v1 and /core/v2 are the current ones. /core/latest is older and mixed: some endpoints live only there and are perfectly current, others are superseded.

The superseded /core/latest operations stop answering on 14 August 2027 24 operations carry deprecated in the source contract: 20 in accounting, 2 in bookings, 1 in bank-reconciliation, 1 in vat-clearing-reports. They are not in the specification published here, and they carry a sunset date in the source contract: on 14 August 2027, they answer 410 Gone instead of returning data. Until then they still respond, so an existing integration does not break today, but the migration has a deadline. New work must use the current path.
SupersededUse instead
GET /core/latest/accounting/accounts/core/v1/accounting/accounts
GET /core/latest/accounting/accounts/account-displaying/core/v1/accounting/accounts/account-displaying
GET /core/latest/accounting/accounts/by-code/{accountCode}/core/v1/accounting/accounts/by-code/{accountCode}
GET /core/latest/accounting/booking-types/core/v1/accounting/booking-types
GET /core/latest/accounting/business-case-templates/core/v1/accounting/business-case-templates
GET /core/latest/accounting/business-case-templates/{businessCaseTemplateId}/core/v1/accounting/business-case-templates/{businessCaseTemplateId}
GET /core/latest/accounting/business-cases/core/v1/accounting/business-cases
GET /core/latest/accounting/business-cases/v2/core/v1/accounting/business-cases/v2
GET /core/latest/accounting/business-cases/{businessCaseId}/core/v1/accounting/business-cases/{businessCaseId}
GET /core/latest/accounting/companies/current/core/v1/accounting/companies/current
GET /core/latest/accounting/companies/current/business-case-templates/core/v1/accounting/companies/current/business-case-templates
GET /core/latest/accounting/companies/current/financial-years/core/v1/accounting/companies/current/financial-years
GET /core/latest/accounting/currencies/exchange-rate/core/v1/accounting/currencies/exchange-rate
GET /core/latest/accounting/master-vats/core/v1/accounting/master-vats
GET /core/latest/accounting/master-vats/current/core/v1/accounting/master-vats/current
GET /core/latest/accounting/master-vats/{masterVatId}/core/v1/accounting/master-vats/{masterVatId}
GET /core/latest/accounting/vat-profile/core/v1/accounting/vat-profile
GET /core/latest/accounting/vat-suggestions/core/v1/accounting/vat-suggestions
GET /core/latest/accounting/vat-types/core/v1/accounting/vat-types
GET /core/latest/accounting/vat-types/{vatTypeId}/core/v1/accounting/vat-types/{vatTypeId}
GET /core/latest/bank-reconciliation/open-positions/core/v1/bank-reconciliation/open-positions
POST /core/latest/bookings/core/v1/bookings
PUT /core/latest/bookings/{id}/documents/core/v1/bookings/{id}/documents
POST /core/latest/vat-clearing-reports/{year}/{quarter}/core/v1/vat-clearing-reports/{year}/{quarter}

Replacing /core/latest/ with /core/v1/ in the path is the whole migration. Request and response are unchanged.

HTTP verbs

VerbUsed forEndpoints
GETRetrieving resources71
PUTReplacing a resource completely10
POSTCreating resources, and some actions such as /send26
DELETERemoving a resource7

114 endpoints in total, which is the same number as in the reference below and in the downloadable specification.

The KLARA API does not use PATCH. To change part of a resource, send a complete PUT. Read the current state first if you do not hold it.

Headers

HeaderValueWhen
X-API-KEYyour API keyAPI key authentication
AuthorizationBearer <JWT>Token authentication
Acceptapplication/json Almost everywhere. Three endpoints return binary or PDF instead, see below
Content-Typedepends on the endpoint On any request with a body. Most take application/json, the token endpoints take application/x-www-form-urlencoded and the upload endpoints take multipart/form-data, see below
Accept-Languagede-CH, fr-CH, it-CH or en Optional, on the endpoints that return translated labels

Media types

Request bodies

Send the matching Content-Type. Form-encoded endpoints reject a JSON body, which is the most common reason a first token request fails.

Media typeEndpointsWhich ones
application/json23every endpoint that has one
application/x-www-form-urlencoded4POST /core/latest/generic-token
POST /core/latest/tenants
POST /core/latest/token
POST /core/latest/token/by-microsoft
multipart/form-data3POST /core/latest/articles/{article-id}/images
POST /core/latest/companies/{company-id}/documents
PUT /core/latest/articles/{article-id}/images/{image-id}

Responses

Ask for what the endpoint returns. Accept: application/json is correct almost everywhere, but not for the binary and PDF responses below.

Media typeEndpointsWhich ones
application/json114every endpoint that has one
application/octet-stream2GET /core/latest/articles/{article-id}/images/{image-id}
POST /core/latest/payroll-interface-file
application/pdf1POST /core/v1/invoices/{id}/printed-document

What an error body contains

The specification declares 533 error responses on 114 operations. Every one of them declares a body, so you can generate a type for the error case and read the code and the uuid from it.

SchemaFieldsError responsesOperations
ErrorMessagecode, createdTime, detail, message, uuid514114
ErrorResponseerror, error_description195

The OAuth-style pair error and error_description is declared on 5 operations:

It is not the shape of the authentication endpoints as a group. What the authentication endpoints declare, per endpoint and per status, is listed under Authentication. That listing is the binding one; do not generalise from this table to them.

Two of the entries above are not the application speaking. A 429 body comes from the gateway, not from the API, so it is outside this contract and may look like none of these shapes. And where a status declares no body, a gateway may still add one; that too is outside the contract.

The contract names 39 error codes of its own, in the code field of the error body:

CodeStatusMeaningWhere
account.unknown404No account with this number exists in the chart of accounts.2 operations
auth.credentials_missing401Neither an Authorization: Bearer header nor an API key header was present on the request.3 operations
balancesheet.date_invalid400date was missing or not an ISO date of the form yyyy-MM-dd, or compare-date was not an ISO date of that form.1 operation
banktransaction.booking_date_invalid400booking-date-from or booking-date-to was not an ISO date of the form yyyy-MM-dd, or booking-date-to was before booking-date-from.1 operation
booking.amount_range_invalid400amount-to was below amount-from.1 operation
booking.amount_zero400grossAmount was zero. The Booking Workflow does not book a document of zero; a negative amount is accepted for a correction.1 operation
booking.booking_date_invalid400booking-date-from or booking-date-to was not an ISO date of the form yyyy-MM-dd, or booking-date-to was before booking-date-from; for a document booking, bookingDate or booking-date was not an ISO date of that form.3 operations
booking.business_case_id_invalid400businessCaseId was set but is not a numeric business case id. Leave it empty when creating a booking; use businessCase for a label.1 operation
booking.due_date_invalid400dueDate was not an ISO date of the form yyyy-MM-dd.1 operation
booking.payment_date_invalid400paymentDate was not an ISO date of the form yyyy-MM-dd.1 operation
booking.payment_date_missing400The chosen payment option has a payment date (bank account, card, cash register, cashless payment, transfer account) and paymentDate was not sent.1 operation
booking.service_period_invalid400servicePeriodFrom or servicePeriodTo was not an ISO date of the form yyyy-MM-dd, only one of them was sent, or servicePeriodTo was before servicePeriodFrom.1 operation
booking.status_not_allowed400bookingStatus was neither BOOKED nor PLANNED.1 operation
booking.unknown404No booking with this id exists in the caller's company.1 operation
businesscase.field_not_offered400A value was sent that the chosen template and payment option do not have (text, servicePeriodFrom, dueDate, paymentPurpose or internalComment). The Booking Workflow does not show that field for this choice; the message names it.1 operation
businesscase.partner_unknown404No customer or supplier with partnerId exists in the caller's company.1 operation
businesscase.payment_group_not_offered400The business case template has no already paid option for the payment group, or the group is not available for the company (as in the Booking Workflow, for example EMPLOYEE without employees).2 operations
businesscase.payment_source_unknown404paymentSourceId was missing or is not one of the sources listBusinessCasePaymentSourcesV1 returns for this template, payment group and booking date.1 operation
businesscase.payroll_date_unknown400payrollDate was missing for EMPLOYEE or is not one of the payroll dates of the employee.1 operation
businesscase.template_not_supported400The business case template is not offered by the Booking Workflow for the booking date, or it needs input this operation does not take (asset purchase, current account, transfer account, tax and social insurance templates). The message names the missing input.1 operation
businesscase.vat_entry_unknown400vatCaseId or vatRateId was missing on a VAT template, or is not one of its entries, or the rate does not belong to the case, or the rate is valid neither on bookingDate nor within the service period.1 operation
document.archive_not_supported400The document is stored in the KLARA eArchive. bookDocumentAsPaidV1 does not book eArchive documents yet; they are booked in the web app.1 operation
document.not_in_booking_queue409The document is not waiting in the booking queue, for example because it is already booked.1 operation
document.unknown404No document with this id exists in the caller's company.1 operation
invoice.id_must_be_zero400The request body carried a non-zero id. This operation only creates invoices; use PUT /core/v1/invoices to modify an existing one.1 operation
invoice.vat_code_missing400At least one orderItems[] entry set VAT on vatType, vatCase or the top-level vatCode while leaving vat.vatCode empty. Only vat.vatCode is stored, so that line would have been booked at 0%. Move the code to vat.vatCode, or send "0" ("No VAT") for a position that genuinely carries none.2 operations
invoice.vat_rate_mismatch400At least one orderItems[] entry sent a vat.rate that is not the rate of its vat.vatCode. The booking always uses the code's rate, so the invoice document would state a different percentage than the accounting record. Send the matching rate, or omit vat.rate and let the server fill it in.2 operations
kpi.date_invalid400date-from or date-to was missing or not an ISO date of the form yyyy-MM-dd with a year from 0001, or date-to was before date-from; for getSpendingsAndEarningsV1 also when the comparison period was incomplete, not of that form or reversed, or the default comparison period would start before the year 0001.2 operations
ledger.account_range_invalid400account-to was below account-from.1 operation
openposition.reference_date_invalid400reference-date was not an ISO date of the form yyyy-MM-dd. Omit it to use today.1 operation
partneramounts.date_invalid400to-date was not an ISO date of the form yyyy-MM-dd.1 operation
profitandloss.date_invalid400date-from or date-to was missing or not an ISO date of the form yyyy-MM-dd, date-to was before date-from, or the comparison period was incomplete, not of that form or reversed.1 operation
request.search_key_unsupported400search-key was sent to an operation that has no text search.2 operations
request.sort_direction_unsupported400sort-direction was sent with the direction an operation with a fixed order does not have. The message names the available direction.3 operations
request.sort_field_invalid400sort-field was not one of the values the operation documents. The message lists the accepted values.7 operations
statement.booking_type_invalid400An entry of booking-types was not one of the published booking types.2 operations
statement.date_invalid400date-from or date-to was not an ISO date of the form yyyy-MM-dd, or date-to was before date-from.2 operations
statement.reference_invalid400reference was not of the form TYPE:id or SUB_ACCOUNT:category:id with a type, category and id as published in references of getBookingV1.2 operations
statement.vat_filter_invalid400An entry of vat was not none, a VAT case id, or a VAT case id and a VAT rate id separated by a colon.2 operations

That list is not exhaustive and is not meant to be: a failure detected by a downstream service carries that service's own code. Branch on the HTTP status, treat an unknown code as a generic error of that status, and log the code and the uuid for a support request.

Errors

Most error responses use this shape:

{
  "uuid":        "b3f1c8e2-...",
  "createdTime": "2026-07-30T09:12:44Z",
  "code":        "VALIDATION_FAILED",
  "message":     "Human readable description"
}

A small group of endpoints uses the OAuth-style shape instead. Which ones is listed in the table above, and the authentication endpoints are covered separately under Authentication.

{ "error": "invalid_grant", "error_description": "Bad credentials" }

The uuid identifies one specific occurrence. Include it in support requests. It is the fastest route to an answer.

The field detail still appears in some responses but is deprecated. Do not build on it.

OpenAPI specification

Download the specification The full KLARA API is published as an OpenAPI 3.0.3 document. Generate clients, import it into Postman or Insomnia, spin up a mock server, or run contract tests against it.

klara-openapi.json

Machine-readable versions of this pageBesides the specification there is llms.txt, an index in Markdown that lists every chapter of this documentation and every area of the reference as a separate Markdown file. Built in the same run as this page, from the same source. Useful for coding assistants, retrieval and anything that would otherwise parse the HTML.

Authentication

The KLARA API accepts two mechanisms. Most endpoints accept either.

MechanismHowBest for
apiKeyAuthHeader X-API-KEY Server-to-server integrations bound to one company
bearerAuthHeader Authorization: Bearer <JWT> User-context flows, multi-tenant tools

Token flow

A KLARA user can belong to several tenants. Resolve the tenant first, then request a token.

POST /core/latest/tenants     # returns tenant id + company id
POST /core/latest/token       # grant_type: password | refresh_token | token_exchange
The token endpoints expect a form body, not JSON All four take Content-Type: application/x-www-form-urlencoded. Sending JSON is the most common reason a first token request fails. Full media type list under Requests and responses.

Which fields each grant needs

The specification does not mark any of these form fields as required, so the table below is taken from the endpoint descriptions rather than from the schema. Treat it as the working contract and expect 400 if a field is missing.

Endpointgrant_typeRequired fields Returns
POST /core/latest/tokenpassword username, password, tenant_id, company_id Access token scoped to one company, plus refresh token
refresh_tokenrefresh_token A new access token without re-sending credentials
token_exchange subject_token, audience OAuth 2.0 Token Exchange, RFC 8693. Pass subject_token as the raw upstream token value, without the Bearer  prefix. The only audience value the specification documents is cossa
POST /core/latest/generic-token passwordusername, password Access token for the user, not bound to a company
refresh_tokenrefresh_token A new access token
POST /core/latest/token/by-microsoftnot applicable microsoft_access_token, tenant_id System token
POST /core/latest/tenantsnot applicable username and password, or access_token The user's tenants with their tenant and company ids

Which one do I use? /core/latest/token returns a token bound to one tenant and company, which is what you want for a normal integration. /core/latest/generic-token takes no tenant or company and returns a token for the user alone. If you are unsure, use /core/latest/token.

Complete example, password grant

curl -X POST "https://api.klara.ch/core/latest/tenants" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "username=$KLARA_USER" \
  --data-urlencode "password=$KLARA_PASSWORD"
# → pick the tenant id and company id you want to work with

curl -X POST "https://api.klara.ch/core/latest/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=password" \
  --data-urlencode "username=$KLARA_USER" \
  --data-urlencode "password=$KLARA_PASSWORD" \
  --data-urlencode "tenant_id=$TENANT_ID" \
  --data-urlencode "company_id=$COMPANY_ID"

# use the access_token from the response on any other endpoint
curl -X GET "https://api.klara.ch/core/v1/customers?limit=10" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Accept: application/json"

Refreshing

curl -X POST "https://api.klara.ch/core/latest/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "refresh_token=$REFRESH_TOKEN"

Endpoints that need no authentication

4 endpoints require no authentication, because they are how you obtain a token in the first place. Everything else in this reference accepts either an API key or a bearer token, and no endpoint accepts only one of the two.

Keeping your API key safe

An API key authenticates as a role inside your company. Treat it like a password.

What the platform does and does not do for you

QuestionAnswer
Do keys expire?No. A key stays valid until someone deletes it
Can you revoke one yourself? Yes, with immediate effect. In KLARA under Benutzer, panel Public API Key Management. A company administrator does this without support
Can you see whether a key is in use? Yes. The same panel shows a last used timestamp per key. One timestamp, not a call-by-call log
How many keys may a company create?No limit
Can you change the role of an existing key? No. The role is fixed when the key is created and there is no edit path. To change it, create a new key and delete the old one
Keys do not expire, so rotation is entirely on you A key that reaches a repository or a log stays valid indefinitely and nothing signals the exposure. Put a rotation interval in your own calendar, and check the last used column when you suspect a key is no longer needed.

Roles & permissions

An API key is linked to one or more KLARA roles. Any user holding that role can use the key to authenticate for that company. You create and manage keys under Benutzer in KLARA.

Least privilege matters more than usual here A key bound to a role reaches every Public API endpoint that role unlocks, regardless of the restrictions configured for that user inside KLARA. Create one key per use case, with the narrowest role that works, and rotate keys when team members change.

What each role reaches

A KLARA business account offers nine assignable roles, plus Object manager and myKLARA user behind a feature switch and Personal dossier with a Spay subscription. Eight of them matter for the API. The figures below count how many of the documented endpoints each one can call.

External user is not a smaller Administrator For the Public API the two hold identical permissions. The difference exists only in user management, payments and billing, none of which the API exposes. Choosing External user over Administrator therefore buys you nothing in terms of least privilege. If you want a narrow key, pick one of the specialist roles below.
Role in KLARATechnical nameEndpoints reachable, of 114
Administratorcompany_administrator95
External userexternal_user95
Kundenbeziehungencustomer_relationship_manager77
Buchhalteraccountant44
Mitarbeiter und Lohnpayroll_specialist35
Online Terminbuchungbooking24
Zeit- und Materialrapportereporter21
Objektmanagerobject_manager13

Administrator and External user reach everything, which is exactly why neither belongs on an integration key unless the integration genuinely needs everything.

Which role carries which permission

Eighteen permissions are in use across the documented endpoints. The Endpoints column counts how many of them check that permission. A tick means the role grants it.

PermissionEndpointsAdministratorExternal userMitarbeiter und LohnBuchhalterKundenbeziehungenZeit- und MaterialrapporteOnline TerminbuchungObjektmanager
ARTICLE21✓✓––✓–––
FINANCE20✓✓––✓–––
ACCOUNTING13✓✓–✓––––
ARTICLE_READ_ONLY7✓✓✓–✓✓✓–
COMPENSATION4✓✓✓✓✓–✓–
ACCOUNTING_GET_MASTER_VAT3✓✓✓✓✓–––
FINANCE_GET_CUSTOMER3✓✓–✓✓–––
ACCOUNTING_GET_BUSINESS_CASE_TEMPLATE2✓✓✓✓––––
FINANCE_COMPANY_GET_VAT2✓✓✓✓✓–––
ACCOUNTING_GET_OPEN_POSITION1✓✓–✓✓–––
ACCOUNTING_INTERFACE1✓✓✓–––––
COMPENSATION_COMPANY_INFO1✓✓✓✓✓✓✓✓
COMPENSATION_TIME_TRACKING1✓✓✓––✓––
FINANCE_BANK_ACCOUNT1✓✓✓✓✓–––
FINANCE_COMPANY_VAT1✓✓✓✓––––
FINANCE_CREATE_CUSTOMER1✓✓––✓–––
FINANCE_GET_INVOICE1✓✓–✓✓–––
STORE_CUSTOMER1✓✓✓✓✓–✓–

Two things stand out. ARTICLE sits with Kundenbeziehungen alone, so only that role can write articles. And COMPENSATION_COMPANY_INFO is the single permission every role holds.

Three rules that decide whether a call succeeds

Roles add up. A user can hold several roles at once and gets the sum of their access. No role ever takes something away.

A permission replaces, it does not extend. Where an endpoint requires ARTICLE_READ_ONLY, a token holding only ARTICLE is not accepted, and the reverse is equally true. Almost every endpoint checks exactly one permission. One does not: POST /core/v2/tenants/companies lists two, and whether both are required is not confirmed. Its reference entry says so.

Every endpoint names the roles that carry its permission. Under Required permission you find not only the constant but also the roles that grant it, so you do not have to work backwards from a list of constants.

The role alone is not enough. The company also needs the matching subscription. Without it the function stays closed even for an Administrator. If a call fails although the role looks right, check the subscription first.

How long a role and an endpoint stay

New endpoints are versioned explicitly and start on /core/v1. There will be no further additions under /core/latest, because a moving target cannot be integrated against safely. Once an endpoint is marked deprecated it stays available for twelve months. That commitment covers new endpoints; the older /core/latest and /core/v2 operations predate it and no policy has been applied to them yet.

Which permission does an endpoint need?

Every endpoint in the reference states it under Required permission. The values come from a source code analysis of the API, not from the specification text, which names them only sporadically.

Two consequences worth knowing before you design

Endpoints that need no particular permission

A valid token is enough for these. They return data that is not tied to one company, such as the chart of accounts, booking types, VAT types and cities.

Endpoint
GET /core/latest/cities/{city-id}
GET /core/latest/vat-cases
GET /core/latest/vat-cases/{vat-case-id}
GET /core/v1/accounting/accounts
GET /core/v1/accounting/accounts/by-code/{accountCode}
GET /core/v1/accounting/booking-types
GET /core/v1/accounting/vat-types
GET /core/v1/accounting/vat-types/{vatTypeId}

The three token endpoints and POST /core/latest/tenants also need no permission, for the obvious reason that they are how a token is obtained. See Authentication.

Common integration flows

Eight things people build most often, each as the sequence of calls it actually takes. Every statement below comes from the specification. Where the specification is silent, this page says so rather than guessing.

All of these need a token or API key, and the permission named per flow. See Authentication and Roles & permissions.

Creating invoices automatically

Turn an order in your system into a KLARA invoice. Five calls, of which three are lookups you can cache.

1. GET  /core/v1/invoices/next-invoice-number   → invoiceNumber
2. GET  /core/v1/customers?search-key=…         → the customer id
3. GET  /core/latest/articles/search?keyword=…  → the article rows for your line items
4. GET  /core/v1/company-bank-accounts          → the bank account to print on the invoice
5. POST /core/v1/invoices                       → the created invoice with its id

Permissions needed for the whole flow: ARTICLE_READ_ONLY, FINANCE, FINANCE_BANK_ACCOUNT, FINANCE_GET_CUSTOMER. Roles that cover all of it: Administrator, External user, Kundenbeziehungen.

What to watch out for

Webshop order to customer and invoice

A new buyer in your shop becomes a KLARA customer and an invoice. This is the invoice flow above with a customer step in front and a delivery step behind.

1. GET  /core/v1/customers?search-key=…   → does this buyer already exist?
2. POST /core/latest/customers            → only if step 1 found nothing
3. …the five calls from Creating invoices…
4. POST /core/v1/invoices/{id}/send       → deliver it

Permissions needed for the whole flow: ARTICLE_READ_ONLY, FINANCE, FINANCE_BANK_ACCOUNT, FINANCE_CREATE_CUSTOMER, FINANCE_GET_CUSTOMER. Roles that cover all of it: Administrator, External user, Kundenbeziehungen.

What to watch out for

Handing over bookings

Post a manual journal entry from your system into KLARA Accounting.

1. GET  /core/v1/accounting/accounts                  → valid account codes
2. GET  /core/v1/accounting/master-vats               → VAT codes and rates
3. GET  /core/v1/accounting/business-case-templates   → the booking categories
4. POST /core/v1/bookings                             → the persisted booking

Permissions needed for the whole flow: ACCOUNTING, ACCOUNTING_GET_BUSINESS_CASE_TEMPLATE, ACCOUNTING_GET_MASTER_VAT. Roles that cover all of it: Administrator, External user, Buchhalter.

What to watch out for

Attaching receipts to bookings

Upload a receipt and attach it to an existing booking. Two calls.

1. POST /core/latest/companies/{company-id}/documents   → the document id
2. PUT  /core/v1/bookings/{id}/documents                → attach it to the booking

Permissions needed for the whole flow: ACCOUNTING. Roles that cover all of it: Administrator, External user, Buchhalter. Not yet established: POST /core/latest/companies/{company-id}/documents. Plan for an Administrator key until this is confirmed.

What to watch out for

Synchronising master data

Keep customers and articles in step between KLARA and your system.

Customers   GET  /core/v1/customers?limit=100&offset=0     → page through them
            POST /core/latest/customers                    → create
Articles    GET  /core/latest/articles?limit=…&offset=…    → page through them
            POST /core/latest/articles                     → create

Permissions needed for the whole flow: ARTICLE, ARTICLE_READ_ONLY, FINANCE_CREATE_CUSTOMER, FINANCE_GET_CUSTOMER. Roles that cover all of it: Administrator, External user, Kundenbeziehungen.

What to watch out for

Showing invoice status in your CRM

Read the state of your invoices, as a filtered list or one at a time.

GET /core/v1/invoices?status=INVOICED&booking-status=OPEN   → invoiced and not yet paid, one page at a time
GET /core/v1/invoices/{id}                                → the full invoice including booking status

Permissions needed for the whole flow: FINANCE, FINANCE_GET_INVOICE. Roles that cover all of it: Administrator, External user, Kundenbeziehungen.

What to watch out for

Reusing finance and VAT data

Pull the VAT catalogue into your own reporting or tax logic.

GET /core/v1/accounting/master-vats                    → the full catalogue
GET /core/v1/accounting/master-vats?code=…             → specific VAT codes
GET /core/v1/accounting/master-vats?default-vat=true   → the company defaults

Permissions needed for the whole flow: ACCOUNTING_GET_MASTER_VAT. Roles that cover all of it: Administrator, External user, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen.

What to watch out for

Fetching the chart of accounts

Get the account structure for your own reports or account mapping.

GET /core/v1/accounting/accounts                        → the master chart of accounts
GET /core/v1/accounting/accounts?legal-form=…           → only accounts for that legal form

Permissions: none of the steps checks a particular permission.

What to watch out for

Sending documents with smart delivery

You do not have to decide how an invoice reaches your customer. Book it, then call POST /core/v1/invoices/{id}/send without a channel. KLARA routes it through EPOST, EBILL, SEND_EMAIL and Print&Send, and only fails if none of them can deliver.

Sending currently works only with a bearer token, not with an API key. See the FAQ on 401.

Smart delivery

Omit the channel query parameter. There is no request body.

curl -X POST "https://api.klara.ch/core/v1/invoices/42/send" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Accept: application/json"

Forcing one channel

Pass channel as a query parameter to force exactly that channel. If the recipient is not eligible for it, for example no email on file, not registered for eBill, or Print&Send not subscribed, the call fails with 400.

curl -X POST "https://api.klara.ch/core/v1/invoices/42/send?channel=SEND_EMAIL" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Accept: application/json"
ValueChannelCan be forced
SEND_EMAILEmail to the recipientyes
EPOSTePost digital letterboxyes
EBILLeBill, straight into the recipient's e-bankingyes
A_POSTPrinted and posted, A Postyes
B_POSTPrinted and posted, B Postyes
PRINT_AND_MANUAL_SENDPrinted for manual dispatch no, rejected with 400

PRINT_AND_MANUAL_SEND is a value you may see on Invoice.postMethod, but it is not a deliverable channel and cannot be forced.

Two things that will bite you
  • The invoice must already be booked. Drafts and cancelled invoices are rejected with 400. Create and book it first through POST /core/v1/invoices with status=INVOICED.
  • This call is not idempotent. Every successful call performs a real delivery, sending an email or handing a letter to the postal channel, and overwrites the invoice's recorded post method. Do not retry blindly after a success. Remember there is no test environment, so this happens on live data.

Requires the FINANCE permission on the target company. The invoice PDF is rendered on demand if it has not been printed yet.

Why ePost and eBill appear here KLARA and ePost are both products of ePost Service AG. ePost and eBill are two of the delivery channels KLARA can use. You reach them through the KLARA API, with no separate integration. Building on the ePost Communication Platform itself? See developer.epost.ch.

Submitting variable payroll data

Available now Payroll used to be read-only through file exports. Three endpoints let you add variable salary items (hours, allowances, bonuses) directly to an employee's payslip.

The flow is three calls. You need the employee first, then the payslip that is still editable, then you post the item.

1. GET  /core/v1/employees/short-info
      → find the employee, take their employeeId

2. GET  /core/v1/payroll/employees/{employeeId}/addable-salary-items
      → returns which item types may be added, plus contractId and payslipId

3. POST /core/v1/payroll/contracts/{contractId}/payslips/{payslipId}/salary-items
      → adds the item and recalculates the month

What you can submit

Salary items come in the types Base, Percent, Quantity, Amount and Comments. Step 2 tells you which types the payslip accepts. Do not guess, the answer depends on the employee's contract.

Finding the right employee

GET /core/v1/employees/short-info returns a lightweight directory: id, name, email, employee number, workplace and status. It supports search-key, filter-by-status, workplace-ids, sort-field and sort-direction. This is the most capable filtering in the whole API today.

Two constraints worth knowing before you build
  • Only editable payslips. Once a payslip is sealed, it no longer accepts items. Your integration needs to run before the salary run is closed, so plan the timing.
  • Recalculation is triggered per call. Pass recalculate=false when adding several items in sequence, then recalculate once at the end. Otherwise you recompute the month for every single item.

Retries and corrections

Adding a salary item is not idempotent A repeated call appends a second item, or fails if the item type is not duplicatable. There is no idempotency key. If a call times out, read the payslip back before you send it again rather than retrying blind. With no test environment, a duplicate is real payroll data.

There is no PUT and no DELETE on salary items today, so a wrong entry is corrected in the KLARA interface, not through the API. Both verbs are confirmed as required for the final version of the endpoint, but they do not exist yet.

Getting responses in German, French, Italian or English

Switzerland has four language regions, and so does your customer base. A number of endpoints return content that is translated, for example account names, VAT descriptions, booking-type labels and salary-item descriptions. You choose the language with the standard Accept-Language request header.

curl -X GET "https://api.klara.ch/core/v1/accounting/accounts" \
  -H "X-API-KEY: $KLARA_API_KEY" \
  -H "Accept-Language: fr-CH" \
  -H "Accept: application/json"

The header takes an IETF language tag. The tags documented in the specification are de-CH, fr-CH, it-CH and en. Where a translation is missing, the response falls back to German. Some endpoints fall back to the language configured on the tenant instead when you omit the header, so pass it explicitly if you care about the result.

Where it applies

31 endpoints accept Accept-Language. Look for it in the parameter list of any endpoint in the API reference. It is most common across accounting: accounts, booking types, VAT types, VAT cases, business-case templates and financial years. It also affects POST /core/v1/bookings, where it selects the language of localised error messages, and the payroll endpoint that lists addable salary items.

Building your own language picker

Two schemas return not just the resolved text but the complete set of translations, keyed by language tag. Use these when your own interface offers a language switch and you would rather not call the API once per language.

SchemaFields
PublicApiBusinessCaseTemplate i18n, keywordI18ns
PublicApiVatType i18n, i18nShortName
This documentation is in English The API specification is maintained in English, so the endpoint reference is English too.

Limits, pagination and environments

Environments

There is one environment: https://api.klara.ch. It serves your live company data.

There is no test environment, and that is a decision Every request you send acts on real data in your company. The product owner confirmed in August 2026 that no sandbox is planned for the Public API, so this is the intended model rather than a gap that will close. Plan for that:
  • Explore with GET first. Reading is safe. Get familiar with the data shapes before you write anything.
  • Writes take effect immediately. A created invoice is a real invoice, and a salary item added to a payslip is real payroll data.
  • Use a separate key for development, named so you can recognise and revoke it, for example integration-dev. Delete it when you go live.
  • If you can, develop against a company you control rather than a client's production company.

Rate limiting

The API enforces a rate limit at the gateway. When you exceed it, the response is 429 API rate limit exceeded. Nearly every endpoint can return it.

WhatValue
LimitAt least 10,000 requests per minute
Counted againstThe calling IP address, not the API key and not the company
ScopeThe same limit everywhere. File exports are not treated differently
Two consequences of counting per IP address

Several customers behind one outbound address share a single budget. If you run a hosting platform or your own software as a service, one busy tenant can throttle the others.

The reverse is also true: spreading calls across several source addresses multiplies your throughput. That works, but it is not a supported pattern and may change.

The figure is stated as a floor rather than an exact number on purpose. Each gateway instance counts on its own, so the effective ceiling rises with the number of instances and the counter resets when one restarts. Today one instance runs, which makes 10,000 per minute correct, but build against the floor.

Headers on 429

The gateway deliberately suppresses the informational headers. You will not see RateLimit-Limit, RateLimit-Remaining or RateLimit-Reset, and their X- variants are absent as well. This is a configuration decision, not an omission in the specification.

Whether Retry-After is sent is being confirmed. Do not depend on it yet.

How to build for it

Pagination

16 endpoints accept pagination parameters:

EndpointParameters
GET /core/latest/article-categorieslimit, offset
GET /core/latest/article-filterslimit, offset
GET /core/latest/articleslimit, offset
GET /core/latest/articles/article-and-variantslimit, offset
GET /core/latest/articles/searchlimit, offset
GET /core/v1/accounting/accounts/{accountCode}/statementlimit, offset
GET /core/v1/accounting/business-case-templateslimit, offset
GET /core/v1/accounting/fiscal-yearslimit, offset
GET /core/v1/accounting/master-vatslimit, offset
GET /core/v1/accounting/reports/general-ledgerlimit, offset
GET /core/v1/accounting/tagslimit, offset
GET /core/v1/bank-transactionslimit, offset
GET /core/v1/bookingslimit, offset
GET /core/v1/customerslimit, offset
GET /core/v1/customers/{customerId}/open-positionslimit, offset
GET /core/v1/invoiceslimit, offset

Three properties of pagination that decide whether a run is reliable.

QuestionAnswer
Is there a total count? No. A page smaller than the limit is the only signal that you have reached the end
Is the order stable between requests? No guarantee, with one exception: GET /core/v1/accounting/business-case-templates takes an optional orderColumns list
Can every page be reached? Yes. GET /core/latest/article-categories and GET /core/latest/article-filters accepted limit without offset until 18 September 2026 and were stuck on the first page. Both take offset now and return X-Total-Count
No stable order means pagination can miss or repeat records Without a guaranteed order, a record can move between two requests and end up counted twice or not at all. For a full read, prefer a single large page over many small ones where the limit allows it, and treat the result as a snapshot rather than a transaction.

Searching and filtering

Free-text search

14 endpoints take a search term and match it against several fields at once. This is the only way to find a record without knowing an id.

EndpointParameter
GET /core/latest/article-categorieskeyword, search-key
GET /core/latest/article-filterskeyword, search-key
GET /core/latest/articles/searchkeyword, search-key
GET /core/v1/accounting/accounts/{accountCode}/statementsearch-key
GET /core/v1/accounting/fiscal-yearssearch-key
GET /core/v1/accounting/reports/general-ledgersearch-key
GET /core/v1/accounting/tagssearch-key
GET /core/v1/bank-reconciliation/open-positionsgeneral-search, search-key
GET /core/v1/bank-transactionssearch-key
GET /core/v1/bookingssearch-key
GET /core/v1/customerssearch-key
GET /core/v1/customers/{customerId}/open-positionssearch-key
GET /core/v1/employees/short-infosearch-key
GET /core/v1/invoicessearch-key

Filtering by field

46 endpoints narrow the result by a field value, 129 parameters in total. Filtering is not searching: you have to know the value you are filtering on.

EndpointParameters
GET /core/latest/article-categoriesactive-status
GET /core/latest/article-filtersactive-status
GET /core/latest/articlesproduct-type
GET /core/latest/articles/article-and-variantsinclude-quantity, sell-in-booking, sell-in-online-shop, use-pos
GET /core/latest/articles/article-numbersarticle-numbers, export-vat, price-date, should-validate-vat
GET /core/latest/articles/searchexport-vat, price-date, should-validate-vat
POST /core/latest/payroll-interface-filefile-format, payslip-ids, salary-run-id
POST /core/latest/subscriptionsmarketing-code
GET /core/latest/vat-casesapplicability
GET /core/v1/accounting/accountslegal-form
GET /core/v1/accounting/accounts/account-displayinglegal-form
GET /core/v1/accounting/accounts/by-code/{accountCode}legal-form
GET /core/v1/accounting/accounts/{accountCode}/statementbooking-types, date-from, date-to, include-delimitation, reference, tags, vat
GET /core/v1/accounting/business-case-templates/{businessCaseTemplateId}/payment-sourcesbooking-date, payment-group
GET /core/v1/accounting/business-casesbusinessCaseTemplateId, dateForFilteringCompanyVat, dateForFilteringFiscalYear
GET /core/v1/accounting/business-cases/v2businessCaseTemplateId, dateForFilteringCompanyVat, dateForFilteringFiscalYear, group-insurance-by-insurer, snippet-id, snippet-value
GET /core/v1/accounting/currencies/exchange-rateexchange-date, from-currency-code
POST /core/v1/accounting/document-bookings/paidconfirm-closing-fiscal-year
GET /core/v1/accounting/fiscal-yearsstatus
GET /core/v1/accounting/kpis/income-expensesdate-from, date-to, include-delimitation
GET /core/v1/accounting/kpis/spendings-and-earningscompare-from, compare-to, date-from, date-to, include-delimitation
GET /core/v1/accounting/master-vatscode, current-period, default-vat, includeHiddenVatCase
GET /core/v1/accounting/reports/balance-sheetaccount-search, compare-date, date, include-delimitation, sub-account-search
GET /core/v1/accounting/reports/general-ledgeraccount-from, account-to, booking-types, date-from, date-to, include-delimitation, reference, tags, vat
GET /core/v1/accounting/reports/partner-amountscustomer-id, to-date
GET /core/v1/accounting/reports/profit-and-lossaccount-search, compare-from, compare-to, date-from, date-to, include-delimitation, tag-search
GET /core/v1/accounting/tagsinclude-combinations
GET /core/v1/accounting/vat-profiledate
GET /core/v1/accounting/vat-suggestionsaccountCode, amount, amountKind, date, direction, vatCase
GET /core/v1/bank-reconciliation/open-positionsaction, booking-type-codes, crdr-type, credit-card-not-reconciled, invoice-date, partner, payment-date, payment-date-from, payment-date-to, position-status, tags
GET /core/v1/bank-transactionsbank-account-id, booking-date-from, booking-date-to, direction
GET /core/v1/bookingsamount-from, amount-to, booking-date-from, booking-date-to, tags
POST /core/v1/bookingsautoCalculateVat, confirmDontMindClosingFiscalYear, ignore-unsubscripted-dates
PUT /core/v1/bookings/{id}/documentsignore-unsubscripted-dates
GET /core/v1/company-bank-accountsiban-number, type
GET /core/v1/customersstatus
GET /core/v1/customers/{customerId}/open-positionsposition-type, reference-date
GET /core/v1/employees/short-infofilter-by-status, status, workplace-ids
GET /core/v1/invoicesbooking-status, status
PUT /core/v1/invoicesconfirmDontMindClosingFiscalYear
POST /core/v1/invoicesconfirmDontMindClosingFiscalYear
POST /core/v1/invoices/{id}/sendchannel
GET /core/v1/order-documents/filter/type-and-order-numberorder-number, type
GET /core/v1/order-numbering-configurationsorder-type
GET /core/v1/payroll/employees/{employeeId}/addable-salary-itemsmonth
POST /core/v1/vat-clearing-reports/{year}/{quarter}recalculate

Sorting

10 endpoints accept a sort order: /core/v1/accounting/accounts/{accountCode}/statement, /core/v1/accounting/business-case-templates, /core/v1/accounting/fiscal-years, /core/v1/accounting/reports/general-ledger, /core/v1/accounting/tags, /core/v1/bank-transactions, /core/v1/bookings, /core/v1/customers/{customerId}/open-positions, /core/v1/employees/short-info, /core/v1/invoices. Everywhere else the order is not guaranteed, which matters when you page through a large collection.

API reference

114 endpoints. Click any endpoint for its description, parameters, request body and responses. Everything below is generated from klara-openapi.json; ePost endpoints and the eBill, SPS, email and print partner channels are removed by the build.

Want to try a request? Download the OpenAPI specification and import it into Postman, Insomnia or Bruno. You get every endpoint, parameter and example as a ready-made collection. Never paste a production API key into a tool you do not control.

Finance & Accounting

Accounting40

GET/core/v1/accounting/accountskey / tokenList KLARA master chart-of-account rows.
Returns the canonical debit/credit accounts maintained by KLARA as the seed of any company's bookkeeping. The data is global — the same chart of accounts is returned for every tenant, so there are no tenant or company path parameters. When the optional legal-form query parameter is supplied, only accounts that carry a translation for that legal form are returned, and the name field is resolved from the legal-form-specific translation column. The Accept-Language header selects which translation is used; if absent or unsupported the platform default applies. The endpoint is a pure read — idempotent, no side effects. Any authenticated bearer token is accepted; the downstream service declares no role or permission requirement on this endpoint.
operationId

listAccountsV1 — the method name a generated client uses.

Required permission

none A valid token is enough. No particular permission is checked for this endpoint.

Parameters 2
NameDescription
legal-form
query string
Restricts the result to accounts that carry a translation for the given Swiss legal form, and resolves name from that legal-form-specific column. Allowed values: LIMITED_LIABILITY, CORPORATION, OR, INDIVIDUALLY_OWNED_COMPANY, ASSOCIATION, SIMPLE_PARTNERSHIP, GENERAL_PARTNERSHIP, LIMITED_PARTNERSHIP, COOPERATIVE_COMPANY, FOUNDATION.
Allowed values: LIMITED_LIABILITY, CORPORATION, OR, INDIVIDUALLY_OWNED_COMPANY, ASSOCIATION, SIMPLE_PARTNERSHIP, GENERAL_PARTNERSHIP, LIMITED_PARTNERSHIP, COOPERATIVE_COMPANY, FOUNDATION
example: CORPORATION
Accept-Language
header string
IETF language tag used to resolve the localized name field of each account. Examples: de-CH, fr-CH, it-CH, en.
example: de-CH
Responses 5
200 Master accounts, sorted by code ascending. Empty array when the chart of accounts has not been seeded yet. show body

application/json array of PublicApiAccount

Array of PublicApiAccount.

  • id integer (int64) format: int64 example: 42
    Internal identifier of the master account.
  • code integer (int32) format: int32 example: 1020
    Numeric account code as printed on the chart of accounts.
  • name string example: Bank
    Localized account name. Resolved against the request's Accept-Language and, when legal-form is supplied, against the legal-form-specific translation.
  • tags string example: bank;konto
    Free-text keyword tokens associated with the account, used by client-side search. Tokens are delimited by comma or semicolon.
  • links string example: bank_account
    Linked-account references used by report computations.
  • accountReportLinks string example: bank_account
    Report-grouping references used to assemble balance-sheet / P&L groupings.
  • initialBalanceSheet boolean example: False
    True when the account is part of the initial opening-balance sheet.
  • visibleFirstFiscalYear boolean example: True
    True when the account is visible during the first fiscal year of a new company.
  • visibleFromSecondFiscalYear boolean example: True
    True when the account becomes visible from the second fiscal year onwards.
  • vatAccount boolean example: False
    True when the account is reserved for VAT postings.
  • accountReportFilters array of PublicApiAccountReportFilter
    Report-grouping configuration rows attached to this account.
    show fields

    Array of PublicApiAccountReportFilter.

    • display string example: Operating expenses
      Human-readable label of the report bucket this account contributes to.
    • linkAccountValue string example: 6000
      Underlying linked-account value used by the accounting engine to resolve the bucket.
  • notManuallyAdded boolean example: True
    True when the account was seeded automatically (not added by an end user).
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 The supplied legal-form value does not match any known legal form.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/accounts/account-displayingkey / tokenList the account-displaying picker rows for the authenticated company.
Returns a flat list of AccountDisplaying rows for every account in the caller's company chart of accounts. Each row represents one selectable combination that a bookkeeper can pick when entering a manual journal line. Tenant and company are derived from the bearer token — there are no tenant or company path parameters.

How rows are produced: For each master account the downstream service checks whether the account carries any linked sub-account definitions (e.g. a bank account linked to specific bank-accounts, a VAT account linked to VAT-rate items). If the account has no sub-account definitions, exactly one bare row is emitted with combinedCode equal to the bare account code (e.g. "3000"), linkType equal to null, and specificationItem equal to null. If the account has one or more sub-account link specifications, one row is emitted per individual sub-account entry, numbered sequentially across all link types with a 0-based counter suffix: "1020-0", "1020-1", …

combinedCode: "<accountCode>-<i>" when a sub-account exists (e.g. "1020-0"), or the bare account code string (e.g. "3000") when linkType is null. The suffix index is a flat 0-based counter per account, spanning all link types in declaration order.

combinedName: "<accountName> (<subAccountDisplay>)" when a sub-account exists (e.g. "Bank (UBS)"), or the bare account name (e.g. "Bürobedarf") when linkType is null.

parentAccount: the full master account this row belongs to. Always populated, including for bare rows.

linkType: the link-type category name (e.g. "BANK", "CUSTOMER", "VAT_RATE"). null when the account has no sub-account definitions.

linkDisplay: the human-readable label for the link type in the current locale (e.g. "Bank account"). Falls back to the German label when no translation exists for the requested language. null when linkType is null.

linkOptional: true when the sub-account selection is optional for the user (link keys are separated by ; in the account definition); false when selecting a sub-account is mandatory (link keys separated by ,); null when the account has no sub-account definitions.

specificationItem: the resolved sub-account entry for this row. Its link field is the URI that must be round-tripped back to the booking endpoint when the user selects this row. Its display field is the human-readable label shown to the bookkeeper (e.g. "UBS", "8.1 %"). null when linkType is null.

Row order is stable: accounts are sorted by code ascending (same order as GET /core/v1/accounting/accounts); sub-account rows within each account preserve the link-type declaration order and then the entry order returned by the underlying service.

The endpoint is a pure read — idempotent, no side effects. The caller must hold the ACCOUNTING permission on the company in scope.
operationId

getAccountDisplayingV1 — the method name a generated client uses.

Required permission

ACCOUNTING
Available through: Administrator, External user, Buchhalter

Parameters 2
NameDescription
legal-form
query string
When supplied, restricts the result to accounts that carry a translation for the given Swiss legal form and resolves the parentAccount.name field from the legal-form-specific translation column. When omitted, all accounts are returned and account.name is resolved from the generic language column. Allowed values: LIMITED_LIABILITY, CORPORATION, OR, INDIVIDUALLY_OWNED_COMPANY, ASSOCIATION, SIMPLE_PARTNERSHIP, GENERAL_PARTNERSHIP, LIMITED_PARTNERSHIP, COOPERATIVE_COMPANY, FOUNDATION.
Allowed values: LIMITED_LIABILITY, CORPORATION, OR, INDIVIDUALLY_OWNED_COMPANY, ASSOCIATION, SIMPLE_PARTNERSHIP, GENERAL_PARTNERSHIP, LIMITED_PARTNERSHIP, COOPERATIVE_COMPANY, FOUNDATION
example: CORPORATION
Accept-Language
header string
IETF language tag used to localize the parentAccount.name field of each row and the linkDisplay label. Falls back to German when no translation exists for the requested language. Examples: de-CH, fr-CH, it-CH, en.
example: de-CH
Responses 6
200 Flat list of account-displaying rows, sorted by account code ascending. Each row contains combinedCode, combinedName, parentAccount, and the link fields populated for sub-account rows or null for bare rows. Returns an empty array when no accounts match the supplied legal-form. show body

application/json array of PublicApiAccountDisplaying

Array of PublicApiAccountDisplaying.

  • combinedCode string example: 1020-0
    Picker key. "<accountCode>-<i>" when a sub-account exists (e.g. "1020-0"); the bare account code string (e.g. "3000") when linkType is null. The suffix index is a flat 0-based counter per account, spanning all link types in declaration order.
  • combinedName string example: Bank (UBS)
    Picker label. "<accountName> (<subAccountDisplay>)" when a sub-account exists (e.g. "Bank (UBS)"); the bare account name (e.g. "Bürobedarf") when linkType is null.
  • parentAccount object
    A master account from KLARA's global chart of accounts.
    show fields
    • id integer (int64) format: int64 example: 42
      Internal identifier of the master account.
    • code integer (int32) format: int32 example: 1020
      Numeric account code as printed on the chart of accounts.
    • name string example: Bank
      Localized account name. Resolved against the request's Accept-Language and, when legal-form is supplied, against the legal-form-specific translation.
    • tags string example: bank;konto
      Free-text keyword tokens associated with the account, used by client-side search. Tokens are delimited by comma or semicolon.
    • links string example: bank_account
      Linked-account references used by report computations.
    • accountReportLinks string example: bank_account
      Report-grouping references used to assemble balance-sheet / P&L groupings.
    • initialBalanceSheet boolean example: False
      True when the account is part of the initial opening-balance sheet.
    • visibleFirstFiscalYear boolean example: True
      True when the account is visible during the first fiscal year of a new company.
    • visibleFromSecondFiscalYear boolean example: True
      True when the account becomes visible from the second fiscal year onwards.
    • vatAccount boolean example: False
      True when the account is reserved for VAT postings.
    • accountReportFilters array of PublicApiAccountReportFilter
      Report-grouping configuration rows attached to this account.
      show fields

      Array of PublicApiAccountReportFilter.

      • display string example: Operating expenses
        Human-readable label of the report bucket this account contributes to.
      • linkAccountValue string example: 6000
        Underlying linked-account value used by the accounting engine to resolve the bucket.
    • notManuallyAdded boolean example: True
      True when the account was seeded automatically (not added by an end user).
  • linkType string example: BANK
    Link-type category. Identifies the kind of entity the sub-account refers to. Common values: VAT_RATE, VAT_CASE, BANK, CUSTOMER, SUPPLIER, EMPLOYEE, SOCIAL_INSURANCE, TAX_AT_SOURCE, EQUITY, TANGIBLE_ASSET, IMMOBILE_TANGIBLE_ASSET, UNFINISHED_PRODUCTS, FINISHED_PRODUCTS, NON_BILLED_SERVICES, INVENTORY_CHANGE_MATERIAL, INVENTORY_CHANGE_GOODS, LONG_TERM_INTEREST_BEARING, OTHER_LONG_TERM_INTEREST_BEARING, GIFT_CARD, VARIOUS. null when the account has no sub-account definitions.
  • linkDisplay string example: Bank account
    Human-readable label for the link type in the requested Accept-Language. Falls back to the German label when no translation exists for the requested language. null when linkType is null.
  • linkOptional boolean example: False
    true when the sub-account selection is optional for the user (link keys are separated by ; in the account definition); false when selecting a sub-account is mandatory (link keys separated by ,); null when the account has no sub-account definitions.
  • specificationItem object
    One concrete sub-account choice; carries the URI to round-trip to the booking endpoint and the display label.
    show fields
    • id string example: 42
      Stable identifier of the underlying entity (e.g. bank-account id, VAT-rate id, customer id). May be null for synthesized entries.
    • filteredBy string example:
      Optional filter token used by the Accounting UI to narrow the picker. Empty for most link types.
    • display string example: UBS
      Human-readable label shown in the picker (e.g. "UBS" for a bank account, "8.1 %" for a VAT rate).
    • link string example: bank_account:/luz_finance/api/5fe76717-60a0-4b20-9819-255a957f3eb9/companies/1/bank-accounts/42
      Canonical URI for this sub-account choice. MUST be round-tripped verbatim to the booking-creation endpoint when the row is selected.
    • additionalAttribute string example:
      Free-form additional attribute attached by the link-type supplier. Most types leave this empty.
    • snippetReference string example:
      Optional snippet reference returned by the underlying entity (used by some link types to carry a template hint).
    • value string example: 8.1
      Optional raw value associated with the entry (e.g. the VAT percentage as a decimal string).
    • validFrom string (date) format: date example: 2024-01-01
      Inclusive start of the validity window of the underlying entity (ISO yyyy-MM-dd). null when not applicable.
    • validTo string (date) format: date example: 2024-12-31
      Inclusive end of the validity window of the underlying entity (ISO yyyy-MM-dd). null when open-ended.
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 The company associated with the caller's session could not be resolved by the downstream accounting service, or the supplied legal-form value does not match any known legal form.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/accounts/by-code/{accountCode}key / tokenResolve a KLARA master account by its chart-of-account code.
Loads a single master account row from KLARA's global chart of accounts, identified by its numeric accountCode. The data is global — the same chart of accounts is shared across every tenant, so there are no tenant or company path parameters. When the optional legal-form query parameter is supplied, the name field is resolved from the legal-form-specific translation column instead of the generic one. The Accept-Language header selects which translation is used; if absent or unsupported the platform default applies. The endpoint is a pure read — idempotent, no side effects. Any authenticated bearer token is accepted; the downstream service declares no role or permission requirement on this endpoint.
operationId

getAccountByCodeV1 — the method name a generated client uses.

Required permission

none A valid token is enough. No particular permission is checked for this endpoint.

Parameters 3
NameDescription
accountCode required
path string
Numeric chart-of-account code as printed on the KLARA master chart of accounts (e.g. 1000 for cash, 6000 for material expense).
example: 6000
legal-form
query string
When supplied, resolves name from the legal-form-specific translation column. Allowed values: LIMITED_LIABILITY, CORPORATION, OR, INDIVIDUALLY_OWNED_COMPANY, ASSOCIATION, SIMPLE_PARTNERSHIP, GENERAL_PARTNERSHIP, LIMITED_PARTNERSHIP, COOPERATIVE_COMPANY, FOUNDATION.
Allowed values: LIMITED_LIABILITY, CORPORATION, OR, INDIVIDUALLY_OWNED_COMPANY, ASSOCIATION, SIMPLE_PARTNERSHIP, GENERAL_PARTNERSHIP, LIMITED_PARTNERSHIP, COOPERATIVE_COMPANY, FOUNDATION
example: CORPORATION
Accept-Language
header string
IETF language tag used to resolve the localized name field of the account. Examples: de-CH, fr-CH, it-CH, en.
example: de-CH
Responses 5
200 The master account matching accountCode. show body

application/json PublicApiAccount

  • id integer (int64) format: int64 example: 42
    Internal identifier of the master account.
  • code integer (int32) format: int32 example: 1020
    Numeric account code as printed on the chart of accounts.
  • name string example: Bank
    Localized account name. Resolved against the request's Accept-Language and, when legal-form is supplied, against the legal-form-specific translation.
  • tags string example: bank;konto
    Free-text keyword tokens associated with the account, used by client-side search. Tokens are delimited by comma or semicolon.
  • links string example: bank_account
    Linked-account references used by report computations.
  • accountReportLinks string example: bank_account
    Report-grouping references used to assemble balance-sheet / P&L groupings.
  • initialBalanceSheet boolean example: False
    True when the account is part of the initial opening-balance sheet.
  • visibleFirstFiscalYear boolean example: True
    True when the account is visible during the first fiscal year of a new company.
  • visibleFromSecondFiscalYear boolean example: True
    True when the account becomes visible from the second fiscal year onwards.
  • vatAccount boolean example: False
    True when the account is reserved for VAT postings.
  • accountReportFilters array of PublicApiAccountReportFilter
    Report-grouping configuration rows attached to this account.
    show fields

    Array of PublicApiAccountReportFilter.

    • display string example: Operating expenses
      Human-readable label of the report bucket this account contributes to.
    • linkAccountValue string example: 6000
      Underlying linked-account value used by the accounting engine to resolve the bucket.
  • notManuallyAdded boolean example: True
    True when the account was seeded automatically (not added by an end user).
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 No master account exists for the supplied accountCode, or the supplied legal-form value does not match any known legal form.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/accounts/{accountCode}/statementkey / tokenGet the statement of one account for a period: opening balance, all movements, closing balance.
Returns the statement of one account of the caller's company, as KLARA shows it under Accounting > Reports > Account details: the opening balance before date-from, the booking lines of the period with booking date, booking id and line id (readable with getBookingV1), contra accounts, posting text, tags, VAT text, debit or credit amount in CHF and the running balance after each line, and the closing balance with the debit and credit totals of the period. Lines are ordered by booking date, booking id and line id, ascending, and paged with offset and limit (default 50, maximum 100); X-Total-Count holds the number of matching lines, and opening and closing balance always refer to the whole period, not to the page. The running balance continues across pages. For P&L accounts the opening balance starts at the beginning of the fiscal year that contains date-from, and the running and closing balance restart at 0 in each new fiscal year, so for a period over several fiscal years only the debit and credit totals of closingBalance cover the whole period; balance sheet accounts accumulate from the first booking. Balances are positive on the normal side of the account (debit for assets and expenses, credit for liabilities, equity and revenue). The statement contains every booking status (planned and inactive bookings too), like the screen; lines carry no booking status and there is no status filter. Amounts are in CHF only. Filters, all optional and combined with AND: date-from and date-to (inclusive, yyyy-MM-dd; without date-from the statement starts with the first booking and the opening balance is 0); reference, one object a line must refer to, written as in references of getBookingV1, for example BANK_ACCOUNT:3, SUB_ACCOUNT:cash:400 or CUSTOMER:1042 (this is the sub-account filter of the screen; the opening balance is filtered the same way). Without reference, an account that KLARA splits into sub-accounts (for example per bank account, cash register or employee) is returned as a whole, all its sub-accounts together; the screen always shows one sub-account, so to get what the screen shows pass that sub-account's reference (from reference of the sub-account rows of getBalanceSheetV1 or references of getBookingV1; the id of listSubAccountsV1 is a different number and cannot be used here); tags, comma-separated, any of them, case-sensitive (names from listBookingTagsV1; a line with several tags is kept when one of its tags equals a requested name, so Marketing finds a line tagged Marketing, Zurich); include-delimitation (default true), false leaves out the delimitation lines (booking type DELIMIT), the original lines they belong to stay; booking-types, comma-separated booking types, any of them; vat, comma-separated, any of them: a VAT case id (listVatCases), a VAT case and VAT rate id as case:rate (listMasterVatsV1), or none for lines without VAT. Tag names are matched as KLARA's screen matches them: % and _ act as wildcards. Sorting is fixed, oldest first: sort-field may only be BOOKING_DATE and sort-direction only ASC (the generic default DESC does not apply here; omit the parameter), and search-key is not supported. All parameters are checked first (400); then 404 with code account.unknown when the account number is not in the master chart of accounts (listAccountsV1). An account of the master chart without bookings of the company returns an empty statement. This is a read-only, idempotent operation without side effects. Tenant and company are derived from the bearer token and are never accepted from the URL or the request. The caller must hold the ACCOUNTING permission on the company; otherwise the endpoint returns 403.
operationId

getAccountStatementV1 — the method name a generated client uses.

Required permission

ACCOUNTING This comes from the description in the specification; the source code analysis behind the other permission statements is older than this endpoint. Roles that carry it: Administrator, External user, Buchhalter.

Parameters 14
NameDescription
accountCode required
path integer (int32)
Account number, as code in listAccountsV1.
format: int32 min: 1 example: 1020
booking-types
query string
Comma-separated booking types as bookingType of getBookingV1, any of them, for example AR_INVOICE,AP_INVOICE. Case-insensitive.
maxLength: 256 example: AR_INVOICE,AP_INVOICE
date-from
query string (date)
First booking date of the statement, inclusive, ISO yyyy-MM-dd. Without it the statement starts with the first booking and the opening balance is 0.
format: date example: 2026-01-01
date-to
query string (date)
Last booking date of the statement, inclusive, ISO yyyy-MM-dd; not before date-from. Without it the period is open-ended.
format: date example: 2026-12-31
include-delimitation
query boolean
false leaves out the delimitation lines (booking type DELIMIT); the original lines they belong to stay. Included by default, as on the screen.
default: true example: True
limit
query integer
Page size. Defaults to 50; hard cap 100. Requests above the cap are rejected with 400.
min: 1 max: 100 default: 50 example: 50
offset
query integer
0-based pagination offset — the number of rows to skip before the returned page. Defaults to 0. Combine with limit to walk the full collection.
min: 0 default: 0 example: 0
reference
query string
Only lines that refer to this object, written as in references of getBookingV1: TYPE:id, for a sub-account SUB_ACCOUNT:category:id. The type is case-insensitive, the category is written as published.
maxLength: 128 example: BANK_ACCOUNT:3
search-key
query string
Free-text search. The fields searched are documented per endpoint. Matches are case-insensitive substring matches. Maximum length 256 characters.
maxLength: 256 example: müller
sort-direction
query string
Sort direction. Allowed values: ASC, DESC. Defaults to DESC.
Allowed values: ASC, DESC
default: DESC example: DESC
sort-field
query string
Field to order the result by. The accepted values are listed per endpoint; an unknown value is rejected with 400. Each endpoint documents the default it applies, chosen so that paging with offset / limit is stable.
tags
query string
Comma-separated tag names; a line is kept when one of its tags equals any of them (case-sensitive; tags combined on one line are compared one by one; % and _ act as wildcards, as on the screen).
maxLength: 256 example: Zurich,Marketing
vat
query string
Comma-separated VAT filters, any of them: a VAT case id (listVatCases), a VAT case id and VAT rate id as case:rate (listMasterVatsV1), or none for lines without VAT.
maxLength: 256 example: 7:12,none
Accept-Language
header string
Language of the VAT texts, for example de-CH, fr-CH, it-CH, en.
example: de-CH
Responses 7
200 The statement: opening balance, the lines of this page and the closing balance of the whole period. show body

application/json PublicApiAccountStatement

  • accountCode integer (int32) format: int32 example: 1020
    Account number of the statement, as in listAccountsV1.
  • dateFrom string (date) format: date example: 2026-01-01
    First booking date of the period as requested; missing when the statement starts with the first booking.
  • dateTo string (date) format: date example: 2026-12-31
    Last booking date of the period as requested; missing when the period is open-ended.
  • openingBalance number example: 12500
    Balance in CHF before dateFrom, with the same filters. Balance sheet accounts accumulate from the first booking, P&L accounts from the start of the fiscal year that contains dateFrom. 0 without dateFrom. Positive for the normal side of the account (debit for assets and expenses, credit for liabilities, equity and revenue).
  • closingBalance object
    Totals of the whole period (all pages) and the balance at its end.
    show fields
    • debitAmount number example: 48200
      Sum in CHF of the debit amounts of all matching lines of the period.
    • creditAmount number example: 39150.5
      Sum in CHF of the credit amounts of all matching lines of the period.
    • balance number example: 21549.5
      Balance in CHF at the end of the period. Balance sheet accounts: opening balance plus all lines, equal to the running balance of the last line. P&L accounts restart at 0 in each fiscal year, so this is the balance of the fiscal year that contains the end of the period (dateTo, or the latest fiscal year when the period is open-ended); it equals the running balance of the last line when that line lies in that fiscal year, and is 0 when that fiscal year has no lines yet.
  • lines array of PublicApiAccountStatementLine
    The booking lines of this page, ordered by booking date, booking id and line id, ascending. Empty when no line matches or the page is beyond the last line.
    show fields

    Array of PublicApiAccountStatementLine.

    • bookingDate string (date) format: date example: 2026-03-31
      Booking date.
    • bookingId integer (int64) format: int64 example: 4321
      Id of the booking; read the whole booking with getBookingV1.
    • lineId integer (int64) format: int64 example: 8765
      Id of this line within the booking, as lines[].id of getBookingV1.
    • contraAccountCodes array of integer (int32)
      Accounts of the other lines of the booking, ascending. The amount of this line is not split among them; getBookingV1 shows the amount of each line.
    • description string example: Rent March 2026
      Posting text of the line.
    • tags array of string
      Tags of the line.
    • vatText string example: 8.1%
      VAT of the line as KLARA shows it, in the language of Accept-Language.
    • debitAmount number example: 1000
      Amount in CHF when the line is a debit; missing otherwise.
    • creditAmount number example: 250
      Amount in CHF when the line is a credit; missing otherwise.
    • runningBalance number example: 13500
      Balance in CHF after this line, continued across pages. Positive for the normal side of the account; P&L accounts restart at 0 with the first line of each fiscal year.
    • documentIds array of string
      Ids of the documents attached to the booking.
400 A filter is malformed (date-from, date-to, reference, booking-types, vat), the range is inverted, the sort is not booking date ascending, search-key was sent, or a parameter is outside its bounds (accountCode below 1, reference longer than 128 characters, tags, booking-types or vat longer than 256 characters, offset negative, limit outside 1-100).

Error codes for this response (the code field of the response body):
  • request.sort_field_invalid — sort-field was not one of the values the operation documents. The message lists the accepted values.
  • request.sort_direction_unsupported — sort-direction was sent with the direction an operation with a fixed order does not have. The message names the available direction.
  • request.search_key_unsupported — search-key was sent to an operation that has no text search.
  • statement.date_invalid — date-from or date-to was not an ISO date of the form yyyy-MM-dd, or date-to was before date-from.
  • statement.reference_invalid — reference was not of the form TYPE:id or SUB_ACCOUNT:category:id with a type, category and id as published in references of getBookingV1.
  • statement.booking_type_invalid — An entry of booking-types was not one of the published booking types.
  • statement.vat_filter_invalid — An entry of vat was not none, a VAT case id, or a VAT case id and a VAT rate id separated by a colon.
Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 The account number does not exist in the chart of accounts.

Error codes for this response (the code field of the response body):
  • account.unknown — No account with this number exists in the chart of accounts.
Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/accounts/{accountCode}/sub-accountskey / tokenList the sub-accounts of one account, for example the bank accounts of 1020.
Returns the sub-accounts of one account of the caller's company as KLARA lists them in the accounting setup of the account, in the order of the screen: for example the bank accounts of 1020 with their IBAN, the transfer accounts of 1090, the social insurers of 2270 with the kind of insurance, the equity rows of 2800. Each row has an id within the account, a type (the kind of sub-account), a name, its position and whether KLARA created it by itself (predefined). Opening balance amounts are not included. Only accounts with sub-accounts can be listed; for any other account (for example 1170 input tax VAT) an internal service answers 400; an account that supports sub-accounts but has none gives an empty list. The list is short and not paged. This is a read-only, idempotent operation without side effects. Tenant and company are derived from the bearer token and are never accepted from the URL or the request. The caller must hold the ACCOUNTING permission on the company; otherwise the endpoint returns 403.
operationId

listSubAccountsV1 — the method name a generated client uses.

Required permission

ACCOUNTING This comes from the description in the specification; the source code analysis behind the other permission statements is older than this endpoint. Roles that carry it: Administrator, External user, Buchhalter.

Parameters 1
NameDescription
accountCode required
path integer (int32)
Account number, as code in listAccountsV1.
format: int32 min: 1 example: 1020
Responses 7
200 The sub-accounts of the account, possibly empty. show body

application/json array of PublicApiSubAccount

Array of PublicApiSubAccount.

  • id integer (int64) format: int64 example: 1
    Id of the sub-account within its account. Missing for a row KLARA shows without storing it, for example "Various" of account 1140. Not the id of a reference: a bank account of 1020 can have id 4 here and be BANK_ACCOUNT:7 in getAccountStatementV1; that reference is in the sub-account rows of getBalanceSheetV1.
  • type string example: BANK
    Kind of sub-account as KLARA names it, for example BANK, TRANSFER, SOCIAL_INSURANCE, EQUITY, DOWN_PAYMENTS_RECEIVED, NOT_BILLED_SERVICES. New kinds can appear.
  • name string example: PostFinance AG
    Name as KLARA shows it, for example the bank or the insurer.
  • position integer (int32) format: int32 example: 1
    Position in the list of the account, as on the screen.
  • predefined boolean example: False
    True for the rows KLARA creates by itself, for example "Transfer account for salaries".
  • iban string example: CH4609000000340027289
    Only BANK: IBAN of the bank account.
  • insuranceType string example: BVG
    Only SOCIAL_INSURANCE: kind of insurance, for example AHV, BVG, UVG.
400 accountCode is below 1, or the account has no sub-accounts.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 No account with this number exists in the chart of accounts.

Error codes for this response (the code field of the response body):
  • account.unknown — No account with this number exists in the chart of accounts.
Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/booking-typeskey / tokenList KLARA master accounting booking types.
Returns the canonical catalog of accounting booking types maintained by KLARA — the stable set of bookkeeping operations (general-ledger postings, payable / receivable invoices, payments, credit notes, prepayments, amortizations, delimitations) that every KLARA company can post against. The data is global — the same catalog is returned for every tenant, so there are no tenant or company path parameters. The Accept-Language header selects which translation of the human-readable description is returned; if absent or unsupported the German translation is used as a fallback. The endpoint is a pure read — idempotent, no side effects. Any authenticated bearer token is accepted; the downstream service declares no role or permission requirement on this endpoint.
operationId

listBookingTypesV1 — the method name a generated client uses.

Required permission

none A valid token is enough. No particular permission is checked for this endpoint.

Parameters 1
NameDescription
Accept-Language
header string
IETF language tag used to resolve the localized description of each booking type. Examples: de-CH, fr-CH, it-CH, en. Falls back to the German translation when no translation exists for the requested language.
example: de-CH
Responses 4
200 Master booking types, ordered by code ascending. Empty array when the catalog has not been seeded yet. show body

application/json array of PublicApiBookingType

Array of PublicApiBookingType.

  • code object example: AP_INVOICE
    Stable machine-readable code of the booking type.
    Allowed values: GENERAL_LEDGER, AP_INVOICE, AP_PAYMENT, AR_INVOICE, AR_PAYMENT, AP_PREPAYMENT, AP_PREPAYUSE, AR_PREPAYMENT, AR_PREPAYUSE, AR_CREDITNOTE, AR_CREDITUSE, AP_CREDITNOTE, AP_CREDITUSE, AMORTIZATION, SELLOFF_AMORTIZATION, DELIMIT
  • description string example: Kreditorenrechnung
    Localized human-readable description of the booking type. Resolved against the request's Accept-Language header; falls back to the German translation when no translation exists for the requested language.
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/business-case-templateskey / tokenList KLARA master accounting business-case templates.
Returns the global catalog of business-case templates — the manual-journal categories that drive the booking form (operating expenses, salary payments, asset purchases, …). The catalog is global KLARA reference data: the same list is returned for every tenant, so there are no tenant or company path parameters. The Accept-Language header selects which translation of the human-readable display label is returned; if absent or unsupported the German translation is used as a fallback and the full per-language i18n / keywordI18ns maps are returned for client-side rendering. Optional sort-field (comma-separated column names) / offset / limit query parameters are forwarded to the downstream catalog for ordering and pagination. The endpoint is a pure read — idempotent, no side effects. Requires a bearer token whose principal carries the ACCOUNTING_GET_BUSINESS_CASE_TEMPLATE permission.
operationId

listBusinessCaseTemplatesV1 — the method name a generated client uses.

Required permission

ACCOUNTING_GET_BUSINESS_CASE_TEMPLATE
Available through: Administrator, External user, Mitarbeiter und Lohn, Buchhalter

Parameters 5
NameDescription
limit
query integer
Maximum number of templates to return. When omitted, the downstream service returns the full catalog.
example: 50
offset
query integer
Zero-based index of the first template to return. When omitted, the response starts at the first row.
example: 0
orderColumns
query array of string
Renamed to sort-field. This name is accepted until 2027-09-01; when both are sent, sort-field wins. After that date, a request sending orderColumns without sort-field is rejected with 400.

Deprecated — use sort-field instead, which takes the columns as one comma-separated value rather than as a repeated parameter. Names of columns to order the result by, ascending. Repeat this query parameter for multi-column ordering.
example: code
sort-field
query string
Comma-separated list of columns to order the result by, ascending (e.g. ?sort-field=group,code). This catalog orders ascending only, so it publishes no sort-direction.
example: group,code
Accept-Language
header string
IETF language tag used to resolve the localized display label of each template. Examples: de-CH, fr-CH, it-CH, en. Falls back to the German translation when no translation exists for the requested language.
example: de-CH
Responses 5
200 Business-case templates matching the supplied ordering and pagination. show body

application/json array of PublicApiBusinessCaseTemplate

Array of PublicApiBusinessCaseTemplate.

  • id integer (int64) format: int64 example: 101
    Internal id of the template in the KLARA catalogue.
  • code string example: OFFICE_SUPPLIES
    Stable catalogue code of the template.
  • display string example: Bürobedarf
    Label of the template, already translated for the request's Accept-Language.
  • i18n object
    All translations of the label, keyed by IETF language tag.
    show fields

    Open map with values of type string.

  • keywordI18ns object
    All translations of the search keywords, keyed by IETF language tag.
    show fields

    Open map with values of type string.

  • group string example: Operating expenses
    Catalogue group the template belongs to.
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/business-case-templates/{businessCaseTemplateId}key / tokenRead a single KLARA master accounting business-case template by id.
Returns one business-case template from the global KLARA catalog — a manual-journal category usable when entering a booking (for example operating expenses, salary payments, asset purchases). The catalog is global KLARA reference data, so this endpoint has no tenant or company path parameters; only the catalogue id selects the template. The Accept-Language header selects which translation of the human-readable display label is returned; if absent or unsupported the German translation is used as a fallback and the full per-language i18n / keywordI18ns maps are returned for client-side rendering. The endpoint is a pure read — idempotent, no side effects. Returns 404 when no template with the requested id exists in the catalog. Requires a bearer token whose principal carries the ACCOUNTING_GET_BUSINESS_CASE_TEMPLATE permission.
operationId

getBusinessCaseTemplateByIdV1 — the method name a generated client uses.

Required permission

ACCOUNTING_GET_BUSINESS_CASE_TEMPLATE
Available through: Administrator, External user, Mitarbeiter und Lohn, Buchhalter

Parameters 2
NameDescription
businessCaseTemplateId required
path integer (int64)
Numeric primary-key id of the business-case template in the KLARA master catalog. Obtain it from a prior call to GET /core/v1/accounting/business-case-templates.
format: int64 example: 101
Accept-Language
header string
IETF language tag used to resolve the localized display label of the template. Examples: de-CH, fr-CH, it-CH, en. Falls back to the German translation when no translation exists for the requested language.
example: de-CH
Responses 6
200 Business-case template matching the supplied id. show body

application/json PublicApiBusinessCaseTemplate

  • id integer (int64) format: int64 example: 101
    Internal id of the template in the KLARA catalogue.
  • code string example: OFFICE_SUPPLIES
    Stable catalogue code of the template.
  • display string example: Bürobedarf
    Label of the template, already translated for the request's Accept-Language.
  • i18n object
    All translations of the label, keyed by IETF language tag.
    show fields

    Open map with values of type string.

  • keywordI18ns object
    All translations of the search keywords, keyed by IETF language tag.
    show fields

    Open map with values of type string.

  • group string example: Operating expenses
    Catalogue group the template belongs to.
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 No business-case template carries the requested id.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/business-case-templates/{businessCaseTemplateId}/payment-sourceskey / tokenList the payment sources a business case template offers for one payment group.
Returns the sources the caller can choose for an already paid booking with this template and payment group, as the Booking Workflow offers them: bank accounts, cards, cash registers, transfer accounts, other persons, cashless payment accounts or employees of the company. Send the id as paymentSourceId to bookDocumentAsPaidV1 with the same template, payment group and booking date. For EMPLOYEE each source also lists the payrollDates it can be reimbursed with. For OTHER the rows name the payment options without a source. The list is not paged; it is short. Read only. Tenant and company come from the token. The caller must hold the ACCOUNTING permission (an internal service); EMPLOYEE also needs COMPENSATION_GET_EMPLOYEE (an internal service), which accountant does not have.
operationId

listBusinessCasePaymentSourcesV1 — the method name a generated client uses.

Required permission

ACCOUNTING This comes from the description in the specification; the source code analysis behind the other permission statements is older than this endpoint. Roles that carry it: Administrator, External user, Buchhalter.

Parameters 4
NameDescription
businessCaseTemplateId required
path integer (int64)
Business case template, from listCurrentCompanyBusinessCaseTemplatesV1.
format: int64 min: 1 example: 30343
payment-group required
query string
Payment group: BANK_ACCOUNT, CARD, CASHLESS_PAYMENT, CASH_REGISTER, EMPLOYEE, OTHER_PERSON, TRANSFER_ACCOUNT, OTHER.
example: BANK_ACCOUNT
booking-date
query string (date)
Booking date (yyyy-MM-dd) that selects the fiscal year, as in the booking. Defaults to today.
format: date example: 2026-10-20
Accept-Language
header string
Language of the source names, as for bookDocumentAsPaidV1: the first of de, fr, it, en in the header, otherwise English. Examples: de-CH, en.
example: de-CH
Responses 7
200 Payment sources of the template for the payment group. show body

application/json array of PublicApiPaymentSource

Array of PublicApiPaymentSource.

  • id string example: 5
    Id to send as paymentSourceId to bookDocumentAsPaidV1 with the same template, payment group and booking date.
  • paymentGroup object example: BANK_ACCOUNT
    How the document was paid: BANK_ACCOUNT bank account, CARD debit, credit or prepaid card, CASHLESS_PAYMENT cashless payment account, CASH_REGISTER cash register, EMPLOYEE paid by an employee who is reimbursed through payroll, OTHER_PERSON paid by another person, TRANSFER_ACCOUNT transfer account, OTHER other payment without a source.
  • display string example: PostFinance CHF
    Name of the source as the Booking Workflow shows it, for example the bank account or the employee.
  • payrollDates array of string
    Payroll dates the employee can be reimbursed with; only for EMPLOYEE. Send one of them as payrollDate.
400 payment-group is not an already paid option of the template, or booking-date is not an ISO date.

Error codes for this response (the code field of the response body):
  • booking.booking_date_invalid — booking-date-from or booking-date-to was not an ISO date of the form yyyy-MM-dd, or booking-date-to was before booking-date-from; for a document booking, bookingDate or booking-date was not an ISO date of that form.
  • businesscase.payment_group_not_offered — The business case template has no already paid option for the payment group, or the group is not available for the company (as in the Booking Workflow, for example EMPLOYEE without employees).
Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Unknown business case template.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/business-caseskey / tokenHydrate a business case from a template id for the authenticated company.
Loads the fully hydrated business-case aggregate the booking form needs: the template id, the company-VAT and fiscal-year context resolved from the optional date filters, the pre-translated display label, and the recursive snippet / field tree. When dateForFilteringFiscalYear is supplied it drives the fiscal-year resolution; otherwise dateForFilteringCompanyVat is used; otherwise the downstream service resolves the fiscal year that covers today. Tenant and company are derived from the bearer-token session — they are never accepted from the URL. The endpoint is a pure read — idempotent, no side effects. The caller must hold the ACCOUNTING permission on the company in scope.
operationId

hydrateBusinessCaseFromTemplateV1 — the method name a generated client uses.

Required permission

ACCOUNTING
Available through: Administrator, External user, Buchhalter

Parameters 4
NameDescription
businessCaseTemplateId required
query integer (int64)
Numeric id of the business-case template to hydrate. Obtain it from GET /core/v1/accounting/companies/current/business-case-templates.
format: int64 example: 101
dateForFilteringCompanyVat
query string (date)
ISO date (yyyy-MM-dd) used to resolve the company-VAT regime applicable to the business case. Used as the fallback for dateForFilteringFiscalYear when that is omitted.
format: date example: 2024-06-15
dateForFilteringFiscalYear
query string (date)
ISO date (yyyy-MM-dd) used to resolve the fiscal year that hydrates the business case. When omitted, falls back to dateForFilteringCompanyVat; when both are omitted the downstream service resolves the fiscal year that covers today.
format: date example: 2024-06-15
Accept-Language
header string
IETF language tag used to translate the snippet labels and field captions. Examples: de-CH, fr-CH, it-CH, en.
example: de-CH
Responses 7
200 Hydrated business-case aggregate for the requested template. show body

application/json PublicApiBusinessCase

  • businessCaseId integer (int64) format: int64 example: null
    Identifier of the business case instance when persisted; null on a freshly hydrated template.
  • businessCaseTemplateId integer (int64) format: int64 example: 101
    Identifier of the business-case template this aggregate was hydrated from.
  • documentId string example: null
    Identifier of the underlying document the business case is attached to; null when the booking is not yet linked to a document.
  • display string example: Bürobedarf
    Pre-translated display label of the business-case template for the request's Accept-Language.
  • bookingNumbers string example:
    Comma-separated list of booking numbers already generated for this business case; empty on a fresh template.
  • effectiveCompanyVatDate string (date) format: date example: 2024-06-15
    Date used to resolve the company-VAT regime applicable to this business case (ISO yyyy-MM-dd).
  • documentDate string (date) format: date example: 2024-06-15
    Document date associated with the business case (ISO yyyy-MM-dd).
  • effectiveFiscalYearDate string (date) format: date example: 2024-06-15
    Date used to resolve the fiscal year applicable to this business case (ISO yyyy-MM-dd).
  • fiscalYearHasCreatedAuto boolean example: False
    True when the downstream service had to auto-create the fiscal year covering the resolved date.
  • withOP boolean example: False
    True when this business case is tracked as an open item (OP). May be null when not applicable.
  • fields object
    Recursive snippet-and-field tree driving the booking form, keyed by snippet code. The shape of each entry follows the downstream BusinessCaseField model.
    show fields

    Open map with values of type object.

  • entriesDefinition array of object
    Per-field entries definitions used by the booking form to resolve enum-like fields. Each entry mirrors the downstream FieldEntriesDefinition model.
    show fields

    Array of object.

    Open map with values of type object.

400 One of dateForFilteringFiscalYear / dateForFilteringCompanyVat is not a valid ISO date (yyyy-MM-dd), or the supplied businessCaseTemplateId is not valid for the company's legal form or VAT regime.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 No business-case template matches the supplied businessCaseTemplateId in the caller's company scope.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/business-cases/v2key / tokenHydrate a business case from a template id, scoped to a single snippet.
Snippet-scoped variant of GET /core/v1/accounting/business-cases: hydrates only the template root plus the snippet identified by snippet-id, so the booking UI can stream the form one snippet at a time instead of loading the whole tree up-front. When dateForFilteringFiscalYear is supplied it drives the fiscal-year resolution; otherwise dateForFilteringCompanyVat is used; otherwise the downstream service resolves the fiscal year that covers today. When group-insurance-by-insurer is true (the default), social-insurance entries that share the same display + value pair are collapsed, keeping the entry with the smallest numeric id. Tenant and company are derived from the bearer-token session — they are never accepted from the URL. The endpoint is a pure read — idempotent, no side effects. The caller must hold the ACCOUNTING permission on the company in scope.
operationId

hydrateBusinessCaseFromTemplateForSnippetV1 — the method name a generated client uses.

Required permission

ACCOUNTING
Available through: Administrator, External user, Buchhalter

Parameters 7
NameDescription
businessCaseTemplateId required
query integer (int64)
Numeric id of the business-case template to hydrate. Obtain it from GET /core/v1/accounting/companies/current/business-case-templates.
format: int64 example: 101
dateForFilteringCompanyVat
query string (date)
ISO date (yyyy-MM-dd) used to resolve the company-VAT regime applicable to the business case. Used as the fallback for dateForFilteringFiscalYear when that is omitted.
format: date example: 2024-06-15
dateForFilteringFiscalYear
query string (date)
ISO date (yyyy-MM-dd) used to resolve the fiscal year that hydrates the business case. When omitted, falls back to dateForFilteringCompanyVat; when both are omitted the downstream service resolves the fiscal year that covers today.
format: date example: 2024-06-15
group-insurance-by-insurer
query boolean
When true, collapses social-insurance entries that share the same display + value pair, keeping the entry with the smallest numeric id. Defaults to true. Allowed values: true, false.
default: true example: True
snippet-id
query integer (int64)
Numeric id of the snippet currently activated by the user; v2 hydrates only this snippet plus the template root. When omitted, only the template root is hydrated.
format: int64 example: 42
snippet-value
query string
Currently ignored on the downstream side; reserved for a future optimisation that would load external entries only for the activated value (for example, payment dates of a single employee). Safe to omit.
example: EMP-1001
Accept-Language
header string
IETF language tag used to translate the snippet labels and field captions. Examples: de-CH, fr-CH, it-CH, en.
example: de-CH
Responses 7
200 Hydrated business-case aggregate for the requested template and snippet. show body

application/json PublicApiBusinessCase

  • businessCaseId integer (int64) format: int64 example: null
    Identifier of the business case instance when persisted; null on a freshly hydrated template.
  • businessCaseTemplateId integer (int64) format: int64 example: 101
    Identifier of the business-case template this aggregate was hydrated from.
  • documentId string example: null
    Identifier of the underlying document the business case is attached to; null when the booking is not yet linked to a document.
  • display string example: Bürobedarf
    Pre-translated display label of the business-case template for the request's Accept-Language.
  • bookingNumbers string example:
    Comma-separated list of booking numbers already generated for this business case; empty on a fresh template.
  • effectiveCompanyVatDate string (date) format: date example: 2024-06-15
    Date used to resolve the company-VAT regime applicable to this business case (ISO yyyy-MM-dd).
  • documentDate string (date) format: date example: 2024-06-15
    Document date associated with the business case (ISO yyyy-MM-dd).
  • effectiveFiscalYearDate string (date) format: date example: 2024-06-15
    Date used to resolve the fiscal year applicable to this business case (ISO yyyy-MM-dd).
  • fiscalYearHasCreatedAuto boolean example: False
    True when the downstream service had to auto-create the fiscal year covering the resolved date.
  • withOP boolean example: False
    True when this business case is tracked as an open item (OP). May be null when not applicable.
  • fields object
    Recursive snippet-and-field tree driving the booking form, keyed by snippet code. The shape of each entry follows the downstream BusinessCaseField model.
    show fields

    Open map with values of type object.

  • entriesDefinition array of object
    Per-field entries definitions used by the booking form to resolve enum-like fields. Each entry mirrors the downstream FieldEntriesDefinition model.
    show fields

    Array of object.

    Open map with values of type object.

400 One of dateForFilteringFiscalYear / dateForFilteringCompanyVat is not a valid ISO date (yyyy-MM-dd), or the supplied businessCaseTemplateId is not valid for the company's legal form or VAT regime.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 No business-case template matches the supplied businessCaseTemplateId in the caller's company scope.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/business-cases/{businessCaseId}key / tokenRead a persisted business-case instance by its id for the authenticated company.
Loads the fully hydrated business-case aggregate that was previously persisted for the authenticated company: the template id, the company-VAT and fiscal-year context that were in force when the case was booked, the pre-translated display label, the recursive snippet / field tree with the persisted scripted values overlaid, and the comma-separated list of booking numbers already generated for it. Tenant and company are derived from the bearer-token session — they are never accepted from the URL; the supplied businessCaseId is matched against the caller's company so that an id owned by another company surfaces as 404. The endpoint is a pure read — idempotent, no side effects. The caller must hold the ACCOUNTING permission on the company in scope.
operationId

getBusinessCaseByIdV1 — the method name a generated client uses.

Required permission

ACCOUNTING
Available through: Administrator, External user, Buchhalter

Parameters 2
NameDescription
businessCaseId required
path integer (int64)
Numeric primary-key id of the persisted business-case instance to hydrate. Obtain it from a prior booking response (for example POST /core/v1/accounting/bookings) or from a journal listing.
format: int64 example: 5001
Accept-Language
header string
IETF language tag used to translate the snippet labels and field captions. Examples: de-CH, fr-CH, it-CH, en.
example: de-CH
Responses 7
200 Hydrated business-case aggregate for the requested id. show body

application/json PublicApiBusinessCase

  • businessCaseId integer (int64) format: int64 example: null
    Identifier of the business case instance when persisted; null on a freshly hydrated template.
  • businessCaseTemplateId integer (int64) format: int64 example: 101
    Identifier of the business-case template this aggregate was hydrated from.
  • documentId string example: null
    Identifier of the underlying document the business case is attached to; null when the booking is not yet linked to a document.
  • display string example: Bürobedarf
    Pre-translated display label of the business-case template for the request's Accept-Language.
  • bookingNumbers string example:
    Comma-separated list of booking numbers already generated for this business case; empty on a fresh template.
  • effectiveCompanyVatDate string (date) format: date example: 2024-06-15
    Date used to resolve the company-VAT regime applicable to this business case (ISO yyyy-MM-dd).
  • documentDate string (date) format: date example: 2024-06-15
    Document date associated with the business case (ISO yyyy-MM-dd).
  • effectiveFiscalYearDate string (date) format: date example: 2024-06-15
    Date used to resolve the fiscal year applicable to this business case (ISO yyyy-MM-dd).
  • fiscalYearHasCreatedAuto boolean example: False
    True when the downstream service had to auto-create the fiscal year covering the resolved date.
  • withOP boolean example: False
    True when this business case is tracked as an open item (OP). May be null when not applicable.
  • fields object
    Recursive snippet-and-field tree driving the booking form, keyed by snippet code. The shape of each entry follows the downstream BusinessCaseField model.
    show fields

    Open map with values of type object.

  • entriesDefinition array of object
    Per-field entries definitions used by the booking form to resolve enum-like fields. Each entry mirrors the downstream FieldEntriesDefinition model.
    show fields

    Array of object.

    Open map with values of type object.

400 The supplied businessCaseId is not a valid numeric id.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 No business case matches the supplied businessCaseId in the caller's company scope.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/companies/currentkey / tokenGet the accounting configuration of the authenticated company.
Returns the dunning waiting periods configured for the authenticated caller's company together with the canonical compensation-side company URI. Tenant and company are derived from the bearer token — there are no path or query parameters to override them. When the company has no accounting configuration row persisted yet, the downstream service synthesises a default record (id = null, waitingDunningTime = 5, dunningWaitingTimeLevelOne / Two / Three = 10) so the response shape stays the same. The endpoint is a pure read — idempotent, no side effects. The caller must hold the ACCOUNTING permission on the company in scope.
operationId

getCurrentAccountingCompanyV1 — the method name a generated client uses.

Required permission

ACCOUNTING
Available through: Administrator, External user, Buchhalter

Responses 6
200 Accounting configuration of the caller's company. show body

application/json PublicApiAccountingCompany

  • id integer (int64) format: int64 example: 17
    Internal id of the accounting-configuration row. Null when no configuration has been persisted yet for the company.
  • companyUri string example: /luz_compensation/api/c60d31fa-f335-4957-872a-90b035632081/companies/1
    Canonical compensation-side URI of the company, of the form /…/{tenant}/companies/{companyId}.
  • waitingDunningTime integer (int64) format: int64 example: 5
    Number of days to wait after the invoice due date before starting the dunning cycle. Defaults to 5 when no configuration exists yet.
  • dunningWaitingTimeLevelOne integer (int64) format: int64 example: 10
    Days to wait between the level-1 dunning notice and the level-2 escalation. Defaults to 10 when no configuration exists yet.
  • dunningWaitingTimeLevelTwo integer (int64) format: int64 example: 10
    Days to wait between the level-2 dunning notice and the level-3 escalation. Defaults to 10 when no configuration exists yet.
  • dunningWaitingTimeLevelThree integer (int64) format: int64 example: 10
    Days to wait between the level-3 dunning notice and the final escalation. Defaults to 10 when no configuration exists yet.
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 The company associated with the caller's session could not be resolved by the downstream accounting service.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/companies/current/business-case-templateskey / tokenList business-case templates available to the authenticated company, grouped by financial-year period.
Returns the manual-journal categories ("business-case templates") the caller's company is allowed to book against, grouped by the financial-year period in which they are valid. Each period carries its periodFrom / periodTo, the company's legalForm and active VAT regime, and the templates that pass the legal-form / VAT-regime filters for that period. Templates are sorted by code; the display field is pre-translated using the Accept-Language header and the full per-language map is also returned in i18n / keywordI18ns. Tenant and company are derived from the bearer token — there are no path or query parameters to override them. The endpoint is a pure read — idempotent, no side effects. The caller must hold the ACCOUNTING permission on the company in scope.
operationId

listCurrentCompanyBusinessCaseTemplatesV1 — the method name a generated client uses.

Required permission

ACCOUNTING
Available through: Administrator, External user, Buchhalter

Parameters 1
NameDescription
Accept-Language
header string
IETF language tag used to translate the display field of each template. Examples: de-CH, fr-CH, it-CH, en.
example: de-CH
Responses 6
200 Business-case templates grouped by financial-year period. May be an empty array when the company has no open fiscal year yet. show body

application/json array of PublicApiBusinessCasePeriod

Array of PublicApiBusinessCasePeriod.

  • companyId integer (int64) format: int64 example: 1
    Internal id of the company this period belongs to.
  • periodFrom string (date) format: date example: 2024-01-01
    Inclusive start date of the financial year (ISO yyyy-MM-dd).
  • periodTo string (date) format: date example: 2024-12-31
    Inclusive end date of the financial year (ISO yyyy-MM-dd).
  • legalForm string example: EINZEL
    Legal form of the company during this period. Allowed values include EINZEL, GMBH, AG, KOLLEKTIV, KOMMANDIT, GENOSSENSCHAFT, VEREIN, STIFTUNG.
  • companyVat object
    VAT regime of a company within a fiscal period.
    show fields
    • id integer (int64) format: int64 example: 42
      Internal id of the company VAT row.
    • reportingVat string example: EFFECTIVE
      Reporting method used to declare VAT. Allowed values: EFFECTIVE, NET_TAX_RATE, FLAT_TAX_RATE.
    • billing string example: AGREED
      Billing method used to determine VAT liability. Allowed values: AGREED, RECEIVED.
    • code string example: EFFECTIVE_AGREED
      Composite VAT code combining reporting method and billing, or NON_VAT when the company is not VAT-liable.
    • hasVat boolean example: True
      True when the company is VAT-liable in this period.
    • validFrom string (date) format: date example: 2024-01-01
      Inclusive start date of the VAT regime (ISO yyyy-MM-dd).
    • validTo string (date) format: date example: 2024-12-31
      Inclusive end date of the VAT regime (ISO yyyy-MM-dd).
    • yearlySettlement boolean example: False
      True for yearly VAT settlement, false for quarterly/semi-annual.
  • status string example: OPEN
    Status of the fiscal year. Allowed values: OPEN, CLOSING, CLOSED.
  • businessCaseTemplates array of PublicApiBusinessCaseTemplate
    Business-case templates valid for the company's legal form and VAT regime within this period, sorted by code.
    show fields

    Array of PublicApiBusinessCaseTemplate.

    • id integer (int64) format: int64 example: 101
      Internal id of the template in the KLARA catalogue.
    • code string example: OFFICE_SUPPLIES
      Stable catalogue code of the template.
    • display string example: Bürobedarf
      Label of the template, already translated for the request's Accept-Language.
    • i18n object
      All translations of the label, keyed by IETF language tag.
      show fields

      Open map with values of type string.

    • keywordI18ns object
      All translations of the search keywords, keyed by IETF language tag.
      show fields

      Open map with values of type string.

    • group string example: Operating expenses
      Catalogue group the template belongs to.
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 The company associated with the caller's session could not be resolved by the downstream accounting service.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/companies/current/financial-yearskey / tokenList active financial-year periods of the authenticated company.
Returns the company's currently active fiscal-year periods (status OPEN or CLOSING), one entry per legal-form / VAT-regime combination valid in the period. When every period shares the same legalForm and VAT regime the downstream service collapses them into a single aggregated period with periodFrom set to the earliest start date and periodTo set to the latest end date; otherwise the individual periods are returned. The businessCaseTemplates field is intentionally left empty on this endpoint — use GET /core/v1/accounting/companies/current/business-case-templates to retrieve the templates valid per period. Tenant and company are derived from the bearer token — there are no path or query parameters to override them. The endpoint is a pure read — idempotent, no side effects. The caller must hold the ACCOUNTING permission on the company in scope.
operationId

listCurrentCompanyFinancialYearsV1 — the method name a generated client uses.

Required permission

ACCOUNTING
Available through: Administrator, External user, Buchhalter

Parameters 1
NameDescription
Accept-Language
header string
IETF language tag forwarded to the downstream accounting service. Examples: de-CH, fr-CH, it-CH, en.
example: de-CH
Responses 6
200 Active financial-year periods of the caller's company. May be an empty array when the company has no open fiscal year yet. show body

application/json array of PublicApiBusinessCasePeriod

Array of PublicApiBusinessCasePeriod.

  • companyId integer (int64) format: int64 example: 1
    Internal id of the company this period belongs to.
  • periodFrom string (date) format: date example: 2024-01-01
    Inclusive start date of the financial year (ISO yyyy-MM-dd).
  • periodTo string (date) format: date example: 2024-12-31
    Inclusive end date of the financial year (ISO yyyy-MM-dd).
  • legalForm string example: EINZEL
    Legal form of the company during this period. Allowed values include EINZEL, GMBH, AG, KOLLEKTIV, KOMMANDIT, GENOSSENSCHAFT, VEREIN, STIFTUNG.
  • companyVat object
    VAT regime of a company within a fiscal period.
    show fields
    • id integer (int64) format: int64 example: 42
      Internal id of the company VAT row.
    • reportingVat string example: EFFECTIVE
      Reporting method used to declare VAT. Allowed values: EFFECTIVE, NET_TAX_RATE, FLAT_TAX_RATE.
    • billing string example: AGREED
      Billing method used to determine VAT liability. Allowed values: AGREED, RECEIVED.
    • code string example: EFFECTIVE_AGREED
      Composite VAT code combining reporting method and billing, or NON_VAT when the company is not VAT-liable.
    • hasVat boolean example: True
      True when the company is VAT-liable in this period.
    • validFrom string (date) format: date example: 2024-01-01
      Inclusive start date of the VAT regime (ISO yyyy-MM-dd).
    • validTo string (date) format: date example: 2024-12-31
      Inclusive end date of the VAT regime (ISO yyyy-MM-dd).
    • yearlySettlement boolean example: False
      True for yearly VAT settlement, false for quarterly/semi-annual.
  • status string example: OPEN
    Status of the fiscal year. Allowed values: OPEN, CLOSING, CLOSED.
  • businessCaseTemplates array of PublicApiBusinessCaseTemplate
    Business-case templates valid for the company's legal form and VAT regime within this period, sorted by code.
    show fields

    Array of PublicApiBusinessCaseTemplate.

    • id integer (int64) format: int64 example: 101
      Internal id of the template in the KLARA catalogue.
    • code string example: OFFICE_SUPPLIES
      Stable catalogue code of the template.
    • display string example: Bürobedarf
      Label of the template, already translated for the request's Accept-Language.
    • i18n object
      All translations of the label, keyed by IETF language tag.
      show fields

      Open map with values of type string.

    • keywordI18ns object
      All translations of the search keywords, keyed by IETF language tag.
      show fields

      Open map with values of type string.

    • group string example: Operating expenses
      Catalogue group the template belongs to.
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 The company associated with the caller's session could not be resolved by the downstream accounting service.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/currencies/exchange-ratekey / tokenGet the CHF exchange rate for a currency on a given date.
Returns the Swiss National Bank reference rate that converts one unit of from-currency-code into CHF on exchange-date. When from-currency-code equals CHF (case-insensitive) the rate is always 1. The exchange-rate table is global SNB data — the same response is returned for every tenant, so there are no tenant or company path parameters. If no rate is stored for the requested day, the downstream service transparently fetches the SNB feed for that date and persists the result; if the feed has no entry either, the most recent rate strictly before exchange-date is returned instead. The endpoint is a pure read for the caller — idempotent. Requires a bearer token whose principal carries the ACCOUNTING permission.
operationId

getExchangeRateV1 — the method name a generated client uses.

Required permission

ACCOUNTING
Available through: Administrator, External user, Buchhalter

Parameters 2
NameDescription
exchange-date required
query string (date)
Reference date for the exchange rate, expressed as an ISO-8601 calendar date (yyyy-MM-dd).
format: date example: 2024-09-30
from-currency-code required
query string
ISO-4217 alpha-3 currency code of the source amount. Case-insensitive; CHF short-circuits to a rate of 1.
example: EUR
Responses 5
200 Exchange rate as a JSON number; the value 1 when from-currency-code is CHF. show body

application/json number

400 exchange-date is not a valid ISO-8601 calendar date, or no rate could be resolved for the supplied from-currency-code.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
POST/core/v1/accounting/document-bookings/paidkey / tokenBook an uploaded document through a business case as already paid.
Books one document from the booking queue through a business case template and marks it as paid from the chosen source, as the Booking Workflow does in the web app: it creates the booking with its VAT lines, links the business case and takes the document out of the queue. Supported templates are the expense templates with a supplier and the revenue templates with a customer that the Booking Workflow offers for the booking date (listCurrentCompanyBusinessCaseTemplatesV1); asset purchase, current account, transfer account, tax and social insurance templates answer 400 businesscase.template_not_supported. Take paymentSourceId from listBusinessCasePaymentSourcesV1, and vatCaseId and vatRateId from the entries vatCase and vatRate of hydrateBusinessCaseFromTemplateForSnippetV1. Optional fields follow the Booking Workflow: servicePeriodFrom/servicePeriodTo, dueDate, paymentPurpose, internalComment and text are accepted only where the template and the payment option show that field, otherwise 400 businesscase.field_not_offered; nothing is dropped silently. Booking texts are written in the language of Accept-Language (de, fr, it, en), English without it; send the language of the KLARA user. A document that is not in the booking queue or is already booked answers 409. No operation undoes the booking. Tenant and company come from the token. Documents stored in the KLARA eArchive are not supported yet (400 document.archive_not_supported). Permissions: the caller must hold ACCOUNTING (an internal service), must have one of the roles company_administrator, trusted_user, accountant, customer_relationship_manager for the document checks (an internal service), and needs FINANCE_GET_CUSTOMER to read the partner (an internal service); the payment group EMPLOYEE also needs COMPENSATION_GET_EMPLOYEE, which accountant does not have. Agents: this call creates a booking in the general ledger and, for EMPLOYEE, a reimbursement request in payroll; ask the user for explicit confirmation first.
operationId

bookDocumentAsPaidV1 — the method name a generated client uses.

Required permission

ACCOUNTING FINANCE_GET_CUSTOMER This comes from the description in the specification; the source code analysis behind the other permission statements is older than this endpoint. Roles that carry it: Administrator, External user, Buchhalter.

Parameters 2
NameDescription
confirm-closing-fiscal-year
query boolean
Book into a fiscal year in status closing. Without it such a booking is rejected with 400 (fiscal.year.is.closing). A sealed fiscal year is always rejected.
default: false example: False
Accept-Language
header string
Language of the booking texts KLARA writes (for example "Verbindlichkeit Leistungsperiode") and of error texts from an internal service: the first of de, fr, it, en in the header. Without the header, or with none of these languages, English. Send the language of the KLARA user. Examples: de-CH, fr.
example: de-CH
Request body required
Document, template, amount, VAT, partner, tags and payment.

application/json PublicApiDocumentBookingPaid

  • documentId string required pattern: \S example: 9007199254
    Id of the document in the booking queue, as returned by the document upload. Documents stored in the KLARA eArchive are not supported yet (400 document.archive_not_supported).
  • businessCaseTemplateId integer (int64) required format: int64 min: 1 example: 30343
    Business case template, from listCurrentCompanyBusinessCaseTemplatesV1 for the booking date. Supported: expense templates with a supplier and revenue templates with a customer.
  • bookingDate string required maxLength: 10 pattern: \S example: 2026-10-20
    Document date (yyyy-MM-dd). It also selects the fiscal year and the company VAT settings.
  • grossAmount number required pattern: ^\d{1,13}([.]\d{1,2})?$ example: 107.7
    Gross amount of the document in CHF, VAT included. Must not be zero; negative for a correction.
  • vatCaseId string maxLength: 255 example: 7
    VAT case of the line: the id of an entry with entriesReference vatCase in hydrateBusinessCaseFromTemplateForSnippetV1. Required for VAT templates.
  • vatRateId string maxLength: 255 example: 41
    VAT rate of the line: the id of an entry with entriesReference vatRate that belongs to the VAT case. Required for VAT templates.
  • partnerId integer (int64) required format: int64 min: 1 example: 1234
    Supplier (expense templates) or customer (revenue templates): the customer id from listCustomers.
  • tags array of string required minItems: 1 maxItems: 20
    Tags of the booking, at least one, as in the Booking Workflow. A tag must not contain a comma.
  • text string maxLength: 140 example: Printer paper
    Booking text (subject). Revenue templates have it; a template without it answers 400 businesscase.field_not_offered.
  • servicePeriodFrom string maxLength: 10 example: 2026-10-01
    Start of the service period (yyyy-MM-dd), together with servicePeriodTo. As in the Booking Workflow, it is set on the document and on the booking line, and a VAT rate is accepted when its validity overlaps the period or covers bookingDate.
  • servicePeriodTo string maxLength: 10 example: 2026-12-31
    End of the service period (yyyy-MM-dd), not before servicePeriodFrom.
  • paymentGroup object required example: BANK_ACCOUNT
    How the document was paid: BANK_ACCOUNT bank account, CARD debit, credit or prepaid card, CASHLESS_PAYMENT cashless payment account, CASH_REGISTER cash register, EMPLOYEE paid by an employee who is reimbursed through payroll, OTHER_PERSON paid by another person, TRANSFER_ACCOUNT transfer account, OTHER other payment without a source.
  • paymentSourceId string maxLength: 512 example: 5
    Source of the payment: the id from listBusinessCasePaymentSourcesV1 for the same template, payment group and booking date. Required except for OTHER.
  • paymentDate string maxLength: 10 example: 2026-10-21
    Payment date (yyyy-MM-dd). Required where the payment option has one: bank account, card, cash register, cashless payment, transfer account.
  • payrollDate string maxLength: 32 example: 31.10.2026
    Payroll date the employee is reimbursed with, one of payrollDates of the source. Required for EMPLOYEE.
  • dueDate string maxLength: 10 example: 2026-11-20
    Due date of the document (yyyy-MM-dd), where the payment option has one, for example bank account and card. Otherwise 400 businesscase.field_not_offered.
  • paymentPurpose string maxLength: 140 example: Travel expenses October
    Payment purpose of the reimbursement, only for EMPLOYEE, as in the Booking Workflow. Otherwise 400 businesscase.field_not_offered.
  • internalComment string maxLength: 5000 example: Approved by the team lead
    Internal remark, stored on the booking (internalComment of getBookingV1). Every already paid option of an expense template has it; otherwise 400 businesscase.field_not_offered.
Responses 8
201 The document was booked. documentMoveStatus says whether it left the booking queue. show body

application/json PublicApiDocumentBookingResult

  • bookingId integer (int64) format: int64 example: 912345
    Id of the created booking; read it with getBookingV1.
  • businessCaseId integer (int64) format: int64 example: 48211
    Id of the created business case; read it with getBusinessCaseByIdV1.
  • documentMoveStatus object example: MOVED
    Whether the document was taken out of the booking queue after the booking: MOVED it now shows under the booked documents, FAILED it could not be moved and still shows in the queue, NOT_FOUND the file was not found. The booking is kept in every case.
  • reimbursementRequested boolean example: False
    true when a reimbursement request was sent to payroll (payment group EMPLOYEE).
400 Invalid input, a template or payment option this operation does not support, or a rule of an internal service (for example a closed or sealed fiscal year, a missing subscription, a zero payment amount).

Error codes for this response (the code field of the response body):
  • booking.booking_date_invalid — booking-date-from or booking-date-to was not an ISO date of the form yyyy-MM-dd, or booking-date-to was before booking-date-from; for a document booking, bookingDate or booking-date was not an ISO date of that form.
  • booking.payment_date_invalid — paymentDate was not an ISO date of the form yyyy-MM-dd.
  • booking.payment_date_missing — The chosen payment option has a payment date (bank account, card, cash register, cashless payment, transfer account) and paymentDate was not sent.
  • booking.due_date_invalid — dueDate was not an ISO date of the form yyyy-MM-dd.
  • booking.service_period_invalid — servicePeriodFrom or servicePeriodTo was not an ISO date of the form yyyy-MM-dd, only one of them was sent, or servicePeriodTo was before servicePeriodFrom.
  • booking.amount_zero — grossAmount was zero. The Booking Workflow does not book a document of zero; a negative amount is accepted for a correction.
  • document.archive_not_supported — The document is stored in the KLARA eArchive. bookDocumentAsPaidV1 does not book eArchive documents yet; they are booked in the web app.
  • businesscase.template_not_supported — The business case template is not offered by the Booking Workflow for the booking date, or it needs input this operation does not take (asset purchase, current account, transfer account, tax and social insurance templates). The message names the missing input.
  • businesscase.payment_group_not_offered — The business case template has no already paid option for the payment group, or the group is not available for the company (as in the Booking Workflow, for example EMPLOYEE without employees).
  • businesscase.vat_entry_unknown — vatCaseId or vatRateId was missing on a VAT template, or is not one of its entries, or the rate does not belong to the case, or the rate is valid neither on bookingDate nor within the service period.
  • businesscase.field_not_offered — A value was sent that the chosen template and payment option do not have (text, servicePeriodFrom, dueDate, paymentPurpose or internalComment). The Booking Workflow does not show that field for this choice; the message names it.
  • businesscase.payroll_date_unknown — payrollDate was missing for EMPLOYEE or is not one of the payroll dates of the employee.
Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Unknown document, payment source or partner in the caller's company.

Error codes for this response (the code field of the response body):
  • document.unknown — No document with this id exists in the caller's company.
  • businesscase.payment_source_unknown — paymentSourceId was missing or is not one of the sources listBusinessCasePaymentSourcesV1 returns for this template, payment group and booking date.
  • businesscase.partner_unknown — No customer or supplier with partnerId exists in the caller's company.
Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
409 The document is not waiting in the booking queue, or it is already booked (document.already.booked, decided by an internal service).

Error codes for this response (the code field of the response body):
  • document.not_in_booking_queue — The document is not waiting in the booking queue, for example because it is already booked.
Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/fiscal-yearskey / tokenList the fiscal years of the company with their status.
Returns the fiscal years of the caller's company as the KLARA fiscal-year screen shows them: name, first and last day, legal form and status in the year-end closing (OPEN, CLOSING, SEALED), plus the sealing date of a sealed year. Use it to find the fiscal year a date falls into before booking: createBookingV1 accepts an OPEN year, asks for confirmDontMindClosingFiscalYear in a CLOSING year and rejects a SEALED one. Opening balances are not part of the answer. search-key keeps the fiscal years whose name contains every word of the search text, case-insensitive. Uses the standard collection parameters: search-key, offset (default 0), limit (default 50, maximum 100), sort-field (only and default FISCAL_FROM) and sort-direction (default DESC, latest year first). The number of fiscal years matching the filters, ignoring offset and limit, is returned in the X-Total-Count header. This is a read-only, idempotent operation without side effects. Tenant and company are derived from the bearer token and are never accepted from the URL or the request. The caller must hold the ACCOUNTING permission on the company; otherwise the endpoint returns 403.
operationId

listFiscalYearsV1 — the method name a generated client uses.

Required permission

ACCOUNTING This comes from the description in the specification; the source code analysis behind the other permission statements is older than this endpoint. Roles that carry it: Administrator, External user, Buchhalter.

Parameters 6
NameDescription
limit
query integer
Page size. Defaults to 50; hard cap 100. Requests above the cap are rejected with 400.
min: 1 max: 100 default: 50 example: 50
offset
query integer
0-based pagination offset — the number of rows to skip before the returned page. Defaults to 0. Combine with limit to walk the full collection.
min: 0 default: 0 example: 0
search-key
query string
Free-text search. The fields searched are documented per endpoint. Matches are case-insensitive substring matches. Maximum length 256 characters.
maxLength: 256 example: müller
sort-direction
query string
Sort direction. Allowed values: ASC, DESC. Defaults to DESC.
Allowed values: ASC, DESC
default: DESC example: DESC
sort-field
query string
Field to order the result by. The accepted values are listed per endpoint; an unknown value is rejected with 400. Each endpoint documents the default it applies, chosen so that paging with offset / limit is stable.
status
query string
Keep only the fiscal years with this status, case-insensitive. Allowed values: OPEN, CLOSING, SEALED. All fiscal years when omitted.
Allowed values: OPEN, CLOSING, SEALED
example: OPEN
Responses 6
200 One page of fiscal years, ordered by first day in sort-direction (default DESC, latest first). Empty array when the company has no accounting set up or nothing matches the filters. show body

application/json array of PublicApiFiscalYear

Array of PublicApiFiscalYear.

  • id integer (int64) format: int64 example: 1
    Id of the fiscal year.
  • name string example: 2026
    Name of the fiscal year as shown in KLARA.
  • fiscalFrom string (date) format: date example: 2026-01-01
    First day of the fiscal year.
  • fiscalTo string (date) format: date example: 2026-12-31
    Last day of the fiscal year.
  • status string example: OPEN
    Status of the fiscal year. OPEN: bookings can be added. CLOSING: the year-end closing has started; createBookingV1 books into it only with confirmDontMindClosingFiscalYear=true. SEALED: the year is closed and takes no new bookings.
    Allowed values: OPEN, CLOSING, SEALED
  • legalForm string example: CORPORATION
    Legal form of the company in this fiscal year.
    Allowed values: LIMITED_LIABILITY, CORPORATION, OR, INDIVIDUALLY_OWNED_COMPANY, ASSOCIATION, SIMPLE_PARTNERSHIP, GENERAL_PARTNERSHIP, LIMITED_PARTNERSHIP, COOPERATIVE_COMPANY, FOUNDATION
  • firstFiscalYear boolean example: False
    True for the first fiscal year of the company.
  • sealingDate string (date) format: date nullable example: 2027-03-15
    Day the fiscal year was sealed; null unless status is SEALED.
400 sort-field is not FISCAL_FROM, or a parameter is outside its bounds (status not OPEN, CLOSING or SEALED, search-key longer than 256 characters, offset negative, limit outside 1-100, sort-direction not ASC or DESC).

Error codes for this response (the code field of the response body):
  • request.sort_field_invalid — sort-field was not one of the values the operation documents. The message lists the accepted values.
Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/kpis/income-expenseskey / tokenGet the company's income and expenses per month for a period.
Returns the operating revenue (chart group 30, credit positive) and the operating expenses (chart groups 40 material, 50 personnel and 60 other operating expense, debit positive) of the caller's company per calendar month for date-from to date-to, with the totals of the period, as the widget "Income and expenses" on the accounting dashboard shows them. Both dates are included; the period can be any range, it does not have to match a financial year (see listCurrentCompanyFinancialYears); bookings count by their booking date. Every calendar month touched by the period is listed in ascending order, also months without bookings (0.00); the first and last month cover only the days inside the period. A month is negative when the net amount is on the other side (for example more credit notes than invoices). include-delimitation=false leaves out delimitation bookings (accruals and deferrals). Depreciation (68), financial result (69), ancillary and non-operating result (70, 80, 85) and direct taxes (89) are not included; getProfitAndLossV1 returns the full result. The money spent and money earned breakdown of the dashboard is getSpendingsAndEarningsV1: for the same period and delimitation, totalIncome equals its earnings.amount and totalExpenses its spendings.amount (account 6000 is the only posting account of chart group 60 in KLARA's chart of accounts). This is a read-only, idempotent operation without side effects. Tenant and company are derived from the bearer token and are never accepted from the URL or the request. The caller must hold the ACCOUNTING permission on the company; otherwise the endpoint returns 403.
operationId

getIncomeExpensesV1 — the method name a generated client uses.

Required permission

ACCOUNTING This comes from the description in the specification; the source code analysis behind the other permission statements is older than this endpoint. Roles that carry it: Administrator, External user, Buchhalter.

Parameters 3
NameDescription
date-from required
query string (date)
First booking date of the period, inclusive, ISO yyyy-MM-dd.
format: date example: 2025-01-01
date-to required
query string (date)
Last booking date of the period, inclusive, ISO yyyy-MM-dd; not before date-from.
format: date example: 2025-12-31
include-delimitation
query boolean
false leaves out delimitation bookings (accruals and deferrals); included by default, as on the dashboard.
default: true example: True
Responses 6
200 Income and expenses per month of the period, with the totals. show body

application/json PublicApiIncomeExpenses

  • dateFrom string (date) format: date example: 2025-01-01
    First day of the period, as requested.
  • dateTo string (date) format: date example: 2025-12-31
    Last day of the period, as requested.
  • totalIncome number example: 214800
    Operating revenue of the period in CHF (chart group 30, credit positive).
  • totalExpenses number example: 187320.4
    Operating expenses of the period in CHF (chart groups 40, 50, 60, debit positive).
  • months array of PublicApiIncomeExpensesMonth
    Every calendar month touched by the period, ascending, also months without bookings (0.00).
    show fields

    Array of PublicApiIncomeExpensesMonth.

    • month string example: 2025-03
      Calendar month, yyyy-MM. The first and the last month of the period cover only the days inside the period.
    • income number example: 18250
      Operating revenue of the month in CHF: lines on accounts of chart group 30 by booking date, credit positive; negative when the net amount is on the debit side.
    • expenses number example: 14980.5
      Operating expenses of the month in CHF: lines on accounts of chart groups 40, 50 and 60 by booking date, debit positive; negative when the net amount is on the credit side.
400 date-from or date-to is missing or not an ISO date yyyy-MM-dd, or date-to is before date-from (code kpi.date_invalid).

Error codes for this response (the code field of the response body):
  • kpi.date_invalid — date-from or date-to was missing or not an ISO date of the form yyyy-MM-dd with a year from 0001, or date-to was before date-from; for getSpendingsAndEarningsV1 also when the comparison period was incomplete, not of that form or reversed, or the default comparison period would start before the year 0001.
Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/kpis/spendings-and-earningskey / tokenGet the company's spendings and earnings for a period, compared with a previous period.
Returns, for the caller's company and the period date-from to date-to, the spendings in three categories - MATERIAL (chart group 40), LABOR (chart group 50) and OTHER_OPERATING_EXPENSE (account 6000, the posting account of chart group 60) - and the earnings in the category REVENUE (chart group 30), as the widgets "Money spent" and "Money earned" on the accounting dashboard show them: each category with its accounts and, per account, the booking tags as a tree. Every row carries amount for the period, compareAmount for the comparison period and changePercent as the dashboard computes it (0 when both amounts are equal, -100 when amount is 0, +100 when compareAmount is 0, otherwise (amount - compareAmount) x 100 / |compareAmount|, two decimals); because of the two special cases it is not a true percentage when one side is 0, so compute your own from amount and compareAmount if you need one. Without compare-from and compare-to the comparison period has the same number of days as the period and ends the day before date-from, as on the dashboard; it is counted in days, not in calendar months: 2025-04-01 to 2025-06-30 compares with 2024-12-31 to 2025-03-31, and the year 2025 with 2024-01-02 to 2024-12-31 (2024 is a leap year). Send compare-from and compare-to for a calendar comparison such as the previous quarter or year. The response always contains the comparison period used. Bookings count by their booking date. Spendings are positive for expenses (debit), earnings for income (credit); spendings.amount is the sum of the three categories and equals totalExpenses of getIncomeExpensesV1 for the same period, earnings.amount equals its totalIncome. The categories are always present (0.00 without bookings; identify them by type, name is missing when a category has no bookings in either period); accounts and tags with 0.00 in both periods are left out; a row present in only one period has 0.00 in the other. Accounts are ordered by number, tags by name. Tags are listed per account (for OTHER_OPERATING_EXPENSE, which is one account, directly on the category); a tag chain such as Projekt,Phase 1 is nested tag under tag. A tag row without name holds the booking lines without a tag at that level (the dashboard's "not assigned" row). Names follow Accept-Language (de, fr, it, en; anything else gives German). The full profit and loss statement is getProfitAndLossV1, the monthly view getIncomeExpensesV1. This is a read-only, idempotent operation without side effects. Tenant and company are derived from the bearer token and are never accepted from the URL or the request. The caller must hold the ACCOUNTING permission on the company; otherwise the endpoint returns 403.
operationId

getSpendingsAndEarningsV1 — the method name a generated client uses.

Required permission

ACCOUNTING This comes from the description in the specification; the source code analysis behind the other permission statements is older than this endpoint. Roles that carry it: Administrator, External user, Buchhalter.

Parameters 6
NameDescription
date-from required
query string (date)
First booking date of the period, inclusive, ISO yyyy-MM-dd.
format: date example: 2025-04-01
date-to required
query string (date)
Last booking date of the period, inclusive, ISO yyyy-MM-dd; not before date-from.
format: date example: 2025-06-30
compare-from
query string (date)
First booking date of the comparison period, ISO yyyy-MM-dd; only together with compare-to. Without both, the previous period of the same length is used.
format: date example: 2025-01-01
compare-to
query string (date)
Last booking date of the comparison period, ISO yyyy-MM-dd; not before compare-from.
format: date example: 2025-03-31
include-delimitation
query boolean
false leaves out delimitation bookings (accruals and deferrals) in both periods; included by default, as on the dashboard.
default: true example: True
Accept-Language
header string
Language of the category and account names: de, fr, it or en; a region is ignored, so fr-CH gives French; other languages give German.
example: de-CH
Responses 6
200 Spendings and earnings for the period and the comparison period. show body

application/json PublicApiSpendingsAndEarnings

  • dateFrom string (date) format: date example: 2025-04-01
    First day of the period, as requested.
  • dateTo string (date) format: date example: 2025-06-30
    Last day of the period, as requested.
  • compareFrom string (date) format: date example: 2024-12-31
    First day of the comparison period: as requested, or computed as the dashboard does (the same number of days as the period, ending the day before dateFrom).
  • compareTo string (date) format: date example: 2025-03-31
    Last day of the comparison period: as requested, or the day before dateFrom.
  • spendings object
    Spendings or earnings with their total in both periods.
    show fields
    • amount number example: 84250
      Total in CHF for the period: for spendings the sum of the three categories, for earnings the revenue.
    • compareAmount number example: 79100
      Total in CHF for the comparison period.
    • changePercent number example: 6.51
      Change against the comparison period in percent, as the accounting dashboard shows it: 0 when both amounts are equal, -100 when amount is 0, +100 when compareAmount is 0, otherwise (amount - compareAmount) x 100 / |compareAmount|, two decimals.
    • categories array of PublicApiCashflowCategory
      The categories in a fixed order: MATERIAL, LABOR, OTHER_OPERATING_EXPENSE for spendings; REVENUE for earnings; always present, 0.00 without bookings.
      show fields

      Array of PublicApiCashflowCategory.

      • type object example: MATERIAL
        MATERIAL = chart group 40, LABOR = chart group 50, OTHER_OPERATING_EXPENSE = account 6000, REVENUE = chart group 30.
      • code string example: 40
        Chart group code (40, 50, 30) or account number (6000).
      • name string example: Material- und Warenaufwand
        Name as KLARA shows it, in the language of Accept-Language; missing when the category has no bookings in either period, so identify categories by type.
      • amount number example: 35600
        Amount in CHF for the period: spendings debit positive, earnings credit positive; a net amount on the other side is negative.
      • compareAmount number example: 31200
        Amount in CHF for the comparison period.
      • changePercent number example: 14.1
        Change against the comparison period in percent, as the accounting dashboard shows it: 0 when both amounts are equal, -100 when amount is 0, +100 when compareAmount is 0, otherwise (amount - compareAmount) x 100 / |compareAmount|, two decimals.
      • accounts array of PublicApiCashflowAccount
        Accounts of the chart group with bookings in one of the periods, ordered by number; missing for OTHER_OPERATING_EXPENSE.
        show fields

        Array of PublicApiCashflowAccount.

        • code string example: 4000
          Account number, as in listAccountsV1.
        • name string example: Materialaufwand
          Account name as KLARA shows it, without the number.
        • amount number example: 35600
          Amount in CHF for the period, with the sign of the category.
        • compareAmount number example: 31200
          Amount in CHF for the comparison period, with the sign of the category.
        • changePercent number example: 14.1
          Change against the comparison period in percent, as the accounting dashboard shows it: 0 when both amounts are equal, -100 when amount is 0, +100 when compareAmount is 0, otherwise (amount - compareAmount) x 100 / |compareAmount|, two decimals.
        • details array of PublicApiCashflowDetail
          Booking tags of the account as a tree, ordered by name; missing when the account has no tagged lines.
          show fields

          Array of PublicApiCashflowDetail.

          • name string example: Projekt Alpha
            Booking tag as KLARA shows it. Missing for the booking lines without a tag at this level (the dashboard row "not assigned").
          • amount number example: 4200
            Amount in CHF for the period, with the sign of the category.
          • compareAmount number example: 3900
            Amount in CHF for the comparison period, with the sign of the category.
          • changePercent number example: 7.69
            Change against the comparison period in percent, as the accounting dashboard shows it: 0 when both amounts are equal, -100 when amount is 0, +100 when compareAmount is 0, otherwise (amount - compareAmount) x 100 / |compareAmount|, two decimals.
          • details array of PublicApiCashflowDetail
            The next level of tags below this row, ordered by name; missing on the last level.
            show fields

            Array of PublicApiCashflowDetail.

            Recursive reference to PublicApiCashflowDetail. The structure repeats from here.

      • details array of PublicApiCashflowDetail
        Booking tags of account 6000 as a tree; only for OTHER_OPERATING_EXPENSE.
        show fields

        Array of PublicApiCashflowDetail.

        • name string example: Projekt Alpha
          Booking tag as KLARA shows it. Missing for the booking lines without a tag at this level (the dashboard row "not assigned").
        • amount number example: 4200
          Amount in CHF for the period, with the sign of the category.
        • compareAmount number example: 3900
          Amount in CHF for the comparison period, with the sign of the category.
        • changePercent number example: 7.69
          Change against the comparison period in percent, as the accounting dashboard shows it: 0 when both amounts are equal, -100 when amount is 0, +100 when compareAmount is 0, otherwise (amount - compareAmount) x 100 / |compareAmount|, two decimals.
        • details array of PublicApiCashflowDetail
          The next level of tags below this row, ordered by name; missing on the last level.
          show fields

          Array of PublicApiCashflowDetail.

          Recursive reference to PublicApiCashflowDetail. The structure repeats from here.

  • earnings object
    Spendings or earnings with their total in both periods.
    show fields
    • amount number example: 84250
      Total in CHF for the period: for spendings the sum of the three categories, for earnings the revenue.
    • compareAmount number example: 79100
      Total in CHF for the comparison period.
    • changePercent number example: 6.51
      Change against the comparison period in percent, as the accounting dashboard shows it: 0 when both amounts are equal, -100 when amount is 0, +100 when compareAmount is 0, otherwise (amount - compareAmount) x 100 / |compareAmount|, two decimals.
    • categories array of PublicApiCashflowCategory
      The categories in a fixed order: MATERIAL, LABOR, OTHER_OPERATING_EXPENSE for spendings; REVENUE for earnings; always present, 0.00 without bookings.
      show fields

      Array of PublicApiCashflowCategory.

      • type object example: MATERIAL
        MATERIAL = chart group 40, LABOR = chart group 50, OTHER_OPERATING_EXPENSE = account 6000, REVENUE = chart group 30.
      • code string example: 40
        Chart group code (40, 50, 30) or account number (6000).
      • name string example: Material- und Warenaufwand
        Name as KLARA shows it, in the language of Accept-Language; missing when the category has no bookings in either period, so identify categories by type.
      • amount number example: 35600
        Amount in CHF for the period: spendings debit positive, earnings credit positive; a net amount on the other side is negative.
      • compareAmount number example: 31200
        Amount in CHF for the comparison period.
      • changePercent number example: 14.1
        Change against the comparison period in percent, as the accounting dashboard shows it: 0 when both amounts are equal, -100 when amount is 0, +100 when compareAmount is 0, otherwise (amount - compareAmount) x 100 / |compareAmount|, two decimals.
      • accounts array of PublicApiCashflowAccount
        Accounts of the chart group with bookings in one of the periods, ordered by number; missing for OTHER_OPERATING_EXPENSE.
        show fields

        Array of PublicApiCashflowAccount.

        • code string example: 4000
          Account number, as in listAccountsV1.
        • name string example: Materialaufwand
          Account name as KLARA shows it, without the number.
        • amount number example: 35600
          Amount in CHF for the period, with the sign of the category.
        • compareAmount number example: 31200
          Amount in CHF for the comparison period, with the sign of the category.
        • changePercent number example: 14.1
          Change against the comparison period in percent, as the accounting dashboard shows it: 0 when both amounts are equal, -100 when amount is 0, +100 when compareAmount is 0, otherwise (amount - compareAmount) x 100 / |compareAmount|, two decimals.
        • details array of PublicApiCashflowDetail
          Booking tags of the account as a tree, ordered by name; missing when the account has no tagged lines.
          show fields

          Array of PublicApiCashflowDetail.

          • name string example: Projekt Alpha
            Booking tag as KLARA shows it. Missing for the booking lines without a tag at this level (the dashboard row "not assigned").
          • amount number example: 4200
            Amount in CHF for the period, with the sign of the category.
          • compareAmount number example: 3900
            Amount in CHF for the comparison period, with the sign of the category.
          • changePercent number example: 7.69
            Change against the comparison period in percent, as the accounting dashboard shows it: 0 when both amounts are equal, -100 when amount is 0, +100 when compareAmount is 0, otherwise (amount - compareAmount) x 100 / |compareAmount|, two decimals.
          • details array of PublicApiCashflowDetail
            The next level of tags below this row, ordered by name; missing on the last level.
            show fields

            Array of PublicApiCashflowDetail.

            Recursive reference to PublicApiCashflowDetail. The structure repeats from here.

      • details array of PublicApiCashflowDetail
        Booking tags of account 6000 as a tree; only for OTHER_OPERATING_EXPENSE.
        show fields

        Array of PublicApiCashflowDetail.

        • name string example: Projekt Alpha
          Booking tag as KLARA shows it. Missing for the booking lines without a tag at this level (the dashboard row "not assigned").
        • amount number example: 4200
          Amount in CHF for the period, with the sign of the category.
        • compareAmount number example: 3900
          Amount in CHF for the comparison period, with the sign of the category.
        • changePercent number example: 7.69
          Change against the comparison period in percent, as the accounting dashboard shows it: 0 when both amounts are equal, -100 when amount is 0, +100 when compareAmount is 0, otherwise (amount - compareAmount) x 100 / |compareAmount|, two decimals.
        • details array of PublicApiCashflowDetail
          The next level of tags below this row, ordered by name; missing on the last level.
          show fields

          Array of PublicApiCashflowDetail.

          Recursive reference to PublicApiCashflowDetail. The structure repeats from here.

400 date-from or date-to is missing or not an ISO date yyyy-MM-dd, or date-to is before date-from (code kpi.date_invalid). Also when the comparison period is incomplete, not ISO dates or reversed.

Error codes for this response (the code field of the response body):
  • kpi.date_invalid — date-from or date-to was missing or not an ISO date of the form yyyy-MM-dd with a year from 0001, or date-to was before date-from; for getSpendingsAndEarningsV1 also when the comparison period was incomplete, not of that form or reversed, or the default comparison period would start before the year 0001.
Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/master-vatskey / tokenList the master VAT catalog used by KLARA Accounting.
Returns the global master VAT catalog — the table of supported VAT rates with their validity ranges and translated labels. The downstream handler is a dispatcher driven by the query string: when code is non-blank only rows whose vatCode matches one of the semicolon-separated codes are returned (and when combined with current-period=true, only the ones valid today); otherwise when default-vat=true only the company-default rows are returned; otherwise the full catalog is returned, ordered by rate ascending, optionally paginated via offset / limit. Pagination is honoured only on the full-catalog branch — it is silently ignored when code or default-vat is set. The endpoint is a pure read and idempotent. Requires a bearer token whose principal carries the ACCOUNTING_GET_MASTER_VAT permission.
operationId

listMasterVatsV1 — the method name a generated client uses.

Required permission

ACCOUNTING_GET_MASTER_VAT
Available through: Administrator, External user, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen

Parameters 6
NameDescription
code
query string
Semicolon-separated list of vatCodes to filter on. When set, switches the response to the by-code branch and ignores default-vat.
example: 1;3;4
current-period
query boolean
When combined with code, restricts the result to master VAT rows whose validity range covers today. Defaults to false.
default: false example: False
default-vat
query boolean
When true, restricts the result to the company-default master VAT rows. Defaults to false. Ignored when code is set.
default: false example: False
includeHiddenVatCase
query boolean
When true, the response also includes hidden VAT-case ids that are not directly mapped to a master VAT row. Defaults to false.
default: false example: False
limit
query integer
Maximum number of results to return. Only honoured on the full-catalog branch.
example: 50
offset
query integer
Zero-based index of the first result. Only honoured on the full-catalog branch (when neither code nor default-vat is set).
example: 0
Responses 4
200 Array of master VAT rows matching the filters. show body

application/json array of PublicApiMasterVat

Array of PublicApiMasterVat.

  • id integer (int64) format: int64 example: 12
    Internal id of the master VAT row.
  • vatCode string example: 1
    Short numeric VAT code as configured in the KLARA accounting plan.
  • rate number example: 8.1
    VAT rate as a percentage value (8.10 means 8.10 %).
  • validFrom string (date) format: date example: 2024-01-01
    Inclusive start date of the validity range (ISO yyyy-MM-dd). May be null when open-ended.
  • validTo string (date) format: date example: 2030-12-31
    Inclusive end date of the validity range (ISO yyyy-MM-dd). May be null when open-ended.
  • defaultVat boolean example: True
    True when the row is one of the company-default VAT entries.
  • masterVatMulties array of PublicApiMasterVatMulti
    Localized labels keyed by language tag.
    show fields

    Array of PublicApiMasterVatMulti.

    • id integer (int64) format: int64 example: 101
      Internal id of the translation row.
    • language string example: de
      Language tag of the translation (ISO 639-1).
    • description string example: Normalsatz 8.1 %
      Human-readable VAT description in the matching language.
  • referenceVatCaseId string example: VC-7
    Optional reference to a hidden VAT case id not directly mapped to a master VAT.
  • createDate string (date-time) format: date-time example: 2024-01-01T08:00:00
    Timestamp when the row was created (ISO yyyy-MM-dd'T'HH:mm:ss).
  • updateDate string (date-time) format: date-time example: 2024-06-15T14:30:00
    Timestamp of the last update (ISO yyyy-MM-dd'T'HH:mm:ss).
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/master-vats/currentkey / tokenList the master VAT rows valid for today.
Returns the subset of the master VAT catalog whose validity range (validFrom / validTo) covers the server's current day. Useful for booking and invoicing UIs that need only the VAT rates that may legally be applied right now. The endpoint is a pure read and idempotent; the downstream handler caches the filtered list in-process. Requires a bearer token whose principal carries the ACCOUNTING_GET_MASTER_VAT permission.
operationId

getCurrentMasterVatsV1 — the method name a generated client uses.

Required permission

ACCOUNTING_GET_MASTER_VAT
Available through: Administrator, External user, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen

Responses 4
200 Array of master VAT rows valid for the current day. show body

application/json array of PublicApiMasterVat

Array of PublicApiMasterVat.

  • id integer (int64) format: int64 example: 12
    Internal id of the master VAT row.
  • vatCode string example: 1
    Short numeric VAT code as configured in the KLARA accounting plan.
  • rate number example: 8.1
    VAT rate as a percentage value (8.10 means 8.10 %).
  • validFrom string (date) format: date example: 2024-01-01
    Inclusive start date of the validity range (ISO yyyy-MM-dd). May be null when open-ended.
  • validTo string (date) format: date example: 2030-12-31
    Inclusive end date of the validity range (ISO yyyy-MM-dd). May be null when open-ended.
  • defaultVat boolean example: True
    True when the row is one of the company-default VAT entries.
  • masterVatMulties array of PublicApiMasterVatMulti
    Localized labels keyed by language tag.
    show fields

    Array of PublicApiMasterVatMulti.

    • id integer (int64) format: int64 example: 101
      Internal id of the translation row.
    • language string example: de
      Language tag of the translation (ISO 639-1).
    • description string example: Normalsatz 8.1 %
      Human-readable VAT description in the matching language.
  • referenceVatCaseId string example: VC-7
    Optional reference to a hidden VAT case id not directly mapped to a master VAT.
  • createDate string (date-time) format: date-time example: 2024-01-01T08:00:00
    Timestamp when the row was created (ISO yyyy-MM-dd'T'HH:mm:ss).
  • updateDate string (date-time) format: date-time example: 2024-06-15T14:30:00
    Timestamp of the last update (ISO yyyy-MM-dd'T'HH:mm:ss).
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/master-vats/{masterVatId}key / tokenResolve a master VAT catalog row by its numeric id.
Loads a single master VAT row from KLARA's global master VAT catalog, identified by its numeric primary-key masterVatId. The catalog is global KLARA reference data — the same row is returned for every tenant, so there are no tenant or company path parameters. The endpoint is a pure read and idempotent. Requires a bearer token whose principal carries the ACCOUNTING_GET_MASTER_VAT permission.
operationId

getMasterVatByIdV1 — the method name a generated client uses.

Required permission

ACCOUNTING_GET_MASTER_VAT
Available through: Administrator, External user, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen

Parameters 1
NameDescription
masterVatId required
path integer (int64)
Numeric primary-key id of the master VAT row to resolve. Obtain it from GET /core/v1/accounting/master-vats or GET /core/v1/accounting/master-vats/current.
format: int64 example: 12
Responses 5
200 The master VAT row matching masterVatId, including its rate, VAT code and validity range. show body

application/json PublicApiMasterVat

  • id integer (int64) format: int64 example: 12
    Internal id of the master VAT row.
  • vatCode string example: 1
    Short numeric VAT code as configured in the KLARA accounting plan.
  • rate number example: 8.1
    VAT rate as a percentage value (8.10 means 8.10 %).
  • validFrom string (date) format: date example: 2024-01-01
    Inclusive start date of the validity range (ISO yyyy-MM-dd). May be null when open-ended.
  • validTo string (date) format: date example: 2030-12-31
    Inclusive end date of the validity range (ISO yyyy-MM-dd). May be null when open-ended.
  • defaultVat boolean example: True
    True when the row is one of the company-default VAT entries.
  • masterVatMulties array of PublicApiMasterVatMulti
    Localized labels keyed by language tag.
    show fields

    Array of PublicApiMasterVatMulti.

    • id integer (int64) format: int64 example: 101
      Internal id of the translation row.
    • language string example: de
      Language tag of the translation (ISO 639-1).
    • description string example: Normalsatz 8.1 %
      Human-readable VAT description in the matching language.
  • referenceVatCaseId string example: VC-7
    Optional reference to a hidden VAT case id not directly mapped to a master VAT.
  • createDate string (date-time) format: date-time example: 2024-01-01T08:00:00
    Timestamp when the row was created (ISO yyyy-MM-dd'T'HH:mm:ss).
  • updateDate string (date-time) format: date-time example: 2024-06-15T14:30:00
    Timestamp of the last update (ISO yyyy-MM-dd'T'HH:mm:ss).
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 No master VAT row exists for the supplied masterVatId.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/reports/balance-sheetkey / tokenGet the balance sheet at a date, optionally with a comparison date.
Returns the balance sheet of the caller's company at date, as KLARA shows it under Accounting > Reports > Balance sheet: the totals current assets, fixed assets, total assets, current liabilities, long-term liabilities, equity and total liabilities; inside them the chart-of-account groups (for example 100 liquid assets) and the accounts with a booking up to the date; and for accounts with sub-accounts one row per sub-account (bank account, cash box, customer or supplier, employee, insurer, asset), with the same typed reference as getBookingV1. With compare-date every row also carries compareAmount, the balance at that date, as in KLARA's two columns; a row present at only one date has 0 at the other. Balances include every booking up to and including the date; include-delimitation=false leaves out delimitation bookings, at both dates. A date in the future gives the balances after all bookings up to it; impossible dates such as 2026-02-31 are rejected. The row "annual profit/loss" in equity (profitOrLoss) is computed by KLARA as total assets minus all liability and equity accounts, negative for a loss, and is part of the EQUITY amount, so TOTAL_ASSETS always equals TOTAL_LIABILITIES (which includes equity). Rows are ordered as on the screen: chart groups in the order of the chart of accounts, accounts by number, sub-accounts by name. Amounts are in CHF and positive on the normal side of the account; an account whose sub-accounts have both signs can appear in two chart groups. account-search and sub-account-search work like the search and tag filter of the screen: they compare with the names in the language of Accept-Language, can be combined (both must match), and only hide rows, every amount and total stays the same. Sub-account names can contain names of persons (employees, private customers), as on the screen. Group and account names follow Accept-Language (de, fr, it, en; anything else gives German). This is a read-only, idempotent operation without side effects. Tenant and company are derived from the bearer token and are never accepted from the URL or the request. The caller must hold the ACCOUNTING permission on the company; otherwise the endpoint returns 403.
operationId

getBalanceSheetV1 — the method name a generated client uses.

Required permission

ACCOUNTING This comes from the description in the specification; the source code analysis behind the other permission statements is older than this endpoint. Roles that carry it: Administrator, External user, Buchhalter.

Parameters 6
NameDescription
date required
query string (date)
Reference date, ISO yyyy-MM-dd: balances after all bookings up to and including this date.
format: date example: 2025-12-31
account-search
query string
Keeps only accounts whose number or name contains this text (case-insensitive), with their groups. Hides rows only; amounts and totals stay the same.
maxLength: 256 example: Bank
compare-date
query string (date)
Second reference date shown side by side (compareAmount), ISO yyyy-MM-dd; before or after date.
format: date example: 2024-12-31
include-delimitation
query boolean
false leaves out delimitation bookings; included by default, as on the screen.
default: true example: True
sub-account-search
query string
Comma-separated texts; keeps only sub-account rows whose name contains any of them (case-insensitive), with their accounts and groups. This is the tag filter of the screen, which matches sub-account names, not booking tags. Hides rows only; amounts and totals stay the same.
maxLength: 256 example: UBS,PostFinance
Accept-Language
header string
Language of the group and account names: de, fr, it or en; a region is ignored, so fr-CH gives French; other languages give German.
example: de-CH
Responses 6
200 The balance sheet at date (and compare-date). show body

application/json PublicApiBalanceSheet

  • date string (date) format: date example: 2025-12-31
    Reference date: balances after all bookings up to and including this date.
  • compareDate string (date) format: date example: 2024-12-31
    Comparison date as requested; missing without compare-date.
  • groups array of PublicApiBalanceSheetGroup
    The balance sheet totals in this fixed order: CURRENT_ASSETS, FIXED_ASSETS, TOTAL_ASSETS, CURRENT_LIABILITIES, LONG_TERM_LIABILITIES, EQUITY, TOTAL_LIABILITIES. With a display filter, totals without remaining rows are left out, as on the screen.
    show fields

    Array of PublicApiBalanceSheetGroup.

    • type object example: CURRENT_ASSETS
      Balance sheet total.
    • name string example: Total current assets
      Name of the total as KLARA shows it, in the language of Accept-Language.
    • amount number example: 184250.4
      Amount in CHF at date.
    • compareAmount number example: 172030.15
      Amount in CHF at compareDate; missing without compare-date.
    • chartGroups array of PublicApiBalanceSheetChartGroup
      Chart-of-account groups of this total, in the order of the chart of accounts. Missing for TOTAL_ASSETS and TOTAL_LIABILITIES, which are sums of other totals.
      show fields

      Array of PublicApiBalanceSheetChartGroup.

      • code string example: 100
        Chart-of-account group code, for example 100 for liquid assets; missing on the annual profit/loss row.
      • name string example: Flüssige Mittel
        Name of the group as KLARA shows it, for the company's legal form and the language of Accept-Language.
      • amount number example: 45210.7
        Amount in CHF at date.
      • compareAmount number example: 38900
        Amount in CHF at compareDate; missing without compare-date.
      • profitOrLoss boolean example: False
        True only on the row "annual profit/loss" that KLARA inserts into EQUITY after group 297 (first when there is no group 297): total assets minus all liability and equity accounts. It is the result of the current fiscal year when the results of earlier years were booked to equity, and otherwise also contains those earlier results. Negative for a loss. Its amount is part of the EQUITY amount, so TOTAL_ASSETS and TOTAL_LIABILITIES always match.
      • accounts array of PublicApiBalanceSheetAccount
        Accounts of the group with a booking up to the date (also with a balance of 0), ordered by account number.
        show fields

        Array of PublicApiBalanceSheetAccount.

        • code string example: 1020
          Account number, as in listAccountsV1.
        • name string example: Bankguthaben
          Account name as KLARA shows it, without the number.
        • amount number example: 45210.7
          Balance in CHF at date, positive on the normal side of the account. An account whose sub-accounts have both signs can appear in two chart groups, for example bank accounts in credit under liquid assets and in overdraft under current liabilities, each as a positive amount.
        • compareAmount number example: 38900
          Balance in CHF at compareDate; missing without compare-date.
        • subAccounts array of PublicApiBalanceSheetSubAccount
          One row per sub-account (bank account, cash box, customer or supplier, employee, insurer, asset), ordered by name; missing for accounts without sub-accounts.
          show fields

          Array of PublicApiBalanceSheetSubAccount.

          • name string example: UBS Geschäftskonto
            Name as KLARA shows it: bank account short name, customer or supplier name, employee name, insurer, asset. Can contain names of persons (employees, private customers), as on the screen. Missing when KLARA cannot resolve a name for the object (for example a deleted customer); reference still identifies it.
          • reference object
            An object a booking line refers to.
            show fields
            • type object example: CUSTOMER
              Kind of object a booking line refers to.
            • id string example: 1042
              Id of the object. Customers and suppliers (one id space): as in listCustomersV1; company bank accounts: as in listCompanyBankAccounts; bank transactions: as in listBankTransactionsV1 (unreconciled only); VAT cases: as in the VAT case list; tax-at-source cantons: KLARA's canton id; gift cards and miscellaneous partners: KLARA's fixed entry; a sub-account: the id of the sub-account of the chart of accounts; other types: KLARA's internal id.
            • category string example: cash
              Only for SUB_ACCOUNT: the kind of sub-account, for example cash, receivable, payable or tangible_asset.
            • name string example: Muster AG
              Name of the object as KLARA shows it on the line now (resolved when the booking is read, not stored at posting time), in the requested language. Missing when it could not be resolved.
          • amount number example: 45210.7
            Balance in CHF at date, positive on the normal side of the account, like the account itself.
          • compareAmount number example: 38900
            Balance in CHF at compareDate; missing without compare-date.
          • subAccounts array of PublicApiBalanceSheetSubAccount
            Only account 2260 (non-interest-bearing current accounts): one grouping row per kind (employees, current accounts) with the individual rows below, ordered by name.
            show fields

            Array of PublicApiBalanceSheetSubAccount.

            Recursive reference to PublicApiBalanceSheetSubAccount. The structure repeats from here.

400 date is missing or not an ISO date, compare-date is not an ISO date, or a search text is longer than 256 characters.

Error codes for this response (the code field of the response body):
  • balancesheet.date_invalid — date was missing or not an ISO date of the form yyyy-MM-dd, or compare-date was not an ISO date of that form.
Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/reports/general-ledgerkey / tokenGet the general ledger: the statements of all accounts for a period, page by page.
Returns the general ledger of the caller's company: for every account of the company's chart of accounts (the chart of its legal form), and separately for each sub-account where KLARA splits an account (for example per bank account, cash register or employee), the opening balance before date-from, the booking lines of the period with booking date, booking id and line id (readable with getBookingV1), contra accounts, posting text, tags, VAT text, debit or credit amount in CHF and the running balance, and the closing balance with the debit and credit totals. This is the data of the export "all accounts" under Accounting > Reports > Account details; each section has the same content as getAccountStatementV1 for that account. A split account has no section of its own, only one section per sub-account, so the sections of one account number do not have to be added to a whole-account section. Accounts without bookings in the period are included with their balances. As in getAccountStatementV1, every booking status is included (planned and inactive bookings too); there is no status filter. Sections are ordered by account number, then sub-account name; the order is fixed, so leave out sort-field, sort-direction and search-key (only ACCOUNT_CODE and ASC are accepted, a search-key is rejected). Paging uses offset and limit counted in sections (default 50, maximum 100); X-Total-Count holds the number of sections. Each section contains all its lines of the period; for an account with very many lines use getAccountStatementV1, which pages the lines, or narrow the page with a smaller limit or an account range. Filters, all optional and combined with AND: date-from and date-to (inclusive, yyyy-MM-dd); account-from and account-to (account number range, inclusive); reference, tags, include-delimitation (default true), booking-types and vat exactly as in getAccountStatementV1; line filters apply to the lines and to the opening balances, they do not remove sections. With reference, tags, booking-types or vat, the opening and closing balances are those of the matching lines only, not the balance of the account. For P&L accounts the balances restart at 0 in each fiscal year, as in getAccountStatementV1. Every page contains all its sections; when KLARA cannot calculate a section, the request fails with 500 and nothing is returned partially. This is a read-only, idempotent operation without side effects. Tenant and company are derived from the bearer token and are never accepted from the URL or the request. The caller must hold the ACCOUNTING permission on the company; otherwise the endpoint returns 403.
operationId

getGeneralLedgerV1 — the method name a generated client uses.

Required permission

ACCOUNTING This comes from the description in the specification; the source code analysis behind the other permission statements is older than this endpoint. Roles that carry it: Administrator, External user, Buchhalter.

Parameters 15
NameDescription
account-from
query integer (int32)
First account number of the range, inclusive.
format: int32 min: 1 example: 1000
account-to
query integer (int32)
Last account number of the range, inclusive; not below account-from.
format: int32 min: 1 example: 1999
booking-types
query string
Comma-separated booking types as bookingType of getBookingV1, any of them, as in getAccountStatementV1.
maxLength: 256 example: AR_INVOICE,AP_INVOICE
date-from
query string (date)
First booking date, inclusive, ISO yyyy-MM-dd. Without it every section starts with the first booking and an opening balance of 0.
format: date example: 2026-01-01
date-to
query string (date)
Last booking date, inclusive, ISO yyyy-MM-dd; not before date-from. Open-ended without it.
format: date example: 2026-12-31
include-delimitation
query boolean
false leaves out the delimitation lines (booking type DELIMIT); included by default, as in the export.
default: true example: True
limit
query integer
Page size. Defaults to 50; hard cap 100. Requests above the cap are rejected with 400.
min: 1 max: 100 default: 50 example: 50
offset
query integer
0-based pagination offset — the number of rows to skip before the returned page. Defaults to 0. Combine with limit to walk the full collection.
min: 0 default: 0 example: 0
reference
query string
Only lines that refer to this object, written as in references of getBookingV1 (TYPE:id or SUB_ACCOUNT:category:id), as in getAccountStatementV1; opening balances are filtered the same way.
maxLength: 128 example: CUSTOMER:1042
search-key
query string
Free-text search. The fields searched are documented per endpoint. Matches are case-insensitive substring matches. Maximum length 256 characters.
maxLength: 256 example: müller
sort-direction
query string
Sort direction. Allowed values: ASC, DESC. Defaults to DESC.
Allowed values: ASC, DESC
default: DESC example: DESC
sort-field
query string
Field to order the result by. The accepted values are listed per endpoint; an unknown value is rejected with 400. Each endpoint documents the default it applies, chosen so that paging with offset / limit is stable.
tags
query string
Comma-separated tag names; a line is kept when one of its tags equals any of them (case-sensitive; tags combined on one line are compared one by one; % and _ act as wildcards), as in getAccountStatementV1.
maxLength: 256 example: Zurich,Marketing
vat
query string
Comma-separated VAT filters, any of them, as in getAccountStatementV1: a VAT case id (listVatCases), caseId:rateId where the rate id is the id of listMasterVatsV1 (not its vatCode), or none for lines without VAT. There is no filter by rate alone.
maxLength: 256 example: 7:12,none
Accept-Language
header string
Language of the account names, VAT texts and sub-account names, and of the sub-account sort order, for example de-CH or fr-CH; the sort order uses the first language of the header and German without one. Posting texts and tags are not translated. Because the sort order follows the language, keep the same language for all pages of one ledger.
example: de-CH
Responses 6
200 The account sections of this page for the period. show body

application/json PublicApiGeneralLedger

  • dateFrom string (date) format: date example: 2026-01-01
    First booking date of the period as requested; missing when the ledger starts with the first booking.
  • dateTo string (date) format: date example: 2026-12-31
    Last booking date of the period as requested; missing when the period is open-ended.
  • accounts array of PublicApiGeneralLedgerAccount
    The account sections of this page, ordered by account number, then sub-account name. Empty when the page is beyond the last section.
    show fields

    Array of PublicApiGeneralLedgerAccount.

    • accountCode integer (int32) format: int32 example: 1020
      Account number, as code in listAccountsV1.
    • accountName string example: Bank
      Account name in the language of Accept-Language.
    • reference string example: BANK_ACCOUNT:3
      The sub-account of this section, written as in references of getBookingV1, for example BANK_ACCOUNT:3, EMPLOYEE:17 or SUB_ACCOUNT:cash:400; usable as reference of getAccountStatementV1. Missing when the section is the whole account, or when the sub-account is not one KLARA publishes as a reference.
    • referenceDisplay string example: Bankkonto - UBS Geschäftskonto
      Name of the sub-account as KLARA shows it; can be the name of a person (employee, private customer), as in the export. Missing when the section is the whole account.
    • openingBalance number example: 12500
      Balance in CHF before dateFrom, with the same filters, as openingBalance of getAccountStatementV1.
    • closingBalance object
      Totals of the whole period (all pages) and the balance at its end.
      show fields
      • debitAmount number example: 48200
        Sum in CHF of the debit amounts of all matching lines of the period.
      • creditAmount number example: 39150.5
        Sum in CHF of the credit amounts of all matching lines of the period.
      • balance number example: 21549.5
        Balance in CHF at the end of the period. Balance sheet accounts: opening balance plus all lines, equal to the running balance of the last line. P&L accounts restart at 0 in each fiscal year, so this is the balance of the fiscal year that contains the end of the period (dateTo, or the latest fiscal year when the period is open-ended); it equals the running balance of the last line when that line lies in that fiscal year, and is 0 when that fiscal year has no lines yet.
    • lines array of PublicApiAccountStatementLine
      All matching booking lines of the section in the period, ordered by booking date, booking id and line id, ascending, with the running balance. Empty when the account has no movement.
      show fields

      Array of PublicApiAccountStatementLine.

      • bookingDate string (date) format: date example: 2026-03-31
        Booking date.
      • bookingId integer (int64) format: int64 example: 4321
        Id of the booking; read the whole booking with getBookingV1.
      • lineId integer (int64) format: int64 example: 8765
        Id of this line within the booking, as lines[].id of getBookingV1.
      • contraAccountCodes array of integer (int32)
        Accounts of the other lines of the booking, ascending. The amount of this line is not split among them; getBookingV1 shows the amount of each line.
      • description string example: Rent March 2026
        Posting text of the line.
      • tags array of string
        Tags of the line.
      • vatText string example: 8.1%
        VAT of the line as KLARA shows it, in the language of Accept-Language.
      • debitAmount number example: 1000
        Amount in CHF when the line is a debit; missing otherwise.
      • creditAmount number example: 250
        Amount in CHF when the line is a credit; missing otherwise.
      • runningBalance number example: 13500
        Balance in CHF after this line, continued across pages. Positive for the normal side of the account; P&L accounts restart at 0 with the first line of each fiscal year.
      • documentIds array of string
        Ids of the documents attached to the booking.
400 A filter is malformed (date-from, date-to, reference, booking-types, vat: codes statement.*), account-to is below account-from (code ledger.account_range_invalid), a sort other than ACCOUNT_CODE ascending or a search-key was sent (codes request.*), or a bound or length is exceeded (code model.invalid).

Error codes for this response (the code field of the response body):
  • request.sort_field_invalid — sort-field was not one of the values the operation documents. The message lists the accepted values.
  • request.sort_direction_unsupported — sort-direction was sent with the direction an operation with a fixed order does not have. The message names the available direction.
  • request.search_key_unsupported — search-key was sent to an operation that has no text search.
  • statement.date_invalid — date-from or date-to was not an ISO date of the form yyyy-MM-dd, or date-to was before date-from.
  • statement.reference_invalid — reference was not of the form TYPE:id or SUB_ACCOUNT:category:id with a type, category and id as published in references of getBookingV1.
  • statement.booking_type_invalid — An entry of booking-types was not one of the published booking types.
  • statement.vat_filter_invalid — An entry of vat was not none, a VAT case id, or a VAT case id and a VAT rate id separated by a colon.
  • ledger.account_range_invalid — account-to was below account-from.
Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/reports/partner-amountskey / tokenGet the open amounts and monthly payments of a customer or supplier, or of all partners.
Returns the figures of the open amount and payment charts of the customer view in KLARA. openAmounts: per side the still open amount of the open and partly paid invoices, partial payments deducted, and the part of it that is overdue today; RECEIVABLE is what customers owe, PAYABLE what is owed to suppliers. monthlyPayments: per calendar month and side the sum of the payments booked, from the first day of the month eight months before to-date to the end of the month of to-date (nine months, stated in paymentsFrom and paymentsTo). With customer-id the figures of that customer or supplier (the id of listCustomersV1; customers and suppliers share one id space); without it the figures of all partners of the company. An unknown id gives empty lists. Amounts are in CHF. Open amounts are always as of today; to-date only moves the payment period. This is a read-only, idempotent operation without side effects. Tenant and company are derived from the bearer token and are never accepted from the URL or the request. The caller must hold the ACCOUNTING permission on the company; otherwise the endpoint returns 403.
operationId

getPartnerAmountsV1 — the method name a generated client uses.

Required permission

ACCOUNTING This comes from the description in the specification; the source code analysis behind the other permission statements is older than this endpoint. Roles that carry it: Administrator, External user, Buchhalter.

Parameters 2
NameDescription
customer-id
query integer (int64)
Id of the customer or supplier, as in listCustomersV1. Leave it out for the figures of all partners of the company.
format: int64 min: 1 example: 37
to-date
query string (date)
Last month of the payment period, ISO yyyy-MM-dd; defaults to today. Does not change the open amounts.
format: date example: 2026-09-30
Responses 6
200 Open amounts and monthly payments. show body

application/json PublicApiPartnerAmounts

  • customerId integer (int64) format: int64 example: 37
    The customer or supplier as requested with customer-id; missing for all partners of the company.
  • paymentsFrom string (date) format: date example: 2026-01-01
    First day of the payment period: the first day of the month eight months before to-date.
  • paymentsTo string (date) format: date example: 2026-09-30
    Last day of the payment period: the last day of the month of to-date.
  • openAmounts array of PublicApiPartnerOpenAmount
    Open amount per side, RECEIVABLE first; a side without open invoices is left out.
    show fields

    Array of PublicApiPartnerOpenAmount.

    • side object example: RECEIVABLE
      RECEIVABLE: customer invoices and payments received from customers. PAYABLE: supplier invoices and payments made to suppliers.
    • openAmount number example: 1250.4
      Still open amount in CHF, partial payments deducted. Positive when the partner owes the company (RECEIVABLE) or the company owes the partner (PAYABLE); credit notes reduce it.
    • overdueAmount number example: 300
      Part of openAmount whose due date is before today, independent of to-date.
  • monthlyPayments array of PublicApiPartnerMonthlyPayment
    Payments per month and side in the payment period, oldest month first, RECEIVABLE before PAYABLE; a month without payments is left out.
    show fields

    Array of PublicApiPartnerMonthlyPayment.

    • year integer (int32) format: int32 example: 2026
      Year of the booking date.
    • month integer (int32) format: int32 example: 9
      Month of the booking date, 1 to 12.
    • side object example: RECEIVABLE
      RECEIVABLE: customer invoices and payments received from customers. PAYABLE: supplier invoices and payments made to suppliers.
    • amount number example: 4200
      Sum of the payments in CHF, positive for money received (RECEIVABLE) or paid (PAYABLE); a refund reduces it.
400 to-date is not an ISO date, or customer-id is less than 1.

Error codes for this response (the code field of the response body):
  • partneramounts.date_invalid — to-date was not an ISO date of the form yyyy-MM-dd.
Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/reports/profit-and-losskey / tokenGet the profit and loss statement for a period, optionally with a comparison period.
Returns the profit and loss statement of the caller's company for the period date-from to date-to, as KLARA shows it under Accounting > Reports > Profit and loss statement: the seven result levels (gross margin after material cost, gross margin after labor cost, EBITDA, EBIT, EBT, profit or loss before taxes, profit or loss), inside them the chart-of-account groups each level adds, the accounts with bookings in the period, and per account the detail rows: the sub-account or insurance institution of the booking lines (kind SUB_ACCOUNT, for example an insurer) and the booking tags (kind TAG) as a tree, as the screen shows them. With compare-from and compare-to every row also carries compareAmount, as in KLARA's two columns; a row present in only one period has 0 in the other. Result amounts are cumulative: income groups (30, 69, 70, 80, 85) minus expense groups (40, 50, 60, 68, 89) up to that level, negative for a loss. Chart groups and accounts are positive for income in groups 30, 69, 70, 80, 85 and for expenses in groups 40, 50, 60, 68, 89. The period includes both dates and can be any range; it does not have to match a financial year (see listCurrentCompanyFinancialYears for the company's financial years). include-delimitation=false leaves out delimitation bookings (accruals and deferrals) in both periods. All seven result levels and their chart groups are returned also without bookings, with 0; accounts only when they have bookings in one of the periods. Chart groups follow the chart of accounts, accounts their number, detail rows their name; detail rows have a name and a kind, no object reference. account-search and tag-search work like the search and the tag filter of the screen: account-search finds the text anywhere in the account number and name (so 600 finds 6000 and 6001; compare code for exactly one account), tag-search anywhere in the detail row names, in the language of Accept-Language, can be combined (both must match) and only hide rows, every amount stays the same. Detail row names can contain names of persons, as on the screen. Names follow Accept-Language (de, fr, it, en; anything else gives German). This is a read-only, idempotent operation without side effects. Tenant and company are derived from the bearer token and are never accepted from the URL or the request. The caller must hold the ACCOUNTING permission on the company; otherwise the endpoint returns 403.
operationId

getProfitAndLossV1 — the method name a generated client uses.

Required permission

ACCOUNTING This comes from the description in the specification; the source code analysis behind the other permission statements is older than this endpoint. Roles that carry it: Administrator, External user, Buchhalter.

Parameters 8
NameDescription
date-from required
query string (date)
First booking date of the period, inclusive, ISO yyyy-MM-dd.
format: date example: 2025-01-01
date-to required
query string (date)
Last booking date of the period, inclusive, ISO yyyy-MM-dd; not before date-from.
format: date example: 2025-12-31
account-search
query string
Keeps only accounts whose number or name contains this text (case-insensitive), with their groups. Hides rows only; amounts and results stay the same.
maxLength: 256 example: 6000
compare-from
query string (date)
First booking date of the comparison period, ISO yyyy-MM-dd; only together with compare-to.
format: date example: 2024-01-01
compare-to
query string (date)
Last booking date of the comparison period, ISO yyyy-MM-dd; not before compare-from.
format: date example: 2024-12-31
include-delimitation
query boolean
false leaves out delimitation bookings in both periods; included by default, as on the screen.
default: true example: True
tag-search
query string
Comma-separated texts; keeps only detail rows (sub-accounts, institutions, tags) whose name contains any of them (case-insensitive), with the rows below them and their accounts and groups. This is the tag filter of the screen. Hides rows only; amounts and results stay the same.
maxLength: 256 example: Projekt Alpha,Zurich
Accept-Language
header string
Language of the names: de, fr, it or en; a region is ignored, so fr-CH gives French; other languages give German.
example: de-CH
Responses 6
200 The profit and loss statement for the period (and the comparison period). show body

application/json PublicApiProfitAndLoss

  • dateFrom string (date) format: date example: 2025-01-01
    First day of the period, as requested.
  • dateTo string (date) format: date example: 2025-12-31
    Last day of the period, as requested.
  • compareFrom string (date) format: date example: 2024-01-01
    First day of the comparison period; missing without a comparison period.
  • compareTo string (date) format: date example: 2024-12-31
    Last day of the comparison period; missing without a comparison period.
  • groups array of PublicApiProfitAndLossGroup
    The seven result levels in this order: GROSS_MARGIN_AFTER_MATERIAL, GROSS_MARGIN_AFTER_LABOR, EBITDA, EBIT, EBT, PROFIT_OR_LOSS_BEFORE_TAXES, PROFIT_OR_LOSS. With a display filter, levels without remaining rows are left out, as on the screen.
    show fields

    Array of PublicApiProfitAndLossGroup.

    • type object example: EBITDA
      Result level of the profit and loss statement.
    • name string example: Earnings before interest and taxes depreciation and amortization (EBITDA)
      Name of the result level as KLARA shows it, in the language of Accept-Language.
    • amount number example: 48210.7
      Cumulative result in CHF for the period: income groups (30, 69, 70, 80, 85) minus expense groups (40, 50, 60, 68, 89) up to this level; negative for a loss.
    • compareAmount number example: 41530.15
      Cumulative result in CHF for the comparison period; missing without a comparison period.
    • chartGroups array of PublicApiProfitAndLossChartGroup
      Chart-of-account groups added at this level, in the order of the chart of accounts.
      show fields

      Array of PublicApiProfitAndLossChartGroup.

      • code string example: 30
        Chart-of-account group code of the Swiss SME chart of accounts: 30 operating revenue, 40 material and goods, 50 personnel expense, 60 other operating expense, 68 depreciation and value adjustments, 69 financial expense and income, 70 ancillary operating result, 80 non-operating result, 85 extraordinary, one-off or prior-period result, 89 direct taxes. The company's own label is in name.
      • name string example: Betrieblicher Ertrag aus Lieferungen und Leistungen
        Name of the group as KLARA shows it, for the company's legal form and the language of Accept-Language.
      • amount number example: 152300
        Amount in CHF for the period. Groups 30, 69, 70, 80 and 85 are positive for income (credit), groups 40, 50, 60, 68 and 89 for expenses (debit); a net amount on the other side is negative.
      • compareAmount number example: 138900
        Amount in CHF for the comparison period; missing without a comparison period.
      • accounts array of PublicApiProfitAndLossAccount
        Accounts of the group with bookings in the period, ordered by account number.
        show fields

        Array of PublicApiProfitAndLossAccount.

        • code string example: 3200
          Account number, as in listAccountsV1.
        • name string example: Handelserlöse
          Account name as KLARA shows it, without the number.
        • amount number example: 98400
          Amount in CHF for the period, with the sign of its chart group.
        • compareAmount number example: 91250
          Amount in CHF for the comparison period; missing without a comparison period.
        • details array of PublicApiProfitAndLossDetail
          Detail rows of the account: the sub-account or insurance institution of the booking lines (kind SUB_ACCOUNT) and the booking tags (kind TAG), as a tree, ordered by name. The amounts of the top-level rows add up to the account.
          show fields

          Array of PublicApiProfitAndLossDetail.

          • name string example: Projekt Alpha
            Name as KLARA shows it: the sub-account or insurance institution (for example an insurer), or the booking tag. Missing for booking lines without a tag. Rows with the same name are one row.
          • kind object example: TAG
            Kind of a detail row.
          • amount number example: 12500
            Amount in CHF for the period, with the sign of the account's chart group.
          • compareAmount number example: 9800
            Amount in CHF for the comparison period; missing without a comparison period.
          • details array of PublicApiProfitAndLossDetail
            The next level of tags below this row, ordered by name; missing on the last level.
            show fields

            Array of PublicApiProfitAndLossDetail.

            Recursive reference to PublicApiProfitAndLossDetail. The structure repeats from here.

400 date-from or date-to is missing or not an ISO date, date-to is before date-from, the comparison period is incomplete, not ISO dates or reversed (code profitandloss.date_invalid), or a search text is longer than 256 characters (code model.invalid).

Error codes for this response (the code field of the response body):
  • profitandloss.date_invalid — date-from or date-to was missing or not an ISO date of the form yyyy-MM-dd, date-to was before date-from, or the comparison period was incomplete, not of that form or reversed.
Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/tagskey / tokenList the tags used on bookings.
Returns the tags that occur on the booking lines of the caller's company, the same tags KLARA suggests when a tag is entered in the journal, a booking template or a business case. All booking lines count, whatever the booking status and fiscal year; tags that exist only on a booking template or a business case are not included. Each tag is returned once; a booking line can carry several tags, which are listed separately. Spellings are kept as entered, so Marketing and marketing are two entries. A single tag never contains a comma, because the comma separates the tags of a booking line. With include-combinations=true the list also contains each combination of tags as stored on a booking line, joined with a comma and a space (for example Marketing, Zurich), which is what the KLARA entry screens suggest; a name containing a comma is such a combination. Use the names as tags of a booking line in createBookingV1, or as tags filter in listBankReconciliationOpenPositionsV1, so new bookings reuse the existing spelling; join several tags with a comma without a space (Marketing,Zurich). Unlike the generic description of search-key, this operation splits the search text into words and keeps the tags that contain every word, case-insensitive (zur mark finds Marketing, Zurich). Characters are compared as written: Zurich does not find Zürich. Uses the standard collection parameters: search-key, offset (default 0), limit (default 50, maximum 100), sort-field (only and default NAME) and sort-direction (default DESC, Z to A; pass ASC for alphabetical order). Names are compared ignoring case and by character code, so letters with umlauts or accents sort after z. The number of tags matching the filters, ignoring offset and limit, is returned in the X-Total-Count header; to read everything, repeat the call with offset increased by limit until X-Total-Count is reached. To count the tags only, call with limit=1 and read X-Total-Count. This is a read-only, idempotent operation without side effects. Tenant and company are derived from the bearer token and are never accepted from the URL or the request. The caller must hold the ACCOUNTING permission on the company; otherwise the endpoint returns 403.
operationId

listBookingTagsV1 — the method name a generated client uses.

Required permission

Not established. Assume a permission is needed, and ask support if a call is rejected.

Parameters 6
NameDescription
include-combinations
query boolean
Also return each combination of tags as stored on one booking line, joined with a comma and a space, as the KLARA entry screens suggest them. true or false (default), case-insensitive.
default: false example: True
limit
query integer
Page size. Defaults to 50; hard cap 100. Requests above the cap are rejected with 400.
min: 1 max: 100 default: 50 example: 50
offset
query integer
0-based pagination offset — the number of rows to skip before the returned page. Defaults to 0. Combine with limit to walk the full collection.
min: 0 default: 0 example: 0
search-key
query string
Free-text search. The fields searched are documented per endpoint. Matches are case-insensitive substring matches. Maximum length 256 characters.
maxLength: 256 example: müller
sort-direction
query string
Sort direction. Allowed values: ASC, DESC. Defaults to DESC.
Allowed values: ASC, DESC
default: DESC example: DESC
sort-field
query string
Field to order the result by. The accepted values are listed per endpoint; an unknown value is rejected with 400. Each endpoint documents the default it applies, chosen so that paging with offset / limit is stable.
Responses 6
200 One page of tags, ordered by name in sort-direction (default DESC, Z to A). Empty array when the company has no tagged booking lines or nothing matches search-key. show body

application/json array of PublicApiBookingTag

Array of PublicApiBookingTag.

  • name string example: Marketing
    Tag as used on booking lines, for example as tags of a booking line in createBookingV1. With include-combinations=true also a combination of tags as stored on one booking line, joined with a comma and a space.
400 sort-field is not NAME, or a parameter is outside its bounds (include-combinations not true or false, search-key longer than 256 characters, offset negative, limit outside 1-100, sort-direction not ASC or DESC).

Error codes for this response (the code field of the response body):
  • request.sort_field_invalid — sort-field was not one of the values the operation documents. The message lists the accepted values.
Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/vat-profilekey / tokenGet the authenticated company's VAT reporting profile.
Returns the company's VAT regime (effective vs net-tax-rate), billing method and flat net-tax rates, so an integration knows when the Saldosteuersatz flat-rate layer applies.
operationId

getVatProfileV1 — the method name a generated client uses.

Required permission

ACCOUNTING
Available through: Administrator, External user, Buchhalter

Parameters 1
NameDescription
date
query string
Date (ISO yyyy-MM-dd) to resolve the company VAT config for; defaults to today. Use the date you intend to book on — the company VAT must be valid for it.
example: 2025-05-08
Responses 5
200 VAT profile. show body

application/json PublicApiVatProfile

  • hasVat boolean example: True
    Whether the company is VAT-registered.
  • reportingMode string example: EFFECTIVE_CLEARING
    VAT regime. EFFECTIVE_CLEARING or REPORTING_USING_NET_TAX_RATES.
  • billing string example: BILLED
    Billing method. BILLED or COLLECTED.
  • sss1 number example: 1
    Flat net-tax rate 1 (percent), when reporting under net tax rates.
  • sss2 number example: 0.5
    Flat net-tax rate 2 (percent), when reporting under net tax rates.
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/vat-suggestionskey / tokenSuggest ready-to-use VAT case / rate / account bundles for a booking line.
Turns a plain-language context — a purchase vs a sale — into ranked, copy-paste-ready VAT bundles. Each bundle carries the verbatim vatCaseLink and vatRateLink to drop into a booking line's links, plus a suggested vatAccountCode. Supply amount to also receive a net/VAT preview. The bundle marked recommended is the server's best guess.

Rebuilding the Manual-booking VAT UI from this response (read this if you are generating a UI). This endpoint returns a flat array, but the Manual-booking screen renders it as three linked dropdowns plus two toggles and an auto-computed amount. Map each control as follows:<table border="1" cellpadding="4"><tr><th>GUI control</th><th>Driven by</th><th>How to build it</th></tr><tr><td>VAT on/off toggle</td><td>client-side state (not in this response)</td><td>OFF → the line has no VAT: don't call this endpoint, add no VAT links/fields. ON → call this endpoint and show the dropdowns below.</td></tr><tr><td>VAT case dropdown (e.g. "taxable supply")</td><td>distinct vatCaseCode (label it with label)</td><td>Group the array by vatCaseCode; one entry per distinct case.</td></tr><tr><td>VAT rate dropdown (e.g. "8.1%")</td><td>vatRateDisplay</td><td>Cascades from the chosen case: the rows sharing the selected vatCaseCode are the rate options.</td></tr><tr><td>VAT account dropdown (e.g. "1170 | Input tax VAT")</td><td>vatAccountCodes</td><td>List all vatAccountCodes; preselect vatAccountCode.</td></tr><tr><td>including / excluding toggle</td><td>the amountKind query param</td><td>including = GROSS_INCLUSIVE; excluding = NET_EXCLUSIVE. Flipping it means re-calling this endpoint to refresh the preview.</td></tr><tr><td>Debit / Credit amount preview</td><td>previewNet / previewVat</td><td>Null until you pass amount. Re-call with the new amount/amountKind to refresh.</td></tr></table>End-to-end recipe (call → render → book):
  1. User turns the VAT toggle ON. Call this endpoint with direction (PURCHASE/SALE), the line's accountCode, the user's amount, the amountKind from the including/excluding toggle, and the date you will book on.
  2. Render the dropdowns per the table above; preselect the row where recommended = true.
  3. When the user picks a row, send it to POST /core/v1/bookings?autoCalculateVat=true: on the VAT-bearing line set links = "<vatCaseLink>,<vatRateLink>" (both verbatim), vatAccountCode = <vatAccountCode>, your amount, and isExcludeVatAmount matching the amountKind you queried — then omit the VAT counterpart line; the server generates it (matching previewNet/previewVat). Pass the same date you will book on.

    Coverage: the response mirrors the booking GUI's two dropdowns. The VAT-case list is direction-agnostic (every configured case is offered regardless of direction), and the rate list includes every configured version of each rate code the case references — current and historical — so a line dated before a rate change still finds its rate.
operationId

listVatSuggestionsV1 — the method name a generated client uses.

Required permission

ACCOUNTING
Available through: Administrator, External user, Buchhalter

Parameters 7
NameDescription
accountCode required
query integer (int32)
Main account being booked against (e.g. 1020); drives VAT-account resolution. Required.
format: int32 example: 4000
direction required
query string
PURCHASE (you are buying) or SALE (you are selling). Required. It does not restrict which VAT cases are returned (the full case list is always offered); it only selects the fallback VAT account — purchases vs sales — and the recommendation wording.
Allowed values: PURCHASE, SALE
example: PURCHASE
amount
query number
Amount to preview the net/VAT split for (optional).
example: 1000
amountKind
query string
GROSS_INCLUSIVE (default) or NET_EXCLUSIVE.
default: GROSS_INCLUSIVE example: GROSS_INCLUSIVE
date
query string
Date (ISO yyyy-MM-dd) to resolve the company VAT config for; defaults to today.
example: 2025-05-08
vatCase
query string
VAT case code to restrict suggestions to a single case; returns all its rate/account bundles (optional). Any valid case code is accepted regardless of direction — e.g. a sales case such as TAXABLE_SUPPLY can be requested with direction=PURCHASE.
Allowed values: TAXABLE_SUPPLY, SUPPLY_WITH_OPTION_ART_22, TAX_EXEMPT_SUPPLY, EXPORT, SUPPLY_ABROAD, EXCLUDED_SUPPLY, DECREASE_IN_PROFITS, INTERNAL_CONSUMPTION, SUBVENTION, CONTRIBUTIONS_DIVIDEND_DAMAGE_COMPENSION, DOMESTIC_PURCHASE, IMPORT_WITH_CUSTOMS, IMPORT_WITH_REVERSE_CHARGE, PURCHASE_ABROAD, TRANSFER_SUPPLY, MISCELLANEOUS, DE_TAXATION, MIXED_USE, REDUCTION, TAX_CREDIT_1050, TAX_CREDIT_1055_1056
example: DOMESTIC_PURCHASE
Accept-Language
header string
Preferred language for the bundle labels.
example: de-CH
Responses 6
200 Ranked VAT suggestions. show body

application/json array of PublicApiVatSuggestion

Array of PublicApiVatSuggestion.

  • label string example: Domestic purchase — 8.1%
    Human-meaningful label. Use it as the option text in the VAT-rate dropdown.
  • recommended boolean example: True
    True on the server's recommended default bundle — preselect this row in the dropdowns.
  • reason string example: Default VAT rate for DOMESTIC_PURCHASE.
    Why this bundle is suggested.
  • vatCaseCode string example: DOMESTIC_PURCHASE
    VAT case code. Group rows by this value to build the VAT-case dropdown.
  • vatCaseLink string example: vat_case:/luz_accounting/api/vat-cases/1
    Verbatim link to copy into a booking line's links (comma-joined with vatRateLink).
  • vatRateDisplay string example: 8.1%
    Display string of the VAT rate — the VAT-rate dropdown option within the selected VAT case.
  • vatRateLink string example: vat_rate:/luz_accounting/api/master-vats/59
    Verbatim link to copy into a booking line's links (comma-joined with vatCaseLink).
  • vatAccountCode integer (int32) format: int32 example: 1170
    Suggested VAT account for the generated VAT line — preselect this in the VAT-account dropdown; the first of vatAccountCodes (confirm against your chart of accounts).
  • vatAccountCodes array of integer (int32)
    All VAT accounts the company's chart maps to this account + VAT case; the options for the GUI's VAT-account dropdown.
  • previewNet number example: 925.93
    Net amount preview — the Debit/Credit preview shown in the GUI. Null until an amount is supplied; refreshes when amount/amountKind change.
  • previewVat number example: 74.07
    VAT amount preview — the VAT portion shown in the GUI. Null until an amount is supplied; refreshes when amount/amountKind change.
400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/vat-typeskey / tokenList KLARA master VAT-type catalogue rows.
Returns every VAT-type row maintained by KLARA — the canonical VAT codes that can participate in a booking together with their posting formulas. The data is global — the same catalogue is returned for every tenant, so there are no tenant or company path parameters. The Accept-Language header selects which translation is used for the description and vatTypeShortName fields; if absent or unsupported, German is used as the fallback. The endpoint is a pure read — idempotent, no side effects. Any authenticated bearer token is accepted; the downstream service declares no role or permission requirement on this endpoint.
operationId

listVatTypesV1 — the method name a generated client uses.

Required permission

none A valid token is enough. No particular permission is checked for this endpoint.

Parameters 1
NameDescription
Accept-Language
header string
IETF language tag used to resolve the localized description and vatTypeShortName fields. Examples: de-CH, fr-CH, it-CH, en. When the header is missing or the language is unknown, the downstream service falls back to German.
example: de-CH
Responses 4
200 Master VAT-type rows. Empty array when the catalogue has not been seeded yet. show body

application/json array of PublicApiVatType

Array of PublicApiVatType.

  • vatTypeCode string example: M81
    KLARA VAT-type code that identifies the row.
  • companyType string example: LIMITED_LIABILITY
    Company-type bucket the VAT type applies to.
  • description string example: Vorsteuer Material- und Dienstleistungsaufwand
    Localized description, resolved against the request Accept-Language header (German fallback).
  • vatTypeShortName string example: VSt MA
    Localized short name, resolved against the request Accept-Language header (German fallback).
  • i18n object
    Raw description translations keyed by lowercase IETF language tag. Useful when a client renders its own language picker; otherwise prefer the resolved description field.
    show fields

    Open map with values of type string.

  • i18nShortName object
    Raw short-name translations keyed by lowercase IETF language tag.
    show fields

    Open map with values of type string.

  • vatTypeFormula array of PublicApiVatTypeFormula
    Posting formulas attached to this VAT type, one per associated VAT case.
    show fields

    Array of PublicApiVatTypeFormula.

    • vatCaseCode string example: VAT_RECEIVABLE
      Linked VAT-case code this formula belongs to.
    • vatTypeCode string example: M81
      VAT-type code this formula belongs to.
    • companyType string example: LIMITED_LIABILITY
      Company-type bucket the formula applies to.
    • account string example: 2200
      Account number on which the VAT entry is booked.
    • contraAccount string example: 1170
      Contra-account number for the VAT entry.
    • linkedBookingAccount string example: 2201
      Linked auxiliary account, when applicable.
    • specialRatesType string example: STANDARD
      Special-rates flag (enum name from the upstream model). Surfaced as a string so future internal enum additions stay backwards compatible.
    • value string example: NORMAL
      Formula value flag (enum name from the upstream model). Surfaced as a string for forward compatibility.
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/vat-types/{vatTypeId}key / tokenResolve a KLARA master VAT-type row by its numeric id.
Loads a single VAT-type row from KLARA's global master VAT-type catalogue, identified by its numeric primary-key vatTypeId. The data is global — the same catalogue is shared across every tenant, so there are no tenant or company path parameters. The Accept-Language header selects which translation is used for the description and vatTypeShortName fields; if absent or unsupported, German is used as the fallback. The endpoint is a pure read — idempotent, no side effects. Any authenticated bearer token is accepted; the downstream service declares no role or permission requirement on this endpoint.
operationId

getVatTypeByIdV1 — the method name a generated client uses.

Required permission

none A valid token is enough. No particular permission is checked for this endpoint.

Parameters 2
NameDescription
vatTypeId required
path integer (int64)
Numeric primary-key id of the master VAT-type row to resolve. Obtain it from GET /core/v1/accounting/vat-types.
format: int64 example: 1
Accept-Language
header string
IETF language tag used to resolve the localized description and vatTypeShortName fields. Examples: de-CH, fr-CH, it-CH, en. When the header is missing or the language is unknown, the downstream service falls back to German.
example: de-CH
Responses 5
200 The master VAT-type row matching vatTypeId, including its localized description, short name and posting formulas. show body

application/json PublicApiVatType

  • vatTypeCode string example: M81
    KLARA VAT-type code that identifies the row.
  • companyType string example: LIMITED_LIABILITY
    Company-type bucket the VAT type applies to.
  • description string example: Vorsteuer Material- und Dienstleistungsaufwand
    Localized description, resolved against the request Accept-Language header (German fallback).
  • vatTypeShortName string example: VSt MA
    Localized short name, resolved against the request Accept-Language header (German fallback).
  • i18n object
    Raw description translations keyed by lowercase IETF language tag. Useful when a client renders its own language picker; otherwise prefer the resolved description field.
    show fields

    Open map with values of type string.

  • i18nShortName object
    Raw short-name translations keyed by lowercase IETF language tag.
    show fields

    Open map with values of type string.

  • vatTypeFormula array of PublicApiVatTypeFormula
    Posting formulas attached to this VAT type, one per associated VAT case.
    show fields

    Array of PublicApiVatTypeFormula.

    • vatCaseCode string example: VAT_RECEIVABLE
      Linked VAT-case code this formula belongs to.
    • vatTypeCode string example: M81
      VAT-type code this formula belongs to.
    • companyType string example: LIMITED_LIABILITY
      Company-type bucket the formula applies to.
    • account string example: 2200
      Account number on which the VAT entry is booked.
    • contraAccount string example: 1170
      Contra-account number for the VAT entry.
    • linkedBookingAccount string example: 2201
      Linked auxiliary account, when applicable.
    • specialRatesType string example: STANDARD
      Special-rates flag (enum name from the upstream model). Surfaced as a string so future internal enum additions stay backwards compatible.
    • value string example: NORMAL
      Formula value flag (enum name from the upstream model). Surfaced as a string for forward compatibility.
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 No master VAT-type row exists for the supplied vatTypeId.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/bank-reconciliation/open-positionskey / tokenList the bank-reconciliation open positions of the authenticated company.
Returns the list of open booking-detail positions (AR / AP invoices, payments, prepayments, credit notes, general-ledger entries) of the caller's company that match the supplied filters, enriched with partner-name display, business-case message id, computed open amount and a stable booking-detail URI. Used by the bank-reconciliation UI to populate the open-position picker for a selected bank or credit-card transaction. The action parameter selects the multi-condition combinator: search (default) is OR-of-conditions, filter is AND-of-conditions. Tenant and company are derived from the bearer-token session — they are never accepted from the URL. The endpoint is a pure read — idempotent, no side effects. The caller must hold the ACCOUNTING_GET_OPEN_POSITION permission on the company in scope.
operationId

listBankReconciliationOpenPositionsV1 — the method name a generated client uses.

Required permission

ACCOUNTING_GET_OPEN_POSITION
Available through: Administrator, External user, Buchhalter, Kundenbeziehungen

Parameters 13
NameDescription
action
query string
Multi-condition combinator. search (default) = OR-of-conditions; filter = AND-of-conditions.
Allowed values: search, filter
default: search example: filter
booking-type-codes
query string
Comma-separated list of booking-type codes to restrict to. Allowed values: GENERAL_LEDGER, AP_INVOICE, AP_PAYMENT, AR_INVOICE, AR_PAYMENT, AP_PREPAYMENT, AP_PREPAYUSE, AR_PREPAYMENT, AR_PREPAYUSE, AR_CREDITNOTE, AR_CREDITUSE, AP_CREDITNOTE, AP_CREDITUSE, AMORTIZATION, SELLOFF_AMORTIZATION, DELIMIT.
example: AR_PREPAYMENT,AR_CREDITNOTE
crdr-type
query string
Restrict to credit (CR) or debit (DR) postings.
Allowed values: CR, DR
example: CR
credit-card-not-reconciled
query boolean
When true, restricts to credit-card transactions still pending reconciliation.
example: True
general-search
query string
Renamed to search-key. This name is accepted until 2027-09-01; when both are sent, search-key wins. After that date, a request sending general-search without search-key is rejected with 400.

Deprecated — use search-key instead. Free-text search across description, partner name, document id and reference fields.
maxLength: 256 example: Migros
invoice-date
query string (date)
Exact-match invoice (document) date filter (ISO date yyyy-MM-dd).
format: date example: 2026-04-15
partner
query string
KLARA partner URI to filter by. Format: /api/…/{tenantId}/companies/{companyId}/partners/{partnerId}. Construct from the partner id returned by the public partner endpoints.
example: /api/luz_person/api/c60d31fa-f335-4957-872a-90b035632081/companies/1/partners/123
payment-date
query string (date)
Exact-match payment date filter (ISO date yyyy-MM-dd).
format: date example: 2026-05-28
payment-date-from
query string (date)
Inclusive lower bound of the payment-date range filter (ISO date yyyy-MM-dd).
format: date example: 2026-01-01
payment-date-to
query string (date)
Inclusive upper bound of the payment-date range filter (ISO date yyyy-MM-dd).
format: date example: 2026-06-30
position-status
query string
Comma-separated list of open-position lifecycle statuses to restrict to. Allowed values: OPEN, PARTLY_PAID, PAID, PARTLY_CLEARED, CLEARED.
example: OPEN,PARTLY_CLEARED
search-key
query string
Free-text search across description, partner name, document id and reference fields. Combined with the other filters using the mode selected by action.
maxLength: 256 example: Migros
tags
query string
Comma-separated list of tag names to filter by (free-form).
maxLength: 256 example: vendor-x,q2
Responses 6
200 List of open positions matching the filters. Empty array when nothing matches. show body

application/json array of PublicApiSuitableOpenPosition

Array of PublicApiSuitableOpenPosition.

  • id integer (int64) format: int64 example: 98765
    Booking-detail row id (database primary key).
  • bookingHeaderId integer (int64) format: int64 example: 4321
    Id of the booking header this detail belongs to.
  • bookingHeaderComment string example: Invoice 2026-0123 from Migros AG
    Free-text comment of the booking header.
  • businessCaseId integer (int64) format: int64 example: 12345
    Id of the parent business case.
  • accountCode string example: 1100
    Numeric account code on which the booking is posted.
  • accountLinkDisplay string example: Forderungen aus L+L
    Localized account label.
  • crdrType object example: DR
    Credit / debit indicator.
    Allowed values: CR, DR
  • description string example: Rechnung Nr. 2026-0123
    Free-text description of the booking line.
  • bookingTypeCode object example: AR_INVOICE
    Stable booking-type code of the underlying business case.
    Allowed values: GENERAL_LEDGER, AP_INVOICE, AP_PAYMENT, AR_INVOICE, AR_PAYMENT, AP_PREPAYMENT, AP_PREPAYUSE, AR_PREPAYMENT, AR_PREPAYUSE, AR_CREDITNOTE, AR_CREDITUSE, AP_CREDITNOTE, AP_CREDITUSE, AMORTIZATION, SELLOFF_AMORTIZATION, DELIMIT
  • openPositionStatus object example: OPEN
    Open-position lifecycle status.
    Allowed values: OPEN, PARTLY_PAID, PAID, PARTLY_CLEARED, CLEARED
  • amount number example: 1250
    Gross posted amount of the booking line.
  • partialPaymentAmount number example: 0
    Sum of payments / clearings already applied to this position.
  • openAmount number example: 1250
    Computed remaining amount still to be cleared (amount - partialPaymentAmount).
  • vatAmount number example: 94.05
    VAT amount included in the gross posting.
  • vatRate number example: 0.081
    VAT rate applied to the line as a decimal (e.g. 0.077).
  • vatRateDisplay string example: 8.1 %
    Localized VAT-rate display string.
  • vatBookingDetailLink string
    Self-link of the companion VAT booking-detail line, when present.
  • vatBookingDetail boolean example: False
    Whether this row is itself a derived VAT booking-detail line.
  • foreignCurrencyAmount number example: 1250
    Posted amount in the document's foreign currency, when applicable.
  • foreignCurrencyUnit string example: EUR
    ISO-4217 currency code of foreignCurrencyAmount.
  • tags string example: test manual
    Free-form tag string attached to the booking line.
  • documentDate string (date) format: date example: 2026-04-15
    Document (invoice) date of the underlying business case.
  • bookingDate string (date) format: date example: 2026-04-15
    Date the booking was journaled.
  • paidDate string (date) format: date example: 2026-05-10
    Date the position was last (partially) paid, if any.
  • dueDate string (date) format: date example: 2026-05-15
    Due date for payment.
  • paymentDate string (date) format: date example: 2026-05-12
    Effective payment date of the booking line.
  • servicePeriodFrom string (date) format: date example: 2026-04-01
    Inclusive lower bound of the service period this booking covers.
  • servicePeriodTo string (date) format: date example: 2026-04-30
    Inclusive upper bound of the service period this booking covers.
  • createDate string (date-time) format: date-time example: 2026-04-15T08:30:00
    Timestamp at which the booking detail was created.
  • updateDate string (date-time) format: date-time example: 2026-05-12T14:15:00
    Timestamp at which the booking detail was last updated.
  • documentId array of string
    List of document ids attached to the booking line.
  • partnerName string example: Migros AG
    Resolved partner display name for the position.
  • bookingDetailUri string example: /api/luz_accounting/api/{tenantId}/companies/{companyId}/booking-headers/4321/booking-details/98765
    Stable URI of the booking-detail row, for cross-service linking.
  • orderManagementInvoiceLink string
    Self-link of the linked order-management invoice, when applicable.
  • orderManagementInvoiceNumber string example: INV-2026-0123
    Resolved order-management invoice number for display.
  • msgId string example: MSG-7788
    Business-case message id, used by the eletter / inbox subsystems.
  • creditorReference string
    Creditor reference (Swiss QR-IBAN reference number) of the position.
  • isrReference string
    ISR reference of the position, when applicable.
  • isrMember string
    ISR member number, when applicable.
  • partnerIban string
    IBAN of the partner / counterparty.
  • endToEndId string
    End-to-end identifier carried on the bank transaction.
400 One of the date filters is not a valid ISO date (yyyy-MM-dd), or one of the enum filters (position-status, booking-type-codes, crdr-type) carries a value that is not in the documented value set, or a free-text filter exceeds 256 characters.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/bank-transactionskey / tokenList bank transactions that are not reconciled yet.
Returns the bank transactions of the caller's company that are not reconciled yet, as listed in KLARA under Accounting > Bank reconciliation. Only transactions of the company's bank accounts are returned, each with the bankAccountId from listCompanyBankAccounts; transactions of a bank account that no longer exists are left out, as in KLARA. To find the accounts of one bank, read swissBank.name in listCompanyBankAccounts. Credit card transactions are not included. A transaction counts as reconciled as soon as it is booked, also when it only partly settles an open item; reconciled transactions are never returned. An empty result for a payment reference therefore means either that no such payment arrived or that it is already reconciled; for the payment status of an invoice use listBankReconciliationOpenPositionsV1 with position-status. Amounts are the full amounts of the bank entry and always positive; direction tells whether money was received (CREDIT) or paid out (DEBIT). amount is set for entries in CHF. For entries in any other currency, including WIR (CHW), amount is empty and the amount is in foreignAmount with the currency in foreignCurrency; no CHF equivalent is provided. There is no server-side total: to sum amounts, read all pages sorted by ID ascending, and keep in mind that transactions reconciled in the meantime drop out of the list. Use paymentReference, remittanceText and counterpartyName to find the matching open item, for example with listBankReconciliationOpenPositionsV1 (use action=filter there so that all conditions apply; money received matches receivables, money paid out matches payables). Reconciling a transaction through the public API is not available yet; the id identifies the transaction for that future operation. Filter with bank-account-id, booking-date-from and booking-date-to (booking date, inclusive, yyyy-MM-dd) and direction; unlike the generic description of search-key, it matches counterparty name, remittance text, payment reference or additional information (contains, case-insensitive, spaces are not ignored). Sort with sort-field BOOKING_DATE (default), VALUE_DATE, AMOUNT or ID; ties are ordered by ID, empty values come last. Uses the standard collection parameters: search-key, offset (default 0), limit (default 50, maximum 100), sort-field and sort-direction (default DESC, newest first). The number of transactions matching the filters, ignoring offset and limit, is returned in the X-Total-Count header; to read everything, repeat the call with offset increased by limit until X-Total-Count is reached. This is a read-only, idempotent operation without side effects. Tenant and company are derived from the bearer token and are never accepted from the URL or the request. The caller must hold the ACCOUNTING permission on the company, and FINANCE_BANK_ACCOUNT to read the bank accounts (every role with ACCOUNTING holds it); otherwise the endpoint returns 403.
operationId

listBankTransactionsV1 — the method name a generated client uses.

Required permission

Not established. Assume a permission is needed, and ask support if a call is rejected.

Parameters 9
NameDescription
bank-account-id
query integer (int64)
Only transactions of this company bank account, as returned by listCompanyBankAccounts. An id that is not a bank account of the company returns an empty list.
format: int64 min: 1 example: 3
booking-date-from
query string (date)
Only transactions booked on or after this date, ISO yyyy-MM-dd.
format: date example: 2026-10-01
booking-date-to
query string (date)
Only transactions booked on or before this date, ISO yyyy-MM-dd; not before booking-date-from.
format: date example: 2026-10-15
direction
query string
CREDIT for money received, DEBIT for money paid out; both when omitted. Case-insensitive.
Allowed values: CREDIT, DEBIT
example: CREDIT
limit
query integer
Page size. Defaults to 50; hard cap 100. Requests above the cap are rejected with 400.
min: 1 max: 100 default: 50 example: 50
offset
query integer
0-based pagination offset — the number of rows to skip before the returned page. Defaults to 0. Combine with limit to walk the full collection.
min: 0 default: 0 example: 0
search-key
query string
Free-text search. The fields searched are documented per endpoint. Matches are case-insensitive substring matches. Maximum length 256 characters.
maxLength: 256 example: müller
sort-direction
query string
Sort direction. Allowed values: ASC, DESC. Defaults to DESC.
Allowed values: ASC, DESC
default: DESC example: DESC
sort-field
query string
Field to order the result by. The accepted values are listed per endpoint; an unknown value is rejected with 400. Each endpoint documents the default it applies, chosen so that paging with offset / limit is stable.
Responses 6
200 One page of transactions, ordered by sort-field. Empty array when the company has no bank account or no unreconciled transaction matches. show body

application/json array of PublicApiBankTransaction

Array of PublicApiBankTransaction.

  • id integer (int64) format: int64 example: 48213
    Id of the bank transaction, used by the reconciliation operations.
  • bankAccountId integer (int64) format: int64 example: 3
    Id of the company bank account the transaction belongs to, as returned by listCompanyBankAccounts.
  • iban string example: CH9300762011623852957
    IBAN of the company bank account, without spaces.
  • bookingDate string (date) format: date example: 2026-10-14
    Booking date at the bank.
  • valueDate string (date) format: date example: 2026-10-14
    Value date.
  • direction object example: CREDIT
    CREDIT: money received on the company bank account. DEBIT: money paid out from it.
  • amount number example: 1250
    Amount in CHF, always positive; the direction is in direction. Empty for transactions only in a foreign currency.
  • currency string example: CHF
    Currency of the transaction.
  • foreignAmount number example: 1300
    Amount in the foreign currency, if any; always positive.
  • foreignCurrency string example: EUR
    Foreign currency, if any.
  • counterpartyName string example: Muster AG
    Name of the payer (CREDIT) or payee (DEBIT), as delivered by the bank, or of the partner of a manually added transaction.
  • paymentReference string example: 210000000003139471430009017
    Structured payment reference: QR or ISR reference, or creditor reference (ISO 11649).
  • paymentReferenceType string example: QRR
    Type of paymentReference as delivered by the bank, for example QRR or SCOR; empty when the reference was recognized in the free text.
  • remittanceText string example: Invoice 2026-104
    Unstructured remittance information; several lines are joined with ;.
  • additionalInfo string example: Payment QR-bill
    Additional information of the bank entry.
  • endToEndId string example: E2E-2026-104
    End-to-end id set by the payer.
400 booking-date-from or booking-date-to is not an ISO date or the range is inverted, sort-field is not one of the documented values, or a parameter is outside its bounds (bank-account-id below 1, direction not CREDIT or DEBIT, search-key longer than 256 characters, offset negative, limit outside 1-100, sort-direction not ASC or DESC).

Error codes for this response (the code field of the response body):
  • request.sort_field_invalid — sort-field was not one of the values the operation documents. The message lists the accepted values.
  • banktransaction.booking_date_invalid — booking-date-from or booking-date-to was not an ISO date of the form yyyy-MM-dd, or booking-date-to was before booking-date-from.
Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/bookingskey / tokenSearch the journal: list bookings by text, booking date, amount or tag.
Returns the bookings of the caller's company, as listed in KLARA under Accounting > Journal, newest first (booking date, then id, both descending). Each entry is the booking header: title (the text of the first booking line), totalAmount (sum of the credit lines), dates, document ids and internal comment. The debit and credit lines are not part of this list; read them per booking with getBookingV1 and the id. The list covers all fiscal years and every booking status (planned, booked, locked, sealed, inactive), like the journal; filter by booking date for one year, and use listCurrentCompanyFinancialYearsV1 when a request means a fiscal year. A booking that consists only of delimitation lines is not listed, and delimitation lines never satisfy a filter. search-key is split into words at spaces and keeps the bookings in which any word occurs (contains, case-insensitive, no umlaut or accent folding, so Miete also finds Mieter) in the description of a booking line (the title is the first one) or in the stored internal comment (HTML markup included). A word that is a number also finds bookings with exactly that account code on a line, the booking with that id, and bookings linked to that booking; there is no filter for an account code alone. booking-date-from and booking-date-to filter by booking date (inclusive, yyyy-MM-dd). amount-from and amount-to keep bookings with at least one line whose amount is in the range (both inclusive; for more than 1000 send amount-from=1000.01); this is the line amount, not totalAmount. tags takes a comma-separated list and keeps bookings with a line that carries any of the tags (contains, case-insensitive: Marketing also finds Online-Marketing; there is no exact match); take the names from listBookingTagsV1. All conditions are checked per line: a booking is listed if one of its lines meets the amount and tag conditions and the search matches that line or the booking header. Uses the standard collection parameters: search-key, offset (default 0), limit (default 50, maximum 100); the order is fixed, sort-field accepts only BOOKING_DATE and sort-direction only DESC (ASC answers 400). The number of bookings matching the filters, ignoring offset and limit, is returned in the X-Total-Count header; to only count, call with limit=1. To read everything, repeat the call with offset increased by limit until X-Total-Count is reached; new bookings appear at the start and shift later pages, so fix booking-date-to for a stable export and remove duplicates by id. This is a read-only, idempotent operation without side effects. Tenant and company are derived from the bearer token and are never accepted from the URL or the request. The caller must hold the ACCOUNTING permission on the company; otherwise the endpoint returns 403.
operationId

listBookingsV1 — the method name a generated client uses.

Required permission

Not established. Assume a permission is needed, and ask support if a call is rejected.

Parameters 10
NameDescription
amount-from
query number
Only bookings with at least one line whose amount is at least this value (CHF, line amounts are always positive). Applies to a line, not to the booking amount.
example: 100
amount-to
query number
Only bookings with at least one line whose amount is at most this value; not below amount-from. Applies to the same line as amount-from.
example: 5000
booking-date-from
query string (date)
Only bookings with a booking date on or after this date, ISO yyyy-MM-dd.
format: date example: 2026-01-01
booking-date-to
query string (date)
Only bookings with a booking date on or before this date, ISO yyyy-MM-dd; not before booking-date-from.
format: date example: 2026-12-31
limit
query integer
Page size. Defaults to 50; hard cap 100. Requests above the cap are rejected with 400.
min: 1 max: 100 default: 50 example: 50
offset
query integer
0-based pagination offset — the number of rows to skip before the returned page. Defaults to 0. Combine with limit to walk the full collection.
min: 0 default: 0 example: 0
search-key
query string
Free-text search. The fields searched are documented per endpoint. Matches are case-insensitive substring matches. Maximum length 256 characters.
maxLength: 256 example: müller
sort-direction
query string
Sort direction. Allowed values: ASC, DESC. Defaults to DESC.
Allowed values: ASC, DESC
default: DESC example: DESC
sort-field
query string
Field to order the result by. The accepted values are listed per endpoint; an unknown value is rejected with 400. Each endpoint documents the default it applies, chosen so that paging with offset / limit is stable.
tags
query string
Comma-separated tags; keeps bookings with a line carrying any of them (contains, case-insensitive). Tag names come from listBookingTagsV1.
maxLength: 256 example: Marketing,Zurich
Responses 6
200 One page of bookings, newest first. Empty array when no booking matches. show body

application/json array of PublicApiBookingSummary

Array of PublicApiBookingSummary.

  • id integer (int64) format: int64 example: 4321
    Id of the booking, as shown in the journal in brackets after the title.
  • bookingDate string (date) format: date example: 2026-10-14
    Booking date.
  • documentDate string (date) format: date example: 2026-10-10
    Document date, if set.
  • title string example: Rent October 2026
    Text of the first booking line, as shown as the title in the journal.
  • totalAmount number example: 2500
    Booking amount in CHF: the sum of the credit lines.
  • documentIds array of string
    Ids of the documents attached to the booking.
  • internalComment string example: Paid by e-banking
    Internal comment as entered in KLARA. It may contain HTML; escape it before rendering.
400 booking-date-from or booking-date-to is not an ISO date or the range is inverted, amount-to is below amount-from, sort-field is not BOOKING_DATE, sort-direction is ASC, or a parameter is outside its bounds (amount-from or amount-to not a decimal number, search-key or tags longer than 256 characters, offset negative, limit outside 1-100, sort-direction not ASC or DESC).

Error codes for this response (the code field of the response body):
  • request.sort_field_invalid — sort-field was not one of the values the operation documents. The message lists the accepted values.
  • request.sort_direction_unsupported — sort-direction was sent with the direction an operation with a fixed order does not have. The message names the available direction.
  • booking.booking_date_invalid — booking-date-from or booking-date-to was not an ISO date of the form yyyy-MM-dd, or booking-date-to was before booking-date-from; for a document booking, bookingDate or booking-date was not an ISO date of that form.
  • booking.amount_range_invalid — amount-to was below amount-from.
Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
POST/core/v1/bookingskey / tokenCreate a new manual booking for the authenticated company.
Records a manual journal entry against the authenticated caller's company and returns the persisted booking with its server-assigned identifiers. The booking must contain at least two debit/credit lines whose totals balance — the downstream service rejects unbalanced postings. By default the bookingDate must fall inside an open fiscal year; set confirmDontMindClosingFiscalYear to true to accept a booking that targets a closing fiscal year. Set ignore-unsubscripted-dates to true to bypass the subscription-period guard that normally rejects bookings outside the active KLARA Accounting subscription window. Tenant and company are derived from the bearer token — the request body's id and companyId are ignored. The caller must hold the ACCOUNTING permission on the targeted company.
operationId

createBookingV1 — the method name a generated client uses.

Required permission

ACCOUNTING
Available through: Administrator, External user, Buchhalter

Parameters 4
NameDescription
autoCalculateVat
query boolean
When true, the server recalculates VAT like the Manual booking GUI: each VAT-bearing line sends a single gross/net amount + a vat_rate link + vatAccountCode + isExcludeVatAmount and omits its VAT counterpart line; the server derives the net/VAT split and generates the VAT line so the entry balances. When false (default), the caller must pre-split and pre-compute every line (current behaviour). Obtain valid VAT values from GET /core/latest/vat-cases and GET /core/v1/accounting/master-vats.
default: false example: False
confirmDontMindClosingFiscalYear
query boolean
When true, accept the booking even if its bookingDate falls in a closing fiscal year. Defaults to false.
default: false example: False
ignore-unsubscripted-dates
query boolean
When true, accept the booking even if its date falls outside the active KLARA Accounting subscription period. Defaults to false.
default: false example: False
Accept-Language
header string
Preferred language for any localized error messages produced downstream. Examples: de-CH, fr-CH, it-CH, en. Defaults to the tenant's configured language when omitted.
example: de-CH
Request body required
The booking to create, including its at-least-two balanced debit/credit lines.

Prerequisite APIs — call these first to obtain valid values:
  • GET /core/v1/accounting/accounts → provides valid accountCode values (e.g. 1020, 1100, 2000, 3200). Only use this endpoint when you want to implement a seperate combobox with a flat master account list without sub-account context.
  • GET /core/v1/accounting/accounts/account-displaying → provide full details about all valid, selectable accounts (combine name, combine code, master account, sub-account details when available). PREFERRED to use this endpoint as the booking line for some account code MUST include sub-account links if the sub-account exists.
  • POST /core/latest/companies/{company-id}/documents → upload supporting documents (invoices, receipts, bank statements) and collect the returned documentId values to populate documentIds. This step should be done BEFORE invoking the booking creation. Important: when calling this endpoint for booking creation, always use category = LIABILITY_UPLOAD — no other category is permitted in this context (the documents are automatically moved to LIABILITIES when the booking is created successfully). The GUI for booking creation must always provide a document-upload step using the LIABILITY_UPLOAD category.
  • GET /core/v1/accounting/booking-types → provides valid bookingTypeCode values (e.g. AR_PAYMENT, AP_INVOICE, GENERAL_LEDGER)
  • GET /core/v1/accounting/tags (listBookingTagsV1) → the tags the company already uses on its booking lines; reuse their spelling in tags instead of creating a new variant
  • GET /core/latest/vat-cases → provides VAT case IDs for the vat_case link key
  • GET /core/v1/accounting/master-vats → provides master VAT rate IDs for the vat_rate link key
  • GET /core/v1/accounting/vat-suggestions?direction=PURCHASE|SALE&amount=…&date=… → RECOMMENDED for VAT. Returns ready-to-use bundles; from the recommended row copy vatCaseLink and vatRateLink straight into the line's links (comma-joined) and vatAccountCode onto the line. Use with autoCalculateVat=true (see VAT auto-calculation below).
  • GET /core/v1/accounting/vat-profile?date=… → the company VAT regime (effective vs net-tax-rate). Informational: it explains how the server will split the amount; you do not copy it into the booking.
Top-level fields:
  • id (long) — Server-assigned. Set to 0 for new bookings.
  • companyId (long) — Server-derived from token. Set to 0.
  • bookingDate (string, yyyy-MM-ddT00:00:00Z, required) — Must fall in an open fiscal year.
  • documentIds (array of string) — IDs of attached documents (gather from POST /core/latest/companies/{company-id}/documents with category = LIABILITY_UPLOAD). The documents are automatically moved to LIABILITIES on success booking creation. A GUI implementing booking creation must always provide a document-upload step — omitting it is only acceptable for purely internal adjustments where no document exists, in which case documentIds may be left empty ([]).
  • internalComment (string) — Internal note visible only to accounting users.
  • bookingStatus (string) — Allowed: DRAFT, BOOKED, CANCELLED.
  • bookingDetails (array, required) — At least 2 balanced debit/credit lines (see below).
  • expand (boolean) — UI hint. Use false.
  • viewDocument (boolean) — UI hint. Use false.
bookingDetails[] fields:
  • id (long) — Server-assigned. Set to 0.
  • seq (int) — Line order starting at 0.
  • accountCode (int, required) — From GET /core/v1/accounting/accounts or GET /core/v1/accounting/accounts/account-displaying (preferred; includes sub-account context when it exists).
  • crdrType (string, required) — DR (debit) or CR (credit).
  • description (string) — Free-text line description.
  • amount (decimal, required) — Always positive. Total DR must equal total CR.
  • tags (string, required) — Comma-separated list of string tags. Each tag should represent a topic that the booking line should be associated with, e.g. Operating Expenses. Tags are free-form and have no semantic meaning to KLARA; they are simply stored and returned as-is. Reuse the existing spelling from listBookingTagsV1, and separate several tags with a comma without a space (Marketing,Zurich). Provide at least one tag per line.
  • links (string) — Comma-separated structured links. Two uses: (a) sub-account entities for the line's account code (from GET /core/v1/accounting/accounts/account-displaying); and (b) VAT links vat_case:… + vat_rate:… (from GET /core/v1/accounting/vat-suggestions) when this line carries VAT. Can be empty when neither applies.
  • bookingTypeCode (string) — From GET /core/v1/accounting/booking-types.
  • vatAccountCode (int) — Only with autoCalculateVat=true. The account the generated VAT line posts to (e.g. 1170); from the vatAccountCode of a vat-suggestions row.
  • isExcludeVatAmount (boolean) — Only with autoCalculateVat=true. false = amount includes VAT (gross); true = amount excludes VAT (net base).
  • isrReference (string) — ISR/QR-bill reference. Empty if not applicable.
  • isrMember (string) — ISR participant number. Empty if not applicable.
  • partnerIban (string) — Counterpart IBAN for payments. Empty if not applicable.
  • vatBookingDetail (boolean) — Set to false for manual lines.
VAT auto-calculation (autoCalculateVat=true) — book like the Manual booking GUI without doing VAT math:
  1. Call GET /core/v1/accounting/vat-suggestions?direction=PURCHASE|SALE&amount=<gross>&date=<bookingDate> and take the recommended row.
  2. On the VAT-bearing line set: links = "<vatCaseLink>,<vatRateLink>" (both values verbatim from that row), vatAccountCode = <row.vatAccountCode>, amount = <your gross or net>, and isExcludeVatAmount matching the amountKind you queried (false = gross).
  3. Do NOT add the VAT counterpart line yourself — the server derives the net/VAT split and generates it (matching the row's previewNet/previewVat). Provide only your account line(s) + the balancing line.
The split depends on the company VAT regime from vat-profile (effective → net + VAT line; net-tax-rate → flat-rate split; reverse-charge → an extra reverse VAT line). When autoCalculateVat is omitted/false you must instead pre-split and pre-compute every line yourself (see the "Invoice received/sent" examples).

Rules: Minimum 2 lines; total DR = total CR (after server VAT expansion when autoCalculateVat=true); amounts always positive; bookingDate in open fiscal year.

application/json PublicApiBookingHeader

  • id integer (int64) format: int64 example: 12345
    Internal id of the booking. Assigned by the server on creation; omit when sending a new booking.
  • companyId integer (int64) format: int64 example: 1
    Internal id of the company this booking belongs to. Filled by the server from the caller's session; ignored on input.
  • documentDate string (date-time) required format: date-time example: 2024-06-15T00:00:00Z
    Date printed on the underlying document, e.g. supplier invoice date (yyyy-MM-ddT00:00:00Z).
  • bookingDate string (date-time) required format: date-time example: 2024-06-15T00:00:00Z
    Effective accounting date of the booking; must fall inside an open fiscal year unless confirmDontMindClosingFiscalYear is set (yyyy-MM-ddT00:00:00Z).
  • documentIds array of string
    Ids of supporting documents (uploaded files / e-mails) attached to this booking.
  • businessCase string example: Office supplies
    Free-text business case label shown on the journal.
  • snippets array of string
    Snippet identifiers applied to this booking, copied from the booking template.
  • bookingStatus string example: BOOKED
    Status of the booking. Allowed values: DRAFT, BOOKED, CANCELLED.
  • internalComment string
    Internal comment, visible only to accounting users.
  • businessCaseId string read-only
    Id of the KLARA business case that produced this booking. Set by the server and ignored on input: a booking created through this API never belongs to a business case, so leave it empty. This is not the business case template code (use businessCase for a label). A non-numeric value is rejected with 400 booking.business_case_id_invalid.
  • relatedBookingHeaderLinks array of string
    URIs of bookings that are related to this one (e.g. payment ↔ invoice, original ↔ delimitation).
  • bookingDetails array of PublicApiBookingDetail required minItems: 2
    Debit and credit lines of the booking. Must contain at least two lines whose debit and credit totals balance.
    show fields

    Array of PublicApiBookingDetail.

    • id integer (int64) format: int64 example: 1001
      Internal id of the booking detail. Assigned by the server on creation; omit when sending a new booking.
    • accountCode integer (int32) required format: int32 min: 1 example: 1020
      Ledger account number the amount is posted to (Swiss SME chart of accounts).
    • crdrType string required example: DR
      Whether this line is a credit or a debit. Allowed values: CR, DR.
    • description string required pattern: \S example: Office supplies — invoice 2024-019
      Free-text description shown on the journal report.
    • amount number required example: 150
      Absolute posting amount in the company main currency. Always positive; sign is carried by crdrType.
    • partialPaymentAmount number example: 0
      Amount already paid against this line — only used for open-position bookings (invoices, credit notes).
    • tags string required example: project-alpha,q2
      Comma-separated list of string tags. Each tag is free-form and should represent a topic that the booking line should be associated with. Reuse the existing spelling from listBookingTagsV1; separate several tags with a comma without a space. Provide at least one tag per line.
    • links string example: bank_account:/luzfin_finance/api/388c822c-7860-41ae-94ac-330684bb63e0/companies/1/bank-accounts/85,vat_case:/luz_accounting/api/vat-cases/1
      Comma-separated list of structured links of entities that are considered the sub-accounts associated with an account code when making a booking line.This string can be empty when no sub-account is required for the current account code of the booking line.Each link has the format key:uri-path. Important: the exact URI values — including the tenant UUID and company ID segments — are returned verbatim by GET /core/v1/accounting/accounts/account-displaying in the account's specificationItem.link field; copy them as-is, do not construct them manually.

      Supported link type keys:
      Bank / cash sub-accounts (secondary dropdown in GUI for accounts 1000, 1020, 1030, 1040, and similar):
      • bank_account — company bank account; URI from /…/{tenant}/companies/{cid}/bank-accounts/{id}
      • cash — cash register; URI from /…/{tenant}/companies/{cid}/cash/{id}
      • transfer_account — transfer account; URI from /…/{tenant}/companies/{cid}/transfer/{id}
      • interest_bearing_current_account — interest-bearing current account; URI from /…/{tenant}/companies/{cid}/interest-bearing-current/{id}
      • non_interest_bearing_current_account — non-interest-bearing current account; URI from /…/{tenant}/companies/{cid}/non-interest-bearing/{id}
      Counterpart links (customer / supplier / employee sub-ledger):
      • customer — accounts-receivable customer; URI from /…/{tenant}/companies/{cid}/customers/{id}
      • supplier — accounts-payable supplier; URI from /…/{tenant}/companies/{cid}/customers/{id}
      • employee — employee (payroll/HR); URI from /…/{tenant}/companies/{cid}/employees/{id}
      Tax / VAT links:
      • vat_case — VAT case; URI from /…/vat-cases/{id} (obtain from GET /core/latest/vat-cases)
      • vat_rate — master VAT rate; URI from /…/master-vats/{id} (obtain from GET /core/v1/accounting/master-vats)
      • social_insurance — social insurance contract; URI from /…/{tenant}/companies/{cid}/insurance-contracts/{id}
      • tax_at_source — tax-at-source (withholding tax) state; URI from /…/states/{id}
      Asset / liability / equity links:
      • financial_asset — financial asset; URI from /…/{tenant}/companies/{cid}/financial-asset/{id}
      • intangible_asset — intangible asset; URI from /…/{tenant}/companies/{cid}/intangible-asset/{id}
      • equity — equity account; URI from /…/{tenant}/companies/{cid}/equity/{id}
      • long_term_interest_bearing_liability — long-term loan; URI from /…/{tenant}/companies/{cid}/long-term-interest-bearing/{id}
      • statutory_profit_reserve — statutory profit reserve; URI from /…/{tenant}/companies/{cid}/statutory-profit-reserve/{id}
      • deferrals — accrual/deferral position; URI from /…/{tenant}/companies/{cid}/deferral/{id}
      Revenue / inventory / other links:
      • gift_card — gift card; URI from /…/{tenant}/companies/{cid}/gift-cards/{id}
      • not_billed_services — unbilled service position; URI from /…/{tenant}/companies/{cid}/not-billed-services/{id}
      • various — miscellaneous counterpart; URI from /…/{tenant}/companies/{cid}/various/{id}
      • inventory_change_goods — inventory type (static); URI: /…/inventory-types/inventory-change-goods
      • inventory_change_material — inventory type (static); URI: /…/inventory-types/inventory-change-material
      • non_billed_services — inventory type (static); URI: /…/inventory-types/non-billed-services
      • finished_products — inventory type (static); URI: /…/inventory-types/finished-products
      • unfinished_products — inventory type (static); URI: /…/inventory-types/unfinished-products
      Multiple entries are comma-separated. Leave empty when none apply.
    • seq integer (int32) format: int32 example: 0
      Ordering of the line inside the booking, starting at 0.
    • vatAccountCode integer (int32) format: int32 example: 1170
      GUI-style VAT input, used only with autoCalculateVat=true: the account the automatically generated VAT counterpart line is posted to (the GUI "VAT account", e.g. 1170). Required on a VAT-bearing line when the line carries a vat_rate link and omits its own VAT line. Ignored when autoCalculateVat is false (caller pre-splits the lines).
    • vatTypeDescription string example: INCLUSIVE
      How VAT is recorded for this line. Allowed values: INCLUSIVE, EXCLUSIVE, NONE.
    • vatBookingDetailLink string
      URI of the companion VAT booking detail, when one was generated automatically.
    • vatAmount number example: 11.4
      VAT amount carried on this line, in the company main currency.
    • vatRate number example: 7.7
      Effective VAT rate (percent) applied to this line.
    • vatRateDisplay string example: 7.7%
      Display string of the VAT rate as rendered in the UI.
    • vatBookingDetail boolean example: False
      True when this line is the automatically generated VAT counterpart of another line.
    • bookingTypeCode string required example: GENERAL_LEDGER
      Business meaning of the booking line. Allowed values include GENERAL_LEDGER, AR_INVOICE, AP_INVOICE, AR_PAYMENT, AP_PAYMENT, AR_CREDIT_NOTE, AP_CREDIT_NOTE.
    • openPositionStatus string example: OPEN
      Lifecycle of the open position represented by this line. Allowed values include OPEN, PARTIALLY_PAID, PAID, CLOSED.
    • creditorReference string
      Creditor reference (QR-bill / ISO 11649) attached to the open position.
    • isrReference string
      ISR reference number attached to the open position.
    • isrMember string
      ISR participant (member) number of the creditor.
    • partnerIban string
      IBAN of the counterpart used for outgoing payments.
    • endToEndId string
      Pain.001 end-to-end id, propagated to the outgoing payment instruction.
    • isExcludeVatAmount boolean example: False
      When true, the gross amount on this line excludes VAT; otherwise it includes VAT.
    • foreignCurrencyAmount number
      Posting amount in the foreign currency, when the line is booked in a non-main currency.
    • foreignCurrencyUnit string example: EUR
      ISO 4217 code of the foreign currency.
    • paidDate string (date-time) format: date-time example: 2024-06-15T00:00:00Z
      Date on which the open position was settled (yyyy-MM-ddT00:00:00Z).
    • dueDate string (date-time) format: date-time example: 2024-06-30T00:00:00Z
      Date on which the open position becomes overdue (yyyy-MM-ddT00:00:00Z).
    • paymentDate string (date-time) format: date-time example: 2024-06-28T00:00:00Z
      Date on which the payment instruction is scheduled (yyyy-MM-ddT00:00:00Z).
    • servicePeriodFrom string (date-time) format: date-time example: 2024-06-01T00:00:00Z
      Start of the service period covered by the line (yyyy-MM-ddT00:00:00Z).
    • servicePeriodTo string (date-time) format: date-time example: 2024-06-30T00:00:00Z
      End of the service period covered by the line (yyyy-MM-ddT00:00:00Z).
    • paymentPercentage number example: 0
      Percentage of the open-position amount already settled.
    • isDunningBlocked boolean example: False
      When true, dunning reminders are suppressed for this open position.
  • invoiceNumber string example: 2024-019
    Invoice number printed on the document.
  • orderManagementInvoiceLink string
    KLARA order-management invoice URI when the booking was generated from a KLARA invoice.
  • bookingTemplateId integer (int64) format: int64 example: 501
    Id of the booking template the user picked when creating this entry.
  • bookingTitle string example: Office supplies — June 2024
    Short title of the booking shown in lists.
  • totalAmount number example: 150
    Sum of the absolute amounts of the booking lines, in the company main currency.
  • bookingTypeCode string example: GENERAL_LEDGER
    Business meaning of the booking. Allowed values include GENERAL_LEDGER, AR_INVOICE, AP_INVOICE, AR_PAYMENT, AP_PAYMENT, AR_CREDIT_NOTE, AP_CREDIT_NOTE.
Responses 6
200 Booking created. show body

application/json PublicApiBookingHeader

  • id integer (int64) format: int64 example: 12345
    Internal id of the booking. Assigned by the server on creation; omit when sending a new booking.
  • companyId integer (int64) format: int64 example: 1
    Internal id of the company this booking belongs to. Filled by the server from the caller's session; ignored on input.
  • documentDate string (date-time) required format: date-time example: 2024-06-15T00:00:00Z
    Date printed on the underlying document, e.g. supplier invoice date (yyyy-MM-ddT00:00:00Z).
  • bookingDate string (date-time) required format: date-time example: 2024-06-15T00:00:00Z
    Effective accounting date of the booking; must fall inside an open fiscal year unless confirmDontMindClosingFiscalYear is set (yyyy-MM-ddT00:00:00Z).
  • documentIds array of string
    Ids of supporting documents (uploaded files / e-mails) attached to this booking.
  • businessCase string example: Office supplies
    Free-text business case label shown on the journal.
  • snippets array of string
    Snippet identifiers applied to this booking, copied from the booking template.
  • bookingStatus string example: BOOKED
    Status of the booking. Allowed values: DRAFT, BOOKED, CANCELLED.
  • internalComment string
    Internal comment, visible only to accounting users.
  • businessCaseId string read-only
    Id of the KLARA business case that produced this booking. Set by the server and ignored on input: a booking created through this API never belongs to a business case, so leave it empty. This is not the business case template code (use businessCase for a label). A non-numeric value is rejected with 400 booking.business_case_id_invalid.
  • relatedBookingHeaderLinks array of string
    URIs of bookings that are related to this one (e.g. payment ↔ invoice, original ↔ delimitation).
  • bookingDetails array of PublicApiBookingDetail required minItems: 2
    Debit and credit lines of the booking. Must contain at least two lines whose debit and credit totals balance.
    show fields

    Array of PublicApiBookingDetail.

    • id integer (int64) format: int64 example: 1001
      Internal id of the booking detail. Assigned by the server on creation; omit when sending a new booking.
    • accountCode integer (int32) required format: int32 min: 1 example: 1020
      Ledger account number the amount is posted to (Swiss SME chart of accounts).
    • crdrType string required example: DR
      Whether this line is a credit or a debit. Allowed values: CR, DR.
    • description string required pattern: \S example: Office supplies — invoice 2024-019
      Free-text description shown on the journal report.
    • amount number required example: 150
      Absolute posting amount in the company main currency. Always positive; sign is carried by crdrType.
    • partialPaymentAmount number example: 0
      Amount already paid against this line — only used for open-position bookings (invoices, credit notes).
    • tags string required example: project-alpha,q2
      Comma-separated list of string tags. Each tag is free-form and should represent a topic that the booking line should be associated with. Reuse the existing spelling from listBookingTagsV1; separate several tags with a comma without a space. Provide at least one tag per line.
    • links string example: bank_account:/luzfin_finance/api/388c822c-7860-41ae-94ac-330684bb63e0/companies/1/bank-accounts/85,vat_case:/luz_accounting/api/vat-cases/1
      Comma-separated list of structured links of entities that are considered the sub-accounts associated with an account code when making a booking line.This string can be empty when no sub-account is required for the current account code of the booking line.Each link has the format key:uri-path. Important: the exact URI values — including the tenant UUID and company ID segments — are returned verbatim by GET /core/v1/accounting/accounts/account-displaying in the account's specificationItem.link field; copy them as-is, do not construct them manually.

      Supported link type keys:
      Bank / cash sub-accounts (secondary dropdown in GUI for accounts 1000, 1020, 1030, 1040, and similar):
      • bank_account — company bank account; URI from /…/{tenant}/companies/{cid}/bank-accounts/{id}
      • cash — cash register; URI from /…/{tenant}/companies/{cid}/cash/{id}
      • transfer_account — transfer account; URI from /…/{tenant}/companies/{cid}/transfer/{id}
      • interest_bearing_current_account — interest-bearing current account; URI from /…/{tenant}/companies/{cid}/interest-bearing-current/{id}
      • non_interest_bearing_current_account — non-interest-bearing current account; URI from /…/{tenant}/companies/{cid}/non-interest-bearing/{id}
      Counterpart links (customer / supplier / employee sub-ledger):
      • customer — accounts-receivable customer; URI from /…/{tenant}/companies/{cid}/customers/{id}
      • supplier — accounts-payable supplier; URI from /…/{tenant}/companies/{cid}/customers/{id}
      • employee — employee (payroll/HR); URI from /…/{tenant}/companies/{cid}/employees/{id}
      Tax / VAT links:
      • vat_case — VAT case; URI from /…/vat-cases/{id} (obtain from GET /core/latest/vat-cases)
      • vat_rate — master VAT rate; URI from /…/master-vats/{id} (obtain from GET /core/v1/accounting/master-vats)
      • social_insurance — social insurance contract; URI from /…/{tenant}/companies/{cid}/insurance-contracts/{id}
      • tax_at_source — tax-at-source (withholding tax) state; URI from /…/states/{id}
      Asset / liability / equity links:
      • financial_asset — financial asset; URI from /…/{tenant}/companies/{cid}/financial-asset/{id}
      • intangible_asset — intangible asset; URI from /…/{tenant}/companies/{cid}/intangible-asset/{id}
      • equity — equity account; URI from /…/{tenant}/companies/{cid}/equity/{id}
      • long_term_interest_bearing_liability — long-term loan; URI from /…/{tenant}/companies/{cid}/long-term-interest-bearing/{id}
      • statutory_profit_reserve — statutory profit reserve; URI from /…/{tenant}/companies/{cid}/statutory-profit-reserve/{id}
      • deferrals — accrual/deferral position; URI from /…/{tenant}/companies/{cid}/deferral/{id}
      Revenue / inventory / other links:
      • gift_card — gift card; URI from /…/{tenant}/companies/{cid}/gift-cards/{id}
      • not_billed_services — unbilled service position; URI from /…/{tenant}/companies/{cid}/not-billed-services/{id}
      • various — miscellaneous counterpart; URI from /…/{tenant}/companies/{cid}/various/{id}
      • inventory_change_goods — inventory type (static); URI: /…/inventory-types/inventory-change-goods
      • inventory_change_material — inventory type (static); URI: /…/inventory-types/inventory-change-material
      • non_billed_services — inventory type (static); URI: /…/inventory-types/non-billed-services
      • finished_products — inventory type (static); URI: /…/inventory-types/finished-products
      • unfinished_products — inventory type (static); URI: /…/inventory-types/unfinished-products
      Multiple entries are comma-separated. Leave empty when none apply.
    • seq integer (int32) format: int32 example: 0
      Ordering of the line inside the booking, starting at 0.
    • vatAccountCode integer (int32) format: int32 example: 1170
      GUI-style VAT input, used only with autoCalculateVat=true: the account the automatically generated VAT counterpart line is posted to (the GUI "VAT account", e.g. 1170). Required on a VAT-bearing line when the line carries a vat_rate link and omits its own VAT line. Ignored when autoCalculateVat is false (caller pre-splits the lines).
    • vatTypeDescription string example: INCLUSIVE
      How VAT is recorded for this line. Allowed values: INCLUSIVE, EXCLUSIVE, NONE.
    • vatBookingDetailLink string
      URI of the companion VAT booking detail, when one was generated automatically.
    • vatAmount number example: 11.4
      VAT amount carried on this line, in the company main currency.
    • vatRate number example: 7.7
      Effective VAT rate (percent) applied to this line.
    • vatRateDisplay string example: 7.7%
      Display string of the VAT rate as rendered in the UI.
    • vatBookingDetail boolean example: False
      True when this line is the automatically generated VAT counterpart of another line.
    • bookingTypeCode string required example: GENERAL_LEDGER
      Business meaning of the booking line. Allowed values include GENERAL_LEDGER, AR_INVOICE, AP_INVOICE, AR_PAYMENT, AP_PAYMENT, AR_CREDIT_NOTE, AP_CREDIT_NOTE.
    • openPositionStatus string example: OPEN
      Lifecycle of the open position represented by this line. Allowed values include OPEN, PARTIALLY_PAID, PAID, CLOSED.
    • creditorReference string
      Creditor reference (QR-bill / ISO 11649) attached to the open position.
    • isrReference string
      ISR reference number attached to the open position.
    • isrMember string
      ISR participant (member) number of the creditor.
    • partnerIban string
      IBAN of the counterpart used for outgoing payments.
    • endToEndId string
      Pain.001 end-to-end id, propagated to the outgoing payment instruction.
    • isExcludeVatAmount boolean example: False
      When true, the gross amount on this line excludes VAT; otherwise it includes VAT.
    • foreignCurrencyAmount number
      Posting amount in the foreign currency, when the line is booked in a non-main currency.
    • foreignCurrencyUnit string example: EUR
      ISO 4217 code of the foreign currency.
    • paidDate string (date-time) format: date-time example: 2024-06-15T00:00:00Z
      Date on which the open position was settled (yyyy-MM-ddT00:00:00Z).
    • dueDate string (date-time) format: date-time example: 2024-06-30T00:00:00Z
      Date on which the open position becomes overdue (yyyy-MM-ddT00:00:00Z).
    • paymentDate string (date-time) format: date-time example: 2024-06-28T00:00:00Z
      Date on which the payment instruction is scheduled (yyyy-MM-ddT00:00:00Z).
    • servicePeriodFrom string (date-time) format: date-time example: 2024-06-01T00:00:00Z
      Start of the service period covered by the line (yyyy-MM-ddT00:00:00Z).
    • servicePeriodTo string (date-time) format: date-time example: 2024-06-30T00:00:00Z
      End of the service period covered by the line (yyyy-MM-ddT00:00:00Z).
    • paymentPercentage number example: 0
      Percentage of the open-position amount already settled.
    • isDunningBlocked boolean example: False
      When true, dunning reminders are suppressed for this open position.
  • invoiceNumber string example: 2024-019
    Invoice number printed on the document.
  • orderManagementInvoiceLink string
    KLARA order-management invoice URI when the booking was generated from a KLARA invoice.
  • bookingTemplateId integer (int64) format: int64 example: 501
    Id of the booking template the user picked when creating this entry.
  • bookingTitle string example: Office supplies — June 2024
    Short title of the booking shown in lists.
  • totalAmount number example: 150
    Sum of the absolute amounts of the booking lines, in the company main currency.
  • bookingTypeCode string example: GENERAL_LEDGER
    Business meaning of the booking. Allowed values include GENERAL_LEDGER, AR_INVOICE, AP_INVOICE, AR_PAYMENT, AP_PAYMENT, AR_CREDIT_NOTE, AP_CREDIT_NOTE.
400 Data invalid

Error codes for this response (the code field of the response body):
  • booking.status_not_allowed — bookingStatus was neither BOOKED nor PLANNED.
  • booking.business_case_id_invalid — businessCaseId was set but is not a numeric business case id. Leave it empty when creating a booking; use businessCase for a label.
Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Error codes for this response (the code field of the response body):
  • auth.credentials_missing — Neither an Authorization: Bearer header nor an API key header was present on the request.
Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/bookings/{bookingId}key / tokenRead one booking with all its debit and credit lines.
Returns one booking of the caller's company with all its lines, as shown when a booking is expanded in KLARA under Accounting > Journal. Take the bookingId from listBookingsV1 or from connectedLines; booking ids are unique within the tenant. The header carries the same title and totalAmount as in listBookingsV1 (text of the line with position 1, sum of all credit lines). lines holds every line in the order KLARA shows them, including VAT lines (separate lines on the VAT account) and delimitation lines (bookingType DELIMIT); a booking that consists only of delimitation lines can be read here although listBookingsV1 does not list it. Each line has its account (number and name), side (DEBIT or CREDIT) and amount in CHF (always positive), the posting text, tags, the kind of line (bookingType), the VAT rate, a foreign currency amount, the open-item state of invoice and payment lines with due date, paid date and overdue, the service period, and who changed the line last (lastModifiedBy: an e-mail address, an API key name or SYSTEM; lastModifiedAt in UTC; a line never changed shows its creation). references lists the objects a line refers to, with type, id and the name KLARA shows now: customers and suppliers (same ids as in listCustomersV1; the partner of an invoice or payment is on its AR_* or AP_* line), company bank accounts (listCompanyBankAccounts), bank transactions, VAT cases, invoices, payments, employees, social insurances, salary runs, tax-at-source cantons, KLARA's built-in gift-card and miscellaneous partner entries, and sub-accounts of the chart of accounts (with category); a name is missing when it could not be resolved. connectedLines lists the lines of other bookings a line is connected to: RECONCILIATION (a payment or bank reconciliation against an open item; listed on every line involved, so the invoice line lists each payment line and the payment line each invoice line), DELIMITATION (accrual), PREPAYMENT_CLEARING, CREDIT_NOTE_CLEARING and MAIN_LINE (the line this automatically created line was derived from, for example a VAT line booked with a payment that points to the revenue line of the invoice); read the connected booking with this operation and its bookingId. Not returned: the booking status (planned and inactive bookings are returned like booked ones, as the journal shows them), the amount still open on an open item (use listCustomerOpenPositionsV1), the VAT amount of a line, the amount a single reconciliation settled, and who changed the booking header (date, comment, documents). Reading the lines of many bookings takes one call per booking. Empty values and empty lists are left out. Account names and reference names follow Accept-Language. Returns 404 with code booking.unknown when no booking with this id exists in the caller's company; a booking of another company is answered the same way, to read it a token for that company is needed. A bookingId that is not a number also answers 404 (no such path). This is a read-only, idempotent operation without side effects. Tenant and company are derived from the bearer token and are never accepted from the URL or the request. The caller must hold the ACCOUNTING permission on the company; otherwise the endpoint returns 403; a 403 never means that the booking exists.
operationId

getBookingV1 — the method name a generated client uses.

Required permission

Not established. Assume a permission is needed, and ask support if a call is rejected.

Parameters 2
NameDescription
bookingId required
path integer (int64)
Id of the booking, from the id of listBookingsV1.
format: int64 min: 1 example: 4321
Accept-Language
header string
Language of account names and reference names, as in KLARA (for example de-CH, fr-CH, it-CH, en); default the tenant's language.
example: de-CH
Responses 7
200 The booking with all its lines. show body

application/json PublicApiBookingWithLines

  • id integer (int64) format: int64 example: 4321
    Id of the booking, as in listBookingsV1.
  • bookingDate string (date) format: date example: 2026-10-14
    Booking date.
  • documentDate string (date) format: date example: 2026-10-10
    Document date, if set.
  • title string example: Rent October 2026
    Text of the first booking line, as shown as the title in the journal and in listBookingsV1.
  • totalAmount number example: 2500
    Booking amount in CHF: the sum of all credit lines (delimitation lines included), as in listBookingsV1.
  • documentIds array of string
    Ids of the documents attached to the booking.
  • internalComment string example: Paid by e-banking
    Internal comment as entered in KLARA. It may contain HTML; escape it before rendering.
  • lines array of PublicApiBookingLine
    All debit and credit lines, in the order KLARA shows them, including VAT lines and delimitation lines.
    show fields

    Array of PublicApiBookingLine.

    • id integer (int64) format: int64 example: 10230
      Id of the line, as used by connectedLines.
    • accountCode integer (int32) format: int32 example: 1020
      Account number.
    • accountName string example: Bank
      Account name in the requested language.
    • side object example: DEBIT
      Side of a booking line: DEBIT or CREDIT.
    • amount number example: 2500
      Amount in CHF, always positive.
    • description string example: Rent October 2026
      Posting text of the line.
    • tags array of string
      Tags of the line.
    • bookingType object example: GENERAL_LEDGER
      Kind of line, for example GENERAL_LEDGER, AR_INVOICE or AP_PAYMENT.
    • vatRate number example: 8.1
      VAT rate of the line in percent, if it has one. With the net tax rate method the net tax rate is shown in vatRateText in parentheses.
    • vatRateText string example: 8.1%
      VAT rate as KLARA shows it, for example 8.1% or, with a net tax rate, 8.1% (6.2%).
    • foreignCurrencyAmount number example: 2300
      Amount in the foreign currency, if the line was booked in one.
    • foreignCurrency string example: EUR
      Foreign currency, if any.
    • openItemStatus object example: OPEN
      Open-item state of an invoice, payment or credit note line.
    • overdue boolean example: False
      Present whenever dueDate is set: true when the due date is before today (Europe/Zurich), as the journal marks it. Also set on lines that are already paid, so check openItemStatus (OPEN or PARTLY_PAID) for items still to be paid. Missing without a due date.
    • dueDate string (date) format: date example: 2026-11-15
      Due date of the open item.
    • paidDate string (date) format: date example: 2026-11-10
      Date the open item was paid.
    • servicePeriodFrom string (date) format: date example: 2026-10-01
      Start of the service period, if set.
    • servicePeriodTo string (date) format: date example: 2026-10-31
      End of the service period, if set.
    • lastModifiedBy string example: anna.muster@example.ch
      Who last changed the line: the e-mail address of the user, the name of an API key, or SYSTEM (automatic bookings). A line never changed shows who created it. Changes to the booking header (date, comment, documents) are not reflected.
    • lastModifiedAt string (date-time) format: date-time example: 2026-10-14T08:12:30.123Z
      When the line was last changed, in UTC; for a line never changed, when it was created.
    • references array of PublicApiBookingLineReference
      Objects the line refers to.
      show fields

      Array of PublicApiBookingLineReference.

      • type object example: CUSTOMER
        Kind of object a booking line refers to.
      • id string example: 1042
        Id of the object. Customers and suppliers (one id space): as in listCustomersV1; company bank accounts: as in listCompanyBankAccounts; bank transactions: as in listBankTransactionsV1 (unreconciled only); VAT cases: as in the VAT case list; tax-at-source cantons: KLARA's canton id; gift cards and miscellaneous partners: KLARA's fixed entry; a sub-account: the id of the sub-account of the chart of accounts; other types: KLARA's internal id.
      • category string example: cash
        Only for SUB_ACCOUNT: the kind of sub-account, for example cash, receivable, payable or tangible_asset.
      • name string example: Muster AG
        Name of the object as KLARA shows it on the line now (resolved when the booking is read, not stored at posting time), in the requested language. Missing when it could not be resolved.
    • connectedLines array of PublicApiConnectedBookingLine
      Lines of other bookings this line is connected to.
      show fields

      Array of PublicApiConnectedBookingLine.

      • type object example: RECONCILIATION
        How a booking line is connected to a line of another booking: RECONCILIATION (a payment or bank reconciliation against an open item), DELIMITATION (accrual), PREPAYMENT_CLEARING, CREDIT_NOTE_CLEARING or MAIN_LINE (the line of another booking this automatically created line was derived from, for example a VAT line booked with a payment that points to the revenue line of the invoice). A reconciliation is listed on every line involved.
      • bookingId integer (int64) format: int64 example: 4388
        Id of the connected booking.
      • lineId integer (int64) format: int64 example: 10231
        Id of the connected line within that booking; missing when the connection points to the booking as a whole.
400 bookingId is below 1.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 No booking with this id exists in the caller's company, or bookingId is not a number.

Error codes for this response (the code field of the response body):
  • booking.unknown — No booking with this id exists in the caller's company.
Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
PUT/core/v1/bookings/{id}/documentskey / tokenReplace the document attachments and document date of an existing booking.
Replaces the set of supporting-document identifiers and the document date stored on an existing accounting booking. The operation is a full replacement — pass an empty documentIds array to clear all existing attachments, or omit documentDate / set it to null to clear it. By default the operation fails when the booking's existing bookingDate falls outside the active KLARA Accounting subscription window; set ignore-unsubscripted-dates to true to bypass this guard. Tenant and company are derived from the bearer token — the booking {id} must belong to the caller's company. The caller must hold the ACCOUNTING permission on that company. The endpoint is idempotent: re-sending the same body produces the same state. Returns HTTP 200 with no body on success.
operationId

updateBookingDocumentsV1 — the method name a generated client uses.

Required permission

ACCOUNTING
Available through: Administrator, External user, Buchhalter

Parameters 2
NameDescription
id required
path integer (int64)
Internal id of the booking whose documents should be replaced. Obtain from the id field returned by POST /core/v1/bookings.
format: int64 example: 12345
ignore-unsubscripted-dates
query boolean
When true, accept the update even if the booking's bookingDate falls outside the active KLARA Accounting subscription period. Defaults to false.
default: false example: False
Request body required
Document metadata to apply to the booking. The operation is a full replacement of both documentDate and documentIds.

Prerequisite APIs — call these first to obtain valid values:
  • POST /core/v1/bookings → provides the booking id used in the URL.
  • POST /core/latest/companies/{company-id}/documents → upload the file first and use the returned documentId as an entry in documentIds. Each entry is either a numeric KLARA document id (e.g. "98765") or a KLARA document URI.
Top-level fields:
  • documentDate (string, ISO date yyyy-MM-dd, optional) — date printed on the underlying paper document. Set to null or omit to clear the existing value.
  • documentIds (array of string, optional, max 50 entries, each ≤ 512 chars) — full replacement of the attached document references. Send [] to clear.
Rules:
  • Replacement semantics — missing or empty documentIds clears all existing attachments on the booking.
  • The booking must belong to the caller's company; tenant and company are derived from the bearer token.
  • By default the booking's existing bookingDate must fall in an active KLARA Accounting subscription window; use ignore-unsubscripted-dates=true to bypass.

application/json object

  • documentDate string (date) format: date example: 2024-06-15
    Date printed on the underlying paper document (e.g. supplier invoice date). When omitted or null, the booking's existing documentDate is cleared.
  • documentIds array of string maxItems: 50
    Identifiers of supporting documents attached to the booking. Replaces the current set on the booking; pass an empty array to clear. Obtain each id by first uploading a file with POST /core/latest/companies/{company-id}/documents and then copying the returned documentId into this array.
Responses 6
200 Document attachments and date applied to the booking (or accepted as a no-op when the booking does not exist on the downstream side). no response body
400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/customers/{customerId}/open-positionskey / tokenList the open items of one customer or supplier.
Returns the open receivables (position-type=RECEIVABLE, default) or open payables (position-type=PAYABLE) of one customer or supplier of the caller's company, as shown in KLARA under Accounting > Open positions. Each item carries the amount still open at reference-date (default: today) and its history: when it was booked, which payments, credit notes or prepayments were reconciled against it, which payment reminders were sent and when the next one is planned (receivables), or when the next payment is due (payables). Obtain customerId from listCustomersV1; suppliers are customers in KLARA and use the same id. An unknown id, an id of another company, or a partner without open items returns an empty list, so check the id with listCustomersV1 if the list is unexpectedly empty. To cover all customers or suppliers, page through listCustomersV1 and call this operation once per customer. Items that reduce the balance (credit notes and prepayments) carry a negative openAmount and totalAmount, so the sum of openAmount is the net amount still owed. search-key matches the posting text (contains, case-insensitive) or, when the whole text is a date of the form dd.MM.yyyy, the due date. Sort with sort-field ID (default), DUE_DATE or OPEN_AMOUNT; items without a value come last. Uses the standard collection parameters: search-key, offset (default 0), limit (default 50, maximum 100), sort-field and sort-direction (default DESC). The number of rows matching the filters, ignoring offset and limit, is returned in the X-Total-Count header; to read everything, repeat the call with offset increased by limit until X-Total-Count is reached. Do not use listBankReconciliationOpenPositionsV1 for this purpose: it lists candidates for reconciling a bank or credit-card transaction, without reference date and without history. This is a read-only, idempotent operation without side effects. Tenant and company are derived from the bearer token and are never accepted from the URL or the request. The caller must hold the ACCOUNTING permission on the company; otherwise the endpoint returns 403.
operationId

listCustomerOpenPositionsV1 — the method name a generated client uses.

Required permission

Not established. Assume a permission is needed, and ask support if a call is rejected.

Parameters 8
NameDescription
customerId required
path integer (int64)
Id of the customer or supplier, as returned by listCustomersV1.
format: int64 min: 1 example: 37
limit
query integer
Page size. Defaults to 50; hard cap 100. Requests above the cap are rejected with 400.
min: 1 max: 100 default: 50 example: 50
offset
query integer
0-based pagination offset — the number of rows to skip before the returned page. Defaults to 0. Combine with limit to walk the full collection.
min: 0 default: 0 example: 0
position-type
query string
RECEIVABLE for the amounts the customer owes the company (default), PAYABLE for the amounts the company owes the supplier. Case-insensitive.
Allowed values: RECEIVABLE, PAYABLE
default: RECEIVABLE example: PAYABLE
reference-date
query string (date)
Date at which the items must be open, ISO yyyy-MM-dd. Items booked after this date are left out and amounts paid after it count as open. Defaults to today (Europe/Zurich). Future dates are accepted.
format: date example: 2026-06-30
search-key
query string
Free-text search. The fields searched are documented per endpoint. Matches are case-insensitive substring matches. Maximum length 256 characters.
maxLength: 256 example: müller
sort-direction
query string
Sort direction. Allowed values: ASC, DESC. Defaults to DESC.
Allowed values: ASC, DESC
default: DESC example: DESC
sort-field
query string
Field to order the result by. The accepted values are listed per endpoint; an unknown value is rejected with 400. Each endpoint documents the default it applies, chosen so that paging with offset / limit is stable.
Responses 6
200 One page of open items, ordered by sort-field. Empty array when the customer has no open items or the id is unknown. show body

application/json array of PublicApiCustomerOpenPosition

Array of PublicApiCustomerOpenPosition.

  • id integer (int64) format: int64 example: 98765
    Id of the open item (booking line). Stable; appears as bookingDetailId in the histories of other items it was reconciled with.
  • postingText string example: Invoice 1000000000007 Consulting services
    Posting text of the item, as shown in the accounting UI.
  • documentIds array of string
    Ids of the receipts attached to the booking; empty when none.
  • dueDate string (date) format: date example: 2026-07-15
    Due date of the item; null when it has none.
  • openAmount number example: 1000
    Amount still open at the requested reference-date. Negative for items that reduce the balance (credit notes, prepayments).
  • totalAmount number example: 1000
    Original amount of the item. Negative for items that reduce the balance (credit notes, prepayments).
  • bookingTypeCode object example: AR_INVOICE
    Booking type of the item, e.g. AR_INVOICE, AR_CREDITNOTE, AP_INVOICE, AP_PREPAYMENT.
  • histories array of PublicApiOpenPositionHistory
    Events of the item, oldest first, including planned ones.
    show fields

    Array of PublicApiOpenPositionHistory.

    • type object example: PAYMENT
      Kind of event in the history of an open item. CREATED: the item was booked (invoice sent for receivables, invoice date for payables). DUNNING: payment reminder or dunning level (receivables only). NEXT_PAYMENT: planned payment of an overdue payable. INVOICE, PAYMENT, PREPAYMENT, CREDITNOTE: a booking reconciled against the item.
    • happened boolean example: True
      true when the event has taken place, false for a planned event (next payment reminder, next payment).
    • happenDate string (date) format: date example: 2026-07-20
      Date of the event, or the planned date when happened is false.
    • dunningLevel object example: FRIENDLY_REMINDER
      Dunning level: FRIENDLY_REMINDER (payment reminder), FRIENDLY_REMINDER_2 (dunning level 1), FRIENDLY_REMINDER_3 (dunning level 2), ENFORCEMENT (debt enforcement).
    • documentLink string example: 4712
      Only for DUNNING events that happened: reference of the reminder document as stored by KLARA, as a rule the numeric document id (the same kind of id as documentIds); entries from older KLARA versions may carry a legacy link instead.
    • bookingDetailId integer (int64) format: int64 example: 98766
      For INVOICE, PAYMENT, PREPAYMENT and CREDITNOTE events: id of the related booking line.
    • amount number example: 500
      For reconciliation events and NEXT_PAYMENT: the amount.
400 reference-date is not an ISO date, sort-field is not one of the documented values, or a parameter is outside its bounds (customerId below 1, position-type not RECEIVABLE or PAYABLE, search-key longer than 256 characters, offset negative, limit outside 1-100, sort-direction not ASC or DESC).

Error codes for this response (the code field of the response body):
  • openposition.reference_date_invalid — reference-date was not an ISO date of the form yyyy-MM-dd. Omit it to use today.
  • request.sort_field_invalid — sort-field was not one of the values the operation documents. The message lists the accepted values.
Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
POST/core/v1/vat-clearing-reports/{year}/{quarter}key / tokenGet or recompute the VAT clearing report of a company for a given period.
Returns the VAT clearing report of the caller's company for the requested calendar year and reporting quarter (quarter, semester or yearly). When recalculate=true the report is recomputed from the current bookings and the stored CALCULATED snapshot is rewritten before being returned; this is why the operation uses POST rather than GET. When recalculate=false the latest CALCULATED snapshot is returned as-is, or — if only a SEALED snapshot exists — that one. The caller must hold the ACCOUNTING permission on the targeted company.
operationId

getVatClearingReportByQuarterV1 — the method name a generated client uses.

Required permission

ACCOUNTING
Available through: Administrator, External user, Buchhalter

Parameters 4
NameDescription
quarter required
path string
Reporting period within the year. Allowed values: Q1, Q2, Q3, Q4, S1, S2, YEAR_NET_TAX_RATE, YEAR_EFFECTIVE.
Allowed values: Q1, Q2, Q3, Q4, S1, S2, YEAR_NET_TAX_RATE, YEAR_EFFECTIVE
example: Q1
year required
path integer
Calendar year of the reporting period.
example: 2024
recalculate
query boolean
If true, recompute the report from current bookings and overwrite the stored CALCULATED snapshot before returning. Defaults to false.
default: false example: False
Accept-Language
header string
Preferred language for localized labels in the response. Examples: de-CH, de, fr-CH, it-CH, en.
example: de-CH
Responses 6
200 The VAT clearing report. show body

application/json VatClearingReport

  • id integer (int64) format: int64 example: 987
    Internal id of the report.
  • codeBoxes array of VatClearingReportCodeBox
    Code boxes that compose the VAT statement.
    show fields

    Array of VatClearingReportCodeBox.

    • id integer (int64) format: int64 example: 1234
      Internal id of the code box.
    • code string example: 302
      Code of the box on the VAT statement.
    • value number example: 12345.67
      Computed amount of the box.
    • description string example: Steuerbarer Umsatz
      Localized description of the box.
    • editable boolean example: False
      Whether the value of this box is editable by the user.
    • editableDescription boolean example: True
      Whether the description of this box is editable by the user.
    • rate number example: 8.1
      VAT rate applied to this code box, in percent.
  • status object example: CALCULATED
    Current status of a VAT clearing report.
  • year integer (int32) format: int32 example: 2024
    Calendar year of the reporting period.
  • period object example: Q1
    Reporting period of a VAT clearing report.
  • correctionCount integer (int32) format: int32 example: 0
    Number of booking corrections detected versus the sealed snapshot.
  • formerVatRateReleaseDate string (date) format: date example: 2023-12-31T00:00:00Z
    Release date of the former VAT rates that still apply to a part of the period.
  • newVatRatesReleased boolean example: False
    Whether new VAT rates have been released and apply to part of the period.
  • periodFrom string (date) format: date example: 2024-01-01T00:00:00Z
    Start date of the reporting period.
  • periodTo string (date) format: date example: 2024-03-31T00:00:00Z
    End date of the reporting period.
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated

Accounting Interface1

POST/core/latest/payroll-interface-filekey / tokenReturn payroll interface file
Return the payroll accounting interface file for a given salary run or payslips in CSV or JSON format
operationId

generatePayrollInterfaceFile — the method name a generated client uses.

Required permission

ACCOUNTING_INTERFACE
Available through: Administrator, External user, Mitarbeiter und Lohn

Parameters 3
NameDescription
file-format
query object
File format
payslip-ids
query string
List of payslip ids, separate by comma
example: 1,2,3,4
salary-run-id
query integer
Salary run id
example: 1
Responses 7
200 Return the payroll accounting interface file for a given salary run or payslips in CSV or JSON format show body

application/octet-stream any

400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated

Finance12

GET/core/v1/company-bank-accountskey / tokenList the bank accounts of the authenticated company.
Returns the bank accounts of the company resolved from the bearer JWT, optionally filtered by business type. The caller must hold the FINANCE_BANK_ACCOUNT permission on the target company. The result is sorted by Swiss-bank name then IBAN. This operation is idempotent and read-only — it can be safely retried.
operationId

listCompanyBankAccounts — the method name a generated client uses.

Required permission

FINANCE_BANK_ACCOUNT
Available through: Administrator, External user, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen

Parameters 2
NameDescription
iban-number
query string
Optional IBAN filter. When provided, the response contains the single matching bank account (returned as a one-element array for a uniform response shape) or HTTP 404 if no account exists with that IBAN. Spaces in the IBAN are tolerated. When provided, the type parameter is ignored.
example: CH7109000000252946932
type
query string
Optional business-type filter. Allowed values: AR (Accounts Receivable), AP (Accounts Payable), HR (Salary / HR payments). When omitted, all bank accounts are returned. Ignored when iban-number is provided.
Allowed values: AR, AP, HR
example: AR
Responses 6
200 Bank accounts of the authenticated company. show body

application/json array of CompanyBankAccount

Array of CompanyBankAccount.

  • id integer (int64) format: int64 example: 1
    Internal database id of the bank account.
  • companyId integer (int64) format: int64 example: 1
    KLARA company id this bank account belongs to.
  • shortName string example: PostFinance CHF
    User-defined short label for the bank account.
  • ibanNumber string example: CH71 0900 0000 2529 4693 2
    IBAN in pretty-printed form (groups of 4 characters).
  • qrIbanNumber string example: CH44 3199 9123 0008 8901 2
    QR-IBAN (only set when markedQrIban is true).
  • currency string example: CHF
    ISO-style currency code. Allowed values: CHF, CHW.
  • wirAcceptanceRate number example: 0
    WIR acceptance percentage (0–100).
  • markedHRPayment boolean example: False
    Default account for salary / HR payments.
  • markedARAccount boolean example: True
    Default account for Accounts Receivable.
  • markedAPAccount boolean example: False
    Default account for Accounts Payable.
  • markedPaymentSlip boolean example: False
    ESR / red payment-slip enabled.
  • markedQrInvoice boolean example: True
    QR-invoice payment enabled.
  • markedQrIban boolean example: False
    QR-IBAN flow enabled.
  • participantNumber string example: 01-12345-6
    ESR participant number (only when markedPaymentSlip).
  • customerIdentificationNumber string example: 123456
    ESR customer identification number (only when markedPaymentSlip and not PostFinance).
  • printParticipantNumber boolean example: False
    Print the participant number on payment slips.
  • printBankAddress boolean example: False
    Print the bank address on payment slips.
  • printBeneficiary boolean example: False
    Print the beneficiary on payment slips.
  • esrPrintingType string example: INTEGRATE
    ESR printing type. Allowed values: INTEGRATE, SEPARATE.
  • contractNumber string example:
    Bank contract number.
  • batchBooking string example: DEFAULT
    Batch-booking preference. Allowed values: DEFAULT, ACTIVE, INACTIVE.
  • debitAdvice string example: DEFAULT
    Debit-advice preference. Allowed values: DEFAULT, NO_ADVICE, SINGLE_ADVICE, ADVICE_WITHOUT_DETAILS, ADVICE_WITH_DETAIL.
  • notMarkedSalaryPayments boolean example: False
    When true, exclude this bank account from salary-payment runs.
  • swissBank object
    Resolved Swiss-bank master-data record (name, address, BCNR). May have empty fields when the IBAN's clearing number does not match a known Swiss bank.
    show fields
    • id integer (int64) format: int64 example: 100
      Internal Swiss-bank master-data id.
    • group string example: 1
      Master-data group code.
    • bankClearingNumber string example: 100
      Bank clearing number (BCNR).
    • branchId string example: 1
      Branch identifier.
    • newBankClearingNumber string example:
      Successor BCNR if the bank has been replaced.
    • sicNumber string example: 100000
      SIC member number.
    • headOfficeNumber string example: 100
      Head-office BCNR.
    • bankClearingType string example: 1
      Bank-clearing classification code.
    • euroSic string example:
      SIC participation in EUR.
    • language string example: de
      Master-data language code.
    • shortName string example: PostFinance AG
      Bank short name.
    • name string example: PostFinance AG
      Bank legal name.
    • address string example: Mingerstrasse 20
      Bank street address.
    • postalAddress string example: Postfach
      Postal address (PO Box).
    • place string example: Bern
      City / locality.
    • phone string example: +41 58 338 25 00
      Bank phone number.
    • fax string example:
      Bank fax number.
    • dailingCode string example: 41
      International dialling code.
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/invoiceskey / tokenSearch and page the invoices of the authenticated company.
Returns a page of the company's invoices, newest first, with optional free-text search (search-key) and status filter (status). Each row is an InvoiceSummary — a flat projection carrying the identity, amounts, dates, customer and both status fields. Retrieve the full document, including order items and attachments, with GET /core/v1/invoices/{id}.

Paging. Walk the collection with offset and limit: iterate offset=0, limit, 2×limit, … until a response returns fewer than limit rows. Ordering defaults to sort-field=ID, sort-direction=DESC, which is unique per row and therefore stable across pages — if you sort by a non-unique field instead (for example LAST_MODIFIED), rows sharing a value may shift between pages.

The two status fields mean different things. status on a row is the invoice document status; bookingStatus is the accounting payment state of its open position, supplied by an internal service. A fully paid invoice reads status: INVOICED with bookingStatus: PAID.

The status query parameter is the KLARA invoice-overview filter, not an equality filter on the row's status field. It matches on both the document status and the payment state, exactly as the KLARA invoice list does:
  • DRAFT, CANCELLED — document status only.
  • INVOICED, SENT — invoiced and still open.
  • OPEN — invoiced or paid, with bookingStatus=OPEN. Rows come back reading status: INVOICED or PAID, so do not expect the filter value to be echoed in the row.
  • PAID — bookingStatus of PAID or PARTLY_PAID.
  • CLEARED — bookingStatus of CLEARED or PARTLY_CLEARED (credit notes).
Use booking-status to filter on the payment state precisely. It matches the row's bookingStatus field and nothing else, accepts the full set — including PARTLY_PAID and PARTLY_CLEARED, which status cannot express — and combines with status: ?status=INVOICED&booking-status=OPEN is the exact way to ask for "invoiced and not yet paid". Invoices that carry no booking at all (DRAFT, cancelled) have no payment state and are excluded whenever booking-status is given.

Two further behaviours worth knowing. Invoices whose order has been archived are excluded. And status=OPEN — only that one value — applies its payment-state check after the page is cut, so such a page can contain fewer than limit rows while the offsets stay stable; keep paging rather than treating a short page as the end. booking-status=OPEN does not behave that way: it is part of the query, so a short page really is the last page. Prefer it.

Read-only and idempotent. Authentication is API key + bearer JWT; the caller must hold the FINANCE permission on the company resolved from the JWT, otherwise the endpoint returns 403.
operationId

listInvoices — the method name a generated client uses.

Required permission

FINANCE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 7
NameDescription
booking-status
query string
Payment-state filter, matched against the row's bookingStatus field. Allowed values: OPEN, PARTLY_PAID, PAID, PARTLY_CLEARED, CLEARED. Independent of status and combinable with it. Invoices without a booking are excluded. When omitted, invoices in every payment state are returned.
Allowed values: OPEN, PARTLY_PAID, PAID, PARTLY_CLEARED, CLEARED
example: OPEN
limit
query integer
Page size. Defaults to 50; hard cap 100. Requests above the cap are rejected with 400.
min: 1 max: 100 default: 50 example: 50
offset
query integer
0-based pagination offset — the number of rows to skip before the returned page. Defaults to 0. Combine with limit to walk the full collection.
min: 0 default: 0 example: 0
search-key
query string
Free-text search. The fields searched are documented per endpoint. Matches are case-insensitive substring matches. Maximum length 256 characters.
maxLength: 256 example: müller
sort-direction
query string
Sort direction. Allowed values: ASC, DESC. Defaults to DESC.
Allowed values: ASC, DESC
default: DESC example: DESC
sort-field
query string
Field to order the result by. The accepted values are listed per endpoint; an unknown value is rejected with 400. Each endpoint documents the default it applies, chosen so that paging with offset / limit is stable.
status
query string
Invoice-overview status filter. Allowed values: DRAFT, INVOICED, SENT, PAID, OPEN, CLEARED, CANCELLED. When omitted, invoices in every status are returned. See the operation description — this is not a plain equality filter on the row's status field.
Allowed values: DRAFT, INVOICED, SENT, PAID, OPEN, CLEARED, CANCELLED
example: OPEN
Responses 6
200 A page of invoices. Empty array when nothing matches. show body

application/json array of InvoiceSummary

Array of InvoiceSummary.

  • id integer (int64) format: int64 example: 42
    Numeric primary key. Pass this to GET /core/v1/invoices/{id} to retrieve the full document.
  • invoiceCode string example: INV-2026-001
    Human-readable invoice code, unique per company.
  • invoiceNumber integer (int64) format: int64 example: 2026001
    Sequential invoice number.
  • orderNumber integer (int32) format: int32 example: 377
    Order number of the invoice's order.
  • subject string example: Consulting Q2 2026
    Invoice subject / title.
  • status string example: INVOICED
    Invoice document status. One of DRAFT, INVOICED, PAID, CANCELLED. Note that SENT is reported as INVOICED for non-negative amounts, and that the status query parameter additionally accepts the payment-state values OPEN, PAID and CLEARED, which are matched against bookingStatus rather than against this field.
  • bookingStatus string example: OPEN
    Accounting payment state of the invoice's open position, from an internal service: OPEN, PARTLY_PAID, PAID, PARTLY_CLEARED or CLEARED. Absent for invoices that carry no booking (DRAFT, cancelled).
  • invoiceType string example: MANUAL
    Invoice type: MANUAL or RECURRING.
  • amount number example: 500
    Invoice total, on the same basis as Invoice.amount.
  • documentDate string (date) format: date example: 2026-05-28
    Invoice document date (ISO 8601).
  • paymentDate string (date) format: date example: 2026-06-27
    Payment due date (ISO 8601).
  • bookingDueDate string (date) format: date example: 2026-06-27
    Booking due date returned by accounting.
  • customerId integer (int64) format: int64 example: 40
    Id of the customer the invoice was issued to.
  • customerName string example: A. Bassi AG
    Display name of the customer — the company name for a COMPANY customer, first and last name for a PERSON.
  • customerType string example: COMPANY
    Customer type: COMPANY or PERSON.
  • bookingNumbers string example: 1982
    Accounting booking numbers created for this invoice, comma-separated. Empty while the invoice is not booked.
  • lastModified string (date-time) format: date-time
    Last modification timestamp.
400 Invalid filter or paging parameter — an unknown status, an unknown sort-field, a sort-direction other than ASC/DESC, a negative offset, or a limit outside 1–100.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
POST/core/v1/invoiceskey / tokenCreate a new KLARA invoice for the authenticated company.
Creates a new invoice for an existing customer under the company resolved from the bearer JWT. The request body's id must be 0 or omitted — this endpoint does not support updating existing invoices.

Typical flow:
  1. Call GET /core/v1/invoices/next-invoice-number to obtain the next invoice number.
  2. (Optional) List existing invoices with GET /core/v1/invoices — filter by status and page with offset/limit — to check what is already booked before creating another.
  3. Look up the customer via GET /core/v1/customers (with search filters and pagination).
  4. Look up company bank accounts via GET /core/v1/company-bank-accounts.
  5. Search articles via GET /core/latest/articles/search or GET /core/latest/articles/article-numbers to populate order items.
  6. (Optional) Look up open positions via GET /core/v1/bank-reconciliation/open-positions to reconcile prepayments / credit notes.
  7. Call GET /core/v1/orders/next-order-number to obtain the next order.orderNumber (required).
  8. (Optional) Call GET /core/latest/company-configuration/including-vat to determine the company default for usingVAT.
  9. Build the invoice payload with order items.
  10. Call this endpoint with status=INVOICED to save and book, or status=DRAFT to save without booking.
On status INVOICED or SENT the invoice is also booked into KLARA accounting and inventory transactions are created. This endpoint does not send/deliver the invoice (no email/ePost/eBill/print&send), regardless of postMethod or a SENT status; retrieve the PDF via POST /core/v1/invoices/{id}/printed-document and deliver it yourself. The caller must hold the FINANCE permission on the target company.

Status is caller-controlled. The KLARA GUI keeps an invoice in DRAFT until the user posts it in the final step; via the API you choose — send status=DRAFT to save without booking, or status=INVOICED (or SENT) to book immediately. A DRAFT can be finalized later with PUT /core/v1/invoices (status=INVOICED).

Important — booking is created without a printed invoice. When you book via this endpoint (status=INVOICED/SENT), the accounting booking is created but no PDF is rendered or stored — the invoice and its booking have no printed document (unlike the GUI, which renders, stores and books in one step). To attach the printed invoice, run two follow-up calls: (1) POST /core/v1/invoices/{id}/printed-document to render the PDF and store its printedFileId on the invoice, then (2) PUT /core/v1/bookings/{id}/documents to link that printedFileId (in documentIds) to the booking returned in bookingNumbers.
operationId

createInvoice — the method name a generated client uses.

Required permission

FINANCE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 2
NameDescription
confirmDontMindClosingFiscalYear
query boolean
When true, allows save/booking even if the document date falls inside a closing or closed fiscal year. Defaults to false.
default: false example: False
Accept-Language
header string
Preferred response language as a BCP-47 tag (e.g. en, de, fr, it). Forwarded to an internal service.
example: en
Request body required
Creates a new invoice for an existing customer. The id field must be 0 or omitted. This endpoint does not support updating existing invoices.

Prerequisite APIs (call these first):
  • GET /core/v1/invoices/next-invoice-number → provides invoiceCode and invoiceNumber (the next available invoice number for the company).
  • GET /core/v1/customers?search-key=...&limit=... → provides order.customer.id, order.customer.company (with addresses, emails), and order.customer.customerType.
  • GET /core/v1/company-bank-accounts → provides ibanNumberCHF / ibanNumberCHW for payment accounts.
  • GET /core/latest/articles/search?keyword=... → search articles by keyword for the autocomplete; provides orderItems[].itemNumer, description, price, vat, unit.
  • GET /core/latest/articles/article-numbers?article-numbers=... → fetch full article data by article number(s) to fill orderItems[].
  • GET /core/latest/articles/{article-id}/article-set-items → expands article set/bundle into component line items for orderItems[].
  • GET /core/v1/bank-reconciliation/open-positions → lists customer's open prepayments / credit notes that can be reconciled; provides openPositionsLinkedToInvoice[].bookingTypeCode, bookingDetailUri, partialPaymentAmount.
  • GET /core/v1/orders/next-order-number → provides order.orderNumber (required); each call advances the in-memory counter — call immediately before creating the invoice, not speculatively.
  • (Optional) GET /core/latest/company-configuration/including-vat → provides the company-level default for usingVAT; returns false when no configuration record exists.
  • printedFileId (String, server-assigned) — populated automatically by POST /core/v1/invoices/{id}/printed-document after PDF generation; omit on creation.

Field names that look like typos but are not. The following names are the literal wire field names accepted by the backend. The corrected-looking spellings are not accepted:
  • orderItems[].itemNumer — article number (not itemNumber). The article lookup endpoints expose the same value under the name articleNumber. Aligning the two names is tracked separately; until then itemNumer is the only accepted spelling.
  • ...address.homeNumber — house number (not houseNumber).
  • ...city.cityName18 / cityName27 — the 18- and 27-character city name variants of the Swiss Post address directory. Neither is a leftover.

Top-level fields:
  • id (long, required) — must be 0 for creation.
  • invoiceCode (String, required) — unique invoice code; obtain from GET /core/v1/invoices/next-invoice-number.
  • orderType (String, required) — must be INVOICE.
  • status (String, required) — determines booking behavior (not delivery). Allowed: DRAFT (saves without booking), INVOICED (saves and books into accounting), SENT (saves and books; does not send/deliver the invoice).
  • postMethod (String, optional) — distribution channel recorded on the invoice only; this endpoint does not deliver the invoice. Allowed: A_POST, B_POST, SEND_EMAIL, PRINT_AND_MANUAL_SEND, EPOST, EBILL.
  • documentDate (date, required) — invoice issue date, format yyyy-MM-dd.
  • paymentDate (date, required) — payment due date, must be on or after documentDate.
  • ibanNumberCHF (String, conditional) — CHF IBAN for payment; required when booking is triggered.
  • ibanNumberCHW (String, optional) — WIR IBAN for combined payments.
  • wirAcceptanceRate (int, optional) — WIR acceptance percentage (0–100).
  • invoiceType (String, required) — MANUAL or RECURRING.
  • amount (BigDecimal, required) — total invoice amount over all items. Caller-supplied; not recomputed by the server. With usingVAT=false this is net + VAT; with usingVAT=true it is the sum of the gross item amounts.
  • usingVAT (boolean) — GUI checkbox "VAT included in amount of each item". Controls whether item price/amount are VAT-inclusive (true, gross) or VAT-exclusive (false, net). It does not switch VAT on/off (that is the company's VAT registration). Use GET /core/latest/company-configuration/including-vat for the company default. See VAT handling below.
  • usingExportVat (boolean, optional) — GUI checkbox "Export". When true, the invoice is an export: set every orderItems[].vat.rate to 0 so no VAT is charged. Defaults to false.
  • subject (String, optional) — invoice subject/title.
  • ourReference / yourReference (String, optional) — reference texts.
  • companyCityAndDate (String, optional) — city and date line printed on invoice.
  • closeAndSignature (String, optional) — closing text and signature block.
  • printedFileId (String, optional) — document ID of uploaded PDF from partner system.

Nested fields — order (required):
  • order.id (long) — must be 0 for new orders.
  • order.orderNumber (int, required) — unique order number; must be > 0 (validated). Obtain from GET /core/v1/orders/next-order-number (not idempotent — each call advances the counter).
  • order.orderName (String, optional) — order description.
  • order.companyId (long, required) — company ID from bearer token scope.
  • order.customer (object, required) — existing customer; obtain from GET /core/v1/customers. Must include customer.id, customer.company (with addresses), and customer.customerType (COMPANY or PERSON).

Nested fields — orderItems[] (required, at least 1):
  • orderItems[].position (int) — line item position (1-based).
  • orderItems[].itemNumer (String) — article number. The field name is itemNumer, not itemNumber — this spelling is the literal wire field name of the KLARA order-management model and is what the backend accepts. It is not a typo in this documentation. The article lookup endpoints expose the same value under the name articleNumber.
  • orderItems[].description (String) — item description.
  • orderItems[].quantity (double) — quantity.
  • orderItems[].unit (String) — unit of measure (e.g. Unit, Hour).
  • orderItems[].price (double) — unit price (negative for credit notes). VAT-inclusive (gross) when usingVAT=true, VAT-exclusive (net) when usingVAT=false. Both variants are available from the article lookup APIs.
  • orderItems[].discount (double) — discount percentage.
  • orderItems[].amount (double) — line total = quantity × price × (1 − discount/100), rounded to the nearest 0.05. Gross or net following usingVAT (same basis as price).
  • orderItems[].tag (String, not persisted with the invoice, but used by the accounting booking of this same request) — the order_item table has no column for it, but the value you send becomes the tags of the line's booking position. Required when status triggers booking (INVOICED/SENT): without it the booking is rejected with 400 model.invalid ("The field tags is mandatory.") and the invoice is not stored. Send the article's accountingTags joined with a comma, the way KLARA builds it for recurring invoices.
  • orderItems[].vatCase (String, not persisted with the invoice, but used by the accounting booking of this same request) — the vatCaseCode of a sales VAT case (applicability REVENUE) from GET /core/latest/vat-cases, for example TAXABLE_SUPPLY, SUPPLY_WITH_OPTION_ART_22 or TAX_EXEMPT_SUPPLY. For a company that reports VAT with effective clearing, any other value, including a purchase case, is rejected by the booking with 400 model.invalid and the invoice is not stored. For a company that reports VAT with effective clearing or net tax rates it becomes the VAT case of the line's booking position.
  • orderItems[].articleType (String, not persisted with the invoice, but used by the accounting booking of this same request) — PRODUCTION, PREPAYMENT, SERVICE. Selects the account: PREPAYMENT books the line to the prepayment receivables account, any other value or none to revenue.
  • Lines that differ in tag, vatCase or articleType are booked as separate positions.
  • orderItems[].vat (object) — VAT details: vatCode, rate, description, masterId. For an export invoice (usingExportVat=true) set rate=0 and the export/zero vatCode. This is the VAT code that is actually stored — the sibling orderItems[].vatCode is a convenience mirror that is not persisted, so do not send the two with conflicting values.
  • orderItems[].id (long) — must be 0 for new items.

Nested fields — documentAddress / mailingAddress (optional):
  • documentAddress (object) — address block printed on the invoice document. Derived from the customer when omitted; send it only to print an address other than the customer's default.
  • documentAddress.customerId (long) — customer the address belongs to.
  • documentAddress.customerType (String) — COMPANY or PERSON.
  • documentAddress.address (object) — the postal address to print (same shape as customer.company.addresses[], including homeNumber and city.cityName18/cityName27).
  • documentAddress.companyName / personFirstName / personLastName / salutation (String) — recipient name parts printed above the address.
  • mailingAddress (object) — address used for postal delivery, same shape as documentAddress. Both are resolved against the customer's stored addresses and referenced by id; the invoice does not keep a private copy of the values sent.

VAT handling — the server does not recalculate amounts. Unlike the KLARA GUI (which recomputes line amounts, VAT and totals whenever you toggle the "VAT included in amount of each item" or "Export" checkbox), this endpoint stores the amounts you send verbatim and does not recalculate them. It does check the VAT of each line: an orderItems[].vat.rate that is not the rate of its vat.vatCode on the booking date is rejected with 400 invoice.vat_rate_mismatch. Omit vat.rate and the server fills it in from the code and the date. Send orderItems[].price, orderItems[].amount, orderItems[].vat and the document amount already consistent with the two flags:
  • usingVAT=false (VAT-exclusive) — price/amount are net; document amount = net + VAT.
  • usingVAT=true (VAT-inclusive) — price/amount are gross (VAT already inside); document amount = sum of gross item amounts.
  • usingExportVat=true (export) — set every orderItems[].vat.rate to 0; VAT = 0 and document amount = sum of net item amounts.
To reproduce the GUI figures exactly: per line amount = round0.05(quantity × price × (1 − discount/100)); VAT per rate group = amount × rate/100 when VAT-exclusive, or amount × (rate/100) / (1 + rate/100) when VAT-inclusive — each rounded to the nearest 0.05 (Swiss commercial rounding). Article unit prices for the inclusive, exclusive and export cases come from the article lookup APIs above (each article exposes both a VAT-inclusive and a VAT-exclusive price); pick the one matching usingVAT/usingExportVat.

Nested fields — attachments[] (optional):
  • attachments[].fileId (String) — document file ID uploaded via partner system.
  • attachments[].orderDetailId (long) — set to 0 for new invoices.
  • attachments[].id (long) — set to 0 for new attachments.

Nested fields — openPositionsLinkedToInvoice[] (optional, for reconciliation):
  • openPositionsLinkedToInvoice[].bookingTypeCode (String) — AR_PREPAYMENT or AR_CREDITNOTE.
  • openPositionsLinkedToInvoice[].bookingDetailUri (String) — internal URI of the booking detail to reconcile (format: /…/{tenant-id}/companies/{companyId}/bookings/{bookingId}/booking-details/{detailId}).
  • openPositionsLinkedToInvoice[].partialPaymentAmount (BigDecimal) — amount to offset from this open position.

Validation rules:
  • paymentDate must be on or after documentDate (when amount > 0).
  • order.orderNumber must be > 0.
  • invoiceCode must be unique within the company.
  • status must not be null.
  • IBAN format is validated when provided.
  • When status is SENT, credit notes (negative total) are not allowed.
  • Each orderItems[].tag must be present when status triggers booking (INVOICED/SENT); otherwise the request fails with 400 model.invalid and nothing is stored.

Server-managed fields (ignored on input, populated on output): vatDate, lastModified, createDate, bookingDueDate, bookingNumbers, businessCaseId, bookingStatus, bookingMessage, bookingSealed, fiscalYearHasCreatedAuto, createBy, issuedDate.

application/json InvoiceCreateRequest

  • id integer (int64) format: int64 example: 0
    Invoice id. Must be 0 or omitted when creating a new invoice. This endpoint only supports creation; updating an existing invoice is not supported.
  • orderType string default: INVOICE example: INVOICE
    Polymorphic discriminator. Must be INVOICE. Allowed values: INVOICE.
  • status string example: INVOICED
    Invoice status. Allowed values: DRAFT, INVOICED, SENT, PAID, CANCELLED. Required. Status INVOICED or SENT triggers accounting booking.
  • invoiceCode string required maxLength: 64 pattern: \S example: INV-2026-001
    Human-readable invoice code. Required and unique per company.
  • invoiceNumber integer (int64) format: int64 example: 2026001
    Sequential invoice number, typically obtained from GET /invoices/next-invoice-number.
  • documentDate string (date) format: date example: 2026-05-28
    Invoice document date (ISO 8601). Required when amount is greater than 0. Must fall inside the company's active Order Management subscription period.
  • paymentDate string (date) format: date example: 2026-06-27
    Payment due date (ISO 8601). Required when amount is greater than 0. Must be on or after documentDate.
  • deliveryDate string (date) format: date example: 2026-05-25
    Service delivery date (ISO 8601).
  • issuedDate string (date) format: date example: 2026-05-28
    Date the invoice was issued (ISO 8601).
  • servicePeriodFrom string (date) format: date example: 2026-05-01
    Service period start date (ISO 8601).
  • servicePeriodTo string (date) format: date example: 2026-05-31
    Service period end date (ISO 8601).
  • servicePeriodPattern string maxLength: 32 example: MONTHLY
    Service period pattern label (e.g. MONTHLY, YEARLY).
  • vatDate string (date) format: date
    VAT date. Server-managed (read-only).
  • bookingDueDate string (date) format: date
    Booking due date returned by accounting. Server-managed (read-only).
  • lastModified string (date-time) format: date-time
    Last modification timestamp. Server-managed (read-only).
  • createDate string (date-time) format: date-time
    Creation timestamp. Server-managed (read-only).
  • amount number example: 1080
    Invoice total. When usingVAT=false (VAT-exclusive items) this is the gross total = net + VAT; when usingVAT=true (VAT-inclusive items) it is the sum of the gross item amounts (VAT already inside). Caller-supplied — the server does not recompute it.
  • usingVAT boolean default: false example: True
    Controls whether each item price/amount is VAT-inclusive (gross) or VAT-exclusive (net). This is the GUI checkbox "VAT included in amount of each item". true = amounts already include VAT (INCLUDE_VAT); false = VAT is added on top of the net amounts (EXCLUDE_VAT). It does not turn VAT on or off — whether VAT applies at all is governed by the company's VAT registration. Use GET /core/latest/company-configuration/including-vat for the company default. The server stores the amounts you send verbatim and does not recompute them from this flag — send price/amount consistent with the chosen mode (see the create operation's VAT-handling notes).
  • usingExportVat boolean default: false example: False
    Export invoice flag — the GUI "Export" checkbox. When true, the invoice is treated as an export: every orderItems[].vat.rate must be 0 (export/zero VAT code), so no VAT is charged. When false (default) the items' normal VAT rates apply. The server does not recompute item VAT from this flag — set the per-item VAT accordingly.
  • hasCompanyVat boolean example: True
    Whether the company is liable for VAT. Leave this out. The server derives it from the company's VAT registration for the invoice's effective VAT date (deliveryDate when set, otherwise documentDate) and a derived value always wins over a value sent here. It is documented only because it is accepted, and because sending false on a VAT-registered company used to book every position at 0% while returning 200 — this field is the master switch for VAT at booking time, ahead of any per-line VAT code. It is only consulted when the company has no VAT configuration for that date, where it cannot be derived at all.
  • subject string maxLength: 1024 example: Invoice 2026-001
    Free-text invoice subject.
  • closeAndSignature string maxLength: 4096 example: Thank you for your business.
    Free-text closing remarks / signature block.
  • ourReference string maxLength: 128 example: ACC-2026
    Internal sender reference.
  • yourReference string maxLength: 128 example: PO-9981
    Customer-side reference (e.g. PO number).
  • companyCityAndDate string maxLength: 256 example: Zurich, 28.05.2026
    Header line such as 'Zurich, 28.05.2026'.
  • postMethod string example: SEND_EMAIL
    Distribution channel recorded on the invoice. Stored only — creating an invoice does not deliver it (no email/ePost/eBill/print&send). Allowed values: A_POST, B_POST, SEND_EMAIL, PRINT_AND_MANUAL_SEND, EPOST, EBILL.
  • delivery string maxLength: 64 example: DHL
    Delivery method label (free text).
  • ibanNumberCHF string example: CH9300762011623852957
    CHF IBAN for payment. Validated by downstream service.
  • ibanNumberCHW string example: CH9300762011623852957
    WIR-franc IBAN for payment.
  • wirAcceptanceRate number example: 0
    WIR acceptance percentage.
  • referenceNumber string maxLength: 64 example: 21 00000 00003 13947 14300 09017
    QR / ISR reference number.
  • qrInvoice boolean default: false example: True
    When true, the invoice is rendered/booked as a Swiss QR-invoice. Defaults to false.
  • fromAutoInvoicing boolean default: false example: False
    Indicates the invoice was generated by auto-invoicing. Defaults to false.
  • fromInvoiceRun boolean default: false example: False
    Indicates the invoice was produced by a recurring invoice run. When true, accounting booking and inventory transactions are skipped. Defaults to false.
  • invoiceType string example: MANUAL
    Invoice type. Allowed values: MANUAL, CREDIT_DEBIT.
  • originDistributionMethod string example: SEND_EMAIL
    Origin distribution method. Allowed values: A_POST, B_POST, SEND_EMAIL, PRINT_AND_MANUAL_SEND, EPOST, EBILL.
  • templateId integer (int64) format: int64 example: 0
    Template id used to create this invoice.
  • runHistoryId integer (int64) format: int64 example: 0
    Recurring invoice run history id.
  • settledAmount number example: 0
    KLARA-Pay settled amount (online shop only).
  • bookingNumbers string
    Accounting booking-number string. Server-managed (read-only).
  • businessCaseId integer (int64) format: int64
    Accounting business case id. Server-managed (read-only).
  • bookingStatus string
    Booking status (e.g. OPEN, PARTIAL, PAID). Server-managed (read-only).
  • bookingMessage string
    Optional booking error/info code (e.g. INVALID_SUBSCRIPTION_FOR_ACCOUNTING). Server-managed (read-only).
  • bookingSealed boolean
    Whether the booking has been finalized. Server-managed (read-only).
  • fiscalYearHasCreatedAuto boolean
    Whether a fiscal year was auto-created during booking. Server-managed (read-only).
  • createBy string
    Server-assigned audit user (token subject). Server-managed (read-only).
  • order object required
    The order header the invoice belongs to. Required. Every invoice is created together with its order — send id=0 and a fresh orderNumber.
    show fields
    • id integer (int64) format: int64 example: 0
      Order id. Must be 0 or omitted for a new order.
    • orderNumber integer (int32) required format: int32 example: 2026001
      Order number, unique within the company. Required and must be greater than 0. Obtain it from GET /core/v1/orders/next-order-number — that endpoint is not idempotent, each call advances the counter.
    • orderName string example: Consulting Q2 2026
      Free-text order name.
    • companyId integer (int64) required format: int64 example: 12345
      Owning KLARA company id — must match the company resolved from the bearer token. Required.
    • customer object required
      The invoice recipient. Must be an existing customer — look it up with GET /core/v1/customers and send the returned block back unchanged. Populate company when customerType is COMPANY, or person when it is PERSON.
      show fields
      • id integer (int64) required format: int64 example: 50123
        Customer id of an existing customer. Required.
      • customerType string required example: COMPANY
        Discriminator selecting company or person. Required. Allowed values: COMPANY, PERSON.
      • companyId integer (int64) format: int64 example: 12345
        Owning KLARA company id — must match the company resolved from the bearer token.
      • company object
        Company partner of an invoice customer. Present when customerType is COMPANY. Obtain it from GET /core/v1/customers and send it back unchanged.
        show fields
        • id integer (int64) format: int64 example: 50123
          Company partner id as returned by the customer lookup.
        • name string required example: Muster AG
          Company name. Required.
        • addresses array of InvoiceAddress
          Postal addresses of the company. At least the billing address must be present for the invoice to be printable.
          show fields

          Array of InvoiceAddress.

          • id integer (int64) format: int64 example: 0
            Address id. Use the id returned by the customer lookup; 0 or omitted for a new address.
          • type string required example: COMPANY
            Partner type this address belongs to. Required. Allowed values: COMPANY, PERSON.
          • addressType string required example: MAIN
            Address type label. Required. Typically MAIN or BILLING.
          • salutation string example: MALE
            Salutation of the addressee. Allowed values: MALE, FEMALE, MALE_FEMALE, FAMILY.
          • firstName string example: Hans
            First name of the addressee (person addresses).
          • lastName string example: Muster
            Last name of the addressee (person addresses).
          • companyName string example: Muster AG
            Company name of the addressee (company addresses).
          • street string example: Bahnhofstrasse
            Street name, without the house number.
          • homeNumber string example: 12a
            House number. homeNumber is the literal field name used throughout the KLARA address model — houseNumber is not accepted.
          • additionalAddress string example: c/o Finance Department
            Additional address line (c/o, department, ...).
          • addressLines string deprecated example: Bahnhofstrasse 12a
            Combined street and house number. Deprecated — use street and homeNumber instead.
          • city object required
            City of an invoice address. Obtain a complete city block from the customer lookup (GET /core/v1/customers) and send it back unchanged.
            show fields
            • id integer (int64) format: int64 example: 4247
              City id from the Swiss Post address directory.
            • addressPostcode string example: 8005
              Postcode (PLZ / NPA).
            • cityName18 string required example: Zuerich
              City name, 18-character Swiss Post variant. Required. cityName18 is the literal field name of the Swiss Post address directory (18-character abbreviation) — it is not a typo or a leftover.
            • cityName27 string required example: Zuerich
              City name, 27-character Swiss Post variant. Required.
            • onrp integer (int32) format: int32 example: 4247
              Swiss Post ONRP identifier of the locality.
            • postcodeType integer (int32) format: int32 example: 20
              Swiss Post postcode type.
            • additionalPostcode string example: 00
              Additional postcode suffix (max 2 characters).
            • basicPostcode integer (int32) format: int32 example: 8005
              Basic postcode.
            • languageCode integer (int32) format: int32 example: 1
              Swiss Post language code of the locality.
            • state object
              Canton / state of an invoice address.
              show fields

              Nesting continues beyond this level. See the specification for the complete structure.

            • country object
              Country of an invoice address.
              show fields

              Nesting continues beyond this level. See the specification for the complete structure.

          • validFrom string (date) format: date example: 2026-01-01
            Address valid-from date (ISO 8601).
          • validTo string (date) format: date example: 2026-12-31
            Address valid-to date (ISO 8601). Must be after validFrom.
        • emails array of InvoiceEmail
          E-mail addresses of the company.
          show fields

          Array of InvoiceEmail.

          • id string example: 1001
            E-mail entry id.
          • emailAddress string example: billing@muster.ch
            The e-mail address.
          • type string example: WORK
            E-mail type. Allowed values: PRIVATE, WORK, OFFICE, OTHER.
        • phones array of InvoicePhone
          Phone numbers of the company.
          show fields

          Array of InvoicePhone.

          • id integer (int64) format: int64 example: 2001
            Phone entry id.
          • phoneNumber string example: +41 44 123 45 67
            The phone number.
          • type string example: WORK
            Phone type. Allowed values: PRIVATE, OFFICE, FAX, WORK, MOBILE.
        • companyBillingAddress object
          Postal address of an invoice customer. Obtain a complete address block from GET /core/v1/customers and send it back unchanged.
          show fields
          • id integer (int64) format: int64 example: 0
            Address id. Use the id returned by the customer lookup; 0 or omitted for a new address.
          • type string required example: COMPANY
            Partner type this address belongs to. Required. Allowed values: COMPANY, PERSON.
          • addressType string required example: MAIN
            Address type label. Required. Typically MAIN or BILLING.
          • salutation string example: MALE
            Salutation of the addressee. Allowed values: MALE, FEMALE, MALE_FEMALE, FAMILY.
          • firstName string example: Hans
            First name of the addressee (person addresses).
          • lastName string example: Muster
            Last name of the addressee (person addresses).
          • companyName string example: Muster AG
            Company name of the addressee (company addresses).
          • street string example: Bahnhofstrasse
            Street name, without the house number.
          • homeNumber string example: 12a
            House number. homeNumber is the literal field name used throughout the KLARA address model — houseNumber is not accepted.
          • additionalAddress string example: c/o Finance Department
            Additional address line (c/o, department, ...).
          • addressLines string deprecated example: Bahnhofstrasse 12a
            Combined street and house number. Deprecated — use street and homeNumber instead.
          • city object required
            City of an invoice address. Obtain a complete city block from the customer lookup (GET /core/v1/customers) and send it back unchanged.
            show fields
            • id integer (int64) format: int64 example: 4247
              City id from the Swiss Post address directory.
            • addressPostcode string example: 8005
              Postcode (PLZ / NPA).
            • cityName18 string required example: Zuerich
              City name, 18-character Swiss Post variant. Required. cityName18 is the literal field name of the Swiss Post address directory (18-character abbreviation) — it is not a typo or a leftover.
            • cityName27 string required example: Zuerich
              City name, 27-character Swiss Post variant. Required.
            • onrp integer (int32) format: int32 example: 4247
              Swiss Post ONRP identifier of the locality.
            • postcodeType integer (int32) format: int32 example: 20
              Swiss Post postcode type.
            • additionalPostcode string example: 00
              Additional postcode suffix (max 2 characters).
            • basicPostcode integer (int32) format: int32 example: 8005
              Basic postcode.
            • languageCode integer (int32) format: int32 example: 1
              Swiss Post language code of the locality.
            • state object
              Canton / state of an invoice address.
              show fields

              Nesting continues beyond this level. See the specification for the complete structure.

            • country object
              Country of an invoice address.
              show fields

              Nesting continues beyond this level. See the specification for the complete structure.

          • validFrom string (date) format: date example: 2026-01-01
            Address valid-from date (ISO 8601).
          • validTo string (date) format: date example: 2026-12-31
            Address valid-to date (ISO 8601). Must be after validFrom.
        • companyBillingAddressEnabled boolean example: False
          Whether companyBillingAddress is used instead of the main address.
        • corporateIdentificationNumber string example: CHE-123.456.789
          Swiss company identification number (UID).
        • vatNumber string example: CHE-123.456.789 MWST
          VAT registration number.
        • hrNumber string example: CH-020.3.926.481-3
          Commercial register number.
        • nogaCode string example: 620100
          NOGA economic activity code.
        • companyNumber string example: C-0001
          Company number in KLARA.
        • companyOriginReference string example: ERP-4711
          External reference of the company in the partner system.
        • website string example: https://www.muster.ch
          Company website.
        • language string example: de
          Preferred correspondence language as a BCP-47 tag.
      • person object
        Natural-person partner of an invoice customer. Present when customerType is PERSON. Obtain it from GET /core/v1/customers and send it back unchanged.
        show fields
        • id integer (int64) format: int64 example: 50124
          Person partner id as returned by the customer lookup.
        • salutation string example: MALE
          Salutation. Allowed values: MALE, FEMALE, MALE_FEMALE, FAMILY.
        • firstName string required example: Hans
          First name. Required.
        • lastName string required example: Muster
          Last name. Required.
        • birthday string (date) required format: date example: 1980-04-17
          Date of birth (ISO 8601). Required by the downstream person model.
        • addressList array of InvoiceAddress
          Postal addresses of the person.
          show fields

          Array of InvoiceAddress.

          • id integer (int64) format: int64 example: 0
            Address id. Use the id returned by the customer lookup; 0 or omitted for a new address.
          • type string required example: COMPANY
            Partner type this address belongs to. Required. Allowed values: COMPANY, PERSON.
          • addressType string required example: MAIN
            Address type label. Required. Typically MAIN or BILLING.
          • salutation string example: MALE
            Salutation of the addressee. Allowed values: MALE, FEMALE, MALE_FEMALE, FAMILY.
          • firstName string example: Hans
            First name of the addressee (person addresses).
          • lastName string example: Muster
            Last name of the addressee (person addresses).
          • companyName string example: Muster AG
            Company name of the addressee (company addresses).
          • street string example: Bahnhofstrasse
            Street name, without the house number.
          • homeNumber string example: 12a
            House number. homeNumber is the literal field name used throughout the KLARA address model — houseNumber is not accepted.
          • additionalAddress string example: c/o Finance Department
            Additional address line (c/o, department, ...).
          • addressLines string deprecated example: Bahnhofstrasse 12a
            Combined street and house number. Deprecated — use street and homeNumber instead.
          • city object required
            City of an invoice address. Obtain a complete city block from the customer lookup (GET /core/v1/customers) and send it back unchanged.
            show fields
            • id integer (int64) format: int64 example: 4247
              City id from the Swiss Post address directory.
            • addressPostcode string example: 8005
              Postcode (PLZ / NPA).
            • cityName18 string required example: Zuerich
              City name, 18-character Swiss Post variant. Required. cityName18 is the literal field name of the Swiss Post address directory (18-character abbreviation) — it is not a typo or a leftover.
            • cityName27 string required example: Zuerich
              City name, 27-character Swiss Post variant. Required.
            • onrp integer (int32) format: int32 example: 4247
              Swiss Post ONRP identifier of the locality.
            • postcodeType integer (int32) format: int32 example: 20
              Swiss Post postcode type.
            • additionalPostcode string example: 00
              Additional postcode suffix (max 2 characters).
            • basicPostcode integer (int32) format: int32 example: 8005
              Basic postcode.
            • languageCode integer (int32) format: int32 example: 1
              Swiss Post language code of the locality.
            • state object
              Canton / state of an invoice address.
              show fields

              Nesting continues beyond this level. See the specification for the complete structure.

            • country object
              Country of an invoice address.
              show fields

              Nesting continues beyond this level. See the specification for the complete structure.

          • validFrom string (date) format: date example: 2026-01-01
            Address valid-from date (ISO 8601).
          • validTo string (date) format: date example: 2026-12-31
            Address valid-to date (ISO 8601). Must be after validFrom.
        • emailList array of InvoiceEmail
          E-mail addresses of the person.
          show fields

          Array of InvoiceEmail.

          • id string example: 1001
            E-mail entry id.
          • emailAddress string example: billing@muster.ch
            The e-mail address.
          • type string example: WORK
            E-mail type. Allowed values: PRIVATE, WORK, OFFICE, OTHER.
        • phoneList array of InvoicePhone
          Phone numbers of the person.
          show fields

          Array of InvoicePhone.

          • id integer (int64) format: int64 example: 2001
            Phone entry id.
          • phoneNumber string example: +41 44 123 45 67
            The phone number.
          • type string example: WORK
            Phone type. Allowed values: PRIVATE, OFFICE, FAX, WORK, MOBILE.
        • personNumber string example: P-0001
          Person number in KLARA.
        • personOriginReference string example: ERP-8150
          External reference of the person in the partner system.
        • website string example: https://www.muster.ch
          Personal website.
        • language string example: de
          Preferred correspondence language as a BCP-47 tag.
      • termsOfPayment integer (int32) format: int32 example: 30
        Payment terms in days, used to derive the default paymentDate.
      • discount number example: 0
        Default customer discount in percent.
      • priceCategory string example: STANDARD
        Price category assigned to the customer.
      • uuid string example: 0d9f4d1e-4a2b-4c8d-9f3e-1b2c3d4e5f60
        Stable external identifier of the customer.
    • invoiceGroup string example: DEFAULT
      Invoice group the order is assigned to.
    • lumpSum boolean example: False
      Whether the order is billed as a lump sum.
    • archived boolean example: False
      Whether the order is archived.
  • orderItems array of InvoiceOrderItem required
    Invoice line items. Required — at least one entry.
    show fields

    Array of InvoiceOrderItem.

    • id integer (int64) format: int64 example: 0
      Item id. Must be 0 or omitted for a new item.
    • position integer (int64) format: int64 example: 1
      Line position, 1-based.
    • itemNumer string example: P0000061123
      Article number of the item, as returned by GET /core/latest/articles/search or GET /core/latest/articles/article-numbers. The field name is itemNumer, not itemNumber. This spelling is the literal wire field name of the KLARA order-management model and is what the backend accepts — it is not a typo in this documentation. Note that the article search endpoints expose the same value under the name articleNumber.
    • description string example: Consulting services
      Item description printed on the invoice line.
    • articleExtendedDescription string example: Sprint 12, May 2026
      Additional descriptive text printed below the line.
    • quantity number example: 10
      Quantity billed.
    • unit string example: Hour
      Unit of measure.
    • price number example: 100
      Unit price. Negative for credit-note lines. VAT-inclusive (gross) when the document has usingVAT=true, VAT-exclusive (net) when usingVAT=false. Both variants are available from the article lookup endpoints.
    • discount number example: 0
      Discount on this line, in percent.
    • amount number example: 1000
      Line total = quantity x price x (1 - discount/100), rounded to the nearest 0.05 (Swiss commercial rounding). Gross or net following usingVAT, on the same basis as price.
    • posAmount number example: 1000
      Position amount as shown in the KLARA GUI. Optional; derived from amount when omitted.
    • vat object
      VAT applied to an invoice line item. The server does not recompute VAT from the document flags — send the rate that matches usingVAT / usingExportVat.
      show fields
      • id integer (int64) format: int64 example: 1
        VAT id.
      • vatCode string required example: 1
        VAT code. Required.
      • rate number example: 8.1
        VAT rate in percent. Set to 0 for export invoices (usingExportVat=true).
      • description string example: Normal rate 8.1%
        Human-readable VAT description.
      • masterId integer (int64) format: int64 example: 0
        Master data id of the VAT record.
      • companySelectedVat boolean example: False
        Whether this is a company-selected VAT.
      • sss1 boolean example: False
        Whether the first Swiss social-security special rate applies.
      • sss2 boolean example: False
        Whether the second Swiss social-security special rate applies.
      • validFrom string (date) format: date example: 2024-01-01
        VAT valid-from date (ISO 8601).
      • validTo string (date) format: date example: 2099-12-31
        VAT valid-to date (ISO 8601).
    • vatCode string example: 1
      VAT code of the line. Convenience mirror of vat.vatCode. Not persisted on this endpoint — the value that is stored comes from vat.vatCode. Do not send the two with different values: this field is silently discarded, so a mismatch results in the vat.vatCode value being booked.
    • vatCase string example: TAXABLE_SUPPLY
      VAT treatment of the line: the vatCaseCode of a sales VAT case (applicability REVENUE) from GET /core/latest/vat-cases, for example TAXABLE_SUPPLY, SUPPLY_WITH_OPTION_ART_22 or TAX_EXEMPT_SUPPLY. For a company that reports VAT with effective clearing, any other value, including a purchase case, is rejected by the booking with 400 model.invalid and the invoice is not stored. Not persisted with the invoice, but used by the accounting booking of this same request — the order_item table has no column for it. For a company that reports VAT with effective clearing or net tax rates it becomes the VAT case of the line's booking position. When it is missing, the VAT case of the article applies, which can be one the company cannot book; send it with every write that books (INVOICED/SENT).
    • articleType string example: SERVICE
      Article category. Allowed values: PRODUCTION, PREPAYMENT, SERVICE. Not persisted with the invoice, but used by the accounting booking of this same request — the order_item table has no column for it. It selects the account: PREPAYMENT books the line to the prepayment receivables account, any other value or none to revenue.
    • tag string example: 3400
      Accounting tag of the line. Not persisted with the invoice, but used by the accounting booking of this same request — the order_item table has no column for it, but the value sent here becomes the tags of the line's booking position. Required when status triggers booking (INVOICED/SENT): without it the booking is rejected with 400 model.invalid ("The field tags is mandatory.") and the invoice is not stored. Send the article's accountingTags joined with a comma, the way KLARA builds it for recurring invoices.
    • servicePeriodFrom string (date) format: date example: 2026-05-01
      Service period start for this line (ISO 8601).
    • servicePeriodTo string (date) format: date example: 2026-05-31
      Service period end for this line (ISO 8601).
    • servicePeriodPattern string example: MONTHLY
      Service period pattern label for this line.
    • specialRates string example: SSS1
      Swiss social-security special rate applied to the line. Allowed values: SSS1, SSS2.
    • articleSet string example: SET-001
      Identifier of the article set this line belongs to.
    • inventorySelections array of InvoiceInventorySelection
      Inventory selections (serial numbers, storage places) for stock-managed articles. Persisted through a dedicated path rather than with the line itself, so the serial numbers you send are validated separately — an invalid serial number fails the request even though the surrounding line is accepted.
      show fields

      Array of InvoiceInventorySelection.

      • storagePlaceId integer (int64) format: int64 example: 77
        Storage place the quantity is taken from.
      • quantity number example: 1
        Quantity taken from this storage place.
      • serialNumbers array of string
        Serial numbers of the units delivered. Duplicates within the same invoice are rejected.
  • attachments array of InvoiceAttachment
    Documents attached to the invoice.
    show fields

    Array of InvoiceAttachment.

    • id integer (int64) format: int64 example: 0
      Attachment id. Must be 0 or omitted for a new attachment.
    • orderDetailId integer (int64) format: int64 example: 0
      Id of the invoice this attachment belongs to. Must be 0 for a new invoice.
    • fileId string example: 5f8d0d55-b1a4-4d6e-9a1f-2c3b4d5e6f70
      Document id of the uploaded file.
  • openPositionsLinkedToInvoice array of InvoiceOpenPositionLink
    Open positions (prepayments, credit notes) offset against this invoice. Persisted through a dedicated path rather than with the invoice row itself.
    show fields

    Array of InvoiceOpenPositionLink.

    • bookingTypeCode string required example: AR_PREPAYMENT
      Type of the linked booking. Required. For invoice reconciliation the relevant values are AR_PREPAYMENT and AR_CREDITNOTE.
    • bookingDetailUri string required example: /luz_accounting/api/klara_tenant/companies/12345/bookings/778/booking-details/9912
      Internal URI of the booking detail to reconcile. Required. Must match the pattern /…/{tenant-id}/companies/{companyId}/bookings/{bookingId}/booking-details/{detailId}.
    • partialPaymentAmount number example: 250
      Amount to offset from this open position.
  • documentAddress object
    The address block printed on the invoice document. Omit it to let the backend derive it from the customer's main address.
    show fields
    • customerId integer (int64) format: int64 example: 50123
      Customer the address belongs to.
    • customerType string example: COMPANY
      Partner type. Allowed values: COMPANY, PERSON.
    • address object
      Postal address of an invoice customer. Obtain a complete address block from GET /core/v1/customers and send it back unchanged.
      show fields
      • id integer (int64) format: int64 example: 0
        Address id. Use the id returned by the customer lookup; 0 or omitted for a new address.
      • type string required example: COMPANY
        Partner type this address belongs to. Required. Allowed values: COMPANY, PERSON.
      • addressType string required example: MAIN
        Address type label. Required. Typically MAIN or BILLING.
      • salutation string example: MALE
        Salutation of the addressee. Allowed values: MALE, FEMALE, MALE_FEMALE, FAMILY.
      • firstName string example: Hans
        First name of the addressee (person addresses).
      • lastName string example: Muster
        Last name of the addressee (person addresses).
      • companyName string example: Muster AG
        Company name of the addressee (company addresses).
      • street string example: Bahnhofstrasse
        Street name, without the house number.
      • homeNumber string example: 12a
        House number. homeNumber is the literal field name used throughout the KLARA address model — houseNumber is not accepted.
      • additionalAddress string example: c/o Finance Department
        Additional address line (c/o, department, ...).
      • addressLines string deprecated example: Bahnhofstrasse 12a
        Combined street and house number. Deprecated — use street and homeNumber instead.
      • city object required
        City of an invoice address. Obtain a complete city block from the customer lookup (GET /core/v1/customers) and send it back unchanged.
        show fields
        • id integer (int64) format: int64 example: 4247
          City id from the Swiss Post address directory.
        • addressPostcode string example: 8005
          Postcode (PLZ / NPA).
        • cityName18 string required example: Zuerich
          City name, 18-character Swiss Post variant. Required. cityName18 is the literal field name of the Swiss Post address directory (18-character abbreviation) — it is not a typo or a leftover.
        • cityName27 string required example: Zuerich
          City name, 27-character Swiss Post variant. Required.
        • onrp integer (int32) format: int32 example: 4247
          Swiss Post ONRP identifier of the locality.
        • postcodeType integer (int32) format: int32 example: 20
          Swiss Post postcode type.
        • additionalPostcode string example: 00
          Additional postcode suffix (max 2 characters).
        • basicPostcode integer (int32) format: int32 example: 8005
          Basic postcode.
        • languageCode integer (int32) format: int32 example: 1
          Swiss Post language code of the locality.
        • state object
          Canton / state of an invoice address.
          show fields
          • id integer (int64) format: int64 example: 26
            State id.
          • code string example: ZH
            Canton code (max 3 characters).
          • description string example: Zuerich
            Canton name.
        • country object
          Country of an invoice address.
          show fields
          • id integer (int64) format: int64 example: 1
            Country id.
          • countryName string example: Switzerland
            Country name.
          • iso2Code string example: CH
            ISO 3166-1 alpha-2 code.
          • iso3Code string example: CHE
            ISO 3166-1 alpha-3 code.
          • phoneCode string example: 41
            International dialling code.
          • numericCode string example: 756
            ISO 3166-1 numeric code.
      • validFrom string (date) format: date example: 2026-01-01
        Address valid-from date (ISO 8601).
      • validTo string (date) format: date example: 2026-12-31
        Address valid-to date (ISO 8601). Must be after validFrom.
    • salutation string example: MALE
      Salutation printed above the address. Allowed values: MALE, FEMALE, MALE_FEMALE, FAMILY.
    • personFirstName string example: Hans
      First name printed on the document (person recipients).
    • personLastName string example: Muster
      Last name printed on the document (person recipients).
    • companyName string example: Muster AG
      Company name printed on the document (company recipients).
  • mailingAddress object
    The address block printed on the invoice document. Omit it to let the backend derive it from the customer's main address.
    show fields
    • customerId integer (int64) format: int64 example: 50123
      Customer the address belongs to.
    • customerType string example: COMPANY
      Partner type. Allowed values: COMPANY, PERSON.
    • address object
      Postal address of an invoice customer. Obtain a complete address block from GET /core/v1/customers and send it back unchanged.
      show fields
      • id integer (int64) format: int64 example: 0
        Address id. Use the id returned by the customer lookup; 0 or omitted for a new address.
      • type string required example: COMPANY
        Partner type this address belongs to. Required. Allowed values: COMPANY, PERSON.
      • addressType string required example: MAIN
        Address type label. Required. Typically MAIN or BILLING.
      • salutation string example: MALE
        Salutation of the addressee. Allowed values: MALE, FEMALE, MALE_FEMALE, FAMILY.
      • firstName string example: Hans
        First name of the addressee (person addresses).
      • lastName string example: Muster
        Last name of the addressee (person addresses).
      • companyName string example: Muster AG
        Company name of the addressee (company addresses).
      • street string example: Bahnhofstrasse
        Street name, without the house number.
      • homeNumber string example: 12a
        House number. homeNumber is the literal field name used throughout the KLARA address model — houseNumber is not accepted.
      • additionalAddress string example: c/o Finance Department
        Additional address line (c/o, department, ...).
      • addressLines string deprecated example: Bahnhofstrasse 12a
        Combined street and house number. Deprecated — use street and homeNumber instead.
      • city object required
        City of an invoice address. Obtain a complete city block from the customer lookup (GET /core/v1/customers) and send it back unchanged.
        show fields
        • id integer (int64) format: int64 example: 4247
          City id from the Swiss Post address directory.
        • addressPostcode string example: 8005
          Postcode (PLZ / NPA).
        • cityName18 string required example: Zuerich
          City name, 18-character Swiss Post variant. Required. cityName18 is the literal field name of the Swiss Post address directory (18-character abbreviation) — it is not a typo or a leftover.
        • cityName27 string required example: Zuerich
          City name, 27-character Swiss Post variant. Required.
        • onrp integer (int32) format: int32 example: 4247
          Swiss Post ONRP identifier of the locality.
        • postcodeType integer (int32) format: int32 example: 20
          Swiss Post postcode type.
        • additionalPostcode string example: 00
          Additional postcode suffix (max 2 characters).
        • basicPostcode integer (int32) format: int32 example: 8005
          Basic postcode.
        • languageCode integer (int32) format: int32 example: 1
          Swiss Post language code of the locality.
        • state object
          Canton / state of an invoice address.
          show fields
          • id integer (int64) format: int64 example: 26
            State id.
          • code string example: ZH
            Canton code (max 3 characters).
          • description string example: Zuerich
            Canton name.
        • country object
          Country of an invoice address.
          show fields
          • id integer (int64) format: int64 example: 1
            Country id.
          • countryName string example: Switzerland
            Country name.
          • iso2Code string example: CH
            ISO 3166-1 alpha-2 code.
          • iso3Code string example: CHE
            ISO 3166-1 alpha-3 code.
          • phoneCode string example: 41
            International dialling code.
          • numericCode string example: 756
            ISO 3166-1 numeric code.
      • validFrom string (date) format: date example: 2026-01-01
        Address valid-from date (ISO 8601).
      • validTo string (date) format: date example: 2026-12-31
        Address valid-to date (ISO 8601). Must be after validFrom.
    • salutation string example: MALE
      Salutation printed above the address. Allowed values: MALE, FEMALE, MALE_FEMALE, FAMILY.
    • personFirstName string example: Hans
      First name printed on the document (person recipients).
    • personLastName string example: Muster
      Last name printed on the document (person recipients).
    • companyName string example: Muster AG
      Company name printed on the document (company recipients).
  • mailingContact integer (int64) format: int64 example: 0
    Contact person id used for postal delivery.
  • emailDistribution object
    E-mail distribution settings recorded on the invoice. Stored only — this endpoint never sends the invoice. Retrieve the PDF via POST /core/v1/invoices/{id}/printed-document and deliver it yourself.
    show fields
    • id integer (int64) format: int64 example: 0
      Distribution entry id. Must be 0 or omitted for a new invoice.
    • subject string example: Invoice INV-2026-001
      Subject line stored for the distribution.
    • emailAddress string example: billing@muster.ch
      Primary recipient address.
    • ccEmailAddresses array of string
      Carbon-copy recipient addresses.
    • replyTo string example: finance@my-company.ch
      Reply-to address.
    • emailText string example: Please find our invoice attached.
      Body text stored for the distribution.
  • partnerContactId integer (int64) format: int64 example: 0
    Contact person of the customer this invoice is addressed to.
  • printedFileId string example: 5f8d0d55-b1a4-4d6e-9a1f-2c3b4d5e6f70
    Document id of the printed invoice PDF. Normally server-assigned by POST /core/v1/invoices/{id}/printed-document — omit it on creation. Set it only to attach a PDF your own system rendered.
Responses 7
200 Invoice persisted successfully. show body

application/json Invoice

  • id integer (int64) format: int64 example: 0
    Invoice id. Must be 0 or omitted when creating a new invoice. This endpoint only supports creation; updating an existing invoice is not supported.
  • orderType string default: INVOICE example: INVOICE
    Polymorphic discriminator. Must be INVOICE. Allowed values: INVOICE.
  • status string example: INVOICED
    Invoice status. Allowed values: DRAFT, INVOICED, SENT, PAID, CANCELLED. Required. Status INVOICED or SENT triggers accounting booking.
  • invoiceCode string required maxLength: 64 pattern: \S example: INV-2026-001
    Human-readable invoice code. Required and unique per company.
  • invoiceNumber integer (int64) format: int64 example: 2026001
    Sequential invoice number, typically obtained from GET /invoices/next-invoice-number.
  • documentDate string (date) format: date example: 2026-05-28
    Invoice document date (ISO 8601). Required when amount is greater than 0. Must fall inside the company's active Order Management subscription period.
  • paymentDate string (date) format: date example: 2026-06-27
    Payment due date (ISO 8601). Required when amount is greater than 0. Must be on or after documentDate.
  • deliveryDate string (date) format: date example: 2026-05-25
    Service delivery date (ISO 8601).
  • issuedDate string (date) format: date example: 2026-05-28
    Date the invoice was issued (ISO 8601).
  • servicePeriodFrom string (date) format: date example: 2026-05-01
    Service period start date (ISO 8601).
  • servicePeriodTo string (date) format: date example: 2026-05-31
    Service period end date (ISO 8601).
  • servicePeriodPattern string maxLength: 32 example: MONTHLY
    Service period pattern label (e.g. MONTHLY, YEARLY).
  • vatDate string (date) format: date
    VAT date. Server-managed (read-only).
  • bookingDueDate string (date) format: date
    Booking due date returned by accounting. Server-managed (read-only).
  • lastModified string (date-time) format: date-time
    Last modification timestamp. Server-managed (read-only).
  • createDate string (date-time) format: date-time
    Creation timestamp. Server-managed (read-only).
  • amount number example: 1080
    Invoice total. When usingVAT=false (VAT-exclusive items) this is the gross total = net + VAT; when usingVAT=true (VAT-inclusive items) it is the sum of the gross item amounts (VAT already inside). Caller-supplied — the server does not recompute it.
  • usingVAT boolean default: false example: True
    Controls whether each item price/amount is VAT-inclusive (gross) or VAT-exclusive (net). This is the GUI checkbox "VAT included in amount of each item". true = amounts already include VAT (INCLUDE_VAT); false = VAT is added on top of the net amounts (EXCLUDE_VAT). It does not turn VAT on or off — whether VAT applies at all is governed by the company's VAT registration. Use GET /core/latest/company-configuration/including-vat for the company default. The server stores the amounts you send verbatim and does not recompute them from this flag — send price/amount consistent with the chosen mode (see the create operation's VAT-handling notes).
  • usingExportVat boolean default: false example: False
    Export invoice flag — the GUI "Export" checkbox. When true, the invoice is treated as an export: every orderItems[].vat.rate must be 0 (export/zero VAT code), so no VAT is charged. When false (default) the items' normal VAT rates apply. The server does not recompute item VAT from this flag — set the per-item VAT accordingly.
  • hasCompanyVat boolean example: True
    Whether the company is liable for VAT. Leave this out. The server derives it from the company's VAT registration for the invoice's effective VAT date (deliveryDate when set, otherwise documentDate) and a derived value always wins over a value sent here. It is documented only because it is accepted, and because sending false on a VAT-registered company used to book every position at 0% while returning 200 — this field is the master switch for VAT at booking time, ahead of any per-line VAT code. It is only consulted when the company has no VAT configuration for that date, where it cannot be derived at all.
  • subject string maxLength: 1024 example: Invoice 2026-001
    Free-text invoice subject.
  • closeAndSignature string maxLength: 4096 example: Thank you for your business.
    Free-text closing remarks / signature block.
  • ourReference string maxLength: 128 example: ACC-2026
    Internal sender reference.
  • yourReference string maxLength: 128 example: PO-9981
    Customer-side reference (e.g. PO number).
  • companyCityAndDate string maxLength: 256 example: Zurich, 28.05.2026
    Header line such as 'Zurich, 28.05.2026'.
  • postMethod string example: SEND_EMAIL
    Distribution channel recorded on the invoice. Stored only — creating an invoice does not deliver it (no email/ePost/eBill/print&send). Allowed values: A_POST, B_POST, SEND_EMAIL, PRINT_AND_MANUAL_SEND, EPOST, EBILL.
  • delivery string maxLength: 64 example: DHL
    Delivery method label (free text).
  • ibanNumberCHF string example: CH9300762011623852957
    CHF IBAN for payment. Validated by downstream service.
  • ibanNumberCHW string example: CH9300762011623852957
    WIR-franc IBAN for payment.
  • wirAcceptanceRate number example: 0
    WIR acceptance percentage.
  • referenceNumber string maxLength: 64 example: 21 00000 00003 13947 14300 09017
    QR / ISR reference number.
  • qrInvoice boolean default: false example: True
    When true, the invoice is rendered/booked as a Swiss QR-invoice. Defaults to false.
  • fromAutoInvoicing boolean default: false example: False
    Indicates the invoice was generated by auto-invoicing. Defaults to false.
  • fromInvoiceRun boolean default: false example: False
    Indicates the invoice was produced by a recurring invoice run. When true, accounting booking and inventory transactions are skipped. Defaults to false.
  • invoiceType string example: MANUAL
    Invoice type. Allowed values: MANUAL, CREDIT_DEBIT.
  • originDistributionMethod string example: SEND_EMAIL
    Origin distribution method. Allowed values: A_POST, B_POST, SEND_EMAIL, PRINT_AND_MANUAL_SEND, EPOST, EBILL.
  • templateId integer (int64) format: int64 example: 0
    Template id used to create this invoice.
  • runHistoryId integer (int64) format: int64 example: 0
    Recurring invoice run history id.
  • settledAmount number example: 0
    KLARA-Pay settled amount (online shop only).
  • bookingNumbers string
    Accounting booking-number string. Server-managed (read-only).
  • businessCaseId integer (int64) format: int64
    Accounting business case id. Server-managed (read-only).
  • bookingStatus string
    Booking status (e.g. OPEN, PARTIAL, PAID). Server-managed (read-only).
  • bookingMessage string
    Optional booking error/info code (e.g. INVALID_SUBSCRIPTION_FOR_ACCOUNTING). Server-managed (read-only).
  • bookingSealed boolean
    Whether the booking has been finalized. Server-managed (read-only).
  • fiscalYearHasCreatedAuto boolean
    Whether a fiscal year was auto-created during booking. Server-managed (read-only).
  • createBy string
    Server-assigned audit user (token subject). Server-managed (read-only).
400 Data invalid

Error codes for this response (the code field of the response body):
  • invoice.id_must_be_zero — The request body carried a non-zero id. This operation only creates invoices; use PUT /core/v1/invoices to modify an existing one.
  • invoice.vat_code_missing — At least one orderItems[] entry set VAT on vatType, vatCase or the top-level vatCode while leaving vat.vatCode empty. Only vat.vatCode is stored, so that line would have been booked at 0%. Move the code to vat.vatCode, or send "0" ("No VAT") for a position that genuinely carries none.
  • invoice.vat_rate_mismatch — At least one orderItems[] entry sent a vat.rate that is not the rate of its vat.vatCode. The booking always uses the code's rate, so the invoice document would state a different percentage than the accounting record. Send the matching rate, or omit vat.rate and let the server fill it in.
Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Error codes for this response (the code field of the response body):
  • auth.credentials_missing — Neither an Authorization: Bearer header nor an API key header was present on the request.
Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
PUT/core/v1/invoiceskey / tokenUpdate an existing DRAFT invoice for the authenticated company.
Updates a DRAFT invoice identified by invoice.id in the request body. Only invoices in DRAFT status can be updated — any other status returns 400. If the incoming status is INVOICED or SENT, the invoice is booked into KLARA accounting and inventory transactions are created, identical to the booking behavior of POST /core/v1/invoices. This is the call that finalizes a DRAFT — the GUI equivalent of posting in the final step; status is caller-controlled, so keep it DRAFT to re-save without booking. This endpoint does not send/deliver the invoice (no email/ePost/eBill/print&send), regardless of postMethod; retrieve the PDF via POST /core/v1/invoices/{id}/printed-document and deliver it yourself. The caller must hold the FINANCE permission on the target company.

Important — finalizing a DRAFT books it without a printed invoice. Setting status=INVOICED/SENT here creates the accounting booking but renders/stores no PDF. To attach the printed invoice to the booking, after this call run (1) POST /core/v1/invoices/{id}/printed-document to render and store the printedFileId, then (2) PUT /core/v1/bookings/{id}/documents to link that printedFileId (in documentIds) to the booking from bookingNumbers.
operationId

updateInvoice — the method name a generated client uses.

Required permission

FINANCE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 1
NameDescription
confirmDontMindClosingFiscalYear
query boolean
When true, allows save/booking even if the document date falls inside a closing or closed fiscal year. Defaults to false.
default: false example: False
Request body required
Updates an existing DRAFT invoice. The body structure is identical to POST /core/v1/invoices with one critical difference: id must be the numeric primary key of an existing invoice currently in DRAFT status.

Typical flow:
  1. Call POST /core/v1/invoices with status=DRAFT to create the invoice.
  2. Call GET /core/v1/invoices/{id} to retrieve the current state.
  3. Modify the desired fields (items, amounts, dates, etc.).
  4. Call this endpoint to update — or to book it by changing status to INVOICED/SENT.
Prerequisite APIs (call these first if modifying related data):
  • GET /core/v1/invoices/{id} → provides the current invoice body to modify and re-submit.
  • GET /core/v1/company-bank-accounts → provides updated ibanNumberCHF / ibanNumberCHW.
  • GET /core/latest/articles/search?keyword=... → search for articles to add/change order items.
  • GET /core/v1/bank-reconciliation/open-positions → provides openPositionsLinkedToInvoice[] for reconciliation.
  • GET /core/latest/company-configuration/including-vat → provides usingVAT default.

Key differences from POST (create):
  • id (long, required) — must be > 0 and match an existing DRAFT invoice. Returns 400 if the stored invoice is not in DRAFT status.
  • invoiceCode — uniqueness is NOT re-validated; retain the original value.
  • order.id — must match the existing order; retain from the original invoice.
  • status — set to INVOICED or SENT to book the invoice (triggers accounting); set to DRAFT to save without booking.

Top-level fields:
  • id (long, required) — must be > 0 (existing DRAFT invoice id).
  • invoiceCode (String, required) — must not be empty; retain the original value.
  • orderType (String, required) — must be INVOICE.
  • status (String, required) — DRAFT (saves without booking), INVOICED (saves and books into accounting), SENT (saves and books; does not send/deliver the invoice).
  • postMethod (String, optional) — distribution channel recorded on the invoice only; not delivered. Allowed: A_POST, B_POST, SEND_EMAIL, PRINT_AND_MANUAL_SEND, EPOST, EBILL.
  • documentDate (date, required) — invoice issue date, format yyyy-MM-dd; must fall inside the active subscription period.
  • paymentDate (date, required when amount > 0) — must be on or after documentDate.
  • ibanNumberCHF (String, conditional) — CHF IBAN; format validated when provided.
  • ibanNumberCHW (String, optional) — WIR IBAN; format validated when provided.
  • wirAcceptanceRate (int, optional) — WIR acceptance percentage (0–100).
  • amount (BigDecimal, required) — total invoice amount. Caller-supplied; not recomputed by the server.
  • usingVAT (boolean) — GUI checkbox "VAT included in amount of each item": item price/amount are VAT-inclusive (true, gross) or VAT-exclusive (false, net). It does not switch VAT on/off. Same VAT-handling rules as POST /core/v1/invoices (server stores amounts verbatim).
  • usingExportVat (boolean, optional) — GUI checkbox "Export"; when true set every orderItems[].vat.rate to 0. Defaults to false.
  • subject, ourReference, yourReference, companyCityAndDate, closeAndSignature — optional text fields.

Nested fields — order (required):
  • order.id (long) — must be the existing order id; retain from the original invoice.
  • order.orderNumber (int) — retain from the original invoice.
  • order.companyId (long) — must match the authenticated company; set from bearer token on the downstream.
  • order.customer (object, required) — existing customer; retain from original invoice.

Nested fields — orderItems[] (required, at least 1):
  • Same structure as POST /core/v1/invoices. Existing item ids (> 0) update items in-place; id = 0 adds new items.
  • orderItems[].tag, orderItems[].vatCase and orderItems[].articleType — not persisted with the invoice, but used by the accounting booking of this same request, as on POST: articleType selects the account (PREPAYMENT or revenue), tag becomes the booking tags and vatCase the VAT case. Because they are not stored, send them again on every PUT; tag must not be empty when status is INVOICED/SENT.

Nested fields — attachments[] and openPositionsLinkedToInvoice[]:
  • Same structure and semantics as POST /core/v1/invoices.

Validation rules:
  • id must be > 0 (adapter guard) and the stored invoice must be DRAFT (downstream guard).
  • paymentDate must be on or after documentDate when amount > 0.
  • IBAN format is validated when provided.
  • Each orderItems[].tag must be present when status triggers booking (INVOICED/SENT); otherwise the request fails with 400 model.invalid and nothing is stored.
  • Subscription for Order Management must be active for documentDate.

Server-managed fields (same as POST): vatDate, lastModified, createDate, bookingDueDate, bookingNumbers, businessCaseId, bookingStatus, bookingMessage, bookingSealed.

application/json InvoiceCreateRequest

  • id integer (int64) format: int64 example: 0
    Invoice id. Must be 0 or omitted when creating a new invoice. This endpoint only supports creation; updating an existing invoice is not supported.
  • orderType string default: INVOICE example: INVOICE
    Polymorphic discriminator. Must be INVOICE. Allowed values: INVOICE.
  • status string example: INVOICED
    Invoice status. Allowed values: DRAFT, INVOICED, SENT, PAID, CANCELLED. Required. Status INVOICED or SENT triggers accounting booking.
  • invoiceCode string required maxLength: 64 pattern: \S example: INV-2026-001
    Human-readable invoice code. Required and unique per company.
  • invoiceNumber integer (int64) format: int64 example: 2026001
    Sequential invoice number, typically obtained from GET /invoices/next-invoice-number.
  • documentDate string (date) format: date example: 2026-05-28
    Invoice document date (ISO 8601). Required when amount is greater than 0. Must fall inside the company's active Order Management subscription period.
  • paymentDate string (date) format: date example: 2026-06-27
    Payment due date (ISO 8601). Required when amount is greater than 0. Must be on or after documentDate.
  • deliveryDate string (date) format: date example: 2026-05-25
    Service delivery date (ISO 8601).
  • issuedDate string (date) format: date example: 2026-05-28
    Date the invoice was issued (ISO 8601).
  • servicePeriodFrom string (date) format: date example: 2026-05-01
    Service period start date (ISO 8601).
  • servicePeriodTo string (date) format: date example: 2026-05-31
    Service period end date (ISO 8601).
  • servicePeriodPattern string maxLength: 32 example: MONTHLY
    Service period pattern label (e.g. MONTHLY, YEARLY).
  • vatDate string (date) format: date
    VAT date. Server-managed (read-only).
  • bookingDueDate string (date) format: date
    Booking due date returned by accounting. Server-managed (read-only).
  • lastModified string (date-time) format: date-time
    Last modification timestamp. Server-managed (read-only).
  • createDate string (date-time) format: date-time
    Creation timestamp. Server-managed (read-only).
  • amount number example: 1080
    Invoice total. When usingVAT=false (VAT-exclusive items) this is the gross total = net + VAT; when usingVAT=true (VAT-inclusive items) it is the sum of the gross item amounts (VAT already inside). Caller-supplied — the server does not recompute it.
  • usingVAT boolean default: false example: True
    Controls whether each item price/amount is VAT-inclusive (gross) or VAT-exclusive (net). This is the GUI checkbox "VAT included in amount of each item". true = amounts already include VAT (INCLUDE_VAT); false = VAT is added on top of the net amounts (EXCLUDE_VAT). It does not turn VAT on or off — whether VAT applies at all is governed by the company's VAT registration. Use GET /core/latest/company-configuration/including-vat for the company default. The server stores the amounts you send verbatim and does not recompute them from this flag — send price/amount consistent with the chosen mode (see the create operation's VAT-handling notes).
  • usingExportVat boolean default: false example: False
    Export invoice flag — the GUI "Export" checkbox. When true, the invoice is treated as an export: every orderItems[].vat.rate must be 0 (export/zero VAT code), so no VAT is charged. When false (default) the items' normal VAT rates apply. The server does not recompute item VAT from this flag — set the per-item VAT accordingly.
  • hasCompanyVat boolean example: True
    Whether the company is liable for VAT. Leave this out. The server derives it from the company's VAT registration for the invoice's effective VAT date (deliveryDate when set, otherwise documentDate) and a derived value always wins over a value sent here. It is documented only because it is accepted, and because sending false on a VAT-registered company used to book every position at 0% while returning 200 — this field is the master switch for VAT at booking time, ahead of any per-line VAT code. It is only consulted when the company has no VAT configuration for that date, where it cannot be derived at all.
  • subject string maxLength: 1024 example: Invoice 2026-001
    Free-text invoice subject.
  • closeAndSignature string maxLength: 4096 example: Thank you for your business.
    Free-text closing remarks / signature block.
  • ourReference string maxLength: 128 example: ACC-2026
    Internal sender reference.
  • yourReference string maxLength: 128 example: PO-9981
    Customer-side reference (e.g. PO number).
  • companyCityAndDate string maxLength: 256 example: Zurich, 28.05.2026
    Header line such as 'Zurich, 28.05.2026'.
  • postMethod string example: SEND_EMAIL
    Distribution channel recorded on the invoice. Stored only — creating an invoice does not deliver it (no email/ePost/eBill/print&send). Allowed values: A_POST, B_POST, SEND_EMAIL, PRINT_AND_MANUAL_SEND, EPOST, EBILL.
  • delivery string maxLength: 64 example: DHL
    Delivery method label (free text).
  • ibanNumberCHF string example: CH9300762011623852957
    CHF IBAN for payment. Validated by downstream service.
  • ibanNumberCHW string example: CH9300762011623852957
    WIR-franc IBAN for payment.
  • wirAcceptanceRate number example: 0
    WIR acceptance percentage.
  • referenceNumber string maxLength: 64 example: 21 00000 00003 13947 14300 09017
    QR / ISR reference number.
  • qrInvoice boolean default: false example: True
    When true, the invoice is rendered/booked as a Swiss QR-invoice. Defaults to false.
  • fromAutoInvoicing boolean default: false example: False
    Indicates the invoice was generated by auto-invoicing. Defaults to false.
  • fromInvoiceRun boolean default: false example: False
    Indicates the invoice was produced by a recurring invoice run. When true, accounting booking and inventory transactions are skipped. Defaults to false.
  • invoiceType string example: MANUAL
    Invoice type. Allowed values: MANUAL, CREDIT_DEBIT.
  • originDistributionMethod string example: SEND_EMAIL
    Origin distribution method. Allowed values: A_POST, B_POST, SEND_EMAIL, PRINT_AND_MANUAL_SEND, EPOST, EBILL.
  • templateId integer (int64) format: int64 example: 0
    Template id used to create this invoice.
  • runHistoryId integer (int64) format: int64 example: 0
    Recurring invoice run history id.
  • settledAmount number example: 0
    KLARA-Pay settled amount (online shop only).
  • bookingNumbers string
    Accounting booking-number string. Server-managed (read-only).
  • businessCaseId integer (int64) format: int64
    Accounting business case id. Server-managed (read-only).
  • bookingStatus string
    Booking status (e.g. OPEN, PARTIAL, PAID). Server-managed (read-only).
  • bookingMessage string
    Optional booking error/info code (e.g. INVALID_SUBSCRIPTION_FOR_ACCOUNTING). Server-managed (read-only).
  • bookingSealed boolean
    Whether the booking has been finalized. Server-managed (read-only).
  • fiscalYearHasCreatedAuto boolean
    Whether a fiscal year was auto-created during booking. Server-managed (read-only).
  • createBy string
    Server-assigned audit user (token subject). Server-managed (read-only).
  • order object required
    The order header the invoice belongs to. Required. Every invoice is created together with its order — send id=0 and a fresh orderNumber.
    show fields
    • id integer (int64) format: int64 example: 0
      Order id. Must be 0 or omitted for a new order.
    • orderNumber integer (int32) required format: int32 example: 2026001
      Order number, unique within the company. Required and must be greater than 0. Obtain it from GET /core/v1/orders/next-order-number — that endpoint is not idempotent, each call advances the counter.
    • orderName string example: Consulting Q2 2026
      Free-text order name.
    • companyId integer (int64) required format: int64 example: 12345
      Owning KLARA company id — must match the company resolved from the bearer token. Required.
    • customer object required
      The invoice recipient. Must be an existing customer — look it up with GET /core/v1/customers and send the returned block back unchanged. Populate company when customerType is COMPANY, or person when it is PERSON.
      show fields
      • id integer (int64) required format: int64 example: 50123
        Customer id of an existing customer. Required.
      • customerType string required example: COMPANY
        Discriminator selecting company or person. Required. Allowed values: COMPANY, PERSON.
      • companyId integer (int64) format: int64 example: 12345
        Owning KLARA company id — must match the company resolved from the bearer token.
      • company object
        Company partner of an invoice customer. Present when customerType is COMPANY. Obtain it from GET /core/v1/customers and send it back unchanged.
        show fields
        • id integer (int64) format: int64 example: 50123
          Company partner id as returned by the customer lookup.
        • name string required example: Muster AG
          Company name. Required.
        • addresses array of InvoiceAddress
          Postal addresses of the company. At least the billing address must be present for the invoice to be printable.
          show fields

          Array of InvoiceAddress.

          • id integer (int64) format: int64 example: 0
            Address id. Use the id returned by the customer lookup; 0 or omitted for a new address.
          • type string required example: COMPANY
            Partner type this address belongs to. Required. Allowed values: COMPANY, PERSON.
          • addressType string required example: MAIN
            Address type label. Required. Typically MAIN or BILLING.
          • salutation string example: MALE
            Salutation of the addressee. Allowed values: MALE, FEMALE, MALE_FEMALE, FAMILY.
          • firstName string example: Hans
            First name of the addressee (person addresses).
          • lastName string example: Muster
            Last name of the addressee (person addresses).
          • companyName string example: Muster AG
            Company name of the addressee (company addresses).
          • street string example: Bahnhofstrasse
            Street name, without the house number.
          • homeNumber string example: 12a
            House number. homeNumber is the literal field name used throughout the KLARA address model — houseNumber is not accepted.
          • additionalAddress string example: c/o Finance Department
            Additional address line (c/o, department, ...).
          • addressLines string deprecated example: Bahnhofstrasse 12a
            Combined street and house number. Deprecated — use street and homeNumber instead.
          • city object required
            City of an invoice address. Obtain a complete city block from the customer lookup (GET /core/v1/customers) and send it back unchanged.
            show fields
            • id integer (int64) format: int64 example: 4247
              City id from the Swiss Post address directory.
            • addressPostcode string example: 8005
              Postcode (PLZ / NPA).
            • cityName18 string required example: Zuerich
              City name, 18-character Swiss Post variant. Required. cityName18 is the literal field name of the Swiss Post address directory (18-character abbreviation) — it is not a typo or a leftover.
            • cityName27 string required example: Zuerich
              City name, 27-character Swiss Post variant. Required.
            • onrp integer (int32) format: int32 example: 4247
              Swiss Post ONRP identifier of the locality.
            • postcodeType integer (int32) format: int32 example: 20
              Swiss Post postcode type.
            • additionalPostcode string example: 00
              Additional postcode suffix (max 2 characters).
            • basicPostcode integer (int32) format: int32 example: 8005
              Basic postcode.
            • languageCode integer (int32) format: int32 example: 1
              Swiss Post language code of the locality.
            • state object
              Canton / state of an invoice address.
              show fields

              Nesting continues beyond this level. See the specification for the complete structure.

            • country object
              Country of an invoice address.
              show fields

              Nesting continues beyond this level. See the specification for the complete structure.

          • validFrom string (date) format: date example: 2026-01-01
            Address valid-from date (ISO 8601).
          • validTo string (date) format: date example: 2026-12-31
            Address valid-to date (ISO 8601). Must be after validFrom.
        • emails array of InvoiceEmail
          E-mail addresses of the company.
          show fields

          Array of InvoiceEmail.

          • id string example: 1001
            E-mail entry id.
          • emailAddress string example: billing@muster.ch
            The e-mail address.
          • type string example: WORK
            E-mail type. Allowed values: PRIVATE, WORK, OFFICE, OTHER.
        • phones array of InvoicePhone
          Phone numbers of the company.
          show fields

          Array of InvoicePhone.

          • id integer (int64) format: int64 example: 2001
            Phone entry id.
          • phoneNumber string example: +41 44 123 45 67
            The phone number.
          • type string example: WORK
            Phone type. Allowed values: PRIVATE, OFFICE, FAX, WORK, MOBILE.
        • companyBillingAddress object
          Postal address of an invoice customer. Obtain a complete address block from GET /core/v1/customers and send it back unchanged.
          show fields
          • id integer (int64) format: int64 example: 0
            Address id. Use the id returned by the customer lookup; 0 or omitted for a new address.
          • type string required example: COMPANY
            Partner type this address belongs to. Required. Allowed values: COMPANY, PERSON.
          • addressType string required example: MAIN
            Address type label. Required. Typically MAIN or BILLING.
          • salutation string example: MALE
            Salutation of the addressee. Allowed values: MALE, FEMALE, MALE_FEMALE, FAMILY.
          • firstName string example: Hans
            First name of the addressee (person addresses).
          • lastName string example: Muster
            Last name of the addressee (person addresses).
          • companyName string example: Muster AG
            Company name of the addressee (company addresses).
          • street string example: Bahnhofstrasse
            Street name, without the house number.
          • homeNumber string example: 12a
            House number. homeNumber is the literal field name used throughout the KLARA address model — houseNumber is not accepted.
          • additionalAddress string example: c/o Finance Department
            Additional address line (c/o, department, ...).
          • addressLines string deprecated example: Bahnhofstrasse 12a
            Combined street and house number. Deprecated — use street and homeNumber instead.
          • city object required
            City of an invoice address. Obtain a complete city block from the customer lookup (GET /core/v1/customers) and send it back unchanged.
            show fields
            • id integer (int64) format: int64 example: 4247
              City id from the Swiss Post address directory.
            • addressPostcode string example: 8005
              Postcode (PLZ / NPA).
            • cityName18 string required example: Zuerich
              City name, 18-character Swiss Post variant. Required. cityName18 is the literal field name of the Swiss Post address directory (18-character abbreviation) — it is not a typo or a leftover.
            • cityName27 string required example: Zuerich
              City name, 27-character Swiss Post variant. Required.
            • onrp integer (int32) format: int32 example: 4247
              Swiss Post ONRP identifier of the locality.
            • postcodeType integer (int32) format: int32 example: 20
              Swiss Post postcode type.
            • additionalPostcode string example: 00
              Additional postcode suffix (max 2 characters).
            • basicPostcode integer (int32) format: int32 example: 8005
              Basic postcode.
            • languageCode integer (int32) format: int32 example: 1
              Swiss Post language code of the locality.
            • state object
              Canton / state of an invoice address.
              show fields

              Nesting continues beyond this level. See the specification for the complete structure.

            • country object
              Country of an invoice address.
              show fields

              Nesting continues beyond this level. See the specification for the complete structure.

          • validFrom string (date) format: date example: 2026-01-01
            Address valid-from date (ISO 8601).
          • validTo string (date) format: date example: 2026-12-31
            Address valid-to date (ISO 8601). Must be after validFrom.
        • companyBillingAddressEnabled boolean example: False
          Whether companyBillingAddress is used instead of the main address.
        • corporateIdentificationNumber string example: CHE-123.456.789
          Swiss company identification number (UID).
        • vatNumber string example: CHE-123.456.789 MWST
          VAT registration number.
        • hrNumber string example: CH-020.3.926.481-3
          Commercial register number.
        • nogaCode string example: 620100
          NOGA economic activity code.
        • companyNumber string example: C-0001
          Company number in KLARA.
        • companyOriginReference string example: ERP-4711
          External reference of the company in the partner system.
        • website string example: https://www.muster.ch
          Company website.
        • language string example: de
          Preferred correspondence language as a BCP-47 tag.
      • person object
        Natural-person partner of an invoice customer. Present when customerType is PERSON. Obtain it from GET /core/v1/customers and send it back unchanged.
        show fields
        • id integer (int64) format: int64 example: 50124
          Person partner id as returned by the customer lookup.
        • salutation string example: MALE
          Salutation. Allowed values: MALE, FEMALE, MALE_FEMALE, FAMILY.
        • firstName string required example: Hans
          First name. Required.
        • lastName string required example: Muster
          Last name. Required.
        • birthday string (date) required format: date example: 1980-04-17
          Date of birth (ISO 8601). Required by the downstream person model.
        • addressList array of InvoiceAddress
          Postal addresses of the person.
          show fields

          Array of InvoiceAddress.

          • id integer (int64) format: int64 example: 0
            Address id. Use the id returned by the customer lookup; 0 or omitted for a new address.
          • type string required example: COMPANY
            Partner type this address belongs to. Required. Allowed values: COMPANY, PERSON.
          • addressType string required example: MAIN
            Address type label. Required. Typically MAIN or BILLING.
          • salutation string example: MALE
            Salutation of the addressee. Allowed values: MALE, FEMALE, MALE_FEMALE, FAMILY.
          • firstName string example: Hans
            First name of the addressee (person addresses).
          • lastName string example: Muster
            Last name of the addressee (person addresses).
          • companyName string example: Muster AG
            Company name of the addressee (company addresses).
          • street string example: Bahnhofstrasse
            Street name, without the house number.
          • homeNumber string example: 12a
            House number. homeNumber is the literal field name used throughout the KLARA address model — houseNumber is not accepted.
          • additionalAddress string example: c/o Finance Department
            Additional address line (c/o, department, ...).
          • addressLines string deprecated example: Bahnhofstrasse 12a
            Combined street and house number. Deprecated — use street and homeNumber instead.
          • city object required
            City of an invoice address. Obtain a complete city block from the customer lookup (GET /core/v1/customers) and send it back unchanged.
            show fields
            • id integer (int64) format: int64 example: 4247
              City id from the Swiss Post address directory.
            • addressPostcode string example: 8005
              Postcode (PLZ / NPA).
            • cityName18 string required example: Zuerich
              City name, 18-character Swiss Post variant. Required. cityName18 is the literal field name of the Swiss Post address directory (18-character abbreviation) — it is not a typo or a leftover.
            • cityName27 string required example: Zuerich
              City name, 27-character Swiss Post variant. Required.
            • onrp integer (int32) format: int32 example: 4247
              Swiss Post ONRP identifier of the locality.
            • postcodeType integer (int32) format: int32 example: 20
              Swiss Post postcode type.
            • additionalPostcode string example: 00
              Additional postcode suffix (max 2 characters).
            • basicPostcode integer (int32) format: int32 example: 8005
              Basic postcode.
            • languageCode integer (int32) format: int32 example: 1
              Swiss Post language code of the locality.
            • state object
              Canton / state of an invoice address.
              show fields

              Nesting continues beyond this level. See the specification for the complete structure.

            • country object
              Country of an invoice address.
              show fields

              Nesting continues beyond this level. See the specification for the complete structure.

          • validFrom string (date) format: date example: 2026-01-01
            Address valid-from date (ISO 8601).
          • validTo string (date) format: date example: 2026-12-31
            Address valid-to date (ISO 8601). Must be after validFrom.
        • emailList array of InvoiceEmail
          E-mail addresses of the person.
          show fields

          Array of InvoiceEmail.

          • id string example: 1001
            E-mail entry id.
          • emailAddress string example: billing@muster.ch
            The e-mail address.
          • type string example: WORK
            E-mail type. Allowed values: PRIVATE, WORK, OFFICE, OTHER.
        • phoneList array of InvoicePhone
          Phone numbers of the person.
          show fields

          Array of InvoicePhone.

          • id integer (int64) format: int64 example: 2001
            Phone entry id.
          • phoneNumber string example: +41 44 123 45 67
            The phone number.
          • type string example: WORK
            Phone type. Allowed values: PRIVATE, OFFICE, FAX, WORK, MOBILE.
        • personNumber string example: P-0001
          Person number in KLARA.
        • personOriginReference string example: ERP-8150
          External reference of the person in the partner system.
        • website string example: https://www.muster.ch
          Personal website.
        • language string example: de
          Preferred correspondence language as a BCP-47 tag.
      • termsOfPayment integer (int32) format: int32 example: 30
        Payment terms in days, used to derive the default paymentDate.
      • discount number example: 0
        Default customer discount in percent.
      • priceCategory string example: STANDARD
        Price category assigned to the customer.
      • uuid string example: 0d9f4d1e-4a2b-4c8d-9f3e-1b2c3d4e5f60
        Stable external identifier of the customer.
    • invoiceGroup string example: DEFAULT
      Invoice group the order is assigned to.
    • lumpSum boolean example: False
      Whether the order is billed as a lump sum.
    • archived boolean example: False
      Whether the order is archived.
  • orderItems array of InvoiceOrderItem required
    Invoice line items. Required — at least one entry.
    show fields

    Array of InvoiceOrderItem.

    • id integer (int64) format: int64 example: 0
      Item id. Must be 0 or omitted for a new item.
    • position integer (int64) format: int64 example: 1
      Line position, 1-based.
    • itemNumer string example: P0000061123
      Article number of the item, as returned by GET /core/latest/articles/search or GET /core/latest/articles/article-numbers. The field name is itemNumer, not itemNumber. This spelling is the literal wire field name of the KLARA order-management model and is what the backend accepts — it is not a typo in this documentation. Note that the article search endpoints expose the same value under the name articleNumber.
    • description string example: Consulting services
      Item description printed on the invoice line.
    • articleExtendedDescription string example: Sprint 12, May 2026
      Additional descriptive text printed below the line.
    • quantity number example: 10
      Quantity billed.
    • unit string example: Hour
      Unit of measure.
    • price number example: 100
      Unit price. Negative for credit-note lines. VAT-inclusive (gross) when the document has usingVAT=true, VAT-exclusive (net) when usingVAT=false. Both variants are available from the article lookup endpoints.
    • discount number example: 0
      Discount on this line, in percent.
    • amount number example: 1000
      Line total = quantity x price x (1 - discount/100), rounded to the nearest 0.05 (Swiss commercial rounding). Gross or net following usingVAT, on the same basis as price.
    • posAmount number example: 1000
      Position amount as shown in the KLARA GUI. Optional; derived from amount when omitted.
    • vat object
      VAT applied to an invoice line item. The server does not recompute VAT from the document flags — send the rate that matches usingVAT / usingExportVat.
      show fields
      • id integer (int64) format: int64 example: 1
        VAT id.
      • vatCode string required example: 1
        VAT code. Required.
      • rate number example: 8.1
        VAT rate in percent. Set to 0 for export invoices (usingExportVat=true).
      • description string example: Normal rate 8.1%
        Human-readable VAT description.
      • masterId integer (int64) format: int64 example: 0
        Master data id of the VAT record.
      • companySelectedVat boolean example: False
        Whether this is a company-selected VAT.
      • sss1 boolean example: False
        Whether the first Swiss social-security special rate applies.
      • sss2 boolean example: False
        Whether the second Swiss social-security special rate applies.
      • validFrom string (date) format: date example: 2024-01-01
        VAT valid-from date (ISO 8601).
      • validTo string (date) format: date example: 2099-12-31
        VAT valid-to date (ISO 8601).
    • vatCode string example: 1
      VAT code of the line. Convenience mirror of vat.vatCode. Not persisted on this endpoint — the value that is stored comes from vat.vatCode. Do not send the two with different values: this field is silently discarded, so a mismatch results in the vat.vatCode value being booked.
    • vatCase string example: TAXABLE_SUPPLY
      VAT treatment of the line: the vatCaseCode of a sales VAT case (applicability REVENUE) from GET /core/latest/vat-cases, for example TAXABLE_SUPPLY, SUPPLY_WITH_OPTION_ART_22 or TAX_EXEMPT_SUPPLY. For a company that reports VAT with effective clearing, any other value, including a purchase case, is rejected by the booking with 400 model.invalid and the invoice is not stored. Not persisted with the invoice, but used by the accounting booking of this same request — the order_item table has no column for it. For a company that reports VAT with effective clearing or net tax rates it becomes the VAT case of the line's booking position. When it is missing, the VAT case of the article applies, which can be one the company cannot book; send it with every write that books (INVOICED/SENT).
    • articleType string example: SERVICE
      Article category. Allowed values: PRODUCTION, PREPAYMENT, SERVICE. Not persisted with the invoice, but used by the accounting booking of this same request — the order_item table has no column for it. It selects the account: PREPAYMENT books the line to the prepayment receivables account, any other value or none to revenue.
    • tag string example: 3400
      Accounting tag of the line. Not persisted with the invoice, but used by the accounting booking of this same request — the order_item table has no column for it, but the value sent here becomes the tags of the line's booking position. Required when status triggers booking (INVOICED/SENT): without it the booking is rejected with 400 model.invalid ("The field tags is mandatory.") and the invoice is not stored. Send the article's accountingTags joined with a comma, the way KLARA builds it for recurring invoices.
    • servicePeriodFrom string (date) format: date example: 2026-05-01
      Service period start for this line (ISO 8601).
    • servicePeriodTo string (date) format: date example: 2026-05-31
      Service period end for this line (ISO 8601).
    • servicePeriodPattern string example: MONTHLY
      Service period pattern label for this line.
    • specialRates string example: SSS1
      Swiss social-security special rate applied to the line. Allowed values: SSS1, SSS2.
    • articleSet string example: SET-001
      Identifier of the article set this line belongs to.
    • inventorySelections array of InvoiceInventorySelection
      Inventory selections (serial numbers, storage places) for stock-managed articles. Persisted through a dedicated path rather than with the line itself, so the serial numbers you send are validated separately — an invalid serial number fails the request even though the surrounding line is accepted.
      show fields

      Array of InvoiceInventorySelection.

      • storagePlaceId integer (int64) format: int64 example: 77
        Storage place the quantity is taken from.
      • quantity number example: 1
        Quantity taken from this storage place.
      • serialNumbers array of string
        Serial numbers of the units delivered. Duplicates within the same invoice are rejected.
  • attachments array of InvoiceAttachment
    Documents attached to the invoice.
    show fields

    Array of InvoiceAttachment.

    • id integer (int64) format: int64 example: 0
      Attachment id. Must be 0 or omitted for a new attachment.
    • orderDetailId integer (int64) format: int64 example: 0
      Id of the invoice this attachment belongs to. Must be 0 for a new invoice.
    • fileId string example: 5f8d0d55-b1a4-4d6e-9a1f-2c3b4d5e6f70
      Document id of the uploaded file.
  • openPositionsLinkedToInvoice array of InvoiceOpenPositionLink
    Open positions (prepayments, credit notes) offset against this invoice. Persisted through a dedicated path rather than with the invoice row itself.
    show fields

    Array of InvoiceOpenPositionLink.

    • bookingTypeCode string required example: AR_PREPAYMENT
      Type of the linked booking. Required. For invoice reconciliation the relevant values are AR_PREPAYMENT and AR_CREDITNOTE.
    • bookingDetailUri string required example: /luz_accounting/api/klara_tenant/companies/12345/bookings/778/booking-details/9912
      Internal URI of the booking detail to reconcile. Required. Must match the pattern /…/{tenant-id}/companies/{companyId}/bookings/{bookingId}/booking-details/{detailId}.
    • partialPaymentAmount number example: 250
      Amount to offset from this open position.
  • documentAddress object
    The address block printed on the invoice document. Omit it to let the backend derive it from the customer's main address.
    show fields
    • customerId integer (int64) format: int64 example: 50123
      Customer the address belongs to.
    • customerType string example: COMPANY
      Partner type. Allowed values: COMPANY, PERSON.
    • address object
      Postal address of an invoice customer. Obtain a complete address block from GET /core/v1/customers and send it back unchanged.
      show fields
      • id integer (int64) format: int64 example: 0
        Address id. Use the id returned by the customer lookup; 0 or omitted for a new address.
      • type string required example: COMPANY
        Partner type this address belongs to. Required. Allowed values: COMPANY, PERSON.
      • addressType string required example: MAIN
        Address type label. Required. Typically MAIN or BILLING.
      • salutation string example: MALE
        Salutation of the addressee. Allowed values: MALE, FEMALE, MALE_FEMALE, FAMILY.
      • firstName string example: Hans
        First name of the addressee (person addresses).
      • lastName string example: Muster
        Last name of the addressee (person addresses).
      • companyName string example: Muster AG
        Company name of the addressee (company addresses).
      • street string example: Bahnhofstrasse
        Street name, without the house number.
      • homeNumber string example: 12a
        House number. homeNumber is the literal field name used throughout the KLARA address model — houseNumber is not accepted.
      • additionalAddress string example: c/o Finance Department
        Additional address line (c/o, department, ...).
      • addressLines string deprecated example: Bahnhofstrasse 12a
        Combined street and house number. Deprecated — use street and homeNumber instead.
      • city object required
        City of an invoice address. Obtain a complete city block from the customer lookup (GET /core/v1/customers) and send it back unchanged.
        show fields
        • id integer (int64) format: int64 example: 4247
          City id from the Swiss Post address directory.
        • addressPostcode string example: 8005
          Postcode (PLZ / NPA).
        • cityName18 string required example: Zuerich
          City name, 18-character Swiss Post variant. Required. cityName18 is the literal field name of the Swiss Post address directory (18-character abbreviation) — it is not a typo or a leftover.
        • cityName27 string required example: Zuerich
          City name, 27-character Swiss Post variant. Required.
        • onrp integer (int32) format: int32 example: 4247
          Swiss Post ONRP identifier of the locality.
        • postcodeType integer (int32) format: int32 example: 20
          Swiss Post postcode type.
        • additionalPostcode string example: 00
          Additional postcode suffix (max 2 characters).
        • basicPostcode integer (int32) format: int32 example: 8005
          Basic postcode.
        • languageCode integer (int32) format: int32 example: 1
          Swiss Post language code of the locality.
        • state object
          Canton / state of an invoice address.
          show fields
          • id integer (int64) format: int64 example: 26
            State id.
          • code string example: ZH
            Canton code (max 3 characters).
          • description string example: Zuerich
            Canton name.
        • country object
          Country of an invoice address.
          show fields
          • id integer (int64) format: int64 example: 1
            Country id.
          • countryName string example: Switzerland
            Country name.
          • iso2Code string example: CH
            ISO 3166-1 alpha-2 code.
          • iso3Code string example: CHE
            ISO 3166-1 alpha-3 code.
          • phoneCode string example: 41
            International dialling code.
          • numericCode string example: 756
            ISO 3166-1 numeric code.
      • validFrom string (date) format: date example: 2026-01-01
        Address valid-from date (ISO 8601).
      • validTo string (date) format: date example: 2026-12-31
        Address valid-to date (ISO 8601). Must be after validFrom.
    • salutation string example: MALE
      Salutation printed above the address. Allowed values: MALE, FEMALE, MALE_FEMALE, FAMILY.
    • personFirstName string example: Hans
      First name printed on the document (person recipients).
    • personLastName string example: Muster
      Last name printed on the document (person recipients).
    • companyName string example: Muster AG
      Company name printed on the document (company recipients).
  • mailingAddress object
    The address block printed on the invoice document. Omit it to let the backend derive it from the customer's main address.
    show fields
    • customerId integer (int64) format: int64 example: 50123
      Customer the address belongs to.
    • customerType string example: COMPANY
      Partner type. Allowed values: COMPANY, PERSON.
    • address object
      Postal address of an invoice customer. Obtain a complete address block from GET /core/v1/customers and send it back unchanged.
      show fields
      • id integer (int64) format: int64 example: 0
        Address id. Use the id returned by the customer lookup; 0 or omitted for a new address.
      • type string required example: COMPANY
        Partner type this address belongs to. Required. Allowed values: COMPANY, PERSON.
      • addressType string required example: MAIN
        Address type label. Required. Typically MAIN or BILLING.
      • salutation string example: MALE
        Salutation of the addressee. Allowed values: MALE, FEMALE, MALE_FEMALE, FAMILY.
      • firstName string example: Hans
        First name of the addressee (person addresses).
      • lastName string example: Muster
        Last name of the addressee (person addresses).
      • companyName string example: Muster AG
        Company name of the addressee (company addresses).
      • street string example: Bahnhofstrasse
        Street name, without the house number.
      • homeNumber string example: 12a
        House number. homeNumber is the literal field name used throughout the KLARA address model — houseNumber is not accepted.
      • additionalAddress string example: c/o Finance Department
        Additional address line (c/o, department, ...).
      • addressLines string deprecated example: Bahnhofstrasse 12a
        Combined street and house number. Deprecated — use street and homeNumber instead.
      • city object required
        City of an invoice address. Obtain a complete city block from the customer lookup (GET /core/v1/customers) and send it back unchanged.
        show fields
        • id integer (int64) format: int64 example: 4247
          City id from the Swiss Post address directory.
        • addressPostcode string example: 8005
          Postcode (PLZ / NPA).
        • cityName18 string required example: Zuerich
          City name, 18-character Swiss Post variant. Required. cityName18 is the literal field name of the Swiss Post address directory (18-character abbreviation) — it is not a typo or a leftover.
        • cityName27 string required example: Zuerich
          City name, 27-character Swiss Post variant. Required.
        • onrp integer (int32) format: int32 example: 4247
          Swiss Post ONRP identifier of the locality.
        • postcodeType integer (int32) format: int32 example: 20
          Swiss Post postcode type.
        • additionalPostcode string example: 00
          Additional postcode suffix (max 2 characters).
        • basicPostcode integer (int32) format: int32 example: 8005
          Basic postcode.
        • languageCode integer (int32) format: int32 example: 1
          Swiss Post language code of the locality.
        • state object
          Canton / state of an invoice address.
          show fields
          • id integer (int64) format: int64 example: 26
            State id.
          • code string example: ZH
            Canton code (max 3 characters).
          • description string example: Zuerich
            Canton name.
        • country object
          Country of an invoice address.
          show fields
          • id integer (int64) format: int64 example: 1
            Country id.
          • countryName string example: Switzerland
            Country name.
          • iso2Code string example: CH
            ISO 3166-1 alpha-2 code.
          • iso3Code string example: CHE
            ISO 3166-1 alpha-3 code.
          • phoneCode string example: 41
            International dialling code.
          • numericCode string example: 756
            ISO 3166-1 numeric code.
      • validFrom string (date) format: date example: 2026-01-01
        Address valid-from date (ISO 8601).
      • validTo string (date) format: date example: 2026-12-31
        Address valid-to date (ISO 8601). Must be after validFrom.
    • salutation string example: MALE
      Salutation printed above the address. Allowed values: MALE, FEMALE, MALE_FEMALE, FAMILY.
    • personFirstName string example: Hans
      First name printed on the document (person recipients).
    • personLastName string example: Muster
      Last name printed on the document (person recipients).
    • companyName string example: Muster AG
      Company name printed on the document (company recipients).
  • mailingContact integer (int64) format: int64 example: 0
    Contact person id used for postal delivery.
  • emailDistribution object
    E-mail distribution settings recorded on the invoice. Stored only — this endpoint never sends the invoice. Retrieve the PDF via POST /core/v1/invoices/{id}/printed-document and deliver it yourself.
    show fields
    • id integer (int64) format: int64 example: 0
      Distribution entry id. Must be 0 or omitted for a new invoice.
    • subject string example: Invoice INV-2026-001
      Subject line stored for the distribution.
    • emailAddress string example: billing@muster.ch
      Primary recipient address.
    • ccEmailAddresses array of string
      Carbon-copy recipient addresses.
    • replyTo string example: finance@my-company.ch
      Reply-to address.
    • emailText string example: Please find our invoice attached.
      Body text stored for the distribution.
  • partnerContactId integer (int64) format: int64 example: 0
    Contact person of the customer this invoice is addressed to.
  • printedFileId string example: 5f8d0d55-b1a4-4d6e-9a1f-2c3b4d5e6f70
    Document id of the printed invoice PDF. Normally server-assigned by POST /core/v1/invoices/{id}/printed-document — omit it on creation. Set it only to attach a PDF your own system rendered.
Responses 7
200 Invoice updated successfully. show body

application/json Invoice

  • id integer (int64) format: int64 example: 0
    Invoice id. Must be 0 or omitted when creating a new invoice. This endpoint only supports creation; updating an existing invoice is not supported.
  • orderType string default: INVOICE example: INVOICE
    Polymorphic discriminator. Must be INVOICE. Allowed values: INVOICE.
  • status string example: INVOICED
    Invoice status. Allowed values: DRAFT, INVOICED, SENT, PAID, CANCELLED. Required. Status INVOICED or SENT triggers accounting booking.
  • invoiceCode string required maxLength: 64 pattern: \S example: INV-2026-001
    Human-readable invoice code. Required and unique per company.
  • invoiceNumber integer (int64) format: int64 example: 2026001
    Sequential invoice number, typically obtained from GET /invoices/next-invoice-number.
  • documentDate string (date) format: date example: 2026-05-28
    Invoice document date (ISO 8601). Required when amount is greater than 0. Must fall inside the company's active Order Management subscription period.
  • paymentDate string (date) format: date example: 2026-06-27
    Payment due date (ISO 8601). Required when amount is greater than 0. Must be on or after documentDate.
  • deliveryDate string (date) format: date example: 2026-05-25
    Service delivery date (ISO 8601).
  • issuedDate string (date) format: date example: 2026-05-28
    Date the invoice was issued (ISO 8601).
  • servicePeriodFrom string (date) format: date example: 2026-05-01
    Service period start date (ISO 8601).
  • servicePeriodTo string (date) format: date example: 2026-05-31
    Service period end date (ISO 8601).
  • servicePeriodPattern string maxLength: 32 example: MONTHLY
    Service period pattern label (e.g. MONTHLY, YEARLY).
  • vatDate string (date) format: date
    VAT date. Server-managed (read-only).
  • bookingDueDate string (date) format: date
    Booking due date returned by accounting. Server-managed (read-only).
  • lastModified string (date-time) format: date-time
    Last modification timestamp. Server-managed (read-only).
  • createDate string (date-time) format: date-time
    Creation timestamp. Server-managed (read-only).
  • amount number example: 1080
    Invoice total. When usingVAT=false (VAT-exclusive items) this is the gross total = net + VAT; when usingVAT=true (VAT-inclusive items) it is the sum of the gross item amounts (VAT already inside). Caller-supplied — the server does not recompute it.
  • usingVAT boolean default: false example: True
    Controls whether each item price/amount is VAT-inclusive (gross) or VAT-exclusive (net). This is the GUI checkbox "VAT included in amount of each item". true = amounts already include VAT (INCLUDE_VAT); false = VAT is added on top of the net amounts (EXCLUDE_VAT). It does not turn VAT on or off — whether VAT applies at all is governed by the company's VAT registration. Use GET /core/latest/company-configuration/including-vat for the company default. The server stores the amounts you send verbatim and does not recompute them from this flag — send price/amount consistent with the chosen mode (see the create operation's VAT-handling notes).
  • usingExportVat boolean default: false example: False
    Export invoice flag — the GUI "Export" checkbox. When true, the invoice is treated as an export: every orderItems[].vat.rate must be 0 (export/zero VAT code), so no VAT is charged. When false (default) the items' normal VAT rates apply. The server does not recompute item VAT from this flag — set the per-item VAT accordingly.
  • hasCompanyVat boolean example: True
    Whether the company is liable for VAT. Leave this out. The server derives it from the company's VAT registration for the invoice's effective VAT date (deliveryDate when set, otherwise documentDate) and a derived value always wins over a value sent here. It is documented only because it is accepted, and because sending false on a VAT-registered company used to book every position at 0% while returning 200 — this field is the master switch for VAT at booking time, ahead of any per-line VAT code. It is only consulted when the company has no VAT configuration for that date, where it cannot be derived at all.
  • subject string maxLength: 1024 example: Invoice 2026-001
    Free-text invoice subject.
  • closeAndSignature string maxLength: 4096 example: Thank you for your business.
    Free-text closing remarks / signature block.
  • ourReference string maxLength: 128 example: ACC-2026
    Internal sender reference.
  • yourReference string maxLength: 128 example: PO-9981
    Customer-side reference (e.g. PO number).
  • companyCityAndDate string maxLength: 256 example: Zurich, 28.05.2026
    Header line such as 'Zurich, 28.05.2026'.
  • postMethod string example: SEND_EMAIL
    Distribution channel recorded on the invoice. Stored only — creating an invoice does not deliver it (no email/ePost/eBill/print&send). Allowed values: A_POST, B_POST, SEND_EMAIL, PRINT_AND_MANUAL_SEND, EPOST, EBILL.
  • delivery string maxLength: 64 example: DHL
    Delivery method label (free text).
  • ibanNumberCHF string example: CH9300762011623852957
    CHF IBAN for payment. Validated by downstream service.
  • ibanNumberCHW string example: CH9300762011623852957
    WIR-franc IBAN for payment.
  • wirAcceptanceRate number example: 0
    WIR acceptance percentage.
  • referenceNumber string maxLength: 64 example: 21 00000 00003 13947 14300 09017
    QR / ISR reference number.
  • qrInvoice boolean default: false example: True
    When true, the invoice is rendered/booked as a Swiss QR-invoice. Defaults to false.
  • fromAutoInvoicing boolean default: false example: False
    Indicates the invoice was generated by auto-invoicing. Defaults to false.
  • fromInvoiceRun boolean default: false example: False
    Indicates the invoice was produced by a recurring invoice run. When true, accounting booking and inventory transactions are skipped. Defaults to false.
  • invoiceType string example: MANUAL
    Invoice type. Allowed values: MANUAL, CREDIT_DEBIT.
  • originDistributionMethod string example: SEND_EMAIL
    Origin distribution method. Allowed values: A_POST, B_POST, SEND_EMAIL, PRINT_AND_MANUAL_SEND, EPOST, EBILL.
  • templateId integer (int64) format: int64 example: 0
    Template id used to create this invoice.
  • runHistoryId integer (int64) format: int64 example: 0
    Recurring invoice run history id.
  • settledAmount number example: 0
    KLARA-Pay settled amount (online shop only).
  • bookingNumbers string
    Accounting booking-number string. Server-managed (read-only).
  • businessCaseId integer (int64) format: int64
    Accounting business case id. Server-managed (read-only).
  • bookingStatus string
    Booking status (e.g. OPEN, PARTIAL, PAID). Server-managed (read-only).
  • bookingMessage string
    Optional booking error/info code (e.g. INVALID_SUBSCRIPTION_FOR_ACCOUNTING). Server-managed (read-only).
  • bookingSealed boolean
    Whether the booking has been finalized. Server-managed (read-only).
  • fiscalYearHasCreatedAuto boolean
    Whether a fiscal year was auto-created during booking. Server-managed (read-only).
  • createBy string
    Server-assigned audit user (token subject). Server-managed (read-only).
400 Data invalid

Error codes for this response (the code field of the response body):
  • invoice.vat_code_missing — At least one orderItems[] entry set VAT on vatType, vatCase or the top-level vatCode while leaving vat.vatCode empty. Only vat.vatCode is stored, so that line would have been booked at 0%. Move the code to vat.vatCode, or send "0" ("No VAT") for a position that genuinely carries none.
  • invoice.vat_rate_mismatch — At least one orderItems[] entry sent a vat.rate that is not the rate of its vat.vatCode. The booking always uses the code's rate, so the invoice document would state a different percentage than the accounting record. Send the matching rate, or omit vat.rate and let the server fill it in.
Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/invoices/next-invoice-numberkey / tokenGet the next available invoice number for the authenticated company.
Returns the next available invoice number for the company resolved from the bearer JWT. The caller must hold the FINANCE permission on the target company. This operation is NOT idempotent — each successful call advances the persisted next-invoice-number counter on an internal service, so the returned value is reserved and will not be returned again. Do not retry on success.
operationId

getNextInvoiceNumber — the method name a generated client uses.

Required permission

FINANCE
Available through: Administrator, External user, Kundenbeziehungen

Responses 6
200 Next available invoice number returned. show body

application/json NextInvoiceNumberResponse

  • nextInvoiceNumber integer (int64) format: int64 example: 2026001
    The next available invoice number reserved for the authenticated company. Each successful call advances the persisted counter; the value is therefore unique per call.
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/invoices/{id}key / tokenGet a single invoice by its numeric id.
Returns the fully-enriched invoice document for the given id under the company resolved from the bearer JWT. The response includes order items enriched with inventory selection data and accounting booking-status fields (bookingStatus, bookingDueDate, bookingSealed) populated by an internal service. The caller must hold the FINANCE permission on the target company.
operationId

getInvoiceById — the method name a generated client uses.

Required permission

FINANCE_GET_INVOICE
Available through: Administrator, External user, Buchhalter, Kundenbeziehungen

Parameters 1
NameDescription
id required
path integer
Numeric primary key of the invoice to retrieve. Obtain this from the id field of a previously created invoice (POST /core/v1/invoices).
example: 42
Responses 6
200 Invoice found and returned. show body

application/json Invoice

  • id integer (int64) format: int64 example: 0
    Invoice id. Must be 0 or omitted when creating a new invoice. This endpoint only supports creation; updating an existing invoice is not supported.
  • orderType string default: INVOICE example: INVOICE
    Polymorphic discriminator. Must be INVOICE. Allowed values: INVOICE.
  • status string example: INVOICED
    Invoice status. Allowed values: DRAFT, INVOICED, SENT, PAID, CANCELLED. Required. Status INVOICED or SENT triggers accounting booking.
  • invoiceCode string required maxLength: 64 pattern: \S example: INV-2026-001
    Human-readable invoice code. Required and unique per company.
  • invoiceNumber integer (int64) format: int64 example: 2026001
    Sequential invoice number, typically obtained from GET /invoices/next-invoice-number.
  • documentDate string (date) format: date example: 2026-05-28
    Invoice document date (ISO 8601). Required when amount is greater than 0. Must fall inside the company's active Order Management subscription period.
  • paymentDate string (date) format: date example: 2026-06-27
    Payment due date (ISO 8601). Required when amount is greater than 0. Must be on or after documentDate.
  • deliveryDate string (date) format: date example: 2026-05-25
    Service delivery date (ISO 8601).
  • issuedDate string (date) format: date example: 2026-05-28
    Date the invoice was issued (ISO 8601).
  • servicePeriodFrom string (date) format: date example: 2026-05-01
    Service period start date (ISO 8601).
  • servicePeriodTo string (date) format: date example: 2026-05-31
    Service period end date (ISO 8601).
  • servicePeriodPattern string maxLength: 32 example: MONTHLY
    Service period pattern label (e.g. MONTHLY, YEARLY).
  • vatDate string (date) format: date
    VAT date. Server-managed (read-only).
  • bookingDueDate string (date) format: date
    Booking due date returned by accounting. Server-managed (read-only).
  • lastModified string (date-time) format: date-time
    Last modification timestamp. Server-managed (read-only).
  • createDate string (date-time) format: date-time
    Creation timestamp. Server-managed (read-only).
  • amount number example: 1080
    Invoice total. When usingVAT=false (VAT-exclusive items) this is the gross total = net + VAT; when usingVAT=true (VAT-inclusive items) it is the sum of the gross item amounts (VAT already inside). Caller-supplied — the server does not recompute it.
  • usingVAT boolean default: false example: True
    Controls whether each item price/amount is VAT-inclusive (gross) or VAT-exclusive (net). This is the GUI checkbox "VAT included in amount of each item". true = amounts already include VAT (INCLUDE_VAT); false = VAT is added on top of the net amounts (EXCLUDE_VAT). It does not turn VAT on or off — whether VAT applies at all is governed by the company's VAT registration. Use GET /core/latest/company-configuration/including-vat for the company default. The server stores the amounts you send verbatim and does not recompute them from this flag — send price/amount consistent with the chosen mode (see the create operation's VAT-handling notes).
  • usingExportVat boolean default: false example: False
    Export invoice flag — the GUI "Export" checkbox. When true, the invoice is treated as an export: every orderItems[].vat.rate must be 0 (export/zero VAT code), so no VAT is charged. When false (default) the items' normal VAT rates apply. The server does not recompute item VAT from this flag — set the per-item VAT accordingly.
  • hasCompanyVat boolean example: True
    Whether the company is liable for VAT. Leave this out. The server derives it from the company's VAT registration for the invoice's effective VAT date (deliveryDate when set, otherwise documentDate) and a derived value always wins over a value sent here. It is documented only because it is accepted, and because sending false on a VAT-registered company used to book every position at 0% while returning 200 — this field is the master switch for VAT at booking time, ahead of any per-line VAT code. It is only consulted when the company has no VAT configuration for that date, where it cannot be derived at all.
  • subject string maxLength: 1024 example: Invoice 2026-001
    Free-text invoice subject.
  • closeAndSignature string maxLength: 4096 example: Thank you for your business.
    Free-text closing remarks / signature block.
  • ourReference string maxLength: 128 example: ACC-2026
    Internal sender reference.
  • yourReference string maxLength: 128 example: PO-9981
    Customer-side reference (e.g. PO number).
  • companyCityAndDate string maxLength: 256 example: Zurich, 28.05.2026
    Header line such as 'Zurich, 28.05.2026'.
  • postMethod string example: SEND_EMAIL
    Distribution channel recorded on the invoice. Stored only — creating an invoice does not deliver it (no email/ePost/eBill/print&send). Allowed values: A_POST, B_POST, SEND_EMAIL, PRINT_AND_MANUAL_SEND, EPOST, EBILL.
  • delivery string maxLength: 64 example: DHL
    Delivery method label (free text).
  • ibanNumberCHF string example: CH9300762011623852957
    CHF IBAN for payment. Validated by downstream service.
  • ibanNumberCHW string example: CH9300762011623852957
    WIR-franc IBAN for payment.
  • wirAcceptanceRate number example: 0
    WIR acceptance percentage.
  • referenceNumber string maxLength: 64 example: 21 00000 00003 13947 14300 09017
    QR / ISR reference number.
  • qrInvoice boolean default: false example: True
    When true, the invoice is rendered/booked as a Swiss QR-invoice. Defaults to false.
  • fromAutoInvoicing boolean default: false example: False
    Indicates the invoice was generated by auto-invoicing. Defaults to false.
  • fromInvoiceRun boolean default: false example: False
    Indicates the invoice was produced by a recurring invoice run. When true, accounting booking and inventory transactions are skipped. Defaults to false.
  • invoiceType string example: MANUAL
    Invoice type. Allowed values: MANUAL, CREDIT_DEBIT.
  • originDistributionMethod string example: SEND_EMAIL
    Origin distribution method. Allowed values: A_POST, B_POST, SEND_EMAIL, PRINT_AND_MANUAL_SEND, EPOST, EBILL.
  • templateId integer (int64) format: int64 example: 0
    Template id used to create this invoice.
  • runHistoryId integer (int64) format: int64 example: 0
    Recurring invoice run history id.
  • settledAmount number example: 0
    KLARA-Pay settled amount (online shop only).
  • bookingNumbers string
    Accounting booking-number string. Server-managed (read-only).
  • businessCaseId integer (int64) format: int64
    Accounting business case id. Server-managed (read-only).
  • bookingStatus string
    Booking status (e.g. OPEN, PARTIAL, PAID). Server-managed (read-only).
  • bookingMessage string
    Optional booking error/info code (e.g. INVALID_SUBSCRIPTION_FOR_ACCOUNTING). Server-managed (read-only).
  • bookingSealed boolean
    Whether the booking has been finalized. Server-managed (read-only).
  • fiscalYearHasCreatedAuto boolean
    Whether a fiscal year was auto-created during booking. Server-managed (read-only).
  • createBy string
    Server-assigned audit user (token subject). Server-managed (read-only).
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 No invoice with the given id exists for the authenticated company.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
POST/core/v1/invoices/{id}/printed-documentkey / tokenReturn the invoice as a PDF (rendering it if needed).
Returns the invoice document as a binary application/pdf stream via the internal KLARA printing pipeline (an internal service + Aspose Words), mirroring the behaviour of the KLARA GUI. The caller must hold the FINANCE permission on the target company.

Reuse vs. render (mirrors the KLARA GUI): if the invoice was already printed, the previously rendered PDF is fetched from storage and returned as-is; if it was not yet printed, it is rendered now and the printedFileId is stored on the invoice record. In both cases the response body is the binary PDF with a Content-Disposition: attachment header containing the suggested filename. This is a POST (not GET) because the first print persists the printedFileId.
operationId

printInvoice — the method name a generated client uses.

Required permission

FINANCE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 1
NameDescription
id required
path integer
ID of the invoice to return as PDF. Must belong to the company resolved from the bearer JWT.
example: 42
Responses 6
200 Invoice PDF returned as a binary application/pdf stream with a Content-Disposition: attachment header — either freshly rendered (first print) or the previously stored PDF (already printed). show body

application/pdf any

401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Invoice not found.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
POST/core/v1/invoices/{id}/sendkey / tokenSend a booked invoice (smart delivery or a forced channel).
Sends an already-booked invoice to its recipient, synchronously, under the company resolved from the bearer JWT.

Omit channel for smart delivery: the system auto-routes through EPOST, EBILL, SEND_EMAIL and Print&Send and only fails if none can deliver. Provide channel to force that exact channel: if the recipient is not eligible (e.g. no email on file, not eBill-registered, Print&Send not subscribed) the call fails with 400. The invoice PDF is rendered on demand when it has not been printed yet.

Prerequisites: the invoice must already be booked — DRAFT and cancelled invoices are rejected with 400. Create/book it via POST /core/v1/invoices (status=INVOICED) first.

Not idempotent: each successful call performs a real delivery (sends an email / hands a letter to the postal channel) and overwrites the invoice's recorded post method — do not retry blindly on success.

channel uses the same values as Invoice.postMethod, except PRINT_AND_MANUAL_SEND, which is not a deliverable channel and is rejected with 400. Authentication is API key + bearer JWT; the caller must hold the FINANCE permission on the target company.
operationId

sendInvoice — the method name a generated client uses.

Required permission

FINANCE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 2
NameDescription
id required
path integer
Numeric primary key of the booked invoice to send. Must belong to the company resolved from the bearer JWT. Obtain it from the id of a previously created invoice (POST /core/v1/invoices).
example: 42
channel
query string
Forced distribution channel. Leave empty for smart delivery (auto-routing) — the default is no forced channel. Allowed values: EPOST, EBILL, SEND_EMAIL, A_POST, B_POST. PRINT_AND_MANUAL_SEND is rejected with 400 (not a deliverable channel).
Allowed values: A_POST, B_POST, SEND_EMAIL, PRINT_AND_MANUAL_SEND, EPOST, EBILL
Responses 7
200 Invoice delivered. Returns the channel actually used, whether it was smart-routed, the OneAPI delivery id and the archived PDF's printedFileId. show body

application/json SendInvoiceResult

  • delivered boolean example: True
    true when delivery was confirmed via the channel actually used.
  • smart boolean example: True
    true when the channel was auto-selected (smart delivery, i.e. no channel was forced); false when a channel was forced.
  • channel object example: SEND_EMAIL
    The channel actually used to deliver the invoice. For physical post this is the resolved postage method (e.g. A_POST).
    Allowed values: A_POST, B_POST, SEND_EMAIL, PRINT_AND_MANUAL_SEND, EPOST, EBILL
  • deliveryId string example: 9b1f4c8e-2d3a-4f6b-8c7d-1e2f3a4b5c6d
    OneAPI delivery id, when available (forced sends only; null for smart delivery).
  • printedFileId string example: 1771764
    The printedFileId of the archived invoice PDF rendered/reused during the send.
400 Invoice is DRAFT/cancelled, the channel is unsupported (PRINT_AND_MANUAL_SEND), the recipient is not eligible for the forced channel, or smart delivery found no channel.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 No invoice with the given id exists for the authenticated company.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/order-documents/filter/type-and-order-numberkey / tokenList order-management documents by type and order number.
Returns every order-management document of the company resolved from the bearer JWT that has the given type and business order-number. Used to discover sibling documents on the same order chain (e.g. find the DELIVERY_NOTEs for an order number before creating an INVOICE from them). The caller must hold the FINANCE permission on the target company. This operation is idempotent and read-only — it can be safely retried.
operationId

listOrderDocumentsByTypeAndOrderNumber — the method name a generated client uses.

Required permission

FINANCE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 2
NameDescription
order-number required
query integer
Business order number shared by all documents in the same order chain (e.g. the order.orderNumber returned by POST /core/v1/invoices). Exact match. Required.
example: 377
type required
query string
Order-document type to filter by. Allowed values: OFFER, CONFIRMATION, DELIVERY_NOTE, INVOICE, CREDIT_NOTE, FRIENDLY_REMINDER, FIRST_REMINDER, SECOND_REMINDER, PAYSLIP, RECURRING_INVOICE_TEMPLATE. Required.
Allowed values: OFFER, CONFIRMATION, DELIVERY_NOTE, INVOICE, CREDIT_NOTE, FRIENDLY_REMINDER, FIRST_REMINDER, SECOND_REMINDER, PAYSLIP, RECURRING_INVOICE_TEMPLATE
example: DELIVERY_NOTE
Responses 6
200 Matching order-management documents. show body

application/json array of OrderDocument

Array of OrderDocument.

  • id integer (int64) format: int64 example: 1234
    Document id (database primary key).
  • orderType string example: DELIVERY_NOTE
    Polymorphic discriminator. Allowed values: OFFER, CONFIRMATION, DELIVERY_NOTE, INVOICE, CREDIT_NOTE, FRIENDLY_REMINDER, FIRST_REMINDER, SECOND_REMINDER, PAYSLIP, RECURRING_INVOICE_TEMPLATE.
  • status string example: SENT
    Document status (subtype-specific). For invoices: DRAFT, INVOICED, SENT, PAID, CANCELLED.
  • documentDate string (date) format: date example: 2026-05-28
    Document creation/business date (ISO 8601).
  • issuedDate string (date) format: date example: 2026-05-28
    Date the document was issued (ISO 8601).
  • amount number example: 500
    Document gross total (incl. VAT when applicable).
  • ourReference string example: ACC-2026
    Internal sender reference.
  • yourReference string example: PO-9981
    Customer-side reference (e.g. PO number).
  • subject string example: Delivery note 377
    Free-text document subject.
  • closeAndSignature string example: Thank you for your business.
    Free-text closing remarks / signature block.
  • companyCityAndDate string example: Zurich, 28.05.2026
    Header line such as 'Zurich, 28.05.2026'.
  • usingVAT boolean default: false example: True
    Whether VAT is applied on this document.
  • vatDate string (date) format: date
    VAT date. Server-managed (read-only).
  • printedFileId string example: 1771764
    Document file id of the rendered PDF (if any).
400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/order-documents/{order-type}/next-document-numberkey / tokenGet the next document number for a given order-document type.
Returns the next available sequence number and its formatted document code for the authenticated company and the given order-type. Use the returned documentCode as invoiceCode / offerCode when subsequently creating a document with POST /core/v1/invoices. Side effect for INVOICE: the persisted counter is advanced on every call — do not call speculatively. Only meaningful for OFFER, CONFIRMATION, DELIVERY_NOTE, and INVOICE; other types always return documentNumber = 0. If the company has configured MANUAL numbering for the requested type, the downstream service returns HTTP 500 — check GET /core/v1/order-numbering-configurations first. The caller must hold the FINANCE permission on the target company.
operationId

getNextDocumentNumber — the method name a generated client uses.

Required permission

FINANCE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 1
NameDescription
order-type required
path string
Order-document type whose counter to advance. Meaningful values: OFFER, CONFIRMATION, DELIVERY_NOTE, INVOICE. Other enum values (CREDIT_NOTE, FRIENDLY_REMINDER, FIRST_REMINDER, SECOND_REMINDER, PAYSLIP, RECURRING_INVOICE_TEMPLATE) are accepted but always return documentNumber = 0. An invalid value returns HTTP 400.
Allowed values: OFFER, CONFIRMATION, DELIVERY_NOTE, INVOICE, CREDIT_NOTE, FRIENDLY_REMINDER, FIRST_REMINDER, SECOND_REMINDER, PAYSLIP, RECURRING_INVOICE_TEMPLATE
example: INVOICE
Responses 6
200 Next document number and formatted code for the requested order type. show body

application/json OrderNumberingResult

  • orderType object example: INVOICE
    Order-management document type. Used as the discriminator on OrderDocument.orderType.
  • orderNumberingType object example: STANDARD
    Strategy used to assign document numbers for an order type. STANDARD — server auto-increments; MANUAL — caller supplies the number; CUSTOMISED — caller supplies a formatted code matching the configured pattern.
  • startingNumber integer (int64) format: int64 example: 1000
    Starting sequence number for STANDARD and CUSTOMISED strategies.
  • increment integer (int64) format: int64 example: 1
    Step size between successive auto-incremented numbers.
  • format string example: INV-2026-
    Alphanumeric prefix for CUSTOMISED numbering (the server appends the sequence number).
  • documentNumber integer (int64) format: int64 example: 1001
    The next document number to use (the sequence integer). For INVOICE this counter is persisted on every call — do not call speculatively.
  • documentCode string example: 1001
    The next document code to use as invoiceCode / offerCode. For STANDARD and MANUAL this equals String.valueOf(documentNumber); for CUSTOMISED it equals format + documentNumber (e.g. "INV-2026-1001").
400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/order-numbering-configurationskey / tokenGet the order-numbering configuration for a document type.
Returns the numbering strategy configured for the given order-type of the company resolved from the bearer JWT. Use this before creating a document to decide how to supply the document number in POST /core/v1/invoices: STANDARD — server auto-assigns; MANUAL — set invoiceCode yourself; CUSTOMISED — set invoiceCode to a value matching the returned format pattern. If no configuration has been saved by the company administrator, a default STANDARD configuration is returned. The caller must hold the FINANCE permission on the target company. This operation is idempotent and read-only.
operationId

getOrderNumberingConfiguration — the method name a generated client uses.

Required permission

FINANCE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 1
NameDescription
order-type
query string
Document type to retrieve the numbering configuration for. Allowed values: OFFER, CONFIRMATION, DELIVERY_NOTE, INVOICE, CREDIT_NOTE, FRIENDLY_REMINDER, FIRST_REMINDER, SECOND_REMINDER, PAYSLIP, RECURRING_INVOICE_TEMPLATE. Recommended — omitting it returns a generic default with a null orderType field.
Allowed values: OFFER, CONFIRMATION, DELIVERY_NOTE, INVOICE, CREDIT_NOTE, FRIENDLY_REMINDER, FIRST_REMINDER, SECOND_REMINDER, PAYSLIP, RECURRING_INVOICE_TEMPLATE
example: INVOICE
Responses 6
200 Numbering configuration for the requested document type. show body

application/json OrderNumberingConfiguration

  • orderType object example: INVOICE
    Order-management document type. Used as the discriminator on OrderDocument.orderType.
  • orderNumberingType object example: STANDARD
    Strategy used to assign document numbers for an order type. STANDARD — server auto-increments; MANUAL — caller supplies the number; CUSTOMISED — caller supplies a formatted code matching the configured pattern.
  • startingNumber integer (int64) format: int64 example: 1000
    The first number in the auto-increment sequence (relevant for STANDARD). Null when not configured.
  • increment integer (int64) format: int64 example: 1
    Step size between successive auto-incremented numbers (relevant for STANDARD). Null when not configured.
  • format string example: INV-2026-{SEQ}
    Alphanumeric format pattern for CUSTOMISED numbering (e.g. INV-{YYYY}-{SEQ}). Null when not configured.
400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/orders/next-order-numberkey / tokenGet the next available order number for the authenticated company.
Returns the next available business order number for the company resolved from the bearer JWT. Use the returned nextOrderNumber as the orderNumber field when subsequently creating an order. Not idempotent: each call reserves and advances the in-memory counter — call this immediately before creating the order and do not call speculatively. Gaps may appear in the sequence if the subsequent order creation fails. The caller must hold the FINANCE permission on the target company.
operationId

getNextOrderNumber — the method name a generated client uses.

Required permission

FINANCE
Available through: Administrator, External user, Kundenbeziehungen

Responses 5
200 Next available order number for the authenticated company. show body

application/json OrderNextNumberResult

  • nextOrderNumber integer (int32) format: int32 example: 10041
    The next available business order number for the authenticated company. Reserved exclusively for this call — use it as the orderNumber when subsequently creating the order. Gaps may appear in the sequence if the order creation fails after this call.
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated

Sales & Articles

Article28

GET/core/latest/article-categorieskey / tokenGet all categories
Returns the company's article categories. Page the collection with offset and limit; the size of the whole filtered collection is returned in the X-Total-Count response header, so a caller knows how far it still has to walk. Omitting limit returns the whole collection, as before.
operationId

listArticleCategories — the method name a generated client uses.

Required permission

ARTICLE_READ_ONLY
Available through: Administrator, External user, Mitarbeiter und Lohn, Kundenbeziehungen, Zeit- und Materialrapporte, Online Terminbuchung

Parameters 6
NameDescription
active-status
query boolean
Active status
keyword
query string
Renamed to search-key. This name is accepted until 2027-09-01; when both are sent, search-key wins. After that date, a request sending keyword without search-key is rejected with 400.

Deprecated — use search-key instead. Free-text search over the name. This name has no length limit and search-key rejects values over 256 characters, so shorten anything longer before migrating.
limit
query integer (int32)
Limit filters returned
format: int32 min: 1
offset
query integer (int32)
0-based pagination offset - the number of rows to skip before the returned page. Defaults to 0. Combine with limit to walk the full collection; the total to walk is returned in the X-Total-Count response header.
format: int32 min: 0 default: 0
search-key
query string
Free-text search over the name, matched case-insensitively in the language selected by Accept-Language. Maximum length 256 characters.
maxLength: 256
Accept-Language
header string
Language code is used for filtering by the keyword with multilingual
example: en
Responses 5
200 Return successfully show body

application/json array of ArticleCategory

Array of ArticleCategory.

  • id string read-only example: 1
    Id of the category. Does not need to be included when creating article category
  • nameDE string required example: German name
    Name of the category in German
  • nameEN string example: English name
    Name of the category in English
  • nameFR string example: French name
    Name of the category in French
  • nameIT string example: Italian name
    Name of the category in Italian
  • order integer (int32) format: int32 read-only
    Order of this category.
    Does not need to be included when creating article category.
  • active boolean
    Indicates if the category is active or not
  • imageId string read-only example: 1
    Image Id of the category. Does not need to be included when creating article category
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
POST/core/latest/article-categorieskey / tokenCreate a new category
operationId

createArticleCategory — the method name a generated client uses.

Required permission

ARTICLE
Available through: Administrator, External user, Kundenbeziehungen

Request body

application/json ArticleCategory

  • id string read-only example: 1
    Id of the category. Does not need to be included when creating article category
  • nameDE string required example: German name
    Name of the category in German
  • nameEN string example: English name
    Name of the category in English
  • nameFR string example: French name
    Name of the category in French
  • nameIT string example: Italian name
    Name of the category in Italian
  • order integer (int32) format: int32 read-only
    Order of this category.
    Does not need to be included when creating article category.
  • active boolean
    Indicates if the category is active or not
  • imageId string read-only example: 1
    Image Id of the category. Does not need to be included when creating article category
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
Responses 5
201 Category created show body

application/json ArticleCategory

  • id string read-only example: 1
    Id of the category. Does not need to be included when creating article category
  • nameDE string required example: German name
    Name of the category in German
  • nameEN string example: English name
    Name of the category in English
  • nameFR string example: French name
    Name of the category in French
  • nameIT string example: Italian name
    Name of the category in Italian
  • order integer (int32) format: int32 read-only
    Order of this category.
    Does not need to be included when creating article category.
  • active boolean
    Indicates if the category is active or not
  • imageId string read-only example: 1
    Image Id of the category. Does not need to be included when creating article category
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
DELETE/core/latest/article-categories/{category-id}key / tokenDelete category by Id
operationId

deleteArticleCategory — the method name a generated client uses.

Required permission

ARTICLE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 1
NameDescription
category-id required
path string
Responses 6
204 Deleted successfully no response body
400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/latest/article-categories/{category-id}key / tokenGet category by id
operationId

getArticleCategoryById — the method name a generated client uses.

Required permission

ARTICLE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 1
NameDescription
category-id required
path string
Responses 5
200 Return successfully show body

application/json ArticleCategory

  • id string read-only example: 1
    Id of the category. Does not need to be included when creating article category
  • nameDE string required example: German name
    Name of the category in German
  • nameEN string example: English name
    Name of the category in English
  • nameFR string example: French name
    Name of the category in French
  • nameIT string example: Italian name
    Name of the category in Italian
  • order integer (int32) format: int32 read-only
    Order of this category.
    Does not need to be included when creating article category.
  • active boolean
    Indicates if the category is active or not
  • imageId string read-only example: 1
    Image Id of the category. Does not need to be included when creating article category
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
PUT/core/latest/article-categories/{category-id}key / tokenUpdate category by Id
operationId

updateArticleCategory — the method name a generated client uses.

Required permission

ARTICLE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 1
NameDescription
category-id required
path string
Request body

application/json ArticleCategory

  • id string read-only example: 1
    Id of the category. Does not need to be included when creating article category
  • nameDE string required example: German name
    Name of the category in German
  • nameEN string example: English name
    Name of the category in English
  • nameFR string example: French name
    Name of the category in French
  • nameIT string example: Italian name
    Name of the category in Italian
  • order integer (int32) format: int32 read-only
    Order of this category.
    Does not need to be included when creating article category.
  • active boolean
    Indicates if the category is active or not
  • imageId string read-only example: 1
    Image Id of the category. Does not need to be included when creating article category
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
Responses 6
200 Updated successfully show body

application/json ArticleCategory

  • id string read-only example: 1
    Id of the category. Does not need to be included when creating article category
  • nameDE string required example: German name
    Name of the category in German
  • nameEN string example: English name
    Name of the category in English
  • nameFR string example: French name
    Name of the category in French
  • nameIT string example: Italian name
    Name of the category in Italian
  • order integer (int32) format: int32 read-only
    Order of this category.
    Does not need to be included when creating article category.
  • active boolean
    Indicates if the category is active or not
  • imageId string read-only example: 1
    Image Id of the category. Does not need to be included when creating article category
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
POST/core/latest/article-categories/{category-id}/assign-to-articleskey / tokenAssign category to articles
Assign the specified article category to multiple articles for usage in Online Booking, Online shop, and Point of sale.
Only the articles entered in the request body will have the specified article category added to their respective filters.
Other articles will not be affected
operationId

assignArticleCategoryToArticles — the method name a generated client uses.

Required permission

ARTICLE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 1
NameDescription
category-id required
path string
Request body

application/json CategoryAssigningGroup

  • articleIdsForOnlineShop array of string
    Article ids need to be assigned with a online shop category
  • articleIdsForBooking array of string
    Article ids need to be assigned with a booking category
  • articleIdsForPos array of string
    Article ids need to be assigned with a pos category
Responses 6
204 Assigned successfully no response body
400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/latest/article-filterskey / tokenSearch article filters
Returns the company's article filters. Page the collection with offset and limit; the size of the whole filtered collection is returned in the X-Total-Count response header, so a caller knows how far it still has to walk. Omitting limit returns the whole collection, as before.
operationId

listArticleFilters — the method name a generated client uses.

Required permission

ARTICLE_READ_ONLY
Available through: Administrator, External user, Mitarbeiter und Lohn, Kundenbeziehungen, Zeit- und Materialrapporte, Online Terminbuchung

Parameters 6
NameDescription
active-status
query boolean
Active status
keyword
query string
Renamed to search-key. This name is accepted until 2027-09-01; when both are sent, search-key wins. After that date, a request sending keyword without search-key is rejected with 400.

Deprecated — use search-key instead. Free-text search over the name. This name has no length limit and search-key rejects values over 256 characters, so shorten anything longer before migrating.
limit
query integer (int32)
Limit filters returned
format: int32 min: 1
offset
query integer (int32)
0-based pagination offset - the number of rows to skip before the returned page. Defaults to 0. Combine with limit to walk the full collection; the total to walk is returned in the X-Total-Count response header.
format: int32 min: 0 default: 0
search-key
query string
Free-text search over the name, matched case-insensitively in the language selected by Accept-Language. Maximum length 256 characters.
maxLength: 256
Accept-Language
header string
Language code is used for filtering by the keyword with multilingual
example: en
Responses 4
200 Filters show body

application/json array of ArticleFilter

Array of ArticleFilter.

  • id string read-only example: 1
    Id of the filter. Does not need to be included when creating article filter
  • nameDE string required example: shop
    Name of the filter in german
  • nameEN string example: shop
    Name of the filter in english
  • nameFR string example: shop
    Name of the filter in french
  • nameIT string example: shop
    Name of the filter in italy
  • order integer (int32) format: int32
    Order of this filter.
    Does not need to be included when creating article filter.
  • active boolean
    Indicates if the filter is active or not
  • imageId string read-only
    The image id of the filter. Does not need to be included when creating article
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
POST/core/latest/article-filterskey / tokenCreate a article filter
operationId

createArticleFilter — the method name a generated client uses.

Required permission

ARTICLE
Available through: Administrator, External user, Kundenbeziehungen

Request body required
Filter data

application/json ArticleFilter

  • id string read-only example: 1
    Id of the filter. Does not need to be included when creating article filter
  • nameDE string required example: shop
    Name of the filter in german
  • nameEN string example: shop
    Name of the filter in english
  • nameFR string example: shop
    Name of the filter in french
  • nameIT string example: shop
    Name of the filter in italy
  • order integer (int32) format: int32
    Order of this filter.
    Does not need to be included when creating article filter.
  • active boolean
    Indicates if the filter is active or not
  • imageId string read-only
    The image id of the filter. Does not need to be included when creating article
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
Responses 5
201 Filter created show body

application/json ArticleFilter

  • id string read-only example: 1
    Id of the filter. Does not need to be included when creating article filter
  • nameDE string required example: shop
    Name of the filter in german
  • nameEN string example: shop
    Name of the filter in english
  • nameFR string example: shop
    Name of the filter in french
  • nameIT string example: shop
    Name of the filter in italy
  • order integer (int32) format: int32
    Order of this filter.
    Does not need to be included when creating article filter.
  • active boolean
    Indicates if the filter is active or not
  • imageId string read-only
    The image id of the filter. Does not need to be included when creating article
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
DELETE/core/latest/article-filters/{filter-id}key / tokenDelete article filter by id
This filter will be removed from all articles
operationId

deleteArticleFilter — the method name a generated client uses.

Required permission

ARTICLE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 1
NameDescription
filter-id required
path string
Responses 5
204 Delete successfully no response body
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/latest/article-filters/{filter-id}key / tokenGet article filter by id
operationId

getArticleFilterById — the method name a generated client uses.

Required permission

ARTICLE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 1
NameDescription
filter-id required
path string
Responses 5
200 Filter show body

application/json ArticleFilter

  • id string read-only example: 1
    Id of the filter. Does not need to be included when creating article filter
  • nameDE string required example: shop
    Name of the filter in german
  • nameEN string example: shop
    Name of the filter in english
  • nameFR string example: shop
    Name of the filter in french
  • nameIT string example: shop
    Name of the filter in italy
  • order integer (int32) format: int32
    Order of this filter.
    Does not need to be included when creating article filter.
  • active boolean
    Indicates if the filter is active or not
  • imageId string read-only
    The image id of the filter. Does not need to be included when creating article
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
PUT/core/latest/article-filters/{filter-id}key / tokenUpdate article filter by id
operationId

updateArticleFilter — the method name a generated client uses.

Required permission

ARTICLE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 1
NameDescription
filter-id required
path string
Request body required
Filter data

application/json ArticleFilter

  • id string read-only example: 1
    Id of the filter. Does not need to be included when creating article filter
  • nameDE string required example: shop
    Name of the filter in german
  • nameEN string example: shop
    Name of the filter in english
  • nameFR string example: shop
    Name of the filter in french
  • nameIT string example: shop
    Name of the filter in italy
  • order integer (int32) format: int32
    Order of this filter.
    Does not need to be included when creating article filter.
  • active boolean
    Indicates if the filter is active or not
  • imageId string read-only
    The image id of the filter. Does not need to be included when creating article
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
Responses 6
200 Update successfully show body

application/json ArticleFilter

  • id string read-only example: 1
    Id of the filter. Does not need to be included when creating article filter
  • nameDE string required example: shop
    Name of the filter in german
  • nameEN string example: shop
    Name of the filter in english
  • nameFR string example: shop
    Name of the filter in french
  • nameIT string example: shop
    Name of the filter in italy
  • order integer (int32) format: int32
    Order of this filter.
    Does not need to be included when creating article filter.
  • active boolean
    Indicates if the filter is active or not
  • imageId string read-only
    The image id of the filter. Does not need to be included when creating article
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
POST/core/latest/article-filters/{filter-id}/assign-to-articleskey / tokenAssign filter to articles
Assign the specified article filter to multiple articles for usage in Online Booking, Online shop, and Point of sale.
Only the articles entered in the request body will have the specified article filter added to their respective filters.
Other articles will not be affected
operationId

assignArticleFilterToArticles — the method name a generated client uses.

Required permission

ARTICLE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 1
NameDescription
filter-id required
path string
Request body required
Article ids

application/json FilterAssigningGroup1

  • assignedPosArticleIds array of string
    Article ids will have the filter as a pos filter
  • assignedOnlineShopArticleIds array of string
    Article ids will have the filter as a online shop filter
  • assignedBookingArticleIds array of string
    Article ids will have the filter as a booking filter
Responses 6
204 Successfully no response body
400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/latest/articleskey / tokenReturns article list of a company
operationId

listArticles — the method name a generated client uses.

Required permission

ARTICLE_READ_ONLY
Available through: Administrator, External user, Mitarbeiter und Lohn, Kundenbeziehungen, Zeit- und Materialrapporte, Online Terminbuchung

Parameters 3
NameDescription
limit
query integer (int32)
Define the limit of the article list that this API returns.
For example, if a company have 20 articles in total, and this limit parameter is 5, and the offset parameter is 0,
then this API will return article list containing the first 5 articles
If not set, then default value of 48 is used
format: int32 min: 1 max: 1000 default: 48
offset
query integer (int32)
Define which position to start getting article list.
For example, if a company have 20 articles in total, and this offset parameter is 5,
then this API will return article list from the 5th article.
If not set, then default value of 0 is used
format: int32 min: 0 default: 0
product-type
query string
Filter articles with this product type.
Allowed values: SERVICE, PRODUCTION, TRADE, OTHER, GIFT_CARD, PREPAYMENT
Responses 4
200 Articles show body

application/json array of Article

Array of Article.

  • id string read-only example: 1
    Id of the article. Does not need to be included when creating article
  • nameDE string required
    Name of the article in German
  • nameEN string
    Name of the article in English
  • nameFR string
    Name of the article in French
  • nameIT string
    Name of the article in Italian
  • descriptionDE string
    Description of the article in German
  • descriptionEN string
    Description of the article in English
  • descriptionFR string
    Description of the article in French
  • descriptionIT string
    Description of the article in Italian
  • extendedDescriptionDE string
    Extended description of the article in German
  • extendedDescriptionEN string
    Extended description of the article in English
  • extendedDescriptionFR string
    Extended description of the article in French
  • extendedDescriptionIT string
    Extended description of the article in Italian
  • unitDE string required
    Unit of the article in German
  • unitEN string
    Unit of the article in English
  • unitFR string
    Unit of the article in French
  • unitIT string
    Unit of the article in Italian
  • barcode string
    Barcode of the article
  • usePos boolean
    Decides if this article is used for POS or not
  • pricePeriods array of PricePeriod
    Price periods for the article.
    If article only has single price period, ignore and don't include validFrom and validTo in the PricePeriod.
    If article have different prices valid for different periods, set value for validFrom for each price period or that price period is ignored.
    show fields

    Array of PricePeriod.

    • validFrom string (date) format: date
      The price period is valid from this time
    • validTo string (date) format: date read-only
      The price period is invalid after this time
    • price number pattern: ^\d{1,19}([.]\d{1,2})?$
      The price used for an article within this price period
    • priceCategories array of PriceCategory
      List of price categories effective for this price period
      show fields

      Array of PriceCategory.

      • name string
        Name of the price category
      • price number pattern: ^\d{1,19}([.]\d{1,2})?$
        Effective price of this price category
  • options array of ArticleOption
    Options for the article. If specify, variants for this article will be generated.
    show fields

    Array of ArticleOption.

    • name string example: color
      Name of the article option
    • values array of string
      Available choices for the article option
  • imageHrefs array of string read-only
    Reference uris for the images of this article if present.
  • isArticleSet boolean
    Decides if this article is an article set
  • articleSetName string
    Name of the article set. Does not need to be included if article is not an article set.
  • defaultQuantity number pattern: ^\d{1,19}([.]\d{1,2})?$
    The default quantity of the article
  • accountingTags array of string required
    Tags used for accounting. Articles with the same tag, same VAT case and same VAT rate are grouped together in the posting
  • articleNumber string required example: ABC123
    Article number
  • hasVariant boolean
    Specify if the article has variants or not
  • includedInArticleSets array of string
    Names of the article sets that the article is included in.
    If the article have some variants, then only the variants will show the article set name they belong to, not the parent article (null value is shown).
  • sellInOnlineShop boolean
    Specify if the article is able to be sold on the Online shop or not
  • isAdultArticle boolean
    Specify if the article is only used for adult or not
  • productType object required
    Type of product used for an article
  • posCategories array of ArticleCategoryRef
    Categories used for Point of Sale of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • posFilters array of ArticleFilterRef
    Filters used for Point of Sale of the article
    Provide only either id or href of each filter when creating Article
    show fields

    Array of ArticleFilterRef.

    • id string read-only example: 1
      Id of the filter. Does not need to be included when creating article.
    • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
      Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
    • nameDE string read-only example: shop
      Name of the filter in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the filter in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the filter in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the filter in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this filter.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the filter is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • onlineShopCategories array of ArticleCategoryRef
    Categories used for Online shop of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • onlineShopFilters array of ArticleFilterRef
    Filters used for Online shop of the article
    Provide only either id or href of each filter when creating Article
    show fields

    Array of ArticleFilterRef.

    • id string read-only example: 1
      Id of the filter. Does not need to be included when creating article.
    • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
      Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
    • nameDE string read-only example: shop
      Name of the filter in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the filter in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the filter in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the filter in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this filter.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the filter is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • bookingCategories array of ArticleCategoryRef
    Categories used for Online Booking of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • searchTags array of string
    Search tags make it easier for your customer to find your product in the online shop
  • shippingInfo object
    shipping information for an article.
    show fields
    • shippingAttributes array of string
      List of attributes used for shipping
    • weightUnit string
      Weight unit used for shipping of the article
      Allowed values: GRAM, KILOGRAM
    • dimensionUnit string
      Dimension unit used for shipping of the article
      Allowed values: CENTIMETER, METER
    • weight number pattern: ^\d{1,19}([.]\d{1,2})?$
      Weight of this article
    • width number pattern: ^\d{1,19}([.]\d{1,2})?$
      Width of this article
    • height number pattern: ^\d{1,19}([.]\d{1,2})?$
      Height of this article
    • depth number pattern: ^\d{1,19}([.]\d{1,2})?$
      Depth of this article
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
  • vats array of ArticleVat
    VAT information for the article
    show fields

    Array of ArticleVat.

    • vatType object example: NORMAL
      Article vat type of the article
    • vatCase string example: TAXABLE_SUPPLY
      VAT case of the article
    • vatCode string example: 1
      VAT code of the article VAT
    • sss1 boolean example: False
      Reporting net tax rate with SSS1 option
    • sss2 boolean example: False
      Reporting net tax rate with SSS2 option
    • reportingNetTaxRate boolean example: False
      Using VAT reporting net tax rate option
    • excludeVat boolean example: False
      Using exclude VAT option
  • numberType object
    Inventory Number Type
    Use either NO_NUMBER or SERIAL_NUMBER
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
POST/core/latest/articleskey / tokenCreate a new article
operationId

createArticle — the method name a generated client uses.

Required permission

ARTICLE
Available through: Administrator, External user, Kundenbeziehungen

Request body required
The article object with the information that needs to be created

application/json Article

  • id string read-only example: 1
    Id of the article. Does not need to be included when creating article
  • nameDE string required
    Name of the article in German
  • nameEN string
    Name of the article in English
  • nameFR string
    Name of the article in French
  • nameIT string
    Name of the article in Italian
  • descriptionDE string
    Description of the article in German
  • descriptionEN string
    Description of the article in English
  • descriptionFR string
    Description of the article in French
  • descriptionIT string
    Description of the article in Italian
  • extendedDescriptionDE string
    Extended description of the article in German
  • extendedDescriptionEN string
    Extended description of the article in English
  • extendedDescriptionFR string
    Extended description of the article in French
  • extendedDescriptionIT string
    Extended description of the article in Italian
  • unitDE string required
    Unit of the article in German
  • unitEN string
    Unit of the article in English
  • unitFR string
    Unit of the article in French
  • unitIT string
    Unit of the article in Italian
  • barcode string
    Barcode of the article
  • usePos boolean
    Decides if this article is used for POS or not
  • pricePeriods array of PricePeriod
    Price periods for the article.
    If article only has single price period, ignore and don't include validFrom and validTo in the PricePeriod.
    If article have different prices valid for different periods, set value for validFrom for each price period or that price period is ignored.
    show fields

    Array of PricePeriod.

    • validFrom string (date) format: date
      The price period is valid from this time
    • validTo string (date) format: date read-only
      The price period is invalid after this time
    • price number pattern: ^\d{1,19}([.]\d{1,2})?$
      The price used for an article within this price period
    • priceCategories array of PriceCategory
      List of price categories effective for this price period
      show fields

      Array of PriceCategory.

      • name string
        Name of the price category
      • price number pattern: ^\d{1,19}([.]\d{1,2})?$
        Effective price of this price category
  • options array of ArticleOption
    Options for the article. If specify, variants for this article will be generated.
    show fields

    Array of ArticleOption.

    • name string example: color
      Name of the article option
    • values array of string
      Available choices for the article option
  • imageHrefs array of string read-only
    Reference uris for the images of this article if present.
  • isArticleSet boolean
    Decides if this article is an article set
  • articleSetName string
    Name of the article set. Does not need to be included if article is not an article set.
  • defaultQuantity number pattern: ^\d{1,19}([.]\d{1,2})?$
    The default quantity of the article
  • accountingTags array of string required
    Tags used for accounting. Articles with the same tag, same VAT case and same VAT rate are grouped together in the posting
  • articleNumber string required example: ABC123
    Article number
  • hasVariant boolean
    Specify if the article has variants or not
  • includedInArticleSets array of string
    Names of the article sets that the article is included in.
    If the article have some variants, then only the variants will show the article set name they belong to, not the parent article (null value is shown).
  • sellInOnlineShop boolean
    Specify if the article is able to be sold on the Online shop or not
  • isAdultArticle boolean
    Specify if the article is only used for adult or not
  • productType object required
    Type of product used for an article
  • posCategories array of ArticleCategoryRef
    Categories used for Point of Sale of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • posFilters array of ArticleFilterRef
    Filters used for Point of Sale of the article
    Provide only either id or href of each filter when creating Article
    show fields

    Array of ArticleFilterRef.

    • id string read-only example: 1
      Id of the filter. Does not need to be included when creating article.
    • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
      Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
    • nameDE string read-only example: shop
      Name of the filter in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the filter in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the filter in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the filter in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this filter.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the filter is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • onlineShopCategories array of ArticleCategoryRef
    Categories used for Online shop of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • onlineShopFilters array of ArticleFilterRef
    Filters used for Online shop of the article
    Provide only either id or href of each filter when creating Article
    show fields

    Array of ArticleFilterRef.

    • id string read-only example: 1
      Id of the filter. Does not need to be included when creating article.
    • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
      Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
    • nameDE string read-only example: shop
      Name of the filter in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the filter in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the filter in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the filter in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this filter.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the filter is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • bookingCategories array of ArticleCategoryRef
    Categories used for Online Booking of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • searchTags array of string
    Search tags make it easier for your customer to find your product in the online shop
  • shippingInfo object
    shipping information for an article.
    show fields
    • shippingAttributes array of string
      List of attributes used for shipping
    • weightUnit string
      Weight unit used for shipping of the article
      Allowed values: GRAM, KILOGRAM
    • dimensionUnit string
      Dimension unit used for shipping of the article
      Allowed values: CENTIMETER, METER
    • weight number pattern: ^\d{1,19}([.]\d{1,2})?$
      Weight of this article
    • width number pattern: ^\d{1,19}([.]\d{1,2})?$
      Width of this article
    • height number pattern: ^\d{1,19}([.]\d{1,2})?$
      Height of this article
    • depth number pattern: ^\d{1,19}([.]\d{1,2})?$
      Depth of this article
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
  • vats array of ArticleVat
    VAT information for the article
    show fields

    Array of ArticleVat.

    • vatType object example: NORMAL
      Article vat type of the article
    • vatCase string example: TAXABLE_SUPPLY
      VAT case of the article
    • vatCode string example: 1
      VAT code of the article VAT
    • sss1 boolean example: False
      Reporting net tax rate with SSS1 option
    • sss2 boolean example: False
      Reporting net tax rate with SSS2 option
    • reportingNetTaxRate boolean example: False
      Using VAT reporting net tax rate option
    • excludeVat boolean example: False
      Using exclude VAT option
  • numberType object
    Inventory Number Type
    Use either NO_NUMBER or SERIAL_NUMBER
Responses 5
201 Article created show body

application/json Article

  • id string read-only example: 1
    Id of the article. Does not need to be included when creating article
  • nameDE string required
    Name of the article in German
  • nameEN string
    Name of the article in English
  • nameFR string
    Name of the article in French
  • nameIT string
    Name of the article in Italian
  • descriptionDE string
    Description of the article in German
  • descriptionEN string
    Description of the article in English
  • descriptionFR string
    Description of the article in French
  • descriptionIT string
    Description of the article in Italian
  • extendedDescriptionDE string
    Extended description of the article in German
  • extendedDescriptionEN string
    Extended description of the article in English
  • extendedDescriptionFR string
    Extended description of the article in French
  • extendedDescriptionIT string
    Extended description of the article in Italian
  • unitDE string required
    Unit of the article in German
  • unitEN string
    Unit of the article in English
  • unitFR string
    Unit of the article in French
  • unitIT string
    Unit of the article in Italian
  • barcode string
    Barcode of the article
  • usePos boolean
    Decides if this article is used for POS or not
  • pricePeriods array of PricePeriod
    Price periods for the article.
    If article only has single price period, ignore and don't include validFrom and validTo in the PricePeriod.
    If article have different prices valid for different periods, set value for validFrom for each price period or that price period is ignored.
    show fields

    Array of PricePeriod.

    • validFrom string (date) format: date
      The price period is valid from this time
    • validTo string (date) format: date read-only
      The price period is invalid after this time
    • price number pattern: ^\d{1,19}([.]\d{1,2})?$
      The price used for an article within this price period
    • priceCategories array of PriceCategory
      List of price categories effective for this price period
      show fields

      Array of PriceCategory.

      • name string
        Name of the price category
      • price number pattern: ^\d{1,19}([.]\d{1,2})?$
        Effective price of this price category
  • options array of ArticleOption
    Options for the article. If specify, variants for this article will be generated.
    show fields

    Array of ArticleOption.

    • name string example: color
      Name of the article option
    • values array of string
      Available choices for the article option
  • imageHrefs array of string read-only
    Reference uris for the images of this article if present.
  • isArticleSet boolean
    Decides if this article is an article set
  • articleSetName string
    Name of the article set. Does not need to be included if article is not an article set.
  • defaultQuantity number pattern: ^\d{1,19}([.]\d{1,2})?$
    The default quantity of the article
  • accountingTags array of string required
    Tags used for accounting. Articles with the same tag, same VAT case and same VAT rate are grouped together in the posting
  • articleNumber string required example: ABC123
    Article number
  • hasVariant boolean
    Specify if the article has variants or not
  • includedInArticleSets array of string
    Names of the article sets that the article is included in.
    If the article have some variants, then only the variants will show the article set name they belong to, not the parent article (null value is shown).
  • sellInOnlineShop boolean
    Specify if the article is able to be sold on the Online shop or not
  • isAdultArticle boolean
    Specify if the article is only used for adult or not
  • productType object required
    Type of product used for an article
  • posCategories array of ArticleCategoryRef
    Categories used for Point of Sale of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • posFilters array of ArticleFilterRef
    Filters used for Point of Sale of the article
    Provide only either id or href of each filter when creating Article
    show fields

    Array of ArticleFilterRef.

    • id string read-only example: 1
      Id of the filter. Does not need to be included when creating article.
    • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
      Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
    • nameDE string read-only example: shop
      Name of the filter in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the filter in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the filter in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the filter in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this filter.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the filter is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • onlineShopCategories array of ArticleCategoryRef
    Categories used for Online shop of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • onlineShopFilters array of ArticleFilterRef
    Filters used for Online shop of the article
    Provide only either id or href of each filter when creating Article
    show fields

    Array of ArticleFilterRef.

    • id string read-only example: 1
      Id of the filter. Does not need to be included when creating article.
    • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
      Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
    • nameDE string read-only example: shop
      Name of the filter in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the filter in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the filter in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the filter in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this filter.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the filter is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • bookingCategories array of ArticleCategoryRef
    Categories used for Online Booking of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • searchTags array of string
    Search tags make it easier for your customer to find your product in the online shop
  • shippingInfo object
    shipping information for an article.
    show fields
    • shippingAttributes array of string
      List of attributes used for shipping
    • weightUnit string
      Weight unit used for shipping of the article
      Allowed values: GRAM, KILOGRAM
    • dimensionUnit string
      Dimension unit used for shipping of the article
      Allowed values: CENTIMETER, METER
    • weight number pattern: ^\d{1,19}([.]\d{1,2})?$
      Weight of this article
    • width number pattern: ^\d{1,19}([.]\d{1,2})?$
      Width of this article
    • height number pattern: ^\d{1,19}([.]\d{1,2})?$
      Height of this article
    • depth number pattern: ^\d{1,19}([.]\d{1,2})?$
      Depth of this article
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
  • vats array of ArticleVat
    VAT information for the article
    show fields

    Array of ArticleVat.

    • vatType object example: NORMAL
      Article vat type of the article
    • vatCase string example: TAXABLE_SUPPLY
      VAT case of the article
    • vatCode string example: 1
      VAT code of the article VAT
    • sss1 boolean example: False
      Reporting net tax rate with SSS1 option
    • sss2 boolean example: False
      Reporting net tax rate with SSS2 option
    • reportingNetTaxRate boolean example: False
      Using VAT reporting net tax rate option
    • excludeVat boolean example: False
      Using exclude VAT option
  • numberType object
    Inventory Number Type
    Use either NO_NUMBER or SERIAL_NUMBER
400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/latest/articles/article-and-variantskey / tokenReturns list of articles and treat a variant combination same as an article
operationId

listArticlesWithVariants — the method name a generated client uses.

Required permission

ARTICLE_READ_ONLY
Available through: Administrator, External user, Mitarbeiter und Lohn, Kundenbeziehungen, Zeit- und Materialrapporte, Online Terminbuchung

Parameters 6
NameDescription
include-quantity
query boolean
flag to include quantity in the result.
limit
query integer (int32)
Define the limit of the article list that this API returns.
For example, if a company have 20 articles in total, and this limit parameter is 5, and the offset parameter is 0,
then this API will return article list containing the first 5 articles
If not set, then default value of 48 is used
format: int32 min: 1 max: 1000 default: 48
offset
query integer (int32)
Define which position to start getting article list.
For example, if a company have 20 articles in total, and this offset parameter is 5,
then this API will return article list from the 5th article.
If not set, then default value of 0 is used
format: int32 min: 0 default: 0
sell-in-booking
query boolean
flag to define sellable article for booking.
sell-in-online-shop
query boolean
flag to query articles that are sold in online shop.
use-pos
query boolean
flag to define article that are using in POS.
Responses 4
200 List of article and variant show body

application/json array of ArticleAndVariant

Array of ArticleAndVariant.

  • id string example: 1
    Id of the article
  • name string
    Name of the article
  • description string
    Description for the article
  • extendedDescription string
    This description will be used for example in your online shop
  • unit string
    Define how the article is count by
  • barcode string
    Barcode of the article
  • defaultQuantity number
    The default quantity of the article
  • accountingTags array of string
    Tags used for accounting. Articles with the same tag, same VAT case and same VAT rate are grouped together in the posting
  • articleNumber string example: ABC123
    Number of the article
  • productType object
    Type of product used for an article
  • priceCategories array of ArticlePriceCategory
    Price categories of the article
    show fields

    Array of ArticlePriceCategory.

    • name string
    • priceIncludeVat number
    • priceExcludeVat number
  • vatRate number
    Vat rate of the article
  • articleType object
    Article type
  • priceIncludeVat number
    price include vat
  • priceExcludeVat number
    price exclude vat
  • hasInventory boolean
    This article has inventory or not
  • quantityInStock number
    Quantity in stock
  • optionValues array of string
    Variant option of this article
  • ableToOrderOutOfStock boolean
    Flag define the article is allow to order out of stock
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/latest/articles/article-numberskey / tokenFind articles by article numbers
Batch-resolve a list of article numbers to their priced article rows of the caller's company. Returns each row enriched with the price valid on `price-date` and the appropriate VAT rate. Unknown article numbers are silently skipped (returned list contains only matching rows). Requires permission `ARTICLE_READ_ONLY`.
operationId

listArticlesByArticleNumbers — the method name a generated client uses.

Required permission

ARTICLE_READ_ONLY
Available through: Administrator, External user, Mitarbeiter und Lohn, Kundenbeziehungen, Zeit- und Materialrapporte, Online Terminbuchung

Parameters 4
NameDescription
article-numbers
query array of any
Article numbers to look up. Repeat the parameter for each value (e.g. `?article-numbers=ART-001&article-numbers=ART-002`). At most 100 entries; each entry up to 64 characters.
maxItems: 100 example: ART-001
export-vat
query boolean
If `true`, return ABROAD (export) VAT rate; otherwise NORMAL. Defaults to false.
default: false
price-date
query string (date)
Date on which prices are evaluated. Format: yyyy-MM-dd. Defaults to today when omitted.
format: date example: 2026-06-01
should-validate-vat
query boolean
If `true`, cross-validate each row's VAT code against the company's VAT setup on `price-date`. Defaults to false.
default: false
Responses 6
200 Matching articles show body

application/json array of ArticleAndVariant

Array of ArticleAndVariant.

  • id string example: 1
    Id of the article
  • name string
    Name of the article
  • description string
    Description for the article
  • extendedDescription string
    This description will be used for example in your online shop
  • unit string
    Define how the article is count by
  • barcode string
    Barcode of the article
  • defaultQuantity number
    The default quantity of the article
  • accountingTags array of string
    Tags used for accounting. Articles with the same tag, same VAT case and same VAT rate are grouped together in the posting
  • articleNumber string example: ABC123
    Number of the article
  • productType object
    Type of product used for an article
  • priceCategories array of ArticlePriceCategory
    Price categories of the article
    show fields

    Array of ArticlePriceCategory.

    • name string
    • priceIncludeVat number
    • priceExcludeVat number
  • vatRate number
    Vat rate of the article
  • articleType object
    Article type
  • priceIncludeVat number
    price include vat
  • priceExcludeVat number
    price exclude vat
  • hasInventory boolean
    This article has inventory or not
  • quantityInStock number
    Quantity in stock
  • optionValues array of string
    Variant option of this article
  • ableToOrderOutOfStock boolean
    Flag define the article is allow to order out of stock
400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
POST/core/latest/articles/bulkkey / tokenCreate articles
operationId

createArticlesBulk — the method name a generated client uses.

Required permission

ARTICLE
Available through: Administrator, External user, Kundenbeziehungen

Request body required
The list of articles

application/json array of Article

Array of Article.

  • id string read-only example: 1
    Id of the article. Does not need to be included when creating article
  • nameDE string required
    Name of the article in German
  • nameEN string
    Name of the article in English
  • nameFR string
    Name of the article in French
  • nameIT string
    Name of the article in Italian
  • descriptionDE string
    Description of the article in German
  • descriptionEN string
    Description of the article in English
  • descriptionFR string
    Description of the article in French
  • descriptionIT string
    Description of the article in Italian
  • extendedDescriptionDE string
    Extended description of the article in German
  • extendedDescriptionEN string
    Extended description of the article in English
  • extendedDescriptionFR string
    Extended description of the article in French
  • extendedDescriptionIT string
    Extended description of the article in Italian
  • unitDE string required
    Unit of the article in German
  • unitEN string
    Unit of the article in English
  • unitFR string
    Unit of the article in French
  • unitIT string
    Unit of the article in Italian
  • barcode string
    Barcode of the article
  • usePos boolean
    Decides if this article is used for POS or not
  • pricePeriods array of PricePeriod
    Price periods for the article.
    If article only has single price period, ignore and don't include validFrom and validTo in the PricePeriod.
    If article have different prices valid for different periods, set value for validFrom for each price period or that price period is ignored.
    show fields

    Array of PricePeriod.

    • validFrom string (date) format: date
      The price period is valid from this time
    • validTo string (date) format: date read-only
      The price period is invalid after this time
    • price number pattern: ^\d{1,19}([.]\d{1,2})?$
      The price used for an article within this price period
    • priceCategories array of PriceCategory
      List of price categories effective for this price period
      show fields

      Array of PriceCategory.

      • name string
        Name of the price category
      • price number pattern: ^\d{1,19}([.]\d{1,2})?$
        Effective price of this price category
  • options array of ArticleOption
    Options for the article. If specify, variants for this article will be generated.
    show fields

    Array of ArticleOption.

    • name string example: color
      Name of the article option
    • values array of string
      Available choices for the article option
  • imageHrefs array of string read-only
    Reference uris for the images of this article if present.
  • isArticleSet boolean
    Decides if this article is an article set
  • articleSetName string
    Name of the article set. Does not need to be included if article is not an article set.
  • defaultQuantity number pattern: ^\d{1,19}([.]\d{1,2})?$
    The default quantity of the article
  • accountingTags array of string required
    Tags used for accounting. Articles with the same tag, same VAT case and same VAT rate are grouped together in the posting
  • articleNumber string required example: ABC123
    Article number
  • hasVariant boolean
    Specify if the article has variants or not
  • includedInArticleSets array of string
    Names of the article sets that the article is included in.
    If the article have some variants, then only the variants will show the article set name they belong to, not the parent article (null value is shown).
  • sellInOnlineShop boolean
    Specify if the article is able to be sold on the Online shop or not
  • isAdultArticle boolean
    Specify if the article is only used for adult or not
  • productType object required
    Type of product used for an article
  • posCategories array of ArticleCategoryRef
    Categories used for Point of Sale of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • posFilters array of ArticleFilterRef
    Filters used for Point of Sale of the article
    Provide only either id or href of each filter when creating Article
    show fields

    Array of ArticleFilterRef.

    • id string read-only example: 1
      Id of the filter. Does not need to be included when creating article.
    • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
      Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
    • nameDE string read-only example: shop
      Name of the filter in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the filter in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the filter in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the filter in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this filter.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the filter is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • onlineShopCategories array of ArticleCategoryRef
    Categories used for Online shop of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • onlineShopFilters array of ArticleFilterRef
    Filters used for Online shop of the article
    Provide only either id or href of each filter when creating Article
    show fields

    Array of ArticleFilterRef.

    • id string read-only example: 1
      Id of the filter. Does not need to be included when creating article.
    • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
      Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
    • nameDE string read-only example: shop
      Name of the filter in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the filter in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the filter in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the filter in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this filter.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the filter is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • bookingCategories array of ArticleCategoryRef
    Categories used for Online Booking of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • searchTags array of string
    Search tags make it easier for your customer to find your product in the online shop
  • shippingInfo object
    shipping information for an article.
    show fields
    • shippingAttributes array of string
      List of attributes used for shipping
    • weightUnit string
      Weight unit used for shipping of the article
      Allowed values: GRAM, KILOGRAM
    • dimensionUnit string
      Dimension unit used for shipping of the article
      Allowed values: CENTIMETER, METER
    • weight number pattern: ^\d{1,19}([.]\d{1,2})?$
      Weight of this article
    • width number pattern: ^\d{1,19}([.]\d{1,2})?$
      Width of this article
    • height number pattern: ^\d{1,19}([.]\d{1,2})?$
      Height of this article
    • depth number pattern: ^\d{1,19}([.]\d{1,2})?$
      Depth of this article
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
  • vats array of ArticleVat
    VAT information for the article
    show fields

    Array of ArticleVat.

    • vatType object example: NORMAL
      Article vat type of the article
    • vatCase string example: TAXABLE_SUPPLY
      VAT case of the article
    • vatCode string example: 1
      VAT code of the article VAT
    • sss1 boolean example: False
      Reporting net tax rate with SSS1 option
    • sss2 boolean example: False
      Reporting net tax rate with SSS2 option
    • reportingNetTaxRate boolean example: False
      Using VAT reporting net tax rate option
    • excludeVat boolean example: False
      Using exclude VAT option
  • numberType object
    Inventory Number Type
    Use either NO_NUMBER or SERIAL_NUMBER
Responses 4
200 Article created show body

application/json BulkArticleCreatingResponse

  • numberOfSuccess integer (int32) format: int32 example: 2
    Number of articles saved successfully
  • numberOfFail integer (int32) format: int32 example: 2
    Number of articles saved unsuccessfully
  • success array of Article
    A list of saved articles
    show fields

    Array of Article.

    • id string read-only example: 1
      Id of the article. Does not need to be included when creating article
    • nameDE string required
      Name of the article in German
    • nameEN string
      Name of the article in English
    • nameFR string
      Name of the article in French
    • nameIT string
      Name of the article in Italian
    • descriptionDE string
      Description of the article in German
    • descriptionEN string
      Description of the article in English
    • descriptionFR string
      Description of the article in French
    • descriptionIT string
      Description of the article in Italian
    • extendedDescriptionDE string
      Extended description of the article in German
    • extendedDescriptionEN string
      Extended description of the article in English
    • extendedDescriptionFR string
      Extended description of the article in French
    • extendedDescriptionIT string
      Extended description of the article in Italian
    • unitDE string required
      Unit of the article in German
    • unitEN string
      Unit of the article in English
    • unitFR string
      Unit of the article in French
    • unitIT string
      Unit of the article in Italian
    • barcode string
      Barcode of the article
    • usePos boolean
      Decides if this article is used for POS or not
    • pricePeriods array of PricePeriod
      Price periods for the article.
      If article only has single price period, ignore and don't include validFrom and validTo in the PricePeriod.
      If article have different prices valid for different periods, set value for validFrom for each price period or that price period is ignored.
      show fields

      Array of PricePeriod.

      • validFrom string (date) format: date
        The price period is valid from this time
      • validTo string (date) format: date read-only
        The price period is invalid after this time
      • price number pattern: ^\d{1,19}([.]\d{1,2})?$
        The price used for an article within this price period
      • priceCategories array of PriceCategory
        List of price categories effective for this price period
        show fields

        Array of PriceCategory.

        • name string
          Name of the price category
        • price number pattern: ^\d{1,19}([.]\d{1,2})?$
          Effective price of this price category
    • options array of ArticleOption
      Options for the article. If specify, variants for this article will be generated.
      show fields

      Array of ArticleOption.

      • name string example: color
        Name of the article option
      • values array of string
        Available choices for the article option
    • imageHrefs array of string read-only
      Reference uris for the images of this article if present.
    • isArticleSet boolean
      Decides if this article is an article set
    • articleSetName string
      Name of the article set. Does not need to be included if article is not an article set.
    • defaultQuantity number pattern: ^\d{1,19}([.]\d{1,2})?$
      The default quantity of the article
    • accountingTags array of string required
      Tags used for accounting. Articles with the same tag, same VAT case and same VAT rate are grouped together in the posting
    • articleNumber string required example: ABC123
      Article number
    • hasVariant boolean
      Specify if the article has variants or not
    • includedInArticleSets array of string
      Names of the article sets that the article is included in.
      If the article have some variants, then only the variants will show the article set name they belong to, not the parent article (null value is shown).
    • sellInOnlineShop boolean
      Specify if the article is able to be sold on the Online shop or not
    • isAdultArticle boolean
      Specify if the article is only used for adult or not
    • productType object required
      Type of product used for an article
    • posCategories array of ArticleCategoryRef
      Categories used for Point of Sale of the article
      Provide only either id or href of each category when creating Article
      show fields

      Array of ArticleCategoryRef.

      • id string read-only example: 1
        Id of the category. Does not need to be included when creating article
      • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
        Reference uri for an article category. If specified, this article will be assigned to the entered article category.
      • nameDE string read-only example: shop
        Name of the category in german.
        Does not need to be included when creating article.
      • nameEN string read-only example: shop
        Name of the category in english.
        Does not need to be included when creating article.
      • nameFR string read-only example: shop
        Name of the category in french.
        Does not need to be included when creating article.
      • nameIT string read-only example: shop
        Name of the category in italy.
        Does not need to be included when creating article.
      • order integer (int32) format: int32 read-only
        Order of this category.
        Does not need to be included when creating article.
      • active boolean read-only
        Indicates if the category is active or not
      • _links object
        links metadata
        show fields
        • self Link
          Link metadata
          show fields
          • href string
    • posFilters array of ArticleFilterRef
      Filters used for Point of Sale of the article
      Provide only either id or href of each filter when creating Article
      show fields

      Array of ArticleFilterRef.

      • id string read-only example: 1
        Id of the filter. Does not need to be included when creating article.
      • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
        Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
      • nameDE string read-only example: shop
        Name of the filter in german.
        Does not need to be included when creating article.
      • nameEN string read-only example: shop
        Name of the filter in english.
        Does not need to be included when creating article.
      • nameFR string read-only example: shop
        Name of the filter in french.
        Does not need to be included when creating article.
      • nameIT string read-only example: shop
        Name of the filter in italy.
        Does not need to be included when creating article.
      • order integer (int32) format: int32 read-only
        Order of this filter.
        Does not need to be included when creating article.
      • active boolean read-only
        Indicates if the filter is active or not
      • _links object
        links metadata
        show fields
        • self Link
          Link metadata
          show fields
          • href string
    • onlineShopCategories array of ArticleCategoryRef
      Categories used for Online shop of the article
      Provide only either id or href of each category when creating Article
      show fields

      Array of ArticleCategoryRef.

      • id string read-only example: 1
        Id of the category. Does not need to be included when creating article
      • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
        Reference uri for an article category. If specified, this article will be assigned to the entered article category.
      • nameDE string read-only example: shop
        Name of the category in german.
        Does not need to be included when creating article.
      • nameEN string read-only example: shop
        Name of the category in english.
        Does not need to be included when creating article.
      • nameFR string read-only example: shop
        Name of the category in french.
        Does not need to be included when creating article.
      • nameIT string read-only example: shop
        Name of the category in italy.
        Does not need to be included when creating article.
      • order integer (int32) format: int32 read-only
        Order of this category.
        Does not need to be included when creating article.
      • active boolean read-only
        Indicates if the category is active or not
      • _links object
        links metadata
        show fields
        • self Link
          Link metadata
          show fields
          • href string
    • onlineShopFilters array of ArticleFilterRef
      Filters used for Online shop of the article
      Provide only either id or href of each filter when creating Article
      show fields

      Array of ArticleFilterRef.

      • id string read-only example: 1
        Id of the filter. Does not need to be included when creating article.
      • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
        Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
      • nameDE string read-only example: shop
        Name of the filter in german.
        Does not need to be included when creating article.
      • nameEN string read-only example: shop
        Name of the filter in english.
        Does not need to be included when creating article.
      • nameFR string read-only example: shop
        Name of the filter in french.
        Does not need to be included when creating article.
      • nameIT string read-only example: shop
        Name of the filter in italy.
        Does not need to be included when creating article.
      • order integer (int32) format: int32 read-only
        Order of this filter.
        Does not need to be included when creating article.
      • active boolean read-only
        Indicates if the filter is active or not
      • _links object
        links metadata
        show fields
        • self Link
          Link metadata
          show fields
          • href string
    • bookingCategories array of ArticleCategoryRef
      Categories used for Online Booking of the article
      Provide only either id or href of each category when creating Article
      show fields

      Array of ArticleCategoryRef.

      • id string read-only example: 1
        Id of the category. Does not need to be included when creating article
      • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
        Reference uri for an article category. If specified, this article will be assigned to the entered article category.
      • nameDE string read-only example: shop
        Name of the category in german.
        Does not need to be included when creating article.
      • nameEN string read-only example: shop
        Name of the category in english.
        Does not need to be included when creating article.
      • nameFR string read-only example: shop
        Name of the category in french.
        Does not need to be included when creating article.
      • nameIT string read-only example: shop
        Name of the category in italy.
        Does not need to be included when creating article.
      • order integer (int32) format: int32 read-only
        Order of this category.
        Does not need to be included when creating article.
      • active boolean read-only
        Indicates if the category is active or not
      • _links object
        links metadata
        show fields
        • self Link
          Link metadata
          show fields
          • href string
    • searchTags array of string
      Search tags make it easier for your customer to find your product in the online shop
    • shippingInfo object
      shipping information for an article.
      show fields
      • shippingAttributes array of string
        List of attributes used for shipping
      • weightUnit string
        Weight unit used for shipping of the article
        Allowed values: GRAM, KILOGRAM
      • dimensionUnit string
        Dimension unit used for shipping of the article
        Allowed values: CENTIMETER, METER
      • weight number pattern: ^\d{1,19}([.]\d{1,2})?$
        Weight of this article
      • width number pattern: ^\d{1,19}([.]\d{1,2})?$
        Width of this article
      • height number pattern: ^\d{1,19}([.]\d{1,2})?$
        Height of this article
      • depth number pattern: ^\d{1,19}([.]\d{1,2})?$
        Depth of this article
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
    • vats array of ArticleVat
      VAT information for the article
      show fields

      Array of ArticleVat.

      • vatType object example: NORMAL
        Article vat type of the article
      • vatCase string example: TAXABLE_SUPPLY
        VAT case of the article
      • vatCode string example: 1
        VAT code of the article VAT
      • sss1 boolean example: False
        Reporting net tax rate with SSS1 option
      • sss2 boolean example: False
        Reporting net tax rate with SSS2 option
      • reportingNetTaxRate boolean example: False
        Using VAT reporting net tax rate option
      • excludeVat boolean example: False
        Using exclude VAT option
    • numberType object
      Inventory Number Type
      Use either NO_NUMBER or SERIAL_NUMBER
  • fail array of PublicApiFailArticle
    A list of unsaved articles with error message
    show fields

    Array of PublicApiFailArticle.

    • errorCode string example: article.number.could.not.be.duplicated
      Error code
    • errorMessage string example: Article number could not be duplicated
      Error message
    • unsavedArticle object
      An article.
      show fields
      • id string read-only example: 1
        Id of the article. Does not need to be included when creating article
      • nameDE string required
        Name of the article in German
      • nameEN string
        Name of the article in English
      • nameFR string
        Name of the article in French
      • nameIT string
        Name of the article in Italian
      • descriptionDE string
        Description of the article in German
      • descriptionEN string
        Description of the article in English
      • descriptionFR string
        Description of the article in French
      • descriptionIT string
        Description of the article in Italian
      • extendedDescriptionDE string
        Extended description of the article in German
      • extendedDescriptionEN string
        Extended description of the article in English
      • extendedDescriptionFR string
        Extended description of the article in French
      • extendedDescriptionIT string
        Extended description of the article in Italian
      • unitDE string required
        Unit of the article in German
      • unitEN string
        Unit of the article in English
      • unitFR string
        Unit of the article in French
      • unitIT string
        Unit of the article in Italian
      • barcode string
        Barcode of the article
      • usePos boolean
        Decides if this article is used for POS or not
      • pricePeriods array of PricePeriod
        Price periods for the article.
        If article only has single price period, ignore and don't include validFrom and validTo in the PricePeriod.
        If article have different prices valid for different periods, set value for validFrom for each price period or that price period is ignored.
        show fields

        Array of PricePeriod.

        • validFrom string (date) format: date
          The price period is valid from this time
        • validTo string (date) format: date read-only
          The price period is invalid after this time
        • price number pattern: ^\d{1,19}([.]\d{1,2})?$
          The price used for an article within this price period
        • priceCategories array of PriceCategory
          List of price categories effective for this price period
          show fields

          Array of PriceCategory.

          • name string
            Name of the price category
          • price number pattern: ^\d{1,19}([.]\d{1,2})?$
            Effective price of this price category
      • options array of ArticleOption
        Options for the article. If specify, variants for this article will be generated.
        show fields

        Array of ArticleOption.

        • name string example: color
          Name of the article option
        • values array of string
          Available choices for the article option
      • imageHrefs array of string read-only
        Reference uris for the images of this article if present.
      • isArticleSet boolean
        Decides if this article is an article set
      • articleSetName string
        Name of the article set. Does not need to be included if article is not an article set.
      • defaultQuantity number pattern: ^\d{1,19}([.]\d{1,2})?$
        The default quantity of the article
      • accountingTags array of string required
        Tags used for accounting. Articles with the same tag, same VAT case and same VAT rate are grouped together in the posting
      • articleNumber string required example: ABC123
        Article number
      • hasVariant boolean
        Specify if the article has variants or not
      • includedInArticleSets array of string
        Names of the article sets that the article is included in.
        If the article have some variants, then only the variants will show the article set name they belong to, not the parent article (null value is shown).
      • sellInOnlineShop boolean
        Specify if the article is able to be sold on the Online shop or not
      • isAdultArticle boolean
        Specify if the article is only used for adult or not
      • productType object required
        Type of product used for an article
      • posCategories array of ArticleCategoryRef
        Categories used for Point of Sale of the article
        Provide only either id or href of each category when creating Article
        show fields

        Array of ArticleCategoryRef.

        • id string read-only example: 1
          Id of the category. Does not need to be included when creating article
        • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
          Reference uri for an article category. If specified, this article will be assigned to the entered article category.
        • nameDE string read-only example: shop
          Name of the category in german.
          Does not need to be included when creating article.
        • nameEN string read-only example: shop
          Name of the category in english.
          Does not need to be included when creating article.
        • nameFR string read-only example: shop
          Name of the category in french.
          Does not need to be included when creating article.
        • nameIT string read-only example: shop
          Name of the category in italy.
          Does not need to be included when creating article.
        • order integer (int32) format: int32 read-only
          Order of this category.
          Does not need to be included when creating article.
        • active boolean read-only
          Indicates if the category is active or not
        • _links object
          links metadata
          show fields
          • self Link
            Link metadata
            show fields
            • href string
      • posFilters array of ArticleFilterRef
        Filters used for Point of Sale of the article
        Provide only either id or href of each filter when creating Article
        show fields

        Array of ArticleFilterRef.

        • id string read-only example: 1
          Id of the filter. Does not need to be included when creating article.
        • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
          Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
        • nameDE string read-only example: shop
          Name of the filter in german.
          Does not need to be included when creating article.
        • nameEN string read-only example: shop
          Name of the filter in english.
          Does not need to be included when creating article.
        • nameFR string read-only example: shop
          Name of the filter in french.
          Does not need to be included when creating article.
        • nameIT string read-only example: shop
          Name of the filter in italy.
          Does not need to be included when creating article.
        • order integer (int32) format: int32 read-only
          Order of this filter.
          Does not need to be included when creating article.
        • active boolean read-only
          Indicates if the filter is active or not
        • _links object
          links metadata
          show fields
          • self Link
            Link metadata
            show fields
            • href string
      • onlineShopCategories array of ArticleCategoryRef
        Categories used for Online shop of the article
        Provide only either id or href of each category when creating Article
        show fields

        Array of ArticleCategoryRef.

        • id string read-only example: 1
          Id of the category. Does not need to be included when creating article
        • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
          Reference uri for an article category. If specified, this article will be assigned to the entered article category.
        • nameDE string read-only example: shop
          Name of the category in german.
          Does not need to be included when creating article.
        • nameEN string read-only example: shop
          Name of the category in english.
          Does not need to be included when creating article.
        • nameFR string read-only example: shop
          Name of the category in french.
          Does not need to be included when creating article.
        • nameIT string read-only example: shop
          Name of the category in italy.
          Does not need to be included when creating article.
        • order integer (int32) format: int32 read-only
          Order of this category.
          Does not need to be included when creating article.
        • active boolean read-only
          Indicates if the category is active or not
        • _links object
          links metadata
          show fields
          • self Link
            Link metadata
            show fields
            • href string
      • onlineShopFilters array of ArticleFilterRef
        Filters used for Online shop of the article
        Provide only either id or href of each filter when creating Article
        show fields

        Array of ArticleFilterRef.

        • id string read-only example: 1
          Id of the filter. Does not need to be included when creating article.
        • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
          Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
        • nameDE string read-only example: shop
          Name of the filter in german.
          Does not need to be included when creating article.
        • nameEN string read-only example: shop
          Name of the filter in english.
          Does not need to be included when creating article.
        • nameFR string read-only example: shop
          Name of the filter in french.
          Does not need to be included when creating article.
        • nameIT string read-only example: shop
          Name of the filter in italy.
          Does not need to be included when creating article.
        • order integer (int32) format: int32 read-only
          Order of this filter.
          Does not need to be included when creating article.
        • active boolean read-only
          Indicates if the filter is active or not
        • _links object
          links metadata
          show fields
          • self Link
            Link metadata
            show fields
            • href string
      • bookingCategories array of ArticleCategoryRef
        Categories used for Online Booking of the article
        Provide only either id or href of each category when creating Article
        show fields

        Array of ArticleCategoryRef.

        • id string read-only example: 1
          Id of the category. Does not need to be included when creating article
        • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
          Reference uri for an article category. If specified, this article will be assigned to the entered article category.
        • nameDE string read-only example: shop
          Name of the category in german.
          Does not need to be included when creating article.
        • nameEN string read-only example: shop
          Name of the category in english.
          Does not need to be included when creating article.
        • nameFR string read-only example: shop
          Name of the category in french.
          Does not need to be included when creating article.
        • nameIT string read-only example: shop
          Name of the category in italy.
          Does not need to be included when creating article.
        • order integer (int32) format: int32 read-only
          Order of this category.
          Does not need to be included when creating article.
        • active boolean read-only
          Indicates if the category is active or not
        • _links object
          links metadata
          show fields
          • self Link
            Link metadata
            show fields
            • href string
      • searchTags array of string
        Search tags make it easier for your customer to find your product in the online shop
      • shippingInfo object
        shipping information for an article.
        show fields
        • shippingAttributes array of string
          List of attributes used for shipping
        • weightUnit string
          Weight unit used for shipping of the article
          Allowed values: GRAM, KILOGRAM
        • dimensionUnit string
          Dimension unit used for shipping of the article
          Allowed values: CENTIMETER, METER
        • weight number pattern: ^\d{1,19}([.]\d{1,2})?$
          Weight of this article
        • width number pattern: ^\d{1,19}([.]\d{1,2})?$
          Width of this article
        • height number pattern: ^\d{1,19}([.]\d{1,2})?$
          Height of this article
        • depth number pattern: ^\d{1,19}([.]\d{1,2})?$
          Depth of this article
      • _links object
        links metadata
        show fields
        • self Link
          Link metadata
          show fields
          • href string
      • vats array of ArticleVat
        VAT information for the article
        show fields

        Array of ArticleVat.

        • vatType object example: NORMAL
          Article vat type of the article
        • vatCase string example: TAXABLE_SUPPLY
          VAT case of the article
        • vatCode string example: 1
          VAT code of the article VAT
        • sss1 boolean example: False
          Reporting net tax rate with SSS1 option
        • sss2 boolean example: False
          Reporting net tax rate with SSS2 option
        • reportingNetTaxRate boolean example: False
          Using VAT reporting net tax rate option
        • excludeVat boolean example: False
          Using exclude VAT option
      • numberType object
        Inventory Number Type
        Use either NO_NUMBER or SERIAL_NUMBER
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
DELETE/core/latest/articles/{article-id}key / tokenDelete an article
operationId

deleteArticle — the method name a generated client uses.

Required permission

ARTICLE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 1
NameDescription
article-id required
path string
Id of the article to be deleted
example: 1
Responses 7
204 Article deleted by given article id no response body
400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/latest/articles/{article-id}key / tokenGet article by article id
operationId

getArticleById — the method name a generated client uses.

Required permission

ARTICLE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 1
NameDescription
article-id required
path string
Responses 5
200 Found article show body

application/json Article

  • id string read-only example: 1
    Id of the article. Does not need to be included when creating article
  • nameDE string required
    Name of the article in German
  • nameEN string
    Name of the article in English
  • nameFR string
    Name of the article in French
  • nameIT string
    Name of the article in Italian
  • descriptionDE string
    Description of the article in German
  • descriptionEN string
    Description of the article in English
  • descriptionFR string
    Description of the article in French
  • descriptionIT string
    Description of the article in Italian
  • extendedDescriptionDE string
    Extended description of the article in German
  • extendedDescriptionEN string
    Extended description of the article in English
  • extendedDescriptionFR string
    Extended description of the article in French
  • extendedDescriptionIT string
    Extended description of the article in Italian
  • unitDE string required
    Unit of the article in German
  • unitEN string
    Unit of the article in English
  • unitFR string
    Unit of the article in French
  • unitIT string
    Unit of the article in Italian
  • barcode string
    Barcode of the article
  • usePos boolean
    Decides if this article is used for POS or not
  • pricePeriods array of PricePeriod
    Price periods for the article.
    If article only has single price period, ignore and don't include validFrom and validTo in the PricePeriod.
    If article have different prices valid for different periods, set value for validFrom for each price period or that price period is ignored.
    show fields

    Array of PricePeriod.

    • validFrom string (date) format: date
      The price period is valid from this time
    • validTo string (date) format: date read-only
      The price period is invalid after this time
    • price number pattern: ^\d{1,19}([.]\d{1,2})?$
      The price used for an article within this price period
    • priceCategories array of PriceCategory
      List of price categories effective for this price period
      show fields

      Array of PriceCategory.

      • name string
        Name of the price category
      • price number pattern: ^\d{1,19}([.]\d{1,2})?$
        Effective price of this price category
  • options array of ArticleOption
    Options for the article. If specify, variants for this article will be generated.
    show fields

    Array of ArticleOption.

    • name string example: color
      Name of the article option
    • values array of string
      Available choices for the article option
  • imageHrefs array of string read-only
    Reference uris for the images of this article if present.
  • isArticleSet boolean
    Decides if this article is an article set
  • articleSetName string
    Name of the article set. Does not need to be included if article is not an article set.
  • defaultQuantity number pattern: ^\d{1,19}([.]\d{1,2})?$
    The default quantity of the article
  • accountingTags array of string required
    Tags used for accounting. Articles with the same tag, same VAT case and same VAT rate are grouped together in the posting
  • articleNumber string required example: ABC123
    Article number
  • hasVariant boolean
    Specify if the article has variants or not
  • includedInArticleSets array of string
    Names of the article sets that the article is included in.
    If the article have some variants, then only the variants will show the article set name they belong to, not the parent article (null value is shown).
  • sellInOnlineShop boolean
    Specify if the article is able to be sold on the Online shop or not
  • isAdultArticle boolean
    Specify if the article is only used for adult or not
  • productType object required
    Type of product used for an article
  • posCategories array of ArticleCategoryRef
    Categories used for Point of Sale of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • posFilters array of ArticleFilterRef
    Filters used for Point of Sale of the article
    Provide only either id or href of each filter when creating Article
    show fields

    Array of ArticleFilterRef.

    • id string read-only example: 1
      Id of the filter. Does not need to be included when creating article.
    • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
      Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
    • nameDE string read-only example: shop
      Name of the filter in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the filter in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the filter in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the filter in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this filter.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the filter is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • onlineShopCategories array of ArticleCategoryRef
    Categories used for Online shop of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • onlineShopFilters array of ArticleFilterRef
    Filters used for Online shop of the article
    Provide only either id or href of each filter when creating Article
    show fields

    Array of ArticleFilterRef.

    • id string read-only example: 1
      Id of the filter. Does not need to be included when creating article.
    • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
      Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
    • nameDE string read-only example: shop
      Name of the filter in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the filter in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the filter in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the filter in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this filter.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the filter is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • bookingCategories array of ArticleCategoryRef
    Categories used for Online Booking of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • searchTags array of string
    Search tags make it easier for your customer to find your product in the online shop
  • shippingInfo object
    shipping information for an article.
    show fields
    • shippingAttributes array of string
      List of attributes used for shipping
    • weightUnit string
      Weight unit used for shipping of the article
      Allowed values: GRAM, KILOGRAM
    • dimensionUnit string
      Dimension unit used for shipping of the article
      Allowed values: CENTIMETER, METER
    • weight number pattern: ^\d{1,19}([.]\d{1,2})?$
      Weight of this article
    • width number pattern: ^\d{1,19}([.]\d{1,2})?$
      Width of this article
    • height number pattern: ^\d{1,19}([.]\d{1,2})?$
      Height of this article
    • depth number pattern: ^\d{1,19}([.]\d{1,2})?$
      Depth of this article
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
  • vats array of ArticleVat
    VAT information for the article
    show fields

    Array of ArticleVat.

    • vatType object example: NORMAL
      Article vat type of the article
    • vatCase string example: TAXABLE_SUPPLY
      VAT case of the article
    • vatCode string example: 1
      VAT code of the article VAT
    • sss1 boolean example: False
      Reporting net tax rate with SSS1 option
    • sss2 boolean example: False
      Reporting net tax rate with SSS2 option
    • reportingNetTaxRate boolean example: False
      Using VAT reporting net tax rate option
    • excludeVat boolean example: False
      Using exclude VAT option
  • numberType object
    Inventory Number Type
    Use either NO_NUMBER or SERIAL_NUMBER
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
PUT/core/latest/articles/{article-id}key / tokenUpdate an existing article
operationId

updateArticle — the method name a generated client uses.

Required permission

ARTICLE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 1
NameDescription
article-id required
path string
Request body required
The article object with the information that needs to be updated

application/json Article

  • id string read-only example: 1
    Id of the article. Does not need to be included when creating article
  • nameDE string required
    Name of the article in German
  • nameEN string
    Name of the article in English
  • nameFR string
    Name of the article in French
  • nameIT string
    Name of the article in Italian
  • descriptionDE string
    Description of the article in German
  • descriptionEN string
    Description of the article in English
  • descriptionFR string
    Description of the article in French
  • descriptionIT string
    Description of the article in Italian
  • extendedDescriptionDE string
    Extended description of the article in German
  • extendedDescriptionEN string
    Extended description of the article in English
  • extendedDescriptionFR string
    Extended description of the article in French
  • extendedDescriptionIT string
    Extended description of the article in Italian
  • unitDE string required
    Unit of the article in German
  • unitEN string
    Unit of the article in English
  • unitFR string
    Unit of the article in French
  • unitIT string
    Unit of the article in Italian
  • barcode string
    Barcode of the article
  • usePos boolean
    Decides if this article is used for POS or not
  • pricePeriods array of PricePeriod
    Price periods for the article.
    If article only has single price period, ignore and don't include validFrom and validTo in the PricePeriod.
    If article have different prices valid for different periods, set value for validFrom for each price period or that price period is ignored.
    show fields

    Array of PricePeriod.

    • validFrom string (date) format: date
      The price period is valid from this time
    • validTo string (date) format: date read-only
      The price period is invalid after this time
    • price number pattern: ^\d{1,19}([.]\d{1,2})?$
      The price used for an article within this price period
    • priceCategories array of PriceCategory
      List of price categories effective for this price period
      show fields

      Array of PriceCategory.

      • name string
        Name of the price category
      • price number pattern: ^\d{1,19}([.]\d{1,2})?$
        Effective price of this price category
  • options array of ArticleOption
    Options for the article. If specify, variants for this article will be generated.
    show fields

    Array of ArticleOption.

    • name string example: color
      Name of the article option
    • values array of string
      Available choices for the article option
  • imageHrefs array of string read-only
    Reference uris for the images of this article if present.
  • isArticleSet boolean
    Decides if this article is an article set
  • articleSetName string
    Name of the article set. Does not need to be included if article is not an article set.
  • defaultQuantity number pattern: ^\d{1,19}([.]\d{1,2})?$
    The default quantity of the article
  • accountingTags array of string required
    Tags used for accounting. Articles with the same tag, same VAT case and same VAT rate are grouped together in the posting
  • articleNumber string required example: ABC123
    Article number
  • hasVariant boolean
    Specify if the article has variants or not
  • includedInArticleSets array of string
    Names of the article sets that the article is included in.
    If the article have some variants, then only the variants will show the article set name they belong to, not the parent article (null value is shown).
  • sellInOnlineShop boolean
    Specify if the article is able to be sold on the Online shop or not
  • isAdultArticle boolean
    Specify if the article is only used for adult or not
  • productType object required
    Type of product used for an article
  • posCategories array of ArticleCategoryRef
    Categories used for Point of Sale of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • posFilters array of ArticleFilterRef
    Filters used for Point of Sale of the article
    Provide only either id or href of each filter when creating Article
    show fields

    Array of ArticleFilterRef.

    • id string read-only example: 1
      Id of the filter. Does not need to be included when creating article.
    • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
      Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
    • nameDE string read-only example: shop
      Name of the filter in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the filter in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the filter in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the filter in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this filter.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the filter is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • onlineShopCategories array of ArticleCategoryRef
    Categories used for Online shop of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • onlineShopFilters array of ArticleFilterRef
    Filters used for Online shop of the article
    Provide only either id or href of each filter when creating Article
    show fields

    Array of ArticleFilterRef.

    • id string read-only example: 1
      Id of the filter. Does not need to be included when creating article.
    • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
      Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
    • nameDE string read-only example: shop
      Name of the filter in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the filter in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the filter in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the filter in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this filter.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the filter is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • bookingCategories array of ArticleCategoryRef
    Categories used for Online Booking of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • searchTags array of string
    Search tags make it easier for your customer to find your product in the online shop
  • shippingInfo object
    shipping information for an article.
    show fields
    • shippingAttributes array of string
      List of attributes used for shipping
    • weightUnit string
      Weight unit used for shipping of the article
      Allowed values: GRAM, KILOGRAM
    • dimensionUnit string
      Dimension unit used for shipping of the article
      Allowed values: CENTIMETER, METER
    • weight number pattern: ^\d{1,19}([.]\d{1,2})?$
      Weight of this article
    • width number pattern: ^\d{1,19}([.]\d{1,2})?$
      Width of this article
    • height number pattern: ^\d{1,19}([.]\d{1,2})?$
      Height of this article
    • depth number pattern: ^\d{1,19}([.]\d{1,2})?$
      Depth of this article
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
  • vats array of ArticleVat
    VAT information for the article
    show fields

    Array of ArticleVat.

    • vatType object example: NORMAL
      Article vat type of the article
    • vatCase string example: TAXABLE_SUPPLY
      VAT case of the article
    • vatCode string example: 1
      VAT code of the article VAT
    • sss1 boolean example: False
      Reporting net tax rate with SSS1 option
    • sss2 boolean example: False
      Reporting net tax rate with SSS2 option
    • reportingNetTaxRate boolean example: False
      Using VAT reporting net tax rate option
    • excludeVat boolean example: False
      Using exclude VAT option
  • numberType object
    Inventory Number Type
    Use either NO_NUMBER or SERIAL_NUMBER
Responses 5
200 Article updated show body

application/json Article

  • id string read-only example: 1
    Id of the article. Does not need to be included when creating article
  • nameDE string required
    Name of the article in German
  • nameEN string
    Name of the article in English
  • nameFR string
    Name of the article in French
  • nameIT string
    Name of the article in Italian
  • descriptionDE string
    Description of the article in German
  • descriptionEN string
    Description of the article in English
  • descriptionFR string
    Description of the article in French
  • descriptionIT string
    Description of the article in Italian
  • extendedDescriptionDE string
    Extended description of the article in German
  • extendedDescriptionEN string
    Extended description of the article in English
  • extendedDescriptionFR string
    Extended description of the article in French
  • extendedDescriptionIT string
    Extended description of the article in Italian
  • unitDE string required
    Unit of the article in German
  • unitEN string
    Unit of the article in English
  • unitFR string
    Unit of the article in French
  • unitIT string
    Unit of the article in Italian
  • barcode string
    Barcode of the article
  • usePos boolean
    Decides if this article is used for POS or not
  • pricePeriods array of PricePeriod
    Price periods for the article.
    If article only has single price period, ignore and don't include validFrom and validTo in the PricePeriod.
    If article have different prices valid for different periods, set value for validFrom for each price period or that price period is ignored.
    show fields

    Array of PricePeriod.

    • validFrom string (date) format: date
      The price period is valid from this time
    • validTo string (date) format: date read-only
      The price period is invalid after this time
    • price number pattern: ^\d{1,19}([.]\d{1,2})?$
      The price used for an article within this price period
    • priceCategories array of PriceCategory
      List of price categories effective for this price period
      show fields

      Array of PriceCategory.

      • name string
        Name of the price category
      • price number pattern: ^\d{1,19}([.]\d{1,2})?$
        Effective price of this price category
  • options array of ArticleOption
    Options for the article. If specify, variants for this article will be generated.
    show fields

    Array of ArticleOption.

    • name string example: color
      Name of the article option
    • values array of string
      Available choices for the article option
  • imageHrefs array of string read-only
    Reference uris for the images of this article if present.
  • isArticleSet boolean
    Decides if this article is an article set
  • articleSetName string
    Name of the article set. Does not need to be included if article is not an article set.
  • defaultQuantity number pattern: ^\d{1,19}([.]\d{1,2})?$
    The default quantity of the article
  • accountingTags array of string required
    Tags used for accounting. Articles with the same tag, same VAT case and same VAT rate are grouped together in the posting
  • articleNumber string required example: ABC123
    Article number
  • hasVariant boolean
    Specify if the article has variants or not
  • includedInArticleSets array of string
    Names of the article sets that the article is included in.
    If the article have some variants, then only the variants will show the article set name they belong to, not the parent article (null value is shown).
  • sellInOnlineShop boolean
    Specify if the article is able to be sold on the Online shop or not
  • isAdultArticle boolean
    Specify if the article is only used for adult or not
  • productType object required
    Type of product used for an article
  • posCategories array of ArticleCategoryRef
    Categories used for Point of Sale of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • posFilters array of ArticleFilterRef
    Filters used for Point of Sale of the article
    Provide only either id or href of each filter when creating Article
    show fields

    Array of ArticleFilterRef.

    • id string read-only example: 1
      Id of the filter. Does not need to be included when creating article.
    • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
      Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
    • nameDE string read-only example: shop
      Name of the filter in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the filter in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the filter in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the filter in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this filter.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the filter is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • onlineShopCategories array of ArticleCategoryRef
    Categories used for Online shop of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • onlineShopFilters array of ArticleFilterRef
    Filters used for Online shop of the article
    Provide only either id or href of each filter when creating Article
    show fields

    Array of ArticleFilterRef.

    • id string read-only example: 1
      Id of the filter. Does not need to be included when creating article.
    • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
      Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
    • nameDE string read-only example: shop
      Name of the filter in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the filter in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the filter in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the filter in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this filter.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the filter is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • bookingCategories array of ArticleCategoryRef
    Categories used for Online Booking of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • searchTags array of string
    Search tags make it easier for your customer to find your product in the online shop
  • shippingInfo object
    shipping information for an article.
    show fields
    • shippingAttributes array of string
      List of attributes used for shipping
    • weightUnit string
      Weight unit used for shipping of the article
      Allowed values: GRAM, KILOGRAM
    • dimensionUnit string
      Dimension unit used for shipping of the article
      Allowed values: CENTIMETER, METER
    • weight number pattern: ^\d{1,19}([.]\d{1,2})?$
      Weight of this article
    • width number pattern: ^\d{1,19}([.]\d{1,2})?$
      Width of this article
    • height number pattern: ^\d{1,19}([.]\d{1,2})?$
      Height of this article
    • depth number pattern: ^\d{1,19}([.]\d{1,2})?$
      Depth of this article
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
  • vats array of ArticleVat
    VAT information for the article
    show fields

    Array of ArticleVat.

    • vatType object example: NORMAL
      Article vat type of the article
    • vatCase string example: TAXABLE_SUPPLY
      VAT case of the article
    • vatCode string example: 1
      VAT code of the article VAT
    • sss1 boolean example: False
      Reporting net tax rate with SSS1 option
    • sss2 boolean example: False
      Reporting net tax rate with SSS2 option
    • reportingNetTaxRate boolean example: False
      Using VAT reporting net tax rate option
    • excludeVat boolean example: False
      Using exclude VAT option
  • numberType object
    Inventory Number Type
    Use either NO_NUMBER or SERIAL_NUMBER
400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/latest/articles/{article-id}/article-set-itemskey / tokenGet list of items from article set
operationId

getArticleSetWithItemsById — the method name a generated client uses.

Required permission

ARTICLE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 1
NameDescription
article-id required
path string
Responses 5
200 Return successfully show body

application/json array of PublicApiArticleSetItem

Array of PublicApiArticleSetItem.

  • id string example: 1
    Id of the article set
  • articleName string example: Mobile phone
    Article name of the article
  • number string example: 1
    The number of the article
  • productType object example: PRODUCTION
    Type of product used for an article
  • price number
    Price of the article
  • vat object
    Vat of the article
    show fields
    • vatType object example: NORMAL
      Article vat type of the article
    • vatCase string example: TAXABLE_SUPPLY
      VAT case of the article
    • vatCode string example: 1
      VAT code of the article VAT
    • sss1 boolean example: False
      Reporting net tax rate with SSS1 option
    • sss2 boolean example: False
      Reporting net tax rate with SSS2 option
    • reportingNetTaxRate boolean example: False
      Using VAT reporting net tax rate option
    • excludeVat boolean example: False
      Using exclude VAT option
  • optionValues array of string
    Options for the set item if it is a variant
  • href string example: https://api.klara.ch/core/latest/articles/1
    Reference resource link
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
POST/core/latest/articles/{article-id}/imageskey / tokenAdd an image to an article
Image size limit: 5MB
Supported image type: PNG, JPG, JPEG
operationId

addArticleImage — the method name a generated client uses.

Required permission

ARTICLE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 1
NameDescription
article-id required
path string
Id of the article to add an image to
example: 1
Request body required

multipart/form-data BinaryFile

  • file string (binary) format: binary
Responses 7
201 Image added for article show body

application/json ArticleImage

  • imageId string
400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
415 Unsupported Media Type

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
DELETE/core/latest/articles/{article-id}/images/{image-id}key / tokenDelete an article image
operationId

deleteArticleImage — the method name a generated client uses.

Required permission

ARTICLE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 2
NameDescription
article-id required
path string
Id of the article to delete an image from
example: 1
image-id required
path string
Id of the image to delete
example: 1
Responses 7
204 Image deleted for given article no response body
400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 The image of the article or the article itself could not be found.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/latest/articles/{article-id}/images/{image-id}key / tokenGet the content of an article image
operationId

getArticleImage — the method name a generated client uses.

Required permission

ARTICLE_READ_ONLY
Available through: Administrator, External user, Mitarbeiter und Lohn, Kundenbeziehungen, Zeit- und Materialrapporte, Online Terminbuchung

Parameters 2
NameDescription
article-id required
path string
Id of the article to get an image from
example: 1
image-id required
path string
Id of the image to get the content from
example: 1
Responses 6
200 Content of an article image show body

application/octet-stream any

401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 The image of the article or the article itself could not be found.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
PUT/core/latest/articles/{article-id}/images/{image-id}key / tokenUpdate an article image
Image size limit: 5MB
Supported image type: PNG, JPG, JPEG
operationId

updateArticleImage — the method name a generated client uses.

Required permission

ARTICLE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 2
NameDescription
article-id required
path string
Id of the article to update an image
example: 1
image-id required
path string
Id of the image to update
example: 1
Request body required

multipart/form-data BinaryFile

  • file string (binary) format: binary
Responses 8
200 Image updated for article show body

application/json ArticleImage

  • imageId string
400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 The image of the article or the article itself could not be found.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
415 Unsupported Media Type

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/latest/articles/{article-id}/variantskey / tokenGet variants of an article
operationId

getVariantsByArticleId — the method name a generated client uses.

Required permission

ARTICLE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 1
NameDescription
article-id required
path string
Responses 5
200 Found variants show body

application/json array of Variant

Array of Variant.

  • id string example: 1
    Id of the variant
  • number string required example: ABC123
    Article number
  • barcode string default:
    Barcode for the variant
  • accountingTags array of string required
    Tags used for accounting. Articles with the same tag, same VAT case and same VAT rate are grouped together in the posting
  • articleSets array of string
    Name of the article sets that the variant is included in
  • defaultQuantity number
    The default quantity of the article
  • active boolean default: false
    Decide if this variant is active or not
  • pricePeriods array of PricePeriod
    Price periods for the article variant.
    If variant only has 1 price, don't include validFrom and validTo in the PricePeriod.
    If variant have many prices, set value for validFrom for the date that the price is active for each PricePeriod.
    show fields

    Array of PricePeriod.

    • validFrom string (date) format: date
      The price period is valid from this time
    • validTo string (date) format: date read-only
      The price period is invalid after this time
    • price number pattern: ^\d{1,19}([.]\d{1,2})?$
      The price used for an article within this price period
    • priceCategories array of PriceCategory
      List of price categories effective for this price period
      show fields

      Array of PriceCategory.

      • name string
        Name of the price category
      • price number pattern: ^\d{1,19}([.]\d{1,2})?$
        Effective price of this price category
  • variantOptionValues array of string
    Values for the options that this article variant represent
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/latest/articles/{article-id}/variants/{variant-id}key / tokenGet variants of an article with id
operationId

getVariantById — the method name a generated client uses.

Required permission

ARTICLE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 2
NameDescription
article-id required
path string
variant-id required
path string
Responses 5
200 Found article variant show body

application/json Variant

  • id string example: 1
    Id of the variant
  • number string required example: ABC123
    Article number
  • barcode string default:
    Barcode for the variant
  • accountingTags array of string required
    Tags used for accounting. Articles with the same tag, same VAT case and same VAT rate are grouped together in the posting
  • articleSets array of string
    Name of the article sets that the variant is included in
  • defaultQuantity number
    The default quantity of the article
  • active boolean default: false
    Decide if this variant is active or not
  • pricePeriods array of PricePeriod
    Price periods for the article variant.
    If variant only has 1 price, don't include validFrom and validTo in the PricePeriod.
    If variant have many prices, set value for validFrom for the date that the price is active for each PricePeriod.
    show fields

    Array of PricePeriod.

    • validFrom string (date) format: date
      The price period is valid from this time
    • validTo string (date) format: date read-only
      The price period is invalid after this time
    • price number pattern: ^\d{1,19}([.]\d{1,2})?$
      The price used for an article within this price period
    • priceCategories array of PriceCategory
      List of price categories effective for this price period
      show fields

      Array of PriceCategory.

      • name string
        Name of the price category
      • price number pattern: ^\d{1,19}([.]\d{1,2})?$
        Effective price of this price category
  • variantOptionValues array of string
    Values for the options that this article variant represent
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated

Customer14

GET/core/latest/customerskey / tokenReturns all customers of a company
operationId

listCustomers — the method name a generated client uses.

Required permission

FINANCE_GET_CUSTOMER
Available through: Administrator, External user, Buchhalter, Kundenbeziehungen

Responses 5
200 Customers show body

application/json array of Customer

Array of Customer.

  • id string read-only example: 1
    Id of this Customer. Does not need to be included when creating customer
  • person object
    A partner person.
    show fields
    • website string example: www.my-company.com
      The website address of this customer
    • categories array of string
      Add one or more categories to this customer that you can use as filter criteria for selecting partners
    • onlinePlatforms array of OnlinePlatform
      The list of online platforms that this customer uses
      show fields

      Array of OnlinePlatform.

      • id string read-only example: 1
        Id of this Online platform. Does not need to be included when creating Customer.
      • platformName object example: FACEBOOK
        Name of the platform that this customer uses
      • platformValue string example: www.linkedin.com/abc
        Url of customer's online platform/webpage
    • language string example: en
      The main language that this partner uses, valid values is [en, de, fr, it]
    • responsibleCounterpart string example: Mr. Marc
      The name of a contact person for this customer
    • correspondence object required example: MAIL
      The preferred method of correspondence, how this customer wants to receive the pay slips by default
    • id string example: 1
      Id of this person. Does not need to be included when creating customer
    • salutation object required example: MALE
      Salutation for this person, valid values is: [MALE, FEMALE, MALE_FEMALE, FAMILY]
    • firstName string required pattern: \S example: John
      First name of this person
    • lastName string required pattern: \S example: Henry
      Last name of this person
    • birthday string (date) format: date example: 2020-01-20
      Birth date of this person in ISO 8601 format (yyyy-MM-dd)
    • addresses array of Address
      Postal addresses of this person. At least one address is required when creating or updating a customer with customerType = PERSON - omitting it is rejected with 400. Not marked required here because existing customers created before this rule may still be returned without an address.
      show fields

      Array of Address.

      • id string example: 1
        Id of this Address. Does not need to be included when creating customer
      • validFrom string (date) format: date
        The timestamp from which this address is valid
      • validTo string (date) format: date
        The timestamp to which this address is valid
      • addressLines string required pattern: \S example: Chemin de la Caquerette 12
        The address lines for this Address
      • addressType string required pattern: \S example: WORK
        The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
      • cityName string required pattern: \S example: Bern
        Name of this City
      • cityZipCode string example: 3003
        The postal code of the city for this address. Required for Switzerland addresses (countryIso2Code = CH), where it is matched against the KLARA city register together with cityName; a missing or non-matching combination is rejected with 400. Ignored for every other country, where cityName is taken as given. Conditional on another field, so it is not marked required.
      • countryIso2Code string required pattern: \S example: CH
        2 letter country code. For company, only accept Switzerland
      • countryIso3Code string example: CHE
        3 letter country code. For company, only accept Switzerland
      • countryNumericCode string example: 756
        ISO-numeric code. For company, only accept Switzerland
      • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
        The path to get City object by city's id, /cities/{}
      • definitionName string example: 2nd address
        definition name of this address; in case main address, value is null; else value is not blank
      • additionalAddress string example: No. 13, street 123
        Additional address for more specific
    • phones array of Phone
      Phone number list of this person
      show fields

      Array of Phone.

      • id string example: 1
        Id of this Phone. Does not need to be included when creating customer.
      • phoneNumber string required example: 41783334444
      • type object required example: PRIVATE
        Type of this phone number. For company, only OFFICE type is supported. The full set of accepted values is the PhoneType schema.
    • emails array of Email
      Email list of this person
      show fields

      Array of Email.

      • id string example: 1
        Id of this Email. Does not need to be included when creating customer
      • emailAddress string example: example@gmail.com
        Email address
      • type object required example: PRIVATE
        Type of this email address. The full set of accepted values is the EmailType schema.
    • personNumber string
      This is a number the KLARA user can give to this customer/partner/supplier
  • company object
    A company.
    show fields
    • website string example: www.my-company.com
      The website address of this customer
    • categories array of string
      Add one or more categories to this customer that you can use as filter criteria for selecting partners
    • onlinePlatforms array of OnlinePlatform
      The list of online platforms that this customer uses
      show fields

      Array of OnlinePlatform.

      • id string read-only example: 1
        Id of this Online platform. Does not need to be included when creating Customer.
      • platformName object example: FACEBOOK
        Name of the platform that this customer uses
      • platformValue string example: www.linkedin.com/abc
        Url of customer's online platform/webpage
    • language string example: en
      The main language that this partner uses, valid values is [en, de, fr, it]
    • responsibleCounterpart string example: Mr. Marc
      The name of a contact person for this customer
    • correspondence object required example: MAIL
      The preferred method of correspondence, how this customer wants to receive the pay slips by default
    • id string read-only example: 1
      Id of this company. Does not need to be included when creating customer
    • name string required pattern: \S example: ABC-Corp
      Name of the company
    • phones array of Phone
      Phone numbers of the company
      show fields

      Array of Phone.

      • id string example: 1
        Id of this Phone. Does not need to be included when creating customer.
      • phoneNumber string required example: 41783334444
      • type object required example: PRIVATE
        Type of this phone number. For company, only OFFICE type is supported. The full set of accepted values is the PhoneType schema.
    • emails array of Email
      Emails of this company
      show fields

      Array of Email.

      • id string example: 1
        Id of this Email. Does not need to be included when creating customer
      • emailAddress string example: example@gmail.com
        Email address
      • type object required example: PRIVATE
        Type of this email address. The full set of accepted values is the EmailType schema.
    • addresses array of Address
      Postal addresses of this company. At least one address is required when creating or updating a customer with customerType = COMPANY - omitting it is rejected with 400. Not marked required here because existing customers created before this rule may still be returned without an address.
      show fields

      Array of Address.

      • id string example: 1
        Id of this Address. Does not need to be included when creating customer
      • validFrom string (date) format: date
        The timestamp from which this address is valid
      • validTo string (date) format: date
        The timestamp to which this address is valid
      • addressLines string required pattern: \S example: Chemin de la Caquerette 12
        The address lines for this Address
      • addressType string required pattern: \S example: WORK
        The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
      • cityName string required pattern: \S example: Bern
        Name of this City
      • cityZipCode string example: 3003
        The postal code of the city for this address. Required for Switzerland addresses (countryIso2Code = CH), where it is matched against the KLARA city register together with cityName; a missing or non-matching combination is rejected with 400. Ignored for every other country, where cityName is taken as given. Conditional on another field, so it is not marked required.
      • countryIso2Code string required pattern: \S example: CH
        2 letter country code. For company, only accept Switzerland
      • countryIso3Code string example: CHE
        3 letter country code. For company, only accept Switzerland
      • countryNumericCode string example: 756
        ISO-numeric code. For company, only accept Switzerland
      • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
        The path to get City object by city's id, /cities/{}
      • definitionName string example: 2nd address
        definition name of this address; in case main address, value is null; else value is not blank
      • additionalAddress string example: No. 13, street 123
        Additional address for more specific
    • corporateIdentificationNumber string example: CHE-123.456.789
      Every business active in Switzerland is given a unique enterprise identification number (UID). To ensure that numbers are correctly allocated and managed, the UID register is run by the Federal Statistical Office
    • vatNumber string example: CHE-123.456.789
      This is the official CH VAT number of the company
    • hrNumber string example: CHE-123.456.789
      This is the official CH number for this company in the CH trade register
    • nogaCode string example: 1234
      The NOGA code of this company
    • foundingDate string (date) format: date example: 2019-12-20
      Founding date of this comany in ISO 8601 format (yyyy-mm-dd)
    • companyNumber string
      This is a number the KLARA user can give to this customer/partner/supplier
  • priceCategory string example: Sale price
    You can select / enter a price category. On the articles you can define a special price for this price category. When such an article is sold / invoiced, the price of this category will apply if it is identical for the article and the customer.
  • customerType object required example: PERSON
    The type of this partner. Could be either Person or Company.
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
POST/core/latest/customerskey / tokenCreate a new customer
operationId

createCustomer — the method name a generated client uses.

Required permission

FINANCE_CREATE_CUSTOMER
Available through: Administrator, External user, Kundenbeziehungen

Request body required
The customer object with the information that needs to be created

application/json Customer

  • id string read-only example: 1
    Id of this Customer. Does not need to be included when creating customer
  • person object
    A partner person.
    show fields
    • website string example: www.my-company.com
      The website address of this customer
    • categories array of string
      Add one or more categories to this customer that you can use as filter criteria for selecting partners
    • onlinePlatforms array of OnlinePlatform
      The list of online platforms that this customer uses
      show fields

      Array of OnlinePlatform.

      • id string read-only example: 1
        Id of this Online platform. Does not need to be included when creating Customer.
      • platformName object example: FACEBOOK
        Name of the platform that this customer uses
      • platformValue string example: www.linkedin.com/abc
        Url of customer's online platform/webpage
    • language string example: en
      The main language that this partner uses, valid values is [en, de, fr, it]
    • responsibleCounterpart string example: Mr. Marc
      The name of a contact person for this customer
    • correspondence object required example: MAIL
      The preferred method of correspondence, how this customer wants to receive the pay slips by default
    • id string example: 1
      Id of this person. Does not need to be included when creating customer
    • salutation object required example: MALE
      Salutation for this person, valid values is: [MALE, FEMALE, MALE_FEMALE, FAMILY]
    • firstName string required pattern: \S example: John
      First name of this person
    • lastName string required pattern: \S example: Henry
      Last name of this person
    • birthday string (date) format: date example: 2020-01-20
      Birth date of this person in ISO 8601 format (yyyy-MM-dd)
    • addresses array of Address
      Postal addresses of this person. At least one address is required when creating or updating a customer with customerType = PERSON - omitting it is rejected with 400. Not marked required here because existing customers created before this rule may still be returned without an address.
      show fields

      Array of Address.

      • id string example: 1
        Id of this Address. Does not need to be included when creating customer
      • validFrom string (date) format: date
        The timestamp from which this address is valid
      • validTo string (date) format: date
        The timestamp to which this address is valid
      • addressLines string required pattern: \S example: Chemin de la Caquerette 12
        The address lines for this Address
      • addressType string required pattern: \S example: WORK
        The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
      • cityName string required pattern: \S example: Bern
        Name of this City
      • cityZipCode string example: 3003
        The postal code of the city for this address. Required for Switzerland addresses (countryIso2Code = CH), where it is matched against the KLARA city register together with cityName; a missing or non-matching combination is rejected with 400. Ignored for every other country, where cityName is taken as given. Conditional on another field, so it is not marked required.
      • countryIso2Code string required pattern: \S example: CH
        2 letter country code. For company, only accept Switzerland
      • countryIso3Code string example: CHE
        3 letter country code. For company, only accept Switzerland
      • countryNumericCode string example: 756
        ISO-numeric code. For company, only accept Switzerland
      • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
        The path to get City object by city's id, /cities/{}
      • definitionName string example: 2nd address
        definition name of this address; in case main address, value is null; else value is not blank
      • additionalAddress string example: No. 13, street 123
        Additional address for more specific
    • phones array of Phone
      Phone number list of this person
      show fields

      Array of Phone.

      • id string example: 1
        Id of this Phone. Does not need to be included when creating customer.
      • phoneNumber string required example: 41783334444
      • type object required example: PRIVATE
        Type of this phone number. For company, only OFFICE type is supported. The full set of accepted values is the PhoneType schema.
    • emails array of Email
      Email list of this person
      show fields

      Array of Email.

      • id string example: 1
        Id of this Email. Does not need to be included when creating customer
      • emailAddress string example: example@gmail.com
        Email address
      • type object required example: PRIVATE
        Type of this email address. The full set of accepted values is the EmailType schema.
    • personNumber string
      This is a number the KLARA user can give to this customer/partner/supplier
  • company object
    A company.
    show fields
    • website string example: www.my-company.com
      The website address of this customer
    • categories array of string
      Add one or more categories to this customer that you can use as filter criteria for selecting partners
    • onlinePlatforms array of OnlinePlatform
      The list of online platforms that this customer uses
      show fields

      Array of OnlinePlatform.

      • id string read-only example: 1
        Id of this Online platform. Does not need to be included when creating Customer.
      • platformName object example: FACEBOOK
        Name of the platform that this customer uses
      • platformValue string example: www.linkedin.com/abc
        Url of customer's online platform/webpage
    • language string example: en
      The main language that this partner uses, valid values is [en, de, fr, it]
    • responsibleCounterpart string example: Mr. Marc
      The name of a contact person for this customer
    • correspondence object required example: MAIL
      The preferred method of correspondence, how this customer wants to receive the pay slips by default
    • id string read-only example: 1
      Id of this company. Does not need to be included when creating customer
    • name string required pattern: \S example: ABC-Corp
      Name of the company
    • phones array of Phone
      Phone numbers of the company
      show fields

      Array of Phone.

      • id string example: 1
        Id of this Phone. Does not need to be included when creating customer.
      • phoneNumber string required example: 41783334444
      • type object required example: PRIVATE
        Type of this phone number. For company, only OFFICE type is supported. The full set of accepted values is the PhoneType schema.
    • emails array of Email
      Emails of this company
      show fields

      Array of Email.

      • id string example: 1
        Id of this Email. Does not need to be included when creating customer
      • emailAddress string example: example@gmail.com
        Email address
      • type object required example: PRIVATE
        Type of this email address. The full set of accepted values is the EmailType schema.
    • addresses array of Address
      Postal addresses of this company. At least one address is required when creating or updating a customer with customerType = COMPANY - omitting it is rejected with 400. Not marked required here because existing customers created before this rule may still be returned without an address.
      show fields

      Array of Address.

      • id string example: 1
        Id of this Address. Does not need to be included when creating customer
      • validFrom string (date) format: date
        The timestamp from which this address is valid
      • validTo string (date) format: date
        The timestamp to which this address is valid
      • addressLines string required pattern: \S example: Chemin de la Caquerette 12
        The address lines for this Address
      • addressType string required pattern: \S example: WORK
        The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
      • cityName string required pattern: \S example: Bern
        Name of this City
      • cityZipCode string example: 3003
        The postal code of the city for this address. Required for Switzerland addresses (countryIso2Code = CH), where it is matched against the KLARA city register together with cityName; a missing or non-matching combination is rejected with 400. Ignored for every other country, where cityName is taken as given. Conditional on another field, so it is not marked required.
      • countryIso2Code string required pattern: \S example: CH
        2 letter country code. For company, only accept Switzerland
      • countryIso3Code string example: CHE
        3 letter country code. For company, only accept Switzerland
      • countryNumericCode string example: 756
        ISO-numeric code. For company, only accept Switzerland
      • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
        The path to get City object by city's id, /cities/{}
      • definitionName string example: 2nd address
        definition name of this address; in case main address, value is null; else value is not blank
      • additionalAddress string example: No. 13, street 123
        Additional address for more specific
    • corporateIdentificationNumber string example: CHE-123.456.789
      Every business active in Switzerland is given a unique enterprise identification number (UID). To ensure that numbers are correctly allocated and managed, the UID register is run by the Federal Statistical Office
    • vatNumber string example: CHE-123.456.789
      This is the official CH VAT number of the company
    • hrNumber string example: CHE-123.456.789
      This is the official CH number for this company in the CH trade register
    • nogaCode string example: 1234
      The NOGA code of this company
    • foundingDate string (date) format: date example: 2019-12-20
      Founding date of this comany in ISO 8601 format (yyyy-mm-dd)
    • companyNumber string
      This is a number the KLARA user can give to this customer/partner/supplier
  • priceCategory string example: Sale price
    You can select / enter a price category. On the articles you can define a special price for this price category. When such an article is sold / invoiced, the price of this category will apply if it is identical for the article and the customer.
  • customerType object required example: PERSON
    The type of this partner. Could be either Person or Company.
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
Responses 6
201 Customer created show body

application/json Customer

  • id string read-only example: 1
    Id of this Customer. Does not need to be included when creating customer
  • person object
    A partner person.
    show fields
    • website string example: www.my-company.com
      The website address of this customer
    • categories array of string
      Add one or more categories to this customer that you can use as filter criteria for selecting partners
    • onlinePlatforms array of OnlinePlatform
      The list of online platforms that this customer uses
      show fields

      Array of OnlinePlatform.

      • id string read-only example: 1
        Id of this Online platform. Does not need to be included when creating Customer.
      • platformName object example: FACEBOOK
        Name of the platform that this customer uses
      • platformValue string example: www.linkedin.com/abc
        Url of customer's online platform/webpage
    • language string example: en
      The main language that this partner uses, valid values is [en, de, fr, it]
    • responsibleCounterpart string example: Mr. Marc
      The name of a contact person for this customer
    • correspondence object required example: MAIL
      The preferred method of correspondence, how this customer wants to receive the pay slips by default
    • id string example: 1
      Id of this person. Does not need to be included when creating customer
    • salutation object required example: MALE
      Salutation for this person, valid values is: [MALE, FEMALE, MALE_FEMALE, FAMILY]
    • firstName string required pattern: \S example: John
      First name of this person
    • lastName string required pattern: \S example: Henry
      Last name of this person
    • birthday string (date) format: date example: 2020-01-20
      Birth date of this person in ISO 8601 format (yyyy-MM-dd)
    • addresses array of Address
      Postal addresses of this person. At least one address is required when creating or updating a customer with customerType = PERSON - omitting it is rejected with 400. Not marked required here because existing customers created before this rule may still be returned without an address.
      show fields

      Array of Address.

      • id string example: 1
        Id of this Address. Does not need to be included when creating customer
      • validFrom string (date) format: date
        The timestamp from which this address is valid
      • validTo string (date) format: date
        The timestamp to which this address is valid
      • addressLines string required pattern: \S example: Chemin de la Caquerette 12
        The address lines for this Address
      • addressType string required pattern: \S example: WORK
        The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
      • cityName string required pattern: \S example: Bern
        Name of this City
      • cityZipCode string example: 3003
        The postal code of the city for this address. Required for Switzerland addresses (countryIso2Code = CH), where it is matched against the KLARA city register together with cityName; a missing or non-matching combination is rejected with 400. Ignored for every other country, where cityName is taken as given. Conditional on another field, so it is not marked required.
      • countryIso2Code string required pattern: \S example: CH
        2 letter country code. For company, only accept Switzerland
      • countryIso3Code string example: CHE
        3 letter country code. For company, only accept Switzerland
      • countryNumericCode string example: 756
        ISO-numeric code. For company, only accept Switzerland
      • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
        The path to get City object by city's id, /cities/{}
      • definitionName string example: 2nd address
        definition name of this address; in case main address, value is null; else value is not blank
      • additionalAddress string example: No. 13, street 123
        Additional address for more specific
    • phones array of Phone
      Phone number list of this person
      show fields

      Array of Phone.

      • id string example: 1
        Id of this Phone. Does not need to be included when creating customer.
      • phoneNumber string required example: 41783334444
      • type object required example: PRIVATE
        Type of this phone number. For company, only OFFICE type is supported. The full set of accepted values is the PhoneType schema.
    • emails array of Email
      Email list of this person
      show fields

      Array of Email.

      • id string example: 1
        Id of this Email. Does not need to be included when creating customer
      • emailAddress string example: example@gmail.com
        Email address
      • type object required example: PRIVATE
        Type of this email address. The full set of accepted values is the EmailType schema.
    • personNumber string
      This is a number the KLARA user can give to this customer/partner/supplier
  • company object
    A company.
    show fields
    • website string example: www.my-company.com
      The website address of this customer
    • categories array of string
      Add one or more categories to this customer that you can use as filter criteria for selecting partners
    • onlinePlatforms array of OnlinePlatform
      The list of online platforms that this customer uses
      show fields

      Array of OnlinePlatform.

      • id string read-only example: 1
        Id of this Online platform. Does not need to be included when creating Customer.
      • platformName object example: FACEBOOK
        Name of the platform that this customer uses
      • platformValue string example: www.linkedin.com/abc
        Url of customer's online platform/webpage
    • language string example: en
      The main language that this partner uses, valid values is [en, de, fr, it]
    • responsibleCounterpart string example: Mr. Marc
      The name of a contact person for this customer
    • correspondence object required example: MAIL
      The preferred method of correspondence, how this customer wants to receive the pay slips by default
    • id string read-only example: 1
      Id of this company. Does not need to be included when creating customer
    • name string required pattern: \S example: ABC-Corp
      Name of the company
    • phones array of Phone
      Phone numbers of the company
      show fields

      Array of Phone.

      • id string example: 1
        Id of this Phone. Does not need to be included when creating customer.
      • phoneNumber string required example: 41783334444
      • type object required example: PRIVATE
        Type of this phone number. For company, only OFFICE type is supported. The full set of accepted values is the PhoneType schema.
    • emails array of Email
      Emails of this company
      show fields

      Array of Email.

      • id string example: 1
        Id of this Email. Does not need to be included when creating customer
      • emailAddress string example: example@gmail.com
        Email address
      • type object required example: PRIVATE
        Type of this email address. The full set of accepted values is the EmailType schema.
    • addresses array of Address
      Postal addresses of this company. At least one address is required when creating or updating a customer with customerType = COMPANY - omitting it is rejected with 400. Not marked required here because existing customers created before this rule may still be returned without an address.
      show fields

      Array of Address.

      • id string example: 1
        Id of this Address. Does not need to be included when creating customer
      • validFrom string (date) format: date
        The timestamp from which this address is valid
      • validTo string (date) format: date
        The timestamp to which this address is valid
      • addressLines string required pattern: \S example: Chemin de la Caquerette 12
        The address lines for this Address
      • addressType string required pattern: \S example: WORK
        The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
      • cityName string required pattern: \S example: Bern
        Name of this City
      • cityZipCode string example: 3003
        The postal code of the city for this address. Required for Switzerland addresses (countryIso2Code = CH), where it is matched against the KLARA city register together with cityName; a missing or non-matching combination is rejected with 400. Ignored for every other country, where cityName is taken as given. Conditional on another field, so it is not marked required.
      • countryIso2Code string required pattern: \S example: CH
        2 letter country code. For company, only accept Switzerland
      • countryIso3Code string example: CHE
        3 letter country code. For company, only accept Switzerland
      • countryNumericCode string example: 756
        ISO-numeric code. For company, only accept Switzerland
      • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
        The path to get City object by city's id, /cities/{}
      • definitionName string example: 2nd address
        definition name of this address; in case main address, value is null; else value is not blank
      • additionalAddress string example: No. 13, street 123
        Additional address for more specific
    • corporateIdentificationNumber string example: CHE-123.456.789
      Every business active in Switzerland is given a unique enterprise identification number (UID). To ensure that numbers are correctly allocated and managed, the UID register is run by the Federal Statistical Office
    • vatNumber string example: CHE-123.456.789
      This is the official CH VAT number of the company
    • hrNumber string example: CHE-123.456.789
      This is the official CH number for this company in the CH trade register
    • nogaCode string example: 1234
      The NOGA code of this company
    • foundingDate string (date) format: date example: 2019-12-20
      Founding date of this comany in ISO 8601 format (yyyy-mm-dd)
    • companyNumber string
      This is a number the KLARA user can give to this customer/partner/supplier
  • priceCategory string example: Sale price
    You can select / enter a price category. On the articles you can define a special price for this price category. When such an article is sold / invoiced, the price of this category will apply if it is identical for the article and the customer.
  • customerType object required example: PERSON
    The type of this partner. Could be either Person or Company.
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
DELETE/core/latest/customers/{customer-id}key / tokenDelete a customer
operationId

deleteCustomer — the method name a generated client uses.

Required permission

FINANCE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 1
NameDescription
customer-id required
path string
Id of the customer to be deleted
example: 1
Responses 6
204 Customer deleted no response body
400 Could not delete Customer that contain orders

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/latest/customers/{customer-id}key / tokenReturns a customer of a company based on given id
operationId

getCustomer — the method name a generated client uses.

Required permission

FINANCE_GET_CUSTOMER
Available through: Administrator, External user, Buchhalter, Kundenbeziehungen

Parameters 1
NameDescription
customer-id required
path string
Id of the customer
example: 1
Responses 5
200 Found Customer show body

application/json Customer

  • id string read-only example: 1
    Id of this Customer. Does not need to be included when creating customer
  • person object
    A partner person.
    show fields
    • website string example: www.my-company.com
      The website address of this customer
    • categories array of string
      Add one or more categories to this customer that you can use as filter criteria for selecting partners
    • onlinePlatforms array of OnlinePlatform
      The list of online platforms that this customer uses
      show fields

      Array of OnlinePlatform.

      • id string read-only example: 1
        Id of this Online platform. Does not need to be included when creating Customer.
      • platformName object example: FACEBOOK
        Name of the platform that this customer uses
      • platformValue string example: www.linkedin.com/abc
        Url of customer's online platform/webpage
    • language string example: en
      The main language that this partner uses, valid values is [en, de, fr, it]
    • responsibleCounterpart string example: Mr. Marc
      The name of a contact person for this customer
    • correspondence object required example: MAIL
      The preferred method of correspondence, how this customer wants to receive the pay slips by default
    • id string example: 1
      Id of this person. Does not need to be included when creating customer
    • salutation object required example: MALE
      Salutation for this person, valid values is: [MALE, FEMALE, MALE_FEMALE, FAMILY]
    • firstName string required pattern: \S example: John
      First name of this person
    • lastName string required pattern: \S example: Henry
      Last name of this person
    • birthday string (date) format: date example: 2020-01-20
      Birth date of this person in ISO 8601 format (yyyy-MM-dd)
    • addresses array of Address
      Postal addresses of this person. At least one address is required when creating or updating a customer with customerType = PERSON - omitting it is rejected with 400. Not marked required here because existing customers created before this rule may still be returned without an address.
      show fields

      Array of Address.

      • id string example: 1
        Id of this Address. Does not need to be included when creating customer
      • validFrom string (date) format: date
        The timestamp from which this address is valid
      • validTo string (date) format: date
        The timestamp to which this address is valid
      • addressLines string required pattern: \S example: Chemin de la Caquerette 12
        The address lines for this Address
      • addressType string required pattern: \S example: WORK
        The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
      • cityName string required pattern: \S example: Bern
        Name of this City
      • cityZipCode string example: 3003
        The postal code of the city for this address. Required for Switzerland addresses (countryIso2Code = CH), where it is matched against the KLARA city register together with cityName; a missing or non-matching combination is rejected with 400. Ignored for every other country, where cityName is taken as given. Conditional on another field, so it is not marked required.
      • countryIso2Code string required pattern: \S example: CH
        2 letter country code. For company, only accept Switzerland
      • countryIso3Code string example: CHE
        3 letter country code. For company, only accept Switzerland
      • countryNumericCode string example: 756
        ISO-numeric code. For company, only accept Switzerland
      • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
        The path to get City object by city's id, /cities/{}
      • definitionName string example: 2nd address
        definition name of this address; in case main address, value is null; else value is not blank
      • additionalAddress string example: No. 13, street 123
        Additional address for more specific
    • phones array of Phone
      Phone number list of this person
      show fields

      Array of Phone.

      • id string example: 1
        Id of this Phone. Does not need to be included when creating customer.
      • phoneNumber string required example: 41783334444
      • type object required example: PRIVATE
        Type of this phone number. For company, only OFFICE type is supported. The full set of accepted values is the PhoneType schema.
    • emails array of Email
      Email list of this person
      show fields

      Array of Email.

      • id string example: 1
        Id of this Email. Does not need to be included when creating customer
      • emailAddress string example: example@gmail.com
        Email address
      • type object required example: PRIVATE
        Type of this email address. The full set of accepted values is the EmailType schema.
    • personNumber string
      This is a number the KLARA user can give to this customer/partner/supplier
  • company object
    A company.
    show fields
    • website string example: www.my-company.com
      The website address of this customer
    • categories array of string
      Add one or more categories to this customer that you can use as filter criteria for selecting partners
    • onlinePlatforms array of OnlinePlatform
      The list of online platforms that this customer uses
      show fields

      Array of OnlinePlatform.

      • id string read-only example: 1
        Id of this Online platform. Does not need to be included when creating Customer.
      • platformName object example: FACEBOOK
        Name of the platform that this customer uses
      • platformValue string example: www.linkedin.com/abc
        Url of customer's online platform/webpage
    • language string example: en
      The main language that this partner uses, valid values is [en, de, fr, it]
    • responsibleCounterpart string example: Mr. Marc
      The name of a contact person for this customer
    • correspondence object required example: MAIL
      The preferred method of correspondence, how this customer wants to receive the pay slips by default
    • id string read-only example: 1
      Id of this company. Does not need to be included when creating customer
    • name string required pattern: \S example: ABC-Corp
      Name of the company
    • phones array of Phone
      Phone numbers of the company
      show fields

      Array of Phone.

      • id string example: 1
        Id of this Phone. Does not need to be included when creating customer.
      • phoneNumber string required example: 41783334444
      • type object required example: PRIVATE
        Type of this phone number. For company, only OFFICE type is supported. The full set of accepted values is the PhoneType schema.
    • emails array of Email
      Emails of this company
      show fields

      Array of Email.

      • id string example: 1
        Id of this Email. Does not need to be included when creating customer
      • emailAddress string example: example@gmail.com
        Email address
      • type object required example: PRIVATE
        Type of this email address. The full set of accepted values is the EmailType schema.
    • addresses array of Address
      Postal addresses of this company. At least one address is required when creating or updating a customer with customerType = COMPANY - omitting it is rejected with 400. Not marked required here because existing customers created before this rule may still be returned without an address.
      show fields

      Array of Address.

      • id string example: 1
        Id of this Address. Does not need to be included when creating customer
      • validFrom string (date) format: date
        The timestamp from which this address is valid
      • validTo string (date) format: date
        The timestamp to which this address is valid
      • addressLines string required pattern: \S example: Chemin de la Caquerette 12
        The address lines for this Address
      • addressType string required pattern: \S example: WORK
        The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
      • cityName string required pattern: \S example: Bern
        Name of this City
      • cityZipCode string example: 3003
        The postal code of the city for this address. Required for Switzerland addresses (countryIso2Code = CH), where it is matched against the KLARA city register together with cityName; a missing or non-matching combination is rejected with 400. Ignored for every other country, where cityName is taken as given. Conditional on another field, so it is not marked required.
      • countryIso2Code string required pattern: \S example: CH
        2 letter country code. For company, only accept Switzerland
      • countryIso3Code string example: CHE
        3 letter country code. For company, only accept Switzerland
      • countryNumericCode string example: 756
        ISO-numeric code. For company, only accept Switzerland
      • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
        The path to get City object by city's id, /cities/{}
      • definitionName string example: 2nd address
        definition name of this address; in case main address, value is null; else value is not blank
      • additionalAddress string example: No. 13, street 123
        Additional address for more specific
    • corporateIdentificationNumber string example: CHE-123.456.789
      Every business active in Switzerland is given a unique enterprise identification number (UID). To ensure that numbers are correctly allocated and managed, the UID register is run by the Federal Statistical Office
    • vatNumber string example: CHE-123.456.789
      This is the official CH VAT number of the company
    • hrNumber string example: CHE-123.456.789
      This is the official CH number for this company in the CH trade register
    • nogaCode string example: 1234
      The NOGA code of this company
    • foundingDate string (date) format: date example: 2019-12-20
      Founding date of this comany in ISO 8601 format (yyyy-mm-dd)
    • companyNumber string
      This is a number the KLARA user can give to this customer/partner/supplier
  • priceCategory string example: Sale price
    You can select / enter a price category. On the articles you can define a special price for this price category. When such an article is sold / invoiced, the price of this category will apply if it is identical for the article and the customer.
  • customerType object required example: PERSON
    The type of this partner. Could be either Person or Company.
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
PUT/core/latest/customers/{customer-id}key / tokenUpdate an existing customer
operationId

updateCustomer — the method name a generated client uses.

Required permission

FINANCE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 1
NameDescription
customer-id required
path string
Id of the customer to be updated
example: 1
Request body required
The customer object with the information that needs to be updated

application/json Customer

  • id string read-only example: 1
    Id of this Customer. Does not need to be included when creating customer
  • person object
    A partner person.
    show fields
    • website string example: www.my-company.com
      The website address of this customer
    • categories array of string
      Add one or more categories to this customer that you can use as filter criteria for selecting partners
    • onlinePlatforms array of OnlinePlatform
      The list of online platforms that this customer uses
      show fields

      Array of OnlinePlatform.

      • id string read-only example: 1
        Id of this Online platform. Does not need to be included when creating Customer.
      • platformName object example: FACEBOOK
        Name of the platform that this customer uses
      • platformValue string example: www.linkedin.com/abc
        Url of customer's online platform/webpage
    • language string example: en
      The main language that this partner uses, valid values is [en, de, fr, it]
    • responsibleCounterpart string example: Mr. Marc
      The name of a contact person for this customer
    • correspondence object required example: MAIL
      The preferred method of correspondence, how this customer wants to receive the pay slips by default
    • id string example: 1
      Id of this person. Does not need to be included when creating customer
    • salutation object required example: MALE
      Salutation for this person, valid values is: [MALE, FEMALE, MALE_FEMALE, FAMILY]
    • firstName string required pattern: \S example: John
      First name of this person
    • lastName string required pattern: \S example: Henry
      Last name of this person
    • birthday string (date) format: date example: 2020-01-20
      Birth date of this person in ISO 8601 format (yyyy-MM-dd)
    • addresses array of Address
      Postal addresses of this person. At least one address is required when creating or updating a customer with customerType = PERSON - omitting it is rejected with 400. Not marked required here because existing customers created before this rule may still be returned without an address.
      show fields

      Array of Address.

      • id string example: 1
        Id of this Address. Does not need to be included when creating customer
      • validFrom string (date) format: date
        The timestamp from which this address is valid
      • validTo string (date) format: date
        The timestamp to which this address is valid
      • addressLines string required pattern: \S example: Chemin de la Caquerette 12
        The address lines for this Address
      • addressType string required pattern: \S example: WORK
        The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
      • cityName string required pattern: \S example: Bern
        Name of this City
      • cityZipCode string example: 3003
        The postal code of the city for this address. Required for Switzerland addresses (countryIso2Code = CH), where it is matched against the KLARA city register together with cityName; a missing or non-matching combination is rejected with 400. Ignored for every other country, where cityName is taken as given. Conditional on another field, so it is not marked required.
      • countryIso2Code string required pattern: \S example: CH
        2 letter country code. For company, only accept Switzerland
      • countryIso3Code string example: CHE
        3 letter country code. For company, only accept Switzerland
      • countryNumericCode string example: 756
        ISO-numeric code. For company, only accept Switzerland
      • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
        The path to get City object by city's id, /cities/{}
      • definitionName string example: 2nd address
        definition name of this address; in case main address, value is null; else value is not blank
      • additionalAddress string example: No. 13, street 123
        Additional address for more specific
    • phones array of Phone
      Phone number list of this person
      show fields

      Array of Phone.

      • id string example: 1
        Id of this Phone. Does not need to be included when creating customer.
      • phoneNumber string required example: 41783334444
      • type object required example: PRIVATE
        Type of this phone number. For company, only OFFICE type is supported. The full set of accepted values is the PhoneType schema.
    • emails array of Email
      Email list of this person
      show fields

      Array of Email.

      • id string example: 1
        Id of this Email. Does not need to be included when creating customer
      • emailAddress string example: example@gmail.com
        Email address
      • type object required example: PRIVATE
        Type of this email address. The full set of accepted values is the EmailType schema.
    • personNumber string
      This is a number the KLARA user can give to this customer/partner/supplier
  • company object
    A company.
    show fields
    • website string example: www.my-company.com
      The website address of this customer
    • categories array of string
      Add one or more categories to this customer that you can use as filter criteria for selecting partners
    • onlinePlatforms array of OnlinePlatform
      The list of online platforms that this customer uses
      show fields

      Array of OnlinePlatform.

      • id string read-only example: 1
        Id of this Online platform. Does not need to be included when creating Customer.
      • platformName object example: FACEBOOK
        Name of the platform that this customer uses
      • platformValue string example: www.linkedin.com/abc
        Url of customer's online platform/webpage
    • language string example: en
      The main language that this partner uses, valid values is [en, de, fr, it]
    • responsibleCounterpart string example: Mr. Marc
      The name of a contact person for this customer
    • correspondence object required example: MAIL
      The preferred method of correspondence, how this customer wants to receive the pay slips by default
    • id string read-only example: 1
      Id of this company. Does not need to be included when creating customer
    • name string required pattern: \S example: ABC-Corp
      Name of the company
    • phones array of Phone
      Phone numbers of the company
      show fields

      Array of Phone.

      • id string example: 1
        Id of this Phone. Does not need to be included when creating customer.
      • phoneNumber string required example: 41783334444
      • type object required example: PRIVATE
        Type of this phone number. For company, only OFFICE type is supported. The full set of accepted values is the PhoneType schema.
    • emails array of Email
      Emails of this company
      show fields

      Array of Email.

      • id string example: 1
        Id of this Email. Does not need to be included when creating customer
      • emailAddress string example: example@gmail.com
        Email address
      • type object required example: PRIVATE
        Type of this email address. The full set of accepted values is the EmailType schema.
    • addresses array of Address
      Postal addresses of this company. At least one address is required when creating or updating a customer with customerType = COMPANY - omitting it is rejected with 400. Not marked required here because existing customers created before this rule may still be returned without an address.
      show fields

      Array of Address.

      • id string example: 1
        Id of this Address. Does not need to be included when creating customer
      • validFrom string (date) format: date
        The timestamp from which this address is valid
      • validTo string (date) format: date
        The timestamp to which this address is valid
      • addressLines string required pattern: \S example: Chemin de la Caquerette 12
        The address lines for this Address
      • addressType string required pattern: \S example: WORK
        The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
      • cityName string required pattern: \S example: Bern
        Name of this City
      • cityZipCode string example: 3003
        The postal code of the city for this address. Required for Switzerland addresses (countryIso2Code = CH), where it is matched against the KLARA city register together with cityName; a missing or non-matching combination is rejected with 400. Ignored for every other country, where cityName is taken as given. Conditional on another field, so it is not marked required.
      • countryIso2Code string required pattern: \S example: CH
        2 letter country code. For company, only accept Switzerland
      • countryIso3Code string example: CHE
        3 letter country code. For company, only accept Switzerland
      • countryNumericCode string example: 756
        ISO-numeric code. For company, only accept Switzerland
      • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
        The path to get City object by city's id, /cities/{}
      • definitionName string example: 2nd address
        definition name of this address; in case main address, value is null; else value is not blank
      • additionalAddress string example: No. 13, street 123
        Additional address for more specific
    • corporateIdentificationNumber string example: CHE-123.456.789
      Every business active in Switzerland is given a unique enterprise identification number (UID). To ensure that numbers are correctly allocated and managed, the UID register is run by the Federal Statistical Office
    • vatNumber string example: CHE-123.456.789
      This is the official CH VAT number of the company
    • hrNumber string example: CHE-123.456.789
      This is the official CH number for this company in the CH trade register
    • nogaCode string example: 1234
      The NOGA code of this company
    • foundingDate string (date) format: date example: 2019-12-20
      Founding date of this comany in ISO 8601 format (yyyy-mm-dd)
    • companyNumber string
      This is a number the KLARA user can give to this customer/partner/supplier
  • priceCategory string example: Sale price
    You can select / enter a price category. On the articles you can define a special price for this price category. When such an article is sold / invoiced, the price of this category will apply if it is identical for the article and the customer.
  • customerType object required example: PERSON
    The type of this partner. Could be either Person or Company.
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
Responses 6
200 Customer updated show body

application/json Customer

  • id string read-only example: 1
    Id of this Customer. Does not need to be included when creating customer
  • person object
    A partner person.
    show fields
    • website string example: www.my-company.com
      The website address of this customer
    • categories array of string
      Add one or more categories to this customer that you can use as filter criteria for selecting partners
    • onlinePlatforms array of OnlinePlatform
      The list of online platforms that this customer uses
      show fields

      Array of OnlinePlatform.

      • id string read-only example: 1
        Id of this Online platform. Does not need to be included when creating Customer.
      • platformName object example: FACEBOOK
        Name of the platform that this customer uses
      • platformValue string example: www.linkedin.com/abc
        Url of customer's online platform/webpage
    • language string example: en
      The main language that this partner uses, valid values is [en, de, fr, it]
    • responsibleCounterpart string example: Mr. Marc
      The name of a contact person for this customer
    • correspondence object required example: MAIL
      The preferred method of correspondence, how this customer wants to receive the pay slips by default
    • id string example: 1
      Id of this person. Does not need to be included when creating customer
    • salutation object required example: MALE
      Salutation for this person, valid values is: [MALE, FEMALE, MALE_FEMALE, FAMILY]
    • firstName string required pattern: \S example: John
      First name of this person
    • lastName string required pattern: \S example: Henry
      Last name of this person
    • birthday string (date) format: date example: 2020-01-20
      Birth date of this person in ISO 8601 format (yyyy-MM-dd)
    • addresses array of Address
      Postal addresses of this person. At least one address is required when creating or updating a customer with customerType = PERSON - omitting it is rejected with 400. Not marked required here because existing customers created before this rule may still be returned without an address.
      show fields

      Array of Address.

      • id string example: 1
        Id of this Address. Does not need to be included when creating customer
      • validFrom string (date) format: date
        The timestamp from which this address is valid
      • validTo string (date) format: date
        The timestamp to which this address is valid
      • addressLines string required pattern: \S example: Chemin de la Caquerette 12
        The address lines for this Address
      • addressType string required pattern: \S example: WORK
        The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
      • cityName string required pattern: \S example: Bern
        Name of this City
      • cityZipCode string example: 3003
        The postal code of the city for this address. Required for Switzerland addresses (countryIso2Code = CH), where it is matched against the KLARA city register together with cityName; a missing or non-matching combination is rejected with 400. Ignored for every other country, where cityName is taken as given. Conditional on another field, so it is not marked required.
      • countryIso2Code string required pattern: \S example: CH
        2 letter country code. For company, only accept Switzerland
      • countryIso3Code string example: CHE
        3 letter country code. For company, only accept Switzerland
      • countryNumericCode string example: 756
        ISO-numeric code. For company, only accept Switzerland
      • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
        The path to get City object by city's id, /cities/{}
      • definitionName string example: 2nd address
        definition name of this address; in case main address, value is null; else value is not blank
      • additionalAddress string example: No. 13, street 123
        Additional address for more specific
    • phones array of Phone
      Phone number list of this person
      show fields

      Array of Phone.

      • id string example: 1
        Id of this Phone. Does not need to be included when creating customer.
      • phoneNumber string required example: 41783334444
      • type object required example: PRIVATE
        Type of this phone number. For company, only OFFICE type is supported. The full set of accepted values is the PhoneType schema.
    • emails array of Email
      Email list of this person
      show fields

      Array of Email.

      • id string example: 1
        Id of this Email. Does not need to be included when creating customer
      • emailAddress string example: example@gmail.com
        Email address
      • type object required example: PRIVATE
        Type of this email address. The full set of accepted values is the EmailType schema.
    • personNumber string
      This is a number the KLARA user can give to this customer/partner/supplier
  • company object
    A company.
    show fields
    • website string example: www.my-company.com
      The website address of this customer
    • categories array of string
      Add one or more categories to this customer that you can use as filter criteria for selecting partners
    • onlinePlatforms array of OnlinePlatform
      The list of online platforms that this customer uses
      show fields

      Array of OnlinePlatform.

      • id string read-only example: 1
        Id of this Online platform. Does not need to be included when creating Customer.
      • platformName object example: FACEBOOK
        Name of the platform that this customer uses
      • platformValue string example: www.linkedin.com/abc
        Url of customer's online platform/webpage
    • language string example: en
      The main language that this partner uses, valid values is [en, de, fr, it]
    • responsibleCounterpart string example: Mr. Marc
      The name of a contact person for this customer
    • correspondence object required example: MAIL
      The preferred method of correspondence, how this customer wants to receive the pay slips by default
    • id string read-only example: 1
      Id of this company. Does not need to be included when creating customer
    • name string required pattern: \S example: ABC-Corp
      Name of the company
    • phones array of Phone
      Phone numbers of the company
      show fields

      Array of Phone.

      • id string example: 1
        Id of this Phone. Does not need to be included when creating customer.
      • phoneNumber string required example: 41783334444
      • type object required example: PRIVATE
        Type of this phone number. For company, only OFFICE type is supported. The full set of accepted values is the PhoneType schema.
    • emails array of Email
      Emails of this company
      show fields

      Array of Email.

      • id string example: 1
        Id of this Email. Does not need to be included when creating customer
      • emailAddress string example: example@gmail.com
        Email address
      • type object required example: PRIVATE
        Type of this email address. The full set of accepted values is the EmailType schema.
    • addresses array of Address
      Postal addresses of this company. At least one address is required when creating or updating a customer with customerType = COMPANY - omitting it is rejected with 400. Not marked required here because existing customers created before this rule may still be returned without an address.
      show fields

      Array of Address.

      • id string example: 1
        Id of this Address. Does not need to be included when creating customer
      • validFrom string (date) format: date
        The timestamp from which this address is valid
      • validTo string (date) format: date
        The timestamp to which this address is valid
      • addressLines string required pattern: \S example: Chemin de la Caquerette 12
        The address lines for this Address
      • addressType string required pattern: \S example: WORK
        The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
      • cityName string required pattern: \S example: Bern
        Name of this City
      • cityZipCode string example: 3003
        The postal code of the city for this address. Required for Switzerland addresses (countryIso2Code = CH), where it is matched against the KLARA city register together with cityName; a missing or non-matching combination is rejected with 400. Ignored for every other country, where cityName is taken as given. Conditional on another field, so it is not marked required.
      • countryIso2Code string required pattern: \S example: CH
        2 letter country code. For company, only accept Switzerland
      • countryIso3Code string example: CHE
        3 letter country code. For company, only accept Switzerland
      • countryNumericCode string example: 756
        ISO-numeric code. For company, only accept Switzerland
      • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
        The path to get City object by city's id, /cities/{}
      • definitionName string example: 2nd address
        definition name of this address; in case main address, value is null; else value is not blank
      • additionalAddress string example: No. 13, street 123
        Additional address for more specific
    • corporateIdentificationNumber string example: CHE-123.456.789
      Every business active in Switzerland is given a unique enterprise identification number (UID). To ensure that numbers are correctly allocated and managed, the UID register is run by the Federal Statistical Office
    • vatNumber string example: CHE-123.456.789
      This is the official CH VAT number of the company
    • hrNumber string example: CHE-123.456.789
      This is the official CH number for this company in the CH trade register
    • nogaCode string example: 1234
      The NOGA code of this company
    • foundingDate string (date) format: date example: 2019-12-20
      Founding date of this comany in ISO 8601 format (yyyy-mm-dd)
    • companyNumber string
      This is a number the KLARA user can give to this customer/partner/supplier
  • priceCategory string example: Sale price
    You can select / enter a price category. On the articles you can define a special price for this price category. When such an article is sold / invoiced, the price of this category will apply if it is identical for the article and the customer.
  • customerType object required example: PERSON
    The type of this partner. Could be either Person or Company.
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/latest/customers/{customer-id}/additional-addresseskey / tokenGets all additional addresses of a customer
operationId

listCustomerAdditionalAddresses — the method name a generated client uses.

Required permission

FINANCE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 1
NameDescription
customer-id required
path string
Id of the customer to get additional addresses
example: 1
Responses 5
200 List of all additional addresses show body

application/json array of Address

Array of Address.

  • id string example: 1
    Id of this Address. Does not need to be included when creating customer
  • validFrom string (date) format: date
    The timestamp from which this address is valid
  • validTo string (date) format: date
    The timestamp to which this address is valid
  • addressLines string required pattern: \S example: Chemin de la Caquerette 12
    The address lines for this Address
  • addressType string required pattern: \S example: WORK
    The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
  • cityName string required pattern: \S example: Bern
    Name of this City
  • cityZipCode string example: 3003
    The postal code of the city for this address. Required for Switzerland addresses (countryIso2Code = CH), where it is matched against the KLARA city register together with cityName; a missing or non-matching combination is rejected with 400. Ignored for every other country, where cityName is taken as given. Conditional on another field, so it is not marked required.
  • countryIso2Code string required pattern: \S example: CH
    2 letter country code. For company, only accept Switzerland
  • countryIso3Code string example: CHE
    3 letter country code. For company, only accept Switzerland
  • countryNumericCode string example: 756
    ISO-numeric code. For company, only accept Switzerland
  • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
    The path to get City object by city's id, /cities/{}
  • definitionName string example: 2nd address
    definition name of this address; in case main address, value is null; else value is not blank
  • additionalAddress string example: No. 13, street 123
    Additional address for more specific
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
POST/core/latest/customers/{customer-id}/additional-addresseskey / tokenCreates a new customer's additional address
operationId

createCustomerAdditionalAddress — the method name a generated client uses.

Required permission

FINANCE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 1
NameDescription
customer-id required
path string
Id of the customer to add additional addresses to
example: 1
Request body required
The additional address object with the information that needs to be created

application/json Address

  • id string example: 1
    Id of this Address. Does not need to be included when creating customer
  • validFrom string (date) format: date
    The timestamp from which this address is valid
  • validTo string (date) format: date
    The timestamp to which this address is valid
  • addressLines string required pattern: \S example: Chemin de la Caquerette 12
    The address lines for this Address
  • addressType string required pattern: \S example: WORK
    The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
  • cityName string required pattern: \S example: Bern
    Name of this City
  • cityZipCode string example: 3003
    The postal code of the city for this address. Required for Switzerland addresses (countryIso2Code = CH), where it is matched against the KLARA city register together with cityName; a missing or non-matching combination is rejected with 400. Ignored for every other country, where cityName is taken as given. Conditional on another field, so it is not marked required.
  • countryIso2Code string required pattern: \S example: CH
    2 letter country code. For company, only accept Switzerland
  • countryIso3Code string example: CHE
    3 letter country code. For company, only accept Switzerland
  • countryNumericCode string example: 756
    ISO-numeric code. For company, only accept Switzerland
  • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
    The path to get City object by city's id, /cities/{}
  • definitionName string example: 2nd address
    definition name of this address; in case main address, value is null; else value is not blank
  • additionalAddress string example: No. 13, street 123
    Additional address for more specific
Responses 6
200 Customer's new additional address created show body

application/json Address

  • id string example: 1
    Id of this Address. Does not need to be included when creating customer
  • validFrom string (date) format: date
    The timestamp from which this address is valid
  • validTo string (date) format: date
    The timestamp to which this address is valid
  • addressLines string required pattern: \S example: Chemin de la Caquerette 12
    The address lines for this Address
  • addressType string required pattern: \S example: WORK
    The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
  • cityName string required pattern: \S example: Bern
    Name of this City
  • cityZipCode string example: 3003
    The postal code of the city for this address. Required for Switzerland addresses (countryIso2Code = CH), where it is matched against the KLARA city register together with cityName; a missing or non-matching combination is rejected with 400. Ignored for every other country, where cityName is taken as given. Conditional on another field, so it is not marked required.
  • countryIso2Code string required pattern: \S example: CH
    2 letter country code. For company, only accept Switzerland
  • countryIso3Code string example: CHE
    3 letter country code. For company, only accept Switzerland
  • countryNumericCode string example: 756
    ISO-numeric code. For company, only accept Switzerland
  • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
    The path to get City object by city's id, /cities/{}
  • definitionName string example: 2nd address
    definition name of this address; in case main address, value is null; else value is not blank
  • additionalAddress string example: No. 13, street 123
    Additional address for more specific
400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
DELETE/core/latest/customers/{customer-id}/additional-addresses/{address-id}key / tokenDelete an additional-address data by customer's id and customer's contact-id
operationId

deleteCustomerAdditionalAddress — the method name a generated client uses.

Required permission

FINANCE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 2
NameDescription
address-id required
path string
Id of the additional address needed to be updated
example: 1
customer-id required
path string
Id of the customer to update an additional address deleted
example: 1
Responses 5
204 Additional-address deleted no response body
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
PUT/core/latest/customers/{customer-id}/additional-addresses/{address-id}key / tokenUpdates a Address
operationId

updateCustomerAdditionalAddress — the method name a generated client uses.

Required permission

FINANCE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 2
NameDescription
address-id required
path string
The id of the requested Address
example: 1
customer-id required
path string
Id of the customer needed to update an additional address
example: 1
Request body required
The Address object with the information that needs to be updated

application/json Address

  • id string example: 1
    Id of this Address. Does not need to be included when creating customer
  • validFrom string (date) format: date
    The timestamp from which this address is valid
  • validTo string (date) format: date
    The timestamp to which this address is valid
  • addressLines string required pattern: \S example: Chemin de la Caquerette 12
    The address lines for this Address
  • addressType string required pattern: \S example: WORK
    The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
  • cityName string required pattern: \S example: Bern
    Name of this City
  • cityZipCode string example: 3003
    The postal code of the city for this address. Required for Switzerland addresses (countryIso2Code = CH), where it is matched against the KLARA city register together with cityName; a missing or non-matching combination is rejected with 400. Ignored for every other country, where cityName is taken as given. Conditional on another field, so it is not marked required.
  • countryIso2Code string required pattern: \S example: CH
    2 letter country code. For company, only accept Switzerland
  • countryIso3Code string example: CHE
    3 letter country code. For company, only accept Switzerland
  • countryNumericCode string example: 756
    ISO-numeric code. For company, only accept Switzerland
  • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
    The path to get City object by city's id, /cities/{}
  • definitionName string example: 2nd address
    definition name of this address; in case main address, value is null; else value is not blank
  • additionalAddress string example: No. 13, street 123
    Additional address for more specific
Responses 6
200 Updated additional-addresses show body

application/json Address

  • id string example: 1
    Id of this Address. Does not need to be included when creating customer
  • validFrom string (date) format: date
    The timestamp from which this address is valid
  • validTo string (date) format: date
    The timestamp to which this address is valid
  • addressLines string required pattern: \S example: Chemin de la Caquerette 12
    The address lines for this Address
  • addressType string required pattern: \S example: WORK
    The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
  • cityName string required pattern: \S example: Bern
    Name of this City
  • cityZipCode string example: 3003
    The postal code of the city for this address. Required for Switzerland addresses (countryIso2Code = CH), where it is matched against the KLARA city register together with cityName; a missing or non-matching combination is rejected with 400. Ignored for every other country, where cityName is taken as given. Conditional on another field, so it is not marked required.
  • countryIso2Code string required pattern: \S example: CH
    2 letter country code. For company, only accept Switzerland
  • countryIso3Code string example: CHE
    3 letter country code. For company, only accept Switzerland
  • countryNumericCode string example: 756
    ISO-numeric code. For company, only accept Switzerland
  • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
    The path to get City object by city's id, /cities/{}
  • definitionName string example: 2nd address
    definition name of this address; in case main address, value is null; else value is not blank
  • additionalAddress string example: No. 13, street 123
    Additional address for more specific
400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/latest/customers/{customer-id}/contactskey / tokenGets all contacts of a customer
operationId

listCustomerContacts — the method name a generated client uses.

Required permission

FINANCE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 1
NameDescription
customer-id required
path string
Id of the customer to get all contacts from
example: 1
Responses 5
200 List of contacts show body

application/json array of CustomerContact

Array of CustomerContact.

  • id string read-only example: 1
    Id of this contact. Does not need to be included when creating CustomerContact
  • imageId string read-only example: 1
    Id of this contact's image. Does not need to be included when creating CustomerContact
  • salutation object example: MALE
    Salutation for this contact
  • firstName string required example: John
    First name of this contact
  • lastName string required example: Henry
    Last name of this contact
  • email string example: john.henry@gmail.com
    Email of this contact
  • website string example: www.youtube.com
    Website of this contact
  • additionalAddressDefinition string
    Additional address definition of this contact
  • phones array of Phone
    Phone number list of this contact
    show fields

    Array of Phone.

    • id string example: 1
      Id of this Phone. Does not need to be included when creating customer.
    • phoneNumber string required example: 41783334444
    • type object required example: PRIVATE
      Type of this phone number. For company, only OFFICE type is supported. The full set of accepted values is the PhoneType schema.
  • categories array of string
    Category list of this contact
  • onlinePlatforms array of OnlinePlatform
    The list of online platforms that this contact uses
    show fields

    Array of OnlinePlatform.

    • id string read-only example: 1
      Id of this Online platform. Does not need to be included when creating Customer.
    • platformName object example: FACEBOOK
      Name of the platform that this customer uses
    • platformValue string example: www.linkedin.com/abc
      Url of customer's online platform/webpage
  • customFields array of CustomField
    The list of custom information of this contact
    show fields

    Array of CustomField.

    • id string read-only example: 1
      Id of this custom field. Does not need to be included when creating CustomerContact
    • customName string example: name at home
      name of this custom field
    • customValue string example: John Henry
      value of this custom field
  • function string
    Function of this contact
  • birthday string (date) format: date example: 2020-12-20
    Birth date of this person in ISO 8601 format (yyyy-mm-dd)
  • note string example: this is a important contact.
    Note of this contact
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
POST/core/latest/customers/{customer-id}/contactskey / tokenCreates a new customer's contact
operationId

createCustomerContact — the method name a generated client uses.

Required permission

FINANCE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 1
NameDescription
customer-id required
path string
The id of the requested customer to add new contact to
example: 1
Request body required
The CustomerContact object with the information that needs to be created

application/json CustomerContact

  • id string read-only example: 1
    Id of this contact. Does not need to be included when creating CustomerContact
  • imageId string read-only example: 1
    Id of this contact's image. Does not need to be included when creating CustomerContact
  • salutation object example: MALE
    Salutation for this contact
  • firstName string required example: John
    First name of this contact
  • lastName string required example: Henry
    Last name of this contact
  • email string example: john.henry@gmail.com
    Email of this contact
  • website string example: www.youtube.com
    Website of this contact
  • additionalAddressDefinition string
    Additional address definition of this contact
  • phones array of Phone
    Phone number list of this contact
    show fields

    Array of Phone.

    • id string example: 1
      Id of this Phone. Does not need to be included when creating customer.
    • phoneNumber string required example: 41783334444
    • type object required example: PRIVATE
      Type of this phone number. For company, only OFFICE type is supported. The full set of accepted values is the PhoneType schema.
  • categories array of string
    Category list of this contact
  • onlinePlatforms array of OnlinePlatform
    The list of online platforms that this contact uses
    show fields

    Array of OnlinePlatform.

    • id string read-only example: 1
      Id of this Online platform. Does not need to be included when creating Customer.
    • platformName object example: FACEBOOK
      Name of the platform that this customer uses
    • platformValue string example: www.linkedin.com/abc
      Url of customer's online platform/webpage
  • customFields array of CustomField
    The list of custom information of this contact
    show fields

    Array of CustomField.

    • id string read-only example: 1
      Id of this custom field. Does not need to be included when creating CustomerContact
    • customName string example: name at home
      name of this custom field
    • customValue string example: John Henry
      value of this custom field
  • function string
    Function of this contact
  • birthday string (date) format: date example: 2020-12-20
    Birth date of this person in ISO 8601 format (yyyy-mm-dd)
  • note string example: this is a important contact.
    Note of this contact
Responses 6
200 Customer's new contact created show body

application/json CustomerContact

  • id string read-only example: 1
    Id of this contact. Does not need to be included when creating CustomerContact
  • imageId string read-only example: 1
    Id of this contact's image. Does not need to be included when creating CustomerContact
  • salutation object example: MALE
    Salutation for this contact
  • firstName string required example: John
    First name of this contact
  • lastName string required example: Henry
    Last name of this contact
  • email string example: john.henry@gmail.com
    Email of this contact
  • website string example: www.youtube.com
    Website of this contact
  • additionalAddressDefinition string
    Additional address definition of this contact
  • phones array of Phone
    Phone number list of this contact
    show fields

    Array of Phone.

    • id string example: 1
      Id of this Phone. Does not need to be included when creating customer.
    • phoneNumber string required example: 41783334444
    • type object required example: PRIVATE
      Type of this phone number. For company, only OFFICE type is supported. The full set of accepted values is the PhoneType schema.
  • categories array of string
    Category list of this contact
  • onlinePlatforms array of OnlinePlatform
    The list of online platforms that this contact uses
    show fields

    Array of OnlinePlatform.

    • id string read-only example: 1
      Id of this Online platform. Does not need to be included when creating Customer.
    • platformName object example: FACEBOOK
      Name of the platform that this customer uses
    • platformValue string example: www.linkedin.com/abc
      Url of customer's online platform/webpage
  • customFields array of CustomField
    The list of custom information of this contact
    show fields

    Array of CustomField.

    • id string read-only example: 1
      Id of this custom field. Does not need to be included when creating CustomerContact
    • customName string example: name at home
      name of this custom field
    • customValue string example: John Henry
      value of this custom field
  • function string
    Function of this contact
  • birthday string (date) format: date example: 2020-12-20
    Birth date of this person in ISO 8601 format (yyyy-mm-dd)
  • note string example: this is a important contact.
    Note of this contact
400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
DELETE/core/latest/customers/{customer-id}/contacts/{contact-id}key / tokenDelete a CustomerContact data by customer's id and customer's contact-id
operationId

deleteCustomerContact — the method name a generated client uses.

Required permission

FINANCE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 2
NameDescription
contact-id required
path string
Id of a customer's contact to be deleted
example: 1
customer-id required
path string
Id of the requested customer to have a contact deleted
example: 1
Responses 5
204 Customer's contact deleted no response body
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
PUT/core/latest/customers/{customer-id}/contacts/{contact-id}key / tokenUpdates a CustomerContact
operationId

updateCustomerContact — the method name a generated client uses.

Required permission

FINANCE
Available through: Administrator, External user, Kundenbeziehungen

Parameters 2
NameDescription
contact-id required
path string
The id of the requested customer's contact to be updated
example: 1
customer-id required
path string
Id of the customer to have a contact updated
example: 1
Request body required
The customer's contact object with the information that needs to be updated

application/json CustomerContact

  • id string read-only example: 1
    Id of this contact. Does not need to be included when creating CustomerContact
  • imageId string read-only example: 1
    Id of this contact's image. Does not need to be included when creating CustomerContact
  • salutation object example: MALE
    Salutation for this contact
  • firstName string required example: John
    First name of this contact
  • lastName string required example: Henry
    Last name of this contact
  • email string example: john.henry@gmail.com
    Email of this contact
  • website string example: www.youtube.com
    Website of this contact
  • additionalAddressDefinition string
    Additional address definition of this contact
  • phones array of Phone
    Phone number list of this contact
    show fields

    Array of Phone.

    • id string example: 1
      Id of this Phone. Does not need to be included when creating customer.
    • phoneNumber string required example: 41783334444
    • type object required example: PRIVATE
      Type of this phone number. For company, only OFFICE type is supported. The full set of accepted values is the PhoneType schema.
  • categories array of string
    Category list of this contact
  • onlinePlatforms array of OnlinePlatform
    The list of online platforms that this contact uses
    show fields

    Array of OnlinePlatform.

    • id string read-only example: 1
      Id of this Online platform. Does not need to be included when creating Customer.
    • platformName object example: FACEBOOK
      Name of the platform that this customer uses
    • platformValue string example: www.linkedin.com/abc
      Url of customer's online platform/webpage
  • customFields array of CustomField
    The list of custom information of this contact
    show fields

    Array of CustomField.

    • id string read-only example: 1
      Id of this custom field. Does not need to be included when creating CustomerContact
    • customName string example: name at home
      name of this custom field
    • customValue string example: John Henry
      value of this custom field
  • function string
    Function of this contact
  • birthday string (date) format: date example: 2020-12-20
    Birth date of this person in ISO 8601 format (yyyy-mm-dd)
  • note string example: this is a important contact.
    Note of this contact
Responses 6
200 Updated contact show body

application/json CustomerContact

  • id string read-only example: 1
    Id of this contact. Does not need to be included when creating CustomerContact
  • imageId string read-only example: 1
    Id of this contact's image. Does not need to be included when creating CustomerContact
  • salutation object example: MALE
    Salutation for this contact
  • firstName string required example: John
    First name of this contact
  • lastName string required example: Henry
    Last name of this contact
  • email string example: john.henry@gmail.com
    Email of this contact
  • website string example: www.youtube.com
    Website of this contact
  • additionalAddressDefinition string
    Additional address definition of this contact
  • phones array of Phone
    Phone number list of this contact
    show fields

    Array of Phone.

    • id string example: 1
      Id of this Phone. Does not need to be included when creating customer.
    • phoneNumber string required example: 41783334444
    • type object required example: PRIVATE
      Type of this phone number. For company, only OFFICE type is supported. The full set of accepted values is the PhoneType schema.
  • categories array of string
    Category list of this contact
  • onlinePlatforms array of OnlinePlatform
    The list of online platforms that this contact uses
    show fields

    Array of OnlinePlatform.

    • id string read-only example: 1
      Id of this Online platform. Does not need to be included when creating Customer.
    • platformName object example: FACEBOOK
      Name of the platform that this customer uses
    • platformValue string example: www.linkedin.com/abc
      Url of customer's online platform/webpage
  • customFields array of CustomField
    The list of custom information of this contact
    show fields

    Array of CustomField.

    • id string read-only example: 1
      Id of this custom field. Does not need to be included when creating CustomerContact
    • customName string example: name at home
      name of this custom field
    • customValue string example: John Henry
      value of this custom field
  • function string
    Function of this contact
  • birthday string (date) format: date example: 2020-12-20
    Birth date of this person in ISO 8601 format (yyyy-mm-dd)
  • note string example: this is a important contact.
    Note of this contact
400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/customerskey / tokenSearch and page the customers of the caller's company.
Returns a page of customers (Persons + Companies) of the caller's company, with optional free-text search (search-key) and status filter (status). Results are paged with offset and limit: to retrieve every customer, iterate offset=0, limit, 2×limit, … until a response returns fewer than limit rows. All query parameters are optional; without any, the endpoint returns the first 50 active customers (downstream default ordering). This is a read-only, idempotent operation.

The tenant and company are derived from the JWT (@CurrentSession Token) and are never accepted as parameters. The caller must be authenticated (apiKeyAuth + bearerAuth) and must hold the FINANCE_GET_CUSTOMER permission on that company; otherwise the endpoint returns 403.
operationId

listCustomersV1 — the method name a generated client uses.

Required permission

FINANCE_GET_CUSTOMER
Available through: Administrator, External user, Buchhalter, Kundenbeziehungen

Parameters 4
NameDescription
limit
query integer
Page size. Defaults to 50; hard cap 100. Requests above the cap are rejected with 400.
min: 1 max: 100 default: 50 example: 50
offset
query integer
0-based pagination offset — the number of customers to skip before the returned page. Defaults to 0. Combine with limit to walk the full list.
min: 0 default: 0 example: 0
search-key
query string
Free-text search across customer name, email, phone and customer number. Tokenised on whitespace; matches are case-insensitive substring matches. Maximum length 256 characters.
maxLength: 256 example: müller
status
query string
Filter by customer state. Allowed values: ACTIVE, ALL, ARCHIVED. When omitted, the downstream service applies its default (active customers only).
Allowed values: ACTIVE, ALL, ARCHIVED
maxLength: 16 example: ACTIVE
Responses 6
200 Customers show body

application/json array of Customer

Array of Customer.

  • id string read-only example: 1
    Id of this Customer. Does not need to be included when creating customer
  • person object
    A partner person.
    show fields
    • website string example: www.my-company.com
      The website address of this customer
    • categories array of string
      Add one or more categories to this customer that you can use as filter criteria for selecting partners
    • onlinePlatforms array of OnlinePlatform
      The list of online platforms that this customer uses
      show fields

      Array of OnlinePlatform.

      • id string read-only example: 1
        Id of this Online platform. Does not need to be included when creating Customer.
      • platformName object example: FACEBOOK
        Name of the platform that this customer uses
      • platformValue string example: www.linkedin.com/abc
        Url of customer's online platform/webpage
    • language string example: en
      The main language that this partner uses, valid values is [en, de, fr, it]
    • responsibleCounterpart string example: Mr. Marc
      The name of a contact person for this customer
    • correspondence object required example: MAIL
      The preferred method of correspondence, how this customer wants to receive the pay slips by default
    • id string example: 1
      Id of this person. Does not need to be included when creating customer
    • salutation object required example: MALE
      Salutation for this person, valid values is: [MALE, FEMALE, MALE_FEMALE, FAMILY]
    • firstName string required pattern: \S example: John
      First name of this person
    • lastName string required pattern: \S example: Henry
      Last name of this person
    • birthday string (date) format: date example: 2020-01-20
      Birth date of this person in ISO 8601 format (yyyy-MM-dd)
    • addresses array of Address
      Postal addresses of this person. At least one address is required when creating or updating a customer with customerType = PERSON - omitting it is rejected with 400. Not marked required here because existing customers created before this rule may still be returned without an address.
      show fields

      Array of Address.

      • id string example: 1
        Id of this Address. Does not need to be included when creating customer
      • validFrom string (date) format: date
        The timestamp from which this address is valid
      • validTo string (date) format: date
        The timestamp to which this address is valid
      • addressLines string required pattern: \S example: Chemin de la Caquerette 12
        The address lines for this Address
      • addressType string required pattern: \S example: WORK
        The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
      • cityName string required pattern: \S example: Bern
        Name of this City
      • cityZipCode string example: 3003
        The postal code of the city for this address. Required for Switzerland addresses (countryIso2Code = CH), where it is matched against the KLARA city register together with cityName; a missing or non-matching combination is rejected with 400. Ignored for every other country, where cityName is taken as given. Conditional on another field, so it is not marked required.
      • countryIso2Code string required pattern: \S example: CH
        2 letter country code. For company, only accept Switzerland
      • countryIso3Code string example: CHE
        3 letter country code. For company, only accept Switzerland
      • countryNumericCode string example: 756
        ISO-numeric code. For company, only accept Switzerland
      • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
        The path to get City object by city's id, /cities/{}
      • definitionName string example: 2nd address
        definition name of this address; in case main address, value is null; else value is not blank
      • additionalAddress string example: No. 13, street 123
        Additional address for more specific
    • phones array of Phone
      Phone number list of this person
      show fields

      Array of Phone.

      • id string example: 1
        Id of this Phone. Does not need to be included when creating customer.
      • phoneNumber string required example: 41783334444
      • type object required example: PRIVATE
        Type of this phone number. For company, only OFFICE type is supported. The full set of accepted values is the PhoneType schema.
    • emails array of Email
      Email list of this person
      show fields

      Array of Email.

      • id string example: 1
        Id of this Email. Does not need to be included when creating customer
      • emailAddress string example: example@gmail.com
        Email address
      • type object required example: PRIVATE
        Type of this email address. The full set of accepted values is the EmailType schema.
    • personNumber string
      This is a number the KLARA user can give to this customer/partner/supplier
  • company object
    A company.
    show fields
    • website string example: www.my-company.com
      The website address of this customer
    • categories array of string
      Add one or more categories to this customer that you can use as filter criteria for selecting partners
    • onlinePlatforms array of OnlinePlatform
      The list of online platforms that this customer uses
      show fields

      Array of OnlinePlatform.

      • id string read-only example: 1
        Id of this Online platform. Does not need to be included when creating Customer.
      • platformName object example: FACEBOOK
        Name of the platform that this customer uses
      • platformValue string example: www.linkedin.com/abc
        Url of customer's online platform/webpage
    • language string example: en
      The main language that this partner uses, valid values is [en, de, fr, it]
    • responsibleCounterpart string example: Mr. Marc
      The name of a contact person for this customer
    • correspondence object required example: MAIL
      The preferred method of correspondence, how this customer wants to receive the pay slips by default
    • id string read-only example: 1
      Id of this company. Does not need to be included when creating customer
    • name string required pattern: \S example: ABC-Corp
      Name of the company
    • phones array of Phone
      Phone numbers of the company
      show fields

      Array of Phone.

      • id string example: 1
        Id of this Phone. Does not need to be included when creating customer.
      • phoneNumber string required example: 41783334444
      • type object required example: PRIVATE
        Type of this phone number. For company, only OFFICE type is supported. The full set of accepted values is the PhoneType schema.
    • emails array of Email
      Emails of this company
      show fields

      Array of Email.

      • id string example: 1
        Id of this Email. Does not need to be included when creating customer
      • emailAddress string example: example@gmail.com
        Email address
      • type object required example: PRIVATE
        Type of this email address. The full set of accepted values is the EmailType schema.
    • addresses array of Address
      Postal addresses of this company. At least one address is required when creating or updating a customer with customerType = COMPANY - omitting it is rejected with 400. Not marked required here because existing customers created before this rule may still be returned without an address.
      show fields

      Array of Address.

      • id string example: 1
        Id of this Address. Does not need to be included when creating customer
      • validFrom string (date) format: date
        The timestamp from which this address is valid
      • validTo string (date) format: date
        The timestamp to which this address is valid
      • addressLines string required pattern: \S example: Chemin de la Caquerette 12
        The address lines for this Address
      • addressType string required pattern: \S example: WORK
        The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
      • cityName string required pattern: \S example: Bern
        Name of this City
      • cityZipCode string example: 3003
        The postal code of the city for this address. Required for Switzerland addresses (countryIso2Code = CH), where it is matched against the KLARA city register together with cityName; a missing or non-matching combination is rejected with 400. Ignored for every other country, where cityName is taken as given. Conditional on another field, so it is not marked required.
      • countryIso2Code string required pattern: \S example: CH
        2 letter country code. For company, only accept Switzerland
      • countryIso3Code string example: CHE
        3 letter country code. For company, only accept Switzerland
      • countryNumericCode string example: 756
        ISO-numeric code. For company, only accept Switzerland
      • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
        The path to get City object by city's id, /cities/{}
      • definitionName string example: 2nd address
        definition name of this address; in case main address, value is null; else value is not blank
      • additionalAddress string example: No. 13, street 123
        Additional address for more specific
    • corporateIdentificationNumber string example: CHE-123.456.789
      Every business active in Switzerland is given a unique enterprise identification number (UID). To ensure that numbers are correctly allocated and managed, the UID register is run by the Federal Statistical Office
    • vatNumber string example: CHE-123.456.789
      This is the official CH VAT number of the company
    • hrNumber string example: CHE-123.456.789
      This is the official CH number for this company in the CH trade register
    • nogaCode string example: 1234
      The NOGA code of this company
    • foundingDate string (date) format: date example: 2019-12-20
      Founding date of this comany in ISO 8601 format (yyyy-mm-dd)
    • companyNumber string
      This is a number the KLARA user can give to this customer/partner/supplier
  • priceCategory string example: Sale price
    You can select / enter a price category. On the articles you can define a special price for this price category. When such an article is sold / invoiced, the price of this category will apply if it is identical for the article and the customer.
  • customerType object required example: PERSON
    The type of this partner. Could be either Person or Company.
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated

Individual2

GET/core/v2/tenants/individuals/profilekey / token[PREVIEW_API] Get profile from tenant's ID
operationId

getIndividualProfile — the method name a generated client uses.

Required permission

Not established. Assume a permission is needed, and ask support if a call is rejected.

Responses 5
200 Retrieved profile successfully show body

application/json object

  • participantId string read-only example: 969b2b24-5ffe-4b7c-b1e2-a2a59fb1acb5
  • firstName string example: Nikola
  • lastName string example: Tesla
  • email string example: email@klara.ch
    Main email address
  • tenantEntryType string example: INDIVIDUAL
    Tenant entry type of the profile
400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Profile not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
POST/core/v2/tenants/individuals/profilekey / token[PREVIEW_API] Create profile
operationId

createIndividualProfile — the method name a generated client uses.

Required permission

Not established. Assume a permission is needed, and ask support if a call is rejected.

Responses 5
200 Created profile successfully show body

application/json object

  • participantId string read-only example: 969b2b24-5ffe-4b7c-b1e2-a2a59fb1acb5
  • firstName string example: Nikola
  • lastName string example: Tesla
  • email string example: email@klara.ch
    Main email address
  • tenantEntryType string example: INDIVIDUAL
    Tenant entry type of the profile
400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated

Payroll

Payroll3

GET/core/v1/employees/short-infokey / tokenList the company's employees as short-info entries, filtered and sorted.
Returns a lightweight directory of the authenticated company's employees (id, name, email, employee number, workplace, status), resolved from the compensation and person records. Each entry's id is the employeeId consumed by other employee-scoped endpoints (e.g. GET /payroll/employees/{employeeId}/addable-salary-items) — call this endpoint first to resolve an employee's id. Results can be narrowed with a free-text search-key (matched against name, employee number and email), restricted to specific workplaces via workplace-ids, and filtered by contract status; ordering is controlled by sort-field and sort-direction. The tenant and company are derived from the authenticated token; the caller must hold the COMPENSATION_GET_EMPLOYEE permission on that company.
operationId

listEmployeesShortInfo — the method name a generated client uses.

Required permission

COMPENSATION_TIME_TRACKING
Available through: Administrator, External user, Mitarbeiter und Lohn, Zeit- und Materialrapporte

Parameters 6
NameDescription
filter-by-status
query string
Renamed to status. This name is accepted until 2027-09-01; when both are sent, status wins. After that date, a request sending filter-by-status without status is rejected with 400.

Deprecated — use status instead. Contract-status filter. Allowed values: ALL, ACTIVE, INACTIVE, DRAFT. Defaults to ALL.
Allowed values: ALL, ACTIVE, INACTIVE, DRAFT
default: ALL example: ALL
search-key
query string
Case-insensitive substring matched against the employee's full name, employee number and email. When omitted, no text filter is applied.
maxLength: 256
sort-direction
query string
Sort direction. Allowed values: ASC, DESC.
Allowed values: ASC, DESC
sort-field
query string
Field to sort by. Allowed values: NAME, EMAIL, EMPLOYEE_NUMBER. Defaults to NAME.
Allowed values: NAME, EMAIL, EMPLOYEE_NUMBER
default: NAME example: NAME
status
query string
Contract-status filter. Allowed values: ALL, ACTIVE, INACTIVE, DRAFT. Defaults to ALL.
Allowed values: ALL, ACTIVE, INACTIVE, DRAFT
default: ALL example: ALL
workplace-ids
query array of integer (int64)
Restrict results to employees whose current contract workplace is in this set. Repeat the parameter for multiple ids (e.g. workplace-ids=12&workplace-ids=13). When omitted, employees of all workplaces are returned.
Responses 7
200 Successful operation show body

application/json array of PublicApiEmployeeShortInfo

Array of PublicApiEmployeeShortInfo.

  • id integer (int64) format: int64 example: 3487
    Employee id. Use this as employeeId in employee-scoped endpoints.
  • firstName string example: Anna
    Employee's first name (resolved from the person record).
  • lastName string example: Müller
    Employee's last name (resolved from the person record).
  • employeeNumber string example: E-00123
    Company-assigned employee number.
  • email string example: anna.mueller@example.com
    Employee's primary email (resolved from the person record).
  • workplaceId integer (int64) format: int64 example: 12
    Id of the workplace of the employee's current contract.
  • personnelNumber string example: P-4711
    Personnel number of the employee.
  • numberOfChildren integer (int64) format: int64 deprecated example: 0
    Deprecated and not populated. Always returns 0; do not read this field. It was published in error — the employee directory does not carry family data — and the compensation service has never supplied a value for it. Scheduled for removal in /core/v2; it is retained here only so the published /core/v1 response shape is not altered.
  • cashPayment boolean deprecated example: False
    Deprecated and not populated. Always returns false; do not read this field. It was published in error — the employee directory does not carry payment arrangements — and the compensation service has never supplied a value for it. Scheduled for removal in /core/v2; it is retained here only so the published /core/v1 response shape is not altered.
  • status string example: ACTIVE
    Contract status of the employee. Allowed values: ACTIVE, INACTIVE, DRAFT.
400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
POST/core/v1/payroll/contracts/{contractId}/payslips/{payslipId}/salary-itemskey / tokenAdd a salary item to an employee's payslip.
Adds a single salary item (Base / Percent / Quantity / Amount / Comments) to the employee's editable (non-sealed) payslip identified by payslipId, then always recalculates that month. Returns the added salary item with its server-assigned id. This operation is not idempotent: repeated calls append duplicate items or throw an error when the item is not duplicatable (subject to the item's duplicatable flag). Salary items can only be added for active employees: if the contract is inactive (the employee has left the company), the request is rejected with 400 and nothing is added. Prerequisite: call GET /payroll/employees/{employeeId}/addable-salary-items first — its response provides the contractId and payslipId to target and the addable codes; resolve employeeId beforehand via GET /employees/short-info. The tenant and company are derived from the authenticated token; the caller must hold the COMPENSATION permission on that company.
operationId

addSalaryItem — the method name a generated client uses.

Required permission

COMPENSATION
Available through: Administrator, External user, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen, Online Terminbuchung

Parameters 2
NameDescription
contractId required
path integer
Id of the employee's contract to add the salary item to. Obtained from the contractId field of the GET /payroll/employees/{employeeId}/addable-salary-items response — call that endpoint first to select the employee and obtain this id.
example: 1
payslipId required
path integer
Id of the target (editable, non-sealed) payslip. Obtained from the payslipId field of the GET /payroll/employees/{employeeId}/addable-salary-items response — call that endpoint first to select the employee and obtain this id.
example: 26
Request body required
Purpose: add one salary item to the target payslip. The code must be one of the addable salary items for this payslip, and only the value fields the item allows may be sent.
Prerequisite APIs / value sources:
  • GET /employees/short-info → provides employeeId
  • GET /payroll/employees/{employeeId}/addable-salary-items → provides the contractId and payslipId path parameters, plus salaryItems[].code (→ code) and each item's editableFields (which of baseValue/rate/quantity/value may be sent)
Top-level fields:
  • code (string, required) — salary-type code from the addable-salary-items response.
  • salaryItemValues (object, optional) — the numeric values; see below.
  • remark (string, optional, max 1024) — free-text comment (GUI "Comments").
Nested salaryItemValues:
  • baseValue — GUI "Base".
  • rate — GUI "Percent (%)", but expressed as a decimal multiplier, not a percentage number: 1 = 100%, 0.5 = 50%, 2 = 200%. If your application wants to keep a normal percentage input for the user (e.g. typing 50 for 50%), it must divide that value by 100 before sending it here (50 / 100 = 0.5).
  • quantity — GUI "Quantity".
  • value — GUI "Amount".
Rules: the payslip must be editable (non-sealed); the employee must be active (a contract of an employee who has left is rejected with 400); the code must be addable to this payslip (returned by the addable-salary-items endpoint); only fields listed in the item's editableFields should be provided and the your application should also only show input boxes for those fields; with salary items that are not duplicatable (duplicatable=false), the your application should have a mechanism to recall the GET /payroll/employees/{employeeId}/addable-salary-items endpoint after each add to refresh the list of addable items and prevent adding duplicates, or automatically remove the added item from the list of addable items in the GUI; salaryItemValues.rate is a decimal multiplier (1 = 100%, 0.5 = 50%, 2 = 200%), not a percentage number — do not send a raw percentage like 50 for 50%, send 0.5.

application/json PayslipSalaryItemRequest

  • code string required maxLength: 64 pattern: \S example: 1005
    Salary-type code identifying the item to add. Must be one of the codes returned by GET /payroll/employees/{employeeId}/addable-salary-items (salaryItems[].code).
  • salaryItemValues object
    Numeric value fields of a salary item (GUI Base / Percent / Quantity / Amount). Only fields listed in the salary item's editableFields may be provided.
    show fields
    • baseValue number example: 5000
      GUI "Base" value.
    • rate number example: 0.5
      GUI "Percent (%)" value, expressed as a decimal multiplier — NOT a percentage number. 1 = 100%, 0.5 = 50%, 2 = 200%. If your application wants to keep a normal percentage input for the user (typing 50 for 50%) instead of a multiplier (0.5), it must divide that input by 100 before sending it here (50 / 100 = 0.5).
    • quantity number example: 1
      GUI "Quantity" value.
    • value number example: 425
      GUI "Amount" value.
  • remark string maxLength: 1024 example: Adjustment for March
    Optional free-text comment (GUI "Comments").
Responses 7
200 Successful operation show body

application/json PayslipSalaryItem

  • id integer (int64) format: int64 example: 778812
    Server-assigned id of the added salary item (present in the response only).
  • code string example: 1005
    Salary-type code of the added salary item.
  • salaryItemValues object
    Numeric value fields of a salary item (GUI Base / Percent / Quantity / Amount). Only fields listed in the salary item's editableFields may be provided.
    show fields
    • baseValue number example: 5000
      GUI "Base" value.
    • rate number example: 0.5
      GUI "Percent (%)" value, expressed as a decimal multiplier — NOT a percentage number. 1 = 100%, 0.5 = 50%, 2 = 200%. If your application wants to keep a normal percentage input for the user (typing 50 for 50%) instead of a multiplier (0.5), it must divide that input by 100 before sending it here (50 / 100 = 0.5).
    • quantity number example: 1
      GUI "Quantity" value.
    • value number example: 425
      GUI "Amount" value.
  • remark string example: Adjustment for March
    Free-text comment attached to the salary item (GUI "Comments").
400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Error codes for this response (the code field of the response body):
  • auth.credentials_missing — Neither an Authorization: Bearer header nor an API key header was present on the request.
Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/payroll/employees/{employeeId}/addable-salary-itemskey / tokenGet the salary items that can be added to an employee's payslip.
Resolves the employee's main (latest) contract and its editable payslip, then returns the salary-item types that can be added to that payslip as blank templates (numeric value fields cleared, distinct by code), together with the resolved contractId and payslipId so the response can be chained into the add-salary-item call. Prerequisite: call GET /employees/short-info first to resolve the employeeId path parameter from the returned entries' id field. When month is provided that month's payslip is used; when it is omitted the employee's current payslip is used. An employee who has left (inactive) is rejected with 400. This call does not recalculate or create payslips, with one exception: the current payslip may be created on first access. A month whose payslip is already sealed (paid) is rejected with 400, and a month for which no payslip exists (e.g. a future month) returns 404. The tenant and company are derived from the authenticated token; the caller must hold the COMPENSATION permission on that company.
operationId

listAddableSalaryItems — the method name a generated client uses.

Required permission

COMPENSATION
Available through: Administrator, External user, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen, Online Terminbuchung

Parameters 3
NameDescription
employeeId required
path integer
Id of the employee whose addable salary items are resolved. Obtained from the id field of an entry returned by GET /employees/short-info.
example: 1
month
query string
Payslip month in the format MM.yyyy (e.g. 06.2025). If omitted, the employee's current payslip is used. The month's payslip must exist and must not be sealed (see the operation description).
example: 06.2025
Accept-Language
header string
Preferred language for localised salary-item descriptions, as an IETF language tag. Examples: de-CH, fr-CH, it-CH, en. Defaults to the tenant's language when omitted.
example: de-CH
Responses 7
200 Successful operation show body

application/json AddablePayslipSalaryItems

  • employeeId integer (int64) format: int64 example: 3487
    Id of the employee the addable salary items were resolved for.
  • contractId integer (int64) format: int64 example: 9021
    Id of the employee's resolved main (latest) contract. Pass this to the add-salary-item call.
  • payslipId integer (int64) format: int64 example: 9542
    Id of the resolved editable payslip. Pass this to the add-salary-item call.
  • periodFrom string (date-time) format: date-time example: 2018-03-01T00:00:00Z
    Month (first day) of the resolved payslip (yyyy-MM-ddT00:00:00Z).
  • salaryItems array of AddableSalaryItem
    Addable salary items as blank templates (value fields cleared), distinct by code.
    show fields

    Array of AddableSalaryItem.

    • code string example: 1005
      Salary-type code. Send this as the salary item code when adding it to the payslip.
    • name string example: Hourly Salary
      Canonical (non-localized) name of the salary item.
    • description string example: Stundenlohn
      Localised description/label of the salary item (localised via the Accept-Language header).
    • editableFields string example: baseValue,quantity
      Comma-separated list of the value fields that can be provided when adding this salary item (baseValue, rate, quantity, value).
    • duplicatable boolean example: True
      Whether more than one instance of this salary item can be added to the same payslip. When false, only one instance of this salary item can be added, try to add another one will result in an error.
    • showOnPayslip boolean example: True
      Whether the salary item is shown on the payslip.
    • employerRelated boolean example: False
      Whether the salary item is employer-related (as opposed to employee-related).
    • paymentTypeSit object example: BANK
      How the salary item is paid out. Allowed values: BANK, PAYINSLIP, CASH.
    • salaryItemTypeId integer (int64) format: int64 example: 42
      Id of the underlying salary-item type definition.
    • accountingGroup string example: SALARY
      Accounting group the salary item belongs to.
    • printSequence integer (int32) format: int32 example: 100
      Print/order sequence of the salary item on the payslip.
400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated

Company & Locations

Company3

GET/core/v2/tenants/companieskey / tokenFind KLARA business company of tenant
Retrieve the business company of a tenant. Use your KLARA token from your username & password & tenant-id.
operationId

findCompany — the method name a generated client uses.

Required permission

COMPENSATION_COMPANY_INFO
Available through: Administrator, External user, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen, Zeit- und Materialrapporte, Online Terminbuchung, Objektmanager

Responses 5
201 Company found show body

application/json BusinessCompany

  • name string required pattern: \S example: ABC-Corp
    Name of the company
  • legalForm object required example: LIMITED_LIABILITY
    Legal form of a company. The values below are what this API returns. On input the German abbreviation (GmbH, AG, EU, V, EG, KG, KDG, G, S, OR, IOER) is also accepted, case-insensitively.
  • phones array of Phone required
    Phone numbers of the company
    show fields

    Array of Phone.

    • id string example: 1
      Id of this Phone. Does not need to be included when creating customer.
    • phoneNumber string required example: 41783334444
    • type object required example: PRIVATE
      Type of this phone number. For company, only OFFICE type is supported. The full set of accepted values is the PhoneType schema.
  • emails array of Email required
    Emails of this company
    show fields

    Array of Email.

    • id string example: 1
      Id of this Email. Does not need to be included when creating customer
    • emailAddress string example: example@gmail.com
      Email address
    • type object required example: PRIVATE
      Type of this email address. The full set of accepted values is the EmailType schema.
  • addresses array of Address required
    Address list of this company, at least one should be add. For company, address type MUST be PRIVATE
    show fields

    Array of Address.

    • id string example: 1
      Id of this Address. Does not need to be included when creating customer
    • validFrom string (date) format: date
      The timestamp from which this address is valid
    • validTo string (date) format: date
      The timestamp to which this address is valid
    • addressLines string required pattern: \S example: Chemin de la Caquerette 12
      The address lines for this Address
    • addressType string required pattern: \S example: WORK
      The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
    • cityName string required pattern: \S example: Bern
      Name of this City
    • cityZipCode string example: 3003
      The postal code of the city for this address. Required for Switzerland addresses (countryIso2Code = CH), where it is matched against the KLARA city register together with cityName; a missing or non-matching combination is rejected with 400. Ignored for every other country, where cityName is taken as given. Conditional on another field, so it is not marked required.
    • countryIso2Code string required pattern: \S example: CH
      2 letter country code. For company, only accept Switzerland
    • countryIso3Code string example: CHE
      3 letter country code. For company, only accept Switzerland
    • countryNumericCode string example: 756
      ISO-numeric code. For company, only accept Switzerland
    • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
      The path to get City object by city's id, /cities/{}
    • definitionName string example: 2nd address
      definition name of this address; in case main address, value is null; else value is not blank
    • additionalAddress string example: No. 13, street 123
      Additional address for more specific
  • language string required pattern: \S example: de
    Preferred language of the company. Supported: English, German, French, Italian
    Allowed values: de, en, fr, it
  • corporateIdentificationNumber string example: CHE-123.456.789
    Every business active in Switzerland is given a unique enterprise identification number (UID). To ensure that numbers are correctly allocated and managed, the UID register is run by the Federal Statistical Office
  • foundingDate string (date) format: date example: 2019-12-20
    Founding date of this company in ISO 8601 format (yyyy-mm-dd)
401 Invalid credentials

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
403 The user has been disabled

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong when find company

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
POST/core/v2/tenants/companieskey / tokenCreate a KLARA business company
A KLARA user might have multiple company tenants. Use this endpoint to create a business company and its correspondence tenant. Use your KLARA token from your username & password & tenant-id.
operationId

createTenantAndBusinessCompany — the method name a generated client uses.

Required permission

COMPENSATION FINANCE_COMPANY_VAT
Whether both are required or one is enough is not confirmed. Plan for both.
Available through: Administrator, External user, Mitarbeiter und Lohn, Buchhalter

Request body
The company information

application/json BusinessCompany

  • name string required pattern: \S example: ABC-Corp
    Name of the company
  • legalForm object required example: LIMITED_LIABILITY
    Legal form of a company. The values below are what this API returns. On input the German abbreviation (GmbH, AG, EU, V, EG, KG, KDG, G, S, OR, IOER) is also accepted, case-insensitively.
  • phones array of Phone required
    Phone numbers of the company
    show fields

    Array of Phone.

    • id string example: 1
      Id of this Phone. Does not need to be included when creating customer.
    • phoneNumber string required example: 41783334444
    • type object required example: PRIVATE
      Type of this phone number. For company, only OFFICE type is supported. The full set of accepted values is the PhoneType schema.
  • emails array of Email required
    Emails of this company
    show fields

    Array of Email.

    • id string example: 1
      Id of this Email. Does not need to be included when creating customer
    • emailAddress string example: example@gmail.com
      Email address
    • type object required example: PRIVATE
      Type of this email address. The full set of accepted values is the EmailType schema.
  • addresses array of Address required
    Address list of this company, at least one should be add. For company, address type MUST be PRIVATE
    show fields

    Array of Address.

    • id string example: 1
      Id of this Address. Does not need to be included when creating customer
    • validFrom string (date) format: date
      The timestamp from which this address is valid
    • validTo string (date) format: date
      The timestamp to which this address is valid
    • addressLines string required pattern: \S example: Chemin de la Caquerette 12
      The address lines for this Address
    • addressType string required pattern: \S example: WORK
      The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
    • cityName string required pattern: \S example: Bern
      Name of this City
    • cityZipCode string example: 3003
      The postal code of the city for this address. Required for Switzerland addresses (countryIso2Code = CH), where it is matched against the KLARA city register together with cityName; a missing or non-matching combination is rejected with 400. Ignored for every other country, where cityName is taken as given. Conditional on another field, so it is not marked required.
    • countryIso2Code string required pattern: \S example: CH
      2 letter country code. For company, only accept Switzerland
    • countryIso3Code string example: CHE
      3 letter country code. For company, only accept Switzerland
    • countryNumericCode string example: 756
      ISO-numeric code. For company, only accept Switzerland
    • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
      The path to get City object by city's id, /cities/{}
    • definitionName string example: 2nd address
      definition name of this address; in case main address, value is null; else value is not blank
    • additionalAddress string example: No. 13, street 123
      Additional address for more specific
  • language string required pattern: \S example: de
    Preferred language of the company. Supported: English, German, French, Italian
    Allowed values: de, en, fr, it
  • corporateIdentificationNumber string example: CHE-123.456.789
    Every business active in Switzerland is given a unique enterprise identification number (UID). To ensure that numbers are correctly allocated and managed, the UID register is run by the Federal Statistical Office
  • foundingDate string (date) format: date example: 2019-12-20
    Founding date of this company in ISO 8601 format (yyyy-mm-dd)
Responses 6
201 Tenant and company created show body

application/json array of Tenant

Array of Tenant.

  • tenant_id string example: aaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
  • company_id integer (int64) format: int64 example: 1
  • company_name string example: ABC Company
400 Invalid company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
401 Invalid credentials

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
403 The user has been disabled

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong when creating tenant and business company

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
PUT/core/v2/tenants/companieskey / tokenUpdate a KLARA business company
A KLARA user might have multiple tenants. Use this endpoint to update a KLARA business company. Use your KLARA token from your username & password & tenant-id.
operationId

updateCompany — the method name a generated client uses.

Required permission

COMPENSATION
Available through: Administrator, External user, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen, Online Terminbuchung

Request body
The updated company information

application/json BusinessCompany

  • name string required pattern: \S example: ABC-Corp
    Name of the company
  • legalForm object required example: LIMITED_LIABILITY
    Legal form of a company. The values below are what this API returns. On input the German abbreviation (GmbH, AG, EU, V, EG, KG, KDG, G, S, OR, IOER) is also accepted, case-insensitively.
  • phones array of Phone required
    Phone numbers of the company
    show fields

    Array of Phone.

    • id string example: 1
      Id of this Phone. Does not need to be included when creating customer.
    • phoneNumber string required example: 41783334444
    • type object required example: PRIVATE
      Type of this phone number. For company, only OFFICE type is supported. The full set of accepted values is the PhoneType schema.
  • emails array of Email required
    Emails of this company
    show fields

    Array of Email.

    • id string example: 1
      Id of this Email. Does not need to be included when creating customer
    • emailAddress string example: example@gmail.com
      Email address
    • type object required example: PRIVATE
      Type of this email address. The full set of accepted values is the EmailType schema.
  • addresses array of Address required
    Address list of this company, at least one should be add. For company, address type MUST be PRIVATE
    show fields

    Array of Address.

    • id string example: 1
      Id of this Address. Does not need to be included when creating customer
    • validFrom string (date) format: date
      The timestamp from which this address is valid
    • validTo string (date) format: date
      The timestamp to which this address is valid
    • addressLines string required pattern: \S example: Chemin de la Caquerette 12
      The address lines for this Address
    • addressType string required pattern: \S example: WORK
      The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
    • cityName string required pattern: \S example: Bern
      Name of this City
    • cityZipCode string example: 3003
      The postal code of the city for this address. Required for Switzerland addresses (countryIso2Code = CH), where it is matched against the KLARA city register together with cityName; a missing or non-matching combination is rejected with 400. Ignored for every other country, where cityName is taken as given. Conditional on another field, so it is not marked required.
    • countryIso2Code string required pattern: \S example: CH
      2 letter country code. For company, only accept Switzerland
    • countryIso3Code string example: CHE
      3 letter country code. For company, only accept Switzerland
    • countryNumericCode string example: 756
      ISO-numeric code. For company, only accept Switzerland
    • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
      The path to get City object by city's id, /cities/{}
    • definitionName string example: 2nd address
      definition name of this address; in case main address, value is null; else value is not blank
    • additionalAddress string example: No. 13, street 123
      Additional address for more specific
  • language string required pattern: \S example: de
    Preferred language of the company. Supported: English, German, French, Italian
    Allowed values: de, en, fr, it
  • corporateIdentificationNumber string example: CHE-123.456.789
    Every business active in Switzerland is given a unique enterprise identification number (UID). To ensure that numbers are correctly allocated and managed, the UID register is run by the Federal Statistical Office
  • foundingDate string (date) format: date example: 2019-12-20
    Founding date of this company in ISO 8601 format (yyyy-mm-dd)
Responses 6
201 Company updated show body

application/json BusinessCompany

  • name string required pattern: \S example: ABC-Corp
    Name of the company
  • legalForm object required example: LIMITED_LIABILITY
    Legal form of a company. The values below are what this API returns. On input the German abbreviation (GmbH, AG, EU, V, EG, KG, KDG, G, S, OR, IOER) is also accepted, case-insensitively.
  • phones array of Phone required
    Phone numbers of the company
    show fields

    Array of Phone.

    • id string example: 1
      Id of this Phone. Does not need to be included when creating customer.
    • phoneNumber string required example: 41783334444
    • type object required example: PRIVATE
      Type of this phone number. For company, only OFFICE type is supported. The full set of accepted values is the PhoneType schema.
  • emails array of Email required
    Emails of this company
    show fields

    Array of Email.

    • id string example: 1
      Id of this Email. Does not need to be included when creating customer
    • emailAddress string example: example@gmail.com
      Email address
    • type object required example: PRIVATE
      Type of this email address. The full set of accepted values is the EmailType schema.
  • addresses array of Address required
    Address list of this company, at least one should be add. For company, address type MUST be PRIVATE
    show fields

    Array of Address.

    • id string example: 1
      Id of this Address. Does not need to be included when creating customer
    • validFrom string (date) format: date
      The timestamp from which this address is valid
    • validTo string (date) format: date
      The timestamp to which this address is valid
    • addressLines string required pattern: \S example: Chemin de la Caquerette 12
      The address lines for this Address
    • addressType string required pattern: \S example: WORK
      The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
    • cityName string required pattern: \S example: Bern
      Name of this City
    • cityZipCode string example: 3003
      The postal code of the city for this address. Required for Switzerland addresses (countryIso2Code = CH), where it is matched against the KLARA city register together with cityName; a missing or non-matching combination is rejected with 400. Ignored for every other country, where cityName is taken as given. Conditional on another field, so it is not marked required.
    • countryIso2Code string required pattern: \S example: CH
      2 letter country code. For company, only accept Switzerland
    • countryIso3Code string example: CHE
      3 letter country code. For company, only accept Switzerland
    • countryNumericCode string example: 756
      ISO-numeric code. For company, only accept Switzerland
    • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
      The path to get City object by city's id, /cities/{}
    • definitionName string example: 2nd address
      definition name of this address; in case main address, value is null; else value is not blank
    • additionalAddress string example: No. 13, street 123
      Additional address for more specific
  • language string required pattern: \S example: de
    Preferred language of the company. Supported: English, German, French, Italian
    Allowed values: de, en, fr, it
  • corporateIdentificationNumber string example: CHE-123.456.789
    Every business active in Switzerland is given a unique enterprise identification number (UID). To ensure that numbers are correctly allocated and managed, the UID register is run by the Federal Statistical Office
  • foundingDate string (date) format: date example: 2019-12-20
    Founding date of this company in ISO 8601 format (yyyy-mm-dd)
400 Invalid company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
401 Invalid credentials

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
403 The user has been disabled

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong when updating tenant

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response

Company general4

GET/core/latest/company-configuration/including-vatkey / tokenGet the VAT inclusion setting for the authenticated company.
Returns whether invoice amounts for the company resolved from the bearer JWT are displayed and calculated including VAT (includingVat: true) or excluding VAT (includingVat: false). Use this value before creating or displaying invoices to apply the correct pricing model. When no configuration record exists for the company, the endpoint returns false (excluding VAT) as the default. The caller must hold the FINANCE permission on the target company.
operationId

getCompanyIncludingVatSetting — the method name a generated client uses.

Required permission

FINANCE_COMPANY_GET_VAT
Available through: Administrator, External user, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen

Responses 5
200 VAT inclusion setting for the authenticated company. show body

application/json CompanyConfigurationIncludingVatResult

  • includingVat boolean example: False
    Whether invoice amounts for the authenticated company are displayed and calculated including VAT. When true, VAT is baked into the displayed prices. When false, VAT is shown as a separate line item. Returns false when no configuration record has been set for the company.
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/latest/company-vatskey / tokenReturns vat list of a company
operationId

listCompanyVatLiabilities — the method name a generated client uses.

Required permission

FINANCE_COMPANY_GET_VAT
Available through: Administrator, External user, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen

Parameters 1
NameDescription
Accept-Language
header string
Responses 3
200 Company vats show body

application/json array of CompanyVAT

Array of CompanyVAT.

  • id string example: 123
    Id of the company VAT.
  • hasVat boolean
    Flag mark the company have VAT or not.
  • vatNumber string example: ABC-123
    The VAT number.
  • validFrom string (date) format: date
    The company VAT is valid from this time.
  • validTo string (date) format: date
    The company VAT is invalid after this time.
  • companyId integer (int64) format: int64 example: 1
    Id of the company
  • vats array of VAT
    This is list VAT value of the company.
    show fields

    Array of VAT.

    • id string example: 1
      Id of the VAT.
    • vatCode string example: ABC
      Code of the VAT.
    • rate number example: 5
      Rate of the VAT. Rate unit is percentage (%)
    • description string example: VAT's description
      The additional infomation for VAT.
    • validFrom string (date) format: date
      The VAT is valid from this time.
    • validTo string (date) format: date
      The VAT is invalid after this time.
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/latest/vat-caseskey / tokenReturns VAT case list.
operationId

listVatCases — the method name a generated client uses.

Required permission

none A valid token is enough. No particular permission is checked for this endpoint.

Parameters 2
NameDescription
applicability
query string
Allowed values: REVENUE, COST
Accept-Language
header string
Responses 3
200 VAT cases show body

application/json array of VatCase

Array of VatCase.

  • id string example: 1
    Id of the VAT Case.
  • vatCaseCode string example: ABC
    Code of the VAT Case.
  • description string example: VAT Case's description
    The additional infomation for VAT.
  • referenceMasterVat string
    The reference master for VAT.
  • vatCaseNames object
    The map contain VAT case names in many languages.
    show fields

    Open map with values of type string.

  • applicability object example: REVENUE
    The VAT case type.
  • orderNumber integer (int32) format: int32 example: 2
    This value present how this VAT case order in the list as sequence.
  • createDate string (date-time) format: date-time
    The date that VAT Case created.
  • updateDate string (date-time) format: date-time
    The date that VAT Case updated.
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/latest/vat-cases/{vat-case-id}key / tokenGet the VAT case by Id.
operationId

getVatCaseById — the method name a generated client uses.

Required permission

none A valid token is enough. No particular permission is checked for this endpoint.

Parameters 2
NameDescription
vat-case-id required
path string
Accept-Language
header string
Responses 3
200 VAT case show body

application/json VatCase

  • id string example: 1
    Id of the VAT Case.
  • vatCaseCode string example: ABC
    Code of the VAT Case.
  • description string example: VAT Case's description
    The additional infomation for VAT.
  • referenceMasterVat string
    The reference master for VAT.
  • vatCaseNames object
    The map contain VAT case names in many languages.
    show fields

    Open map with values of type string.

  • applicability object example: REVENUE
    The VAT case type.
  • orderNumber integer (int32) format: int32 example: 2
    This value present how this VAT case order in the list as sequence.
  • createDate string (date-time) format: date-time
    The date that VAT Case created.
  • updateDate string (date-time) format: date-time
    The date that VAT Case updated.
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated

Company documents1

POST/core/latest/companies/{company-id}/documentskey / tokenUpload a document for a company
Uploads a single file under one of a fixed set of document categories. The tenant is derived from the bearer token; only the authenticated company's id may be used in the path. Maximum file size: 25 MB. For category LIABILITY_UPLOAD the downstream service additionally triggers asynchronous AI analysis (the upload response is returned regardless of the AI outcome). Required caller roles (enforced by the downstream service): COMPANY_ADMINISTRATOR, TRUSTED_USER, ACCOUNTANT, CUSTOMER_RELATIONSHIP_MANAGER, EMPLOYEE or MYKLARA_USER.

Important: When uploading documents as part of the create booking functionality only the LIABILITY_UPLOAD category is allowed (the documents are automatically moved to LIABILITIES when the booking is created successfully via POST /core/v1/bookings).
operationId

uploadCompanyDocument — the method name a generated client uses.

Required roles

COMPANY_ADMINISTRATOR TRUSTED_USER ACCOUNTANT CUSTOMER_RELATIONSHIP_MANAGER EMPLOYEE MYKLARA_USER One of them is enough. This comes from the specification text, not from the source code analysis behind the other permission statements: the service that enforces it was not available for analysis. Of these, Administrator, Buchhalter, Kundenbeziehungen are roles you can assign in KLARA, see Roles & permissions. The others are platform roles and are not part of that matrix.

Parameters 1
NameDescription
company-id required
path integer (int64)
Identifier of the company that owns the document. Must match the company id carried by the bearer token, otherwise the request is rejected with 403.
format: int64
Request body required
Multipart body with two parts: 'category' (text) and 'file' (binary, ≤ 25 MB).

multipart/form-data CompanyDocumentUploadForm

  • category string required
    Document category. Determines where the file is stored and which downstream post-processing is triggered (e.g. LIABILITY_UPLOAD triggers asynchronous AI analysis). Important: For the create booking functionality, only LIABILITY_UPLOAD is allowed — the booking creation GUI must always use LIABILITY_UPLOAD when uploading documents in this context.
    Allowed values: SALARY_STATEMENTS, YEARLY_REPORTS, PAYMENT_FILES, INSURANCE_CERTIFICATES, SALARY_TRANSMISSIONS, OWN_DOCUMENTS, LIABILITY_UPLOAD, EXPENSES, LIABILITIES
  • file string (binary) required format: binary
    The document file to upload. Maximum size 25 MB. Allowed file types are enforced by the downstream service.
Responses 8
200 Document successfully uploaded. show body

application/json object

  • documentId string example: 550e8400-e29b-41d4-a716-446655440000
    Identifier of the stored document, assigned by the document service.
400 Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
403 The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
413 Uploaded file exceeds the 25 MB limit.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
415 Unsupported Media Type

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated

Location1

GET/core/latest/cities/{city-id}key / tokenReturns city details
Returns a City details with given id.
operationId

getCityById — the method name a generated client uses.

Required permission

none A valid token is enough. No particular permission is checked for this endpoint.

Parameters 1
NameDescription
city-id required
path string
City id
example: 1
Responses 4
200 Found city show body

application/json City

  • id integer (int64) format: int64 read-only example: 1
    The id of this City object
  • zipCode string example: 8034
    The postal code for this city
  • basicPostcode string
  • name string example: Gerlafingen
    Name of this City
  • cityName27 string
  • state object
    A partner State.
    show fields
    • id string read-only
    • code string example: VD
      Code of this State
    • description string example: Vaud
      Extended description of this State
  • community object
    A Community that this partner locates.
    show fields
    • id string read-only
    • bfsNumber integer (int32) format: int32 example: 5480
      BFS number of this Community
    • communityName string example: Daillens
      Name of this Community
    • conurbationNumber string example: 5586
      Conurbation number of this Community
    • state object
      A partner State.
      show fields
      • id string read-only
      • code string example: VD
        Code of this State
      • description string example: Vaud
        Extended description of this State
  • country object
    A Country that this partner locates.
    show fields
    • id string read-only
    • countryName string example: Schweiz
      Name of this Country
    • iso2Code string example: CH
      2 letter country code
    • iso3Code string example: CHE
      3 letter country code
    • phoneCode string example: 41
      Country calling code
    • numericCode string example: 756
      ISO-numeric code
401 No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated

Subscription1

POST/core/latest/subscriptionskey / tokenCreate subscriptions for KLARA tenants.
A KLARA user might have multiple subscriptions. Each subscription will enable a set of feature inside KLARA platform. This endpoint allows to create subscriptions for a KLARA tenant.

Each subscription is subjective to its own terms and conditions. Please ask your KLARA contacts or see more details using the KLARA webclient.

operationId

createSubscription — the method name a generated client uses.

Required permission

STORE_CUSTOMER
Available through: Administrator, External user, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen, Online Terminbuchung

Parameters 1
NameDescription
marketing-code
query array of string
Marketing code to identify which product will be subscribed. The marketing codes to create subscriptions for.
example: K-01-0002-00-M
Responses 6
201 Subscription created successfully show body

application/json array of Subscription

Array of Subscription.

  • product object required
    A product in KLARA widget store. Enable different features for users.
    show fields
    • code string required pattern: \S example: PRINTANDSENT
      Identifier code for each product-should be unique across all products
    • name string required example: Print and sent
      The name of the product
  • marketingCodes array of string required example: K-01-0002-00-M, K-02-0005-00-Y
    Marketing code to identify which product will be subscribed.
  • pricePlan object example: MONTHLY
    Specify how the subscription is paid. The full set of accepted values is the PricePlan schema.
    • SINGLE: Pay once for the whole subscription period.
    • VOLUME: Pay once for the whole subscription period and pay for each volume.
    • MONTHLY: Pay monthly for the subscription period.
    • QUARTERLY: Pay quarterly for the subscription period.
    • YEARLY: Pay yearly for the subscription period.
    • FREE: Free subscription.
    • PAY_PER_USE: Pay for each usage.
  • price number read-only example: 10
    The price of this subscription at this moment
  • subscriptionFrom string (date-time) format: date-time example: 2023-11-20 T10:15:30
    Specify when the subscription will start effectively. By default, the start date is today
  • subscriptionUntil string (date-time) format: date-time read-only example: 2024-11-20 T10:15:30
    Specify when the subscription will end effectively after unsubscribe. This value will be calculated by service itself.
  • renewalDate string (date) format: date example: 2024-20-11
    Indicates the date that subscription will automatically renewed for another period if no cancellation is made before this date.
400 Invalid subscription data. Note: for historical reasons this operation reports errors in the OAuth error/error_description shape rather than the ErrorMessage shape used elsewhere in the business API.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
401 Invalid credentials

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
403 The user has been disabled

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong when creating subscriptions for the company. Note: for historical reasons this operation reports errors in the OAuth error/error_description shape rather than the ErrorMessage shape used elsewhere in the business API.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response

Authentication

Authentication3

POST/core/latest/tenantspublicReturns all tenants of a user
A KLARA user might have multiple tenants. Use this endpoint to get the list of tenants containing tenant id, company id.
The tenant and company id returned by this endpoint can be used to generate tokens to access other endpoints. Use your KLARA username and password OR access-token to get the list of tenants.
operationId

listTenants — the method name a generated client uses.

Required permission

none A valid token is enough. No particular permission is checked for this endpoint.

Request body

application/x-www-form-urlencoded object

  • username string
  • password string
  • access_token string
Responses 6
200 Found tenants show body

application/json array of Tenant

Array of Tenant.

  • tenant_id string example: aaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
  • company_id integer (int64) format: int64 example: 1
  • company_name string example: ABC Company
400 Missing parameters

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
401 Invalid credentials

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
403 The user has been disabled

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong when getting list of tenants

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
POST/core/latest/tokenpublicGenerate tokens to access other KLARA core endpoints
After obtaining tenant id and company id for the desired tenant, use this endpoint to get the access token for a specific tenant, and refresh token.
A grant_type of password is used for a Password grant, which requires username, password, tenant and company id to produce access token, refresh token from scratch.
A grant_type of refresh_token is used for a Refresh token grant, which is used for acquiring the access token using refresh token.
A grant_type of token_exchange performs an OAuth 2.0 Token Exchange (RFC 8693). Provide subject_token (the raw upstream Bearer token, without the 'Bearer ' prefix) and audience to identify the target token type.
Supported audience values:
  • cossa — exchanges a COSSA bearer token for a ePost access token.
Note: subject_token must be the raw token value without the 'Bearer ' prefix.
operationId

createPublicApiToken — the method name a generated client uses.

Required permission

none A valid token is enough. No particular permission is checked for this endpoint.

Request body

application/x-www-form-urlencoded object

  • username string default:
  • password string default:
  • grant_type string default:
  • tenant_id string default:
  • company_id string default:
  • refresh_token string default:
  • subject_token string default:
  • audience string default:
Responses 5
200 Token created show body

application/json PublicAPIToken

  • access_token string
    Token used to access KLARA Public API endpoints, should be place at Authorization header of request. Access token is valid only for one company tenant
  • expires_in integer (int64) format: int64
    Amount of time in seconds left that the access token is valid for
  • refresh_expires_in integer (int64) format: int64
    Amount of time in seconds left that the refresh token is valid for
  • refreshToken string
    Token used to renew the access token
  • token_type string
    Type of access token that should be included in the Authorziation header of each request
400 Could not get token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 Invalid credentials

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Internal server error

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
POST/core/latest/token/by-microsoftpublicExchange Microsoft access token for system token
Provide a Microsoft access token and tenant id to exchange for a system token.
operationId

createPublicApiTokenByMicrosoft — the method name a generated client uses.

Required permission

none A valid token is enough. No particular permission is checked for this endpoint.

Request body

application/x-www-form-urlencoded object

  • microsoft_access_token string
  • tenant_id string
Responses 5
200 Token created show body

application/json AccessTokenResponse

  • access_token string
  • expires_in integer (int64) format: int64
  • refresh_expires_in integer (int64) format: int64
  • refresh_token string
  • token_type string
  • id_token string
  • not-before-policy integer (int32) format: int32
  • session_state string
  • otherClaims object
    show fields

    Open map with values of type object.

400 Could not get token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 Invalid credentials

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Internal server error

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated

KLARA authentication generic1

POST/core/latest/generic-tokenpublicGenerate tokens to use KLARA specific endpoint
Use this endpoint to get the access token for a specific user, and refresh token.
A grant_type of password is used for a Password grant, which requires username, password, access token, refresh token from scratch.
A grant_type of refresh_token is used for a Refresh token grant, which is used for acquiring the access token using refresh token.
operationId

createGenericApiToken — the method name a generated client uses.

Required permission

none A valid token is enough. No particular permission is checked for this endpoint.

Request body

application/x-www-form-urlencoded object

  • username string default:
  • password string default:
  • grant_type string default:
  • refresh_token string default:
Responses 5
200 Token created show body

application/json PublicAPIToken

  • access_token string
    Token used to access KLARA Public API endpoints, should be place at Authorization header of request. Access token is valid only for one company tenant
  • expires_in integer (int64) format: int64
    Amount of time in seconds left that the access token is valid for
  • refresh_expires_in integer (int64) format: int64
    Amount of time in seconds left that the refresh token is valid for
  • refreshToken string
    Token used to renew the access token
  • token_type string
    Type of access token that should be included in the Authorziation header of each request
400 Could not get token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 Invalid credentials

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Internal server error

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated

Changelog

What changed and when. Changes that can break an existing integration are marked as such.

API changes

9 November 202611 new

New

  • GET /core/v1/accounting/accounts/{accountCode}/statement — Get the statement of one account for a period: opening balance, all movements, closing balance.
  • GET /core/v1/accounting/accounts/{accountCode}/sub-accounts — List the sub-accounts of one account, for example the bank accounts of 1020.
  • GET /core/v1/accounting/business-case-templates/{businessCaseTemplateId}/payment-sources — List the payment sources a business case template offers for one payment group.
  • POST /core/v1/accounting/document-bookings/paid — Book an uploaded document through a business case as already paid.
  • GET /core/v1/accounting/fiscal-years — List the fiscal years of the company with their status.
  • GET /core/v1/accounting/kpis/income-expenses — Get the company's income and expenses per month for a period.
  • GET /core/v1/accounting/kpis/spendings-and-earnings — Get the company's spendings and earnings for a period, compared with a previous period.
  • GET /core/v1/accounting/reports/balance-sheet — Get the balance sheet at a date, optionally with a comparison date.
  • GET /core/v1/accounting/reports/general-ledger — Get the general ledger: the statements of all accounts for a period, page by page.
  • GET /core/v1/accounting/reports/partner-amounts — Get the open amounts and monthly payments of a customer or supplier, or of all partners.
  • GET /core/v1/accounting/reports/profit-and-loss — Get the profit and loss statement for a period, optionally with a comparison period.
20 October 20265 new

New

  • GET /core/v1/accounting/tags — List the tags used on bookings.
  • GET /core/v1/bank-transactions — List bank transactions that are not reconciled yet.
  • GET /core/v1/bookings — Search the journal: list bookings by text, booking date, amount or tag.
  • GET /core/v1/bookings/{bookingId} — Read one booking with all its debit and credit lines.
  • GET /core/v1/customers/{customerId}/open-positions — List the open items of one customer or supplier.
7 October 20263 changed · breaking
Breaking changes Existing integrations may be affected. This concerns POST /core/v1/payroll/contracts/{contractId}/payslips/{payslipId}/salary-items.

Changed

  • PUT /core/v1/invoices — documentation correction: `order` and `orderItems` have always been required, the specification now lists them. Existing integrations are not affected
  • POST /core/v1/invoices — documentation correction: `order` and `orderItems` have always been required, the specification now lists them. Existing integrations are not affected
  • POST /core/v1/payroll/contracts/{contractId}/payslips/{payslipId}/salary-items — parameter `query:recalculate` removed
18 September 20261 new · 97 changed

New

  • GET /core/v1/invoices — Search and page the invoices of the authenticated company.

Changed

  • GET /core/latest/article-categories — new parameter `query:offset`; new parameter `query:search-key`; response body now documented for 401 (ErrorMessage), 429 (ErrorMessage)
  • GET /core/latest/article-filters — new parameter `query:offset`; new parameter `query:search-key`; response body now documented for 401 (ErrorMessage), 429 (ErrorMessage)
  • 33 endpoints — response body now documented for 401 (ErrorMessage), 429 (ErrorMessage)
    Show the endpoints
    • GET /core/latest/articles
    • GET /core/latest/articles/article-and-variants
    • GET /core/latest/articles/{article-id}
    • GET /core/latest/articles/{article-id}/article-set-items
    • GET /core/latest/articles/{article-id}/variants
    • GET /core/latest/articles/{article-id}/variants/{variant-id}
    • GET /core/latest/company-configuration/including-vat
    • GET /core/v1/accounting/accounts
    • GET /core/v1/accounting/accounts/account-displaying
    • GET /core/v1/accounting/accounts/by-code/{accountCode}
    • GET /core/v1/accounting/booking-types
    • GET /core/v1/accounting/business-cases
    • GET /core/v1/accounting/business-cases/v2
    • GET /core/v1/accounting/business-cases/{businessCaseId}
    • GET /core/v1/accounting/companies/current
    • GET /core/v1/accounting/companies/current/business-case-templates
    • GET /core/v1/accounting/companies/current/financial-years
    • GET /core/v1/accounting/currencies/exchange-rate
    • GET /core/v1/accounting/master-vats
    • GET /core/v1/accounting/master-vats/current
    • GET /core/v1/accounting/master-vats/{masterVatId}
    • GET /core/v1/accounting/vat-types
    • GET /core/v1/accounting/vat-types/{vatTypeId}
    • GET /core/v1/order-documents/{order-type}/next-document-number
    • GET /core/v1/order-numbering-configurations
    • GET /core/v1/orders/next-order-number
    • POST /core/latest/article-categories
    • POST /core/latest/article-filters
    • POST /core/latest/articles
    • POST /core/latest/articles/bulk
    • POST /core/v1/bookings
    • PUT /core/latest/articles/{article-id}
    • PUT /core/v1/bookings/{id}/documents
  • 25 endpoints — response body now documented for 401 (ErrorMessage), 404 (ErrorMessage), 429 (ErrorMessage)
    Show the endpoints
    • DELETE /core/latest/article-categories/{category-id}
    • DELETE /core/latest/article-filters/{filter-id}
    • DELETE /core/latest/customers/{customer-id}/additional-addresses/{address-id}
    • DELETE /core/latest/customers/{customer-id}/contacts/{contact-id}
    • GET /core/latest/article-categories/{category-id}
    • GET /core/latest/article-filters/{filter-id}
    • GET /core/latest/cities/{city-id}
    • GET /core/latest/customers
    • GET /core/latest/customers/{customer-id}
    • GET /core/latest/customers/{customer-id}/additional-addresses
    • GET /core/latest/customers/{customer-id}/contacts
    • GET /core/v1/accounting/business-case-templates/{businessCaseTemplateId}
    • GET /core/v1/customers
    • GET /core/v1/invoices/{id}
    • POST /core/latest/article-categories/{category-id}/assign-to-articles
    • POST /core/latest/article-filters/{filter-id}/assign-to-articles
    • POST /core/latest/customers
    • POST /core/latest/customers/{customer-id}/additional-addresses
    • POST /core/latest/customers/{customer-id}/contacts
    • POST /core/v1/invoices/{id}/send
    • PUT /core/latest/article-categories/{category-id}
    • PUT /core/latest/article-filters/{filter-id}
    • PUT /core/latest/customers/{customer-id}
    • PUT /core/latest/customers/{customer-id}/additional-addresses/{address-id}
    • PUT /core/latest/customers/{customer-id}/contacts/{contact-id}
  • 6 endpoints — response body now documented for 401 (ErrorMessage), 429 (ErrorMessage), 500 (ErrorMessage)
    Show the endpoints
    • DELETE /core/latest/articles/{article-id}
    • DELETE /core/latest/articles/{article-id}/images/{image-id}
    • GET /core/latest/articles/article-numbers
    • GET /core/latest/articles/{article-id}/images/{image-id}
    • GET /core/v1/order-documents/filter/type-and-order-number
    • POST /core/latest/payroll-interface-file
  • POST /core/latest/articles/{article-id}/images — response body now documented for 401 (ErrorMessage), 415 (ErrorMessage), 429 (ErrorMessage), 500 (ErrorMessage)
  • PUT /core/latest/articles/{article-id}/images/{image-id} — response body now documented for 401 (ErrorMessage), 415 (ErrorMessage), 429 (ErrorMessage), 500 (ErrorMessage)
  • GET /core/latest/articles/search — new parameter `query:search-key`; response body now documented for 401 (ErrorMessage), 429 (ErrorMessage), 500 (ErrorMessage)
  • POST /core/latest/companies/{company-id}/documents — response body now documented for 401 (ErrorMessage), 415 (ErrorMessage), 429 (ErrorMessage); response schema renamed, 400: `ErrorMessage1` to `ErrorMessage`; 403: `ErrorMessage1` to `ErrorMessage`; 413: `ErrorMessage1` to `ErrorMessage`; 500: `ErrorMessage1` to `ErrorMessage`. Generated client type names change with it
  • 5 endpoints — response body now documented for 401 (ErrorMessage)
    Show the endpoints
    • GET /core/latest/company-vats
    • GET /core/latest/vat-cases
    • GET /core/latest/vat-cases/{vat-case-id}
    • GET /core/v2/tenants/individuals/profile
    • POST /core/v2/tenants/individuals/profile
  • DELETE /core/latest/customers/{customer-id} — response body now documented for 401 (ErrorMessage), 404 (ErrorMessage), 429 (ErrorMessage); response schema renamed, 400: `ErrorResponse` to `ErrorMessage`. Generated client type names change with it
  • POST /core/latest/generic-token — response body now documented for 400 (ErrorMessage), 401 (ErrorMessage), 429 (ErrorMessage), 500 (ErrorMessage)
  • POST /core/latest/token — response body now documented for 400 (ErrorMessage), 401 (ErrorMessage), 429 (ErrorMessage), 500 (ErrorMessage)
  • POST /core/latest/token/by-microsoft — response body now documented for 400 (ErrorMessage), 401 (ErrorMessage), 429 (ErrorMessage), 500 (ErrorMessage)
  • 5 endpoints — response body now documented for 429 (ErrorMessage)
    Show the endpoints
    • GET /core/v2/tenants/companies
    • POST /core/latest/subscriptions
    • POST /core/latest/tenants
    • POST /core/v2/tenants/companies
    • PUT /core/v2/tenants/companies
  • GET /core/v1/accounting/business-case-templates — new parameter `query:sort-field`; response body now documented for 401 (ErrorMessage), 429 (ErrorMessage)
  • GET /core/v1/bank-reconciliation/open-positions — new parameter `query:search-key`; response body now documented for 401 (ErrorMessage), 429 (ErrorMessage)
  • GET /core/v1/accounting/vat-profile — new status codes: 429; response body now documented for 401 (ErrorMessage)
  • GET /core/v1/accounting/vat-suggestions — new status codes: 429; response body now documented for 401 (ErrorMessage)
  • 6 endpoints — response body now documented for 401 (ErrorMessage), 404 (ErrorMessage), 429 (ErrorMessage), 500 (ErrorMessage)
    Show the endpoints
    • GET /core/v1/company-bank-accounts
    • GET /core/v1/invoices/next-invoice-number
    • POST /core/v1/invoices
    • POST /core/v1/invoices/{id}/printed-document
    • POST /core/v1/vat-clearing-reports/{year}/{quarter}
    • PUT /core/v1/invoices
  • GET /core/v1/employees/short-info — new parameter `query:status`; response body now documented for 401 (ErrorMessage), 429 (ErrorMessage), 500 (ErrorMessage); response schema renamed, 400: `ErrorMessage1` to `ErrorMessage`; 403: `ErrorMessage1` to `ErrorMessage`; 404: `ErrorMessage1` to `ErrorMessage`. Generated client type names change with it
  • POST /core/v1/payroll/contracts/{contractId}/payslips/{payslipId}/salary-items — response body now documented for 401 (ErrorMessage), 429 (ErrorMessage), 500 (ErrorMessage); response schema renamed, 400: `ErrorMessage1` to `ErrorMessage`; 403: `ErrorMessage1` to `ErrorMessage`; 404: `ErrorMessage1` to `ErrorMessage`. Generated client type names change with it
  • GET /core/v1/payroll/employees/{employeeId}/addable-salary-items — response body now documented for 401 (ErrorMessage), 429 (ErrorMessage), 500 (ErrorMessage); response schema renamed, 400: `ErrorMessage1` to `ErrorMessage`; 403: `ErrorMessage1` to `ErrorMessage`; 404: `ErrorMessage1` to `ErrorMessage`. Generated client type names change with it
7 September 20267 changed

Changed

  • 7 endpoints — new status codes: 404
    Show the endpoints
    • GET /core/latest/customers
    • GET /core/latest/customers/{customer-id}/additional-addresses
    • GET /core/latest/customers/{customer-id}/contacts
    • GET /core/v1/customers
    • POST /core/latest/customers
    • POST /core/latest/customers/{customer-id}/additional-addresses
    • POST /core/latest/customers/{customer-id}/contacts
31 August 202672 changed

Changed

  • 68 endpoints — operationId added, `…`. A generated client used to invent a method name from the path and will now use this id
    Show the endpoints
    • DELETE /core/latest/article-categories/{category-id}
    • DELETE /core/latest/article-filters/{filter-id}
    • DELETE /core/latest/articles/{article-id}
    • DELETE /core/latest/articles/{article-id}/images/{image-id}
    • DELETE /core/latest/customers/{customer-id}
    • GET /core/latest/article-categories
    • GET /core/latest/article-categories/{category-id}
    • GET /core/latest/article-filters
    • GET /core/latest/article-filters/{filter-id}
    • GET /core/latest/articles
    • GET /core/latest/articles/article-and-variants
    • GET /core/latest/articles/article-numbers
    • GET /core/latest/articles/search
    • GET /core/latest/articles/{article-id}
    • GET /core/latest/articles/{article-id}/article-set-items
    • GET /core/latest/articles/{article-id}/images/{image-id}
    • GET /core/latest/articles/{article-id}/variants
    • GET /core/latest/articles/{article-id}/variants/{variant-id}
    • GET /core/latest/cities/{city-id}
    • GET /core/latest/company-configuration/including-vat
    • GET /core/latest/company-vats
    • GET /core/latest/customers
    • GET /core/latest/customers/{customer-id}
    • GET /core/latest/customers/{customer-id}/additional-addresses
    • GET /core/latest/customers/{customer-id}/contacts
    • GET /core/latest/vat-cases
    • GET /core/latest/vat-cases/{vat-case-id}
    • GET /core/v1/company-bank-accounts
    • GET /core/v1/customers
    • GET /core/v1/employees/short-info
    • GET /core/v1/invoices/next-invoice-number
    • GET /core/v1/invoices/{id}
    • GET /core/v1/order-documents/filter/type-and-order-number
    • GET /core/v1/order-documents/{order-type}/next-document-number
    • GET /core/v1/order-numbering-configurations
    • GET /core/v1/orders/next-order-number
    • GET /core/v1/payroll/employees/{employeeId}/addable-salary-items
    • GET /core/v2/tenants/companies
    • GET /core/v2/tenants/individuals/profile
    • POST /core/latest/article-categories
    • POST /core/latest/article-categories/{category-id}/assign-to-articles
    • POST /core/latest/article-filters
    • POST /core/latest/article-filters/{filter-id}/assign-to-articles
    • POST /core/latest/articles
    • POST /core/latest/articles/bulk
    • POST /core/latest/articles/{article-id}/images
    • POST /core/latest/customers
    • POST /core/latest/customers/{customer-id}/additional-addresses
    • POST /core/latest/customers/{customer-id}/contacts
    • POST /core/latest/generic-token
    • POST /core/latest/payroll-interface-file
    • POST /core/latest/subscriptions
    • POST /core/latest/tenants
    • POST /core/latest/token
    • POST /core/latest/token/by-microsoft
    • POST /core/v1/invoices
    • POST /core/v1/invoices/{id}/printed-document
    • POST /core/v1/invoices/{id}/send
    • POST /core/v1/payroll/contracts/{contractId}/payslips/{payslipId}/salary-items
    • POST /core/v2/tenants/companies
    • POST /core/v2/tenants/individuals/profile
    • PUT /core/latest/article-categories/{category-id}
    • PUT /core/latest/article-filters/{filter-id}
    • PUT /core/latest/articles/{article-id}
    • PUT /core/latest/articles/{article-id}/images/{image-id}
    • PUT /core/latest/customers/{customer-id}
    • PUT /core/v1/invoices
    • PUT /core/v2/tenants/companies
  • PUT /core/latest/customers/{customer-id}/additional-addresses/{address-id} — operationId renamed from `update additional-addresses` to `updateCustomerAdditionalAddress`. Generated method names change with it
  • DELETE /core/latest/customers/{customer-id}/additional-addresses/{address-id} — operationId renamed from `delete additional-address` to `deleteCustomerAdditionalAddress`. Generated method names change with it
  • PUT /core/latest/customers/{customer-id}/contacts/{contact-id} — operationId renamed from `update CustomerContact` to `updateCustomerContact`. Generated method names change with it
  • DELETE /core/latest/customers/{customer-id}/contacts/{contact-id} — operationId renamed from `delete CustomerContact` to `deleteCustomerContact`. Generated method names change with it
28 August 20261 changed

Changed

  • POST /core/latest/generic-token — moved from area Klara authentication generic to KLARA authentication generic

Documentation changes

11 November 2026Permissions confirmed, sending needs a bearer token, booking title
  • Permissions confirmed for two accounting endpoints. Booking a document as paid and listing the payment sources of a business case template work for Administrator, External user and Buchhalter. For the payment group of employees, access to payroll is also needed, so Buchhalter receives 403 there.
  • Sending an invoice also needs a bearer token for now. The FAQ on 401 now lists four endpoints, and the examples under smart delivery use a bearer token.
  • bookingTitle is not stored. The title KLARA shows is the description of the line with the lowest account code, VAT lines excluded.
  • New FAQ: whether an API key can be restricted to articles.
9 November 2026Bearer token for three endpoints, VAT notes updated
  • Three endpoints currently need a bearer token. Uploading a document, booking a document as paid and fetching the invoice PDF fail with an API key (401 or 500). Use a bearer token and send no X-API-KEY header. See the FAQ on 401.
  • autoCalculateVat no longer rejects bookings. The temporary note about 400 errors is removed.
  • Do not rely on the recommended VAT suggestion. Choose the VAT rate and account yourself until the recommendation is corrected.
12 October 2026Fewer roles can create and send invoices

Breaking for existing keys. This changed in the KLARA roles, not in the API contract, so the list of API changes above does not show it.

  • Since September 2026, Buchhalter, Mitarbeiter und Lohn and Online Terminbuchung no longer hold FINANCE. Keys with only these roles can no longer create, update, send or list invoices, and no longer update or delete customers. They receive 403. This page still listed them until today. For invoicing, use Administrator, External user or Kundenbeziehungen.
  • Four endpoints check a narrower permission than this page said. GET /core/v1/invoices/{id} checks FINANCE_GET_INVOICE, so Buchhalter can read a single invoice again. GET /core/latest/customers/{customer-id} checks FINANCE_GET_CUSTOMER. Both VAT reads, GET /core/latest/company-configuration/including-vat and GET /core/latest/company-vats, check FINANCE_COMPANY_GET_VAT.
9 October 2026Invoice status guide starts from the invoice list
  • Showing invoice status in your CRM now starts from the invoice list. Filter with status and booking-status instead of keeping every invoice id in your own system. Two older notes that still said invoices could not be listed are gone.
18 September 2026Invoice list, one search pattern, sunset dates and error bodies
  • New: GET /core/v1/invoices returns a page of invoices with free-text search, paging and sorting, so you no longer have to keep every invoice id in your own system. It needs the FINANCE permission. Read the note on status before you build on it: that parameter is the filter from the KLARA invoice overview, not an equality check on the field. status=OPEN returns rows that read INVOICED or PAID. Use booking-status to filter on the payment state exactly.
  • The superseded /core/latest accounting operations now carry a sunset date: 14 August 2027. From the day after, they answer 410 Gone instead of data. Each one names its /core/v1 successor in the contract. Replacing the prefix remains the whole migration. See Path prefixes and what is current.
  • One search and sort pattern across the API. search-key, offset, limit, sort-field, sort-direction and status are now the names everywhere. Nothing was renamed: the old names keyword, general-search, orderColumns and filter-by-status keep working and are marked deprecated. Send both and the new name wins.
  • Every error response now carries a documented body. Until now 444 of them declared none. At the same time the duplicate schema ErrorMessage1 is gone, and four operations that used it now answer with ErrorMessage. If you generate a client, this is the one change that forces a regeneration: the type name changes, the fields do not.
  • The contract now names its own error codes in x-error-codes. There are three today, and the list is not exhaustive on purpose. See What an error body contains.
  • Pagination on article categories and article filters is fixed. Both accept offset now and return the total in the X-Total-Count header. Until now they took limit without offset, so nothing beyond the first page was reachable.
  • The specification names the real host https://api.klara.ch instead of /, and states in its own description that this is the only environment customers can reach.
7 September 2026Roles for the document upload, and 404 on the customer endpoints
  • The document upload now names the roles that may call it. POST /core/latest/companies/{company-id}/documents lists COMPANY_ADMINISTRATOR, TRUSTED_USER, ACCOUNTANT, CUSTOMER_RELATIONSHIP_MANAGER, EMPLOYEE and MYKLARA_USER, and one of them is enough. Until now this endpoint said the requirement was not established. The statement comes from the specification text rather than from the source analysis behind the other permission statements, and the endpoint says so.
  • Seven customer endpoints now declare 404: reading and creating customers under both /core/latest and /core/v1, plus their additional addresses and contacts. No response body, as with the other error statuses there. If you generate a client, it gains a 404 branch on those calls.
  • Nothing was added or removed. 97 endpoints, same paths, same request and response shapes.
31 August 2026Every endpoint now has a stable operationId
  • All 97 operations carry an operationId, 68 of them for the first time. Until now a client generator had to invent method names from the path, and those names changed whenever a path changed. From now on the id is the name.
  • If you generate a client, expect method names to change once. Where no operationId existed, your generator invented one; it will now use ours. Paths, parameters, request bodies and responses are untouched, so nothing changes on the wire. Regenerate, fix the names in your code, and you are done.
  • Four ids that contained spaces and could not be used in generated code are corrected: update additional-addresses is now updateCustomerAdditionalAddress, delete additional-address is deleteCustomerAdditionalAddress, update CustomerContact is updateCustomerContact, and delete CustomerContact is deleteCustomerContact.
  • The endpoint set is unchanged: 97 operations, same paths, same permissions.
28 August 2026Machine-readable formats, error bodies, search, roles and superseded paths
  • This documentation is now available in machine-readable form. llms.txt indexes every chapter as a Markdown file and every area of the reference as a Markdown file with parameters, request and response bodies, the required permission and the roles that carry it. Built in the same run as this page, from the same source. The specification itself is unchanged and remains the contract.
  • The specification is now linked at the top of this page instead of only inside API basics.
  • The specification now spells the brand KLARA in capitals, including one tag name that was Klara authentication generic. If your client generator groups methods by tag, that group is renamed. Paths, parameters and response shapes are untouched.
  • The superseded /core/latest accounting and booking operations are excluded from the published specification, not just left undocumented. They still respond at the API. Each has an identical counterpart under /core/v1, and replacing the prefix is the whole migration. See Path prefixes and what is current.
  • Error bodies on the authentication endpoints are now listed per endpoint and per status, because the general rule does not hold for them. Three of them declare no body for any error status. POST /core/latest/tenants declares error and error_description for 400, 401, 403 and 500, and nothing for 429. See Authentication.
  • Free-text search and filtering by field are now separated, because they are not the same thing. Free-text search exists on six endpoints. 32 endpoints filter by field, with 73 parameters in total, and there you have to know the value you are filtering on. Two endpoints accept a sort order. See Searching and filtering.
  • Correction, please check your key: the permission summary of Webshop order to customer and invoice was incomplete. It did not include the permissions of the invoicing steps that flow reuses. ARTICLE_READ_ONLY and FINANCE_BANK_ACCOUNT are now listed. A key provisioned from the earlier list is short of both.
  • Correction, the recommended starting role has changed. The getting started guide recommended Accountant, which cannot read articles, so the first call of the guide answered 403. The guide now recommends a role that covers every call it makes.
24 August 2026Rate limit, error responses, pagination and API keys
  • The rate limit is at least 10,000 requests per minute, counted per calling IP address, the same on every endpoint. The informational rate limit headers are suppressed at the gateway, so do not expect them. See Limits.
  • 401 returns ErrorMessage even where the specification declares no body. 429 returns a body produced by the gateway rather than the application. There is no governed catalogue of error codes, so branch on the HTTP status and not on the code.
  • Pagination has no total count and no guaranteed order, so a full read is a snapshot rather than a transaction. GET /core/latest/article-categories and GET /core/latest/article-filters accept limit without offset, so only the first page is reachable.
  • API keys do not expire. You can revoke one yourself with immediate effect under Benutzer, and a last used timestamp is shown per key. The role of a key is fixed when it is created and cannot be changed later.
  • Adding a salary item is not idempotent: a retry after a timeout appends a second item. PUT and DELETE do not exist on salary items yet, so corrections happen in the KLARA interface.
  • New endpoints are versioned explicitly and start on /core/v1. A replaced endpoint stays available for twelve months after it is marked deprecated.
  • Correction to an earlier statement: External user holds the same Public API permissions as Administrator. Choosing it instead of Administrator does not narrow what a key can reach.
17 August 2026Initial publication
  • 97 endpoints across accounting, finance, articles, customers, payroll and delivery. Accounting, finance and payroll are served under /core/v1, articles, customers and authentication under /core/latest.
  • Every endpoint names the permission it requires and the roles that carry it.
  • Eight integration flows with the calls they take and the permissions those calls need in total.
  • The full specification is available for download, for generating clients and for contract testing.

Known limitations

We open KLARA step by step rather than all at once. These are the gaps we know about, listed here so you find out before you build rather than halfway through.

Separately, KLARA operates file-based interfaces for certified payroll partner systems. They are not part of this documentation. If you are a payroll partner, contact support.

Are you blocked by one of these? Tell us via support and describe what you are building. That is what shapes what we open next.

FAQ

Straight answers, including where the API cannot help you yet. Better to find out here than halfway through an integration.

Is an OpenAPI specification available?

Yes. Download it here. Use it to generate clients, mock servers or contract tests.

Can I list all invoices, or filter them by status?

Yes, since 18 September 2026. GET /core/v1/invoices returns a page of invoices with free-text search, paging and sorting. One thing to know before you build on it: the status parameter is the filter from the KLARA invoice overview, not an equality check on the status field of a row. status=OPEN returns rows that read INVOICED or PAID, because it also looks at the payment state. Use booking-status when you want to filter on the payment state exactly, and ?status=INVOICED&booking-status=OPEN for «invoiced and not yet paid».

Can I write variable payroll data?

Yes. Add salary items such as hours, allowances and bonuses to an employee's editable payslip. See Submitting variable payroll data. Master data such as contracts and base salaries is still not writable through the API.

Is there a general order API?

No. Order endpoints exist only as a two-step partner protocol and are not part of this documentation. For webshop integrations, create a customer and an invoice instead. See Getting started.

Are there webhooks?

No. You need to poll, and poll gently. See rate limiting. If this blocks your use case, let us know and describe what you are building.

Can I book appointments through the API?

No. Despite the role name, KLARA Online Terminbuchung has no public endpoints. The tag SHRM Booking refers to salary-run bookings, not calendar appointments.

Why do I get a 401 even though my API key is correct?

Check three things first: the key belongs to the company whose data you are requesting, the header is spelled X-API-KEY, and the user behind the key holds the permission the endpoint needs. See Roles & permissions. If all three are right and the call still fails, repeat it with a bearer token instead of the API key, and send only one of the two headers. If the bearer token works, please tell support which endpoint it was. Note that the token endpoints themselves take no authentication at all, listed under Authentication.

Four endpoints currently work only with a bearer token: POST /core/latest/companies/{company-id}/documents (upload a document), POST /core/v1/accounting/document-bookings/paid (book a document as paid), POST /core/v1/invoices/{id}/printed-document (invoice PDF) and POST /core/v1/invoices/{id}/send (send an invoice). With an API key they return 401 or 500. Use a bearer token and send no X-API-KEY header.

Can I restrict an API key to articles only?

No. A key carries the roles chosen when it was created, and there is no role for articles only. The narrowest roles are Zeit- und Materialrapporte, which can read articles, and Kundenbeziehungen, which can read and write them. Both reach more than articles. See Roles & permissions.

Why do ePost and eBill appear in a KLARA API?

They are delivery channels for KLARA invoices, not separate products you need to integrate. See Sending documents. If you are building on the ePost Communication Platform itself, you want developer.epost.ch.

Why is my use case not supported?

We open KLARA step by step rather than all at once. The gaps we already know about are listed under Known limitations. If yours is not there, tell us via support and describe what you are building. That is what shapes what we open next.

Support

Questions and problem reports: support.klara.ch. When reporting an error, include the uuid from the error response and the steps to reproduce it, but never your API key or any credentials.

What this documentation is, and what it is not The KLARA API is provided as is, on the basis of this documentation. We do not offer guided implementation or code support for individual integrations.

Every release is recorded in the changelog, including breaking changes.